Settings Storage

Trial offers a standardised way to store and access user settings for your game. The settings are stored as a nested tree of plists.

Using Settings

Setting the default properties of the settings works simply by setfing +settings+:

(setf +settings+
      (copy-tree '(:audio (:latency 0.005
                           :backend :default
                           :device :default
                           :volume (:master 0.5
                                    :effect 1.0
                                    :music 1.0))
                   :display (:resolution (T T)
                             :fullscreen T
                             :vsync T
                             :target-framerate :none
                             :gamma 2.2
                             :ui-scale 1.0)
                   :gameplay (:rumble 1.0
                              :screen-shake 1.0)
                   :language :system)))

When you save-settings this plist structure is output to a local file appropriate for your game, provided +app-system+ and +app-vendor+ are correctly set (see config-directory).

When you load-settings the plist is read from the file and merged with the existing settings. This means missing keys are augmented, existing keys are overwritten, and superfluous keys are retained.

Accessing settings happens through the setting function, which takes a path to the value you want to access. When you update a setting through this function, it similarly merges things, adding and overwriting keys as necessary. Reading settings out with this function should be very fast provided that the setting compiler-macro can be expanded (so not called through funcall, not declared notinline).

Often it is also useful to react in various parts of the game when a setting is changed. To install change hooks, use define-setting-observer:

(define-setting-observer update-resolution :display :resolution (value)
  (when *context*
    (show *context* :fullscreen (setting :display :fullscreen) :mode value)))

Standard Fields

Trial defines the following setting paths as standard. It will integrate better if you structure your settings in the same way.


Settings related to audio playback. See audio.mess


Settings related to graphics and context. See context.mess


General gameplay options and tweaks for the user.


The language to use. See localization.mess


Debugging options for diagnostics.


See input.mess

Loading and saving the keymap.lisp file can be conveniently done through load-keymap and save-keymap. When load-keymap is called, it will check whether the keymap.lisp file in the root is newer, and if so, update the old one. This ensures that changes to the actions or keymaps will propagate to installations that already have a potentially stale map.