lichess.org
Donate

Interactive lessons: keep hints (and "wrong move" feedback) in PGN import/export

benitotrm

Hi all,

I build interactive lesson chapters (gamebooks) from master games for my own opening study: guess every move, with an on-demand hint for each one. Comments, variations and arrows survive PGN import and export, but the per-move hint and deviation text of an interactive lesson do not: as far as I can tell the PGN importer and exporter ignore them, and there is no API endpoint to set them. The only way to add them is the chapter editor, one move at a time.

That makes interactive lessons hard to build or maintain at scale. A 40-move game needs ~40 hints, and re-importing a chapter (to fix a typo, reorder, etc.) silently drops all of them.

Proposal: carry the two gamebook fields in the PGN comment, the same way arrows and highlights already use [%cal ...] / [%csl ...], for example:

13. d5 { [%hint Black is pressing d4 with everything; what do you do with the centre?] }

and the equivalent for the deviation text (shown when the student plays a wrong move). Import would read them into the node's gamebook data, and export (when the chapter is an interactive lesson) would write them back. Alternatively, an API endpoint to set a node's gamebook hint/deviation would also solve it.

This would let authors keep lessons in plain PGN files, version them, and re-import without losing work. Happy to help test, or to look at contributing a PR if the approach is acceptable.

Related (2024, unanswered): https://lichess.org/forum/lichess-feedback/copy-a-study-chapter-with-interactive-lesson-hints-to-another-study

Thanks!

Hi all, I build interactive lesson chapters (gamebooks) from master games for my own opening study: guess every move, with an on-demand hint for each one. Comments, variations and arrows survive PGN import and export, but the per-move **hint** and **deviation** text of an interactive lesson do not: as far as I can tell the PGN importer and exporter ignore them, and there is no API endpoint to set them. The only way to add them is the chapter editor, one move at a time. That makes interactive lessons hard to build or maintain at scale. A 40-move game needs ~40 hints, and re-importing a chapter (to fix a typo, reorder, etc.) silently drops all of them. Proposal: carry the two gamebook fields in the PGN comment, the same way arrows and highlights already use `[%cal ...]` / `[%csl ...]`, for example: 13. d5 { [%hint Black is pressing d4 with everything; what do you do with the centre?] } and the equivalent for the deviation text (shown when the student plays a wrong move). Import would read them into the node's gamebook data, and export (when the chapter is an interactive lesson) would write them back. Alternatively, an API endpoint to set a node's gamebook hint/deviation would also solve it. This would let authors keep lessons in plain PGN files, version them, and re-import without losing work. Happy to help test, or to look at contributing a PR if the approach is acceptable. Related (2024, unanswered): https://lichess.org/forum/lichess-feedback/copy-a-study-chapter-with-interactive-lesson-hints-to-another-study Thanks!