Puzzle Sets

Status: implemented


Puzzle sets are the way we group puzzles together. At its heart, Crosswords is a simple UI: It shows available puzzle sets, lets you select them, and then play all the puzzles within the set.

The PuzzleSet class is a GObject that represents a set of puzzles, and can be used by the game to both control the UI and load/save files. It isn’t a widget directly, but provides widgets for the game to display depending on the state of the game.

By default, there is a GResource containing a GKeyFile for every PuzzleSets that stores all information about the set. Originally more PuzzleSet config formats were planned, but over time it became clear that a the resource puzzle set could be extended to provide everything we need.

Interacting with PlayWindow

The PuzzleSet is the primary way for the PlayWindow to communicate with widgets or puzzles.

The main game window provides some UI functionality in the header. That includes the navigation controls, as well

There’s a default implementation of the play_window UI control interfaces within the PuzzleSet. For it to work, three things need to happen. First, ::get_widget() has to be stable and the widget returned have to be constant for the life of the puzzle set. Second, the PUZZLE_PHASE_GAME widget must be PlayXword. Third, subclasses need to chain up to the parent widget.

It is recommended that a subclass either handles none of the PlayWindow interface and chains up, or all of it without chaining.

PuzzleSet properties

PuzzleSets have two game phases that they need to handle: the PICKER phase and the GAME phase.

  • PICKER: Let the user pick a puzzle to play and potentially show a meta-puzzle. This phase is optional but used by every instance in the current game.

  • GAME: Solve an actual crossword.

By default, we provide two different widgets that can be used as a picker (PickerList and PickerGrid). These can be customized and extended through the keyfile.

There is a PuzzlePicker base class to share common functionality between the two pickers, and it’s plausible to write completely type of picker using it.

Directories and File Names

Puzzle sets are all installed in:


It will search all directories within that path, and can be overridden with the $PUZZLE_SET_PATH environment variable.

The filename should be named either $ID.gresource or $ID.config depending on the type of the puzzle set.

Saved files are all saved in:


Where $ID is the ID of the puzzle-set.

Finally the resource puzzle-set can save files that it has downloaded. Those are stored in


Where $ID is the ID of the puzzle-set.