Game State
Status: implemented | obsolete
Control flow in the game is centralized in two different places. All
navigation throughout the game between puzzles, is controlled by
PlayWindow. In addition, all navigation within a crossword once it’s
loaded is handled by PlayXword. This doc covers the former. For the
latter, see xword-state.md.
When the main PlayWindow is first loaded, it loads list of all the
possible PlayPuzzleSets that the game knows about and puts them in a
GListModel (:play_set_list). It also creates a GtkStack with the
contents of the main window as the first page in the stack. These
contents are the first element in the stack and have the name main.
They shouldn’t change for the lifetime of the window
Once the user selects a puzzle, PlayWindow will call
::start_puzzles on the appropriate puzzle set. It will then call get
phase to get widgets to display for the appropriate phases. Puzzles
should be prepared to give a widget at the start and populate them as
necessary (or display loading information, such as in the case of
network-based puzzles).
Control will flow to the PuzzleSet, which can call ::change_phase
whenever appropriate to update the stack. Dialogs are fine to popup as
well as part of a phase change.
Once a puzzle is finished (either by beating the whole set, or from a
UI element), ::puzzles_done is called on the puzzle set which will
free up memory / clear any widgets.
It’s up to a puzzle set if it wants to keep the widget around when it
is removed from the stack. It should either call ref_sink() and
reparent it in future calls, or drop all references after puzzles_done
is called.
Notes:
Calling
::change_phaseto"main"will not trigger a::puzzles_donecall. However, if the user selects a different puzzle set, it will be called.Every
::start_puzzlescall needs to be mirrored by apuzzles_donecall before another puzzle set can start. Only one PuzzleSet is run at a time.If a puzzle set intends to keep a widget around between invocations, it should ref_sink it first.