Sessions

A session holds what one run of a game owns beyond its scene trees, such as the resources it loaded. Each system keeps its part with define-session-value, and each session has its own:

(pyssel:define-session-value levels-seen (make-hash-table :test 'equal)
  :type hash-table :documentation "The levels this run has loaded, by name.")

(levels-seen)                                    ; the current session's table
(pyssel:with-session ((pyssel:make-session :name "another run"))
  (levels-seen))                                 ; another, that session's own

*session* is the current session. Its global value is the image's session, which the REPL, tests and tools use. make-session makes one for a run, and (pyssel:start ... :bindings `((pyssel:*session* ,session))) gives it to every thread of the run's engine, so that what the run changes is its own and the image's stays as it was. with-session binds it around a body. Bind *session*; never set it, since a setting on one thread would not reach the others. A value's initial form runs the first time a session asks for it, with that session current, and reading it afterwards allocates nothing.

Keep a game's state in its nodes and resources. Session values are for systems built on Pyssel that keep something for each run, rather than in a global variable that every run would share: a game played in the editor's image shares the image's global variables with the editor and with every play after it, and a play says which of its game's it changed.