$Id: game-options.txt 4215 2021-05-30 00:20:41Z dsb $

Defining Game Options
=====================
Addons can define their own game options by passing a suitable option
definition file to GameOptions:loadDefinition(), as follows:

  local GameOptions = require 'mod.dialogs.GameOptions'
  GameOptions:loadDefinition('/data-addon_short_name/your-options-file.lua')
  GameOptions:setupOptions()

Typically this will be done in your /hooks/load.lua.  The loader provides
methods newOption() and newOptionGroup() for your definition file to use;
both take a single table parameter, and thus are typically invoked using
the Lua syntax:

  newOption {
    field = value,
    ...
  }

newOptionGroup()
----------------
  Defines a new option group, which will be represented as a tab on the
  Game Options dialog.  The module predefines four option groups:  'ui'
  ("User Interface"), 'gameplay' ("Gameplay"), 'display' ("Display") and
  'birth' ("Birth Options").  Options in the 'birth' group will be made
  available for setting in the character creation dialog, and for display
  only in the in-game Game Options dialog.

  newOptionsGroup() takes the following parameter fields:
    key:		The internal identifying key, by which the group
			will be referenced by newOption().  Required.
    name:		The display name of the option group, used in the
			dialog tab for the group.  Required.
    before, after:	Influences ordering of the option groups.  At most
			one may be specified; if present, its value should
			be the key of the option group before/after which
			this group should be placed.  If neither is present,
			the group will be placed at the end of the list.

newOption()
-----------
  Defines a new option.  Takes the following field parameters:
    key:		The internal identifying key of the option, and the
			field name in config.settings.tome2{} by which your
			addon code can obtain the current option value.
			Required.
    name:		Display name of the option.  Required.
    group:		Identifying key of the option group into which this
			option should be placed, as defined by
			newOptionGroup() above.  Required.
    desc:		Description text for the option.  If absent, a
			short boilerplate description will be used.
    default:		The initial default value for the option.  The type
			of this value will determine what interface the
			Game Options dialog provides to the user to change
			the option value.  Required.
    min, max:		The minimum and maximum allowed values of the
			option, respectively.  Required if the option has a
			number value.
    values:		A list of string values representing the allowed
			values of the option.  This or dialog() is required
			for string-valued options.
    short_values:	An optional table mapping option values to short
			display strings for use in the current-value column
			of the Game Options dialog.
    list_values:	An optional table mapping option values to
			corresponding display names for use in the list
			dialog created to select a value for the option.
    display_val:	If present, will be called to obtain a display
			string for use in the current-value column of the
			Game Options dialog.  The function will receive two
			arguments:  the option definition table and the
			current option value.  Required unless the option's
			value is a number, string or boolesn
    dialog:		If present, will be called by the Game Options
			dialog to allow the user to select a new option
			value.  Useful for complex, table-valued option
			values.  See "Option Value Dialogs" below for more
			information.  Required unless the option's value is
			a number, string or boolean; for string-valued
			options, this or values{} is required.
    on_change:		If present, will be called when the option's value
			is changed.  The function will recieve three argu-
			ments:  the option definition table, the new option
			value and a boolean which will be true if the
			option was changed from the character creation
			dialog.
    legacy_convert:	An optional map from old value to new value, which
			will be applied to the option's value when it is
			loaded at game start.  This is useful to convert
			old option values if your option's value changes
			type.
    show_in_birther:	If set, this option will be available for setting
			in the character creation dialog even if it is not
			in the 'birth' group.  If the option is not in the
			'birth' group, it will also be available for
			setting in the in-game Game Options dialog.
    require_restart:	If set, the option description will include boiler-
			plate text to the effect that the game will need to
			be restarted for the option to take effect.
    placeholder:	If set, the option description will include boiler-
			plate text to the effect that the option is not yet
			implemented.

GameOptions:setupOptions()
--------------------------
This method should be called after loading your options file; it will
process the 'default' and 'legacy_convert' fields of your defined options.

GameOptions:addValueToOption(key, val, list_val, short_val)
------------------------------
This method can be used to add option values to an option that defines a
list of values via the values{} field.  Typically this will be done in a
T2:load hook; for instance, a tileset addon could do something like this:

  class:bindHook('T2:load', function(self, data)
    local GameOptions = require 'mod.dialogs.GameOptions'
    -- The addon's tile images live in overload/data/gfx/funky32x32.
    GameOptions:addValueToOption('tiles', 'funky32x32', 'Funky Tiles', 'Funky')
  end)

The list_val and short_val arguments are optional and provide corresponding
values for the list_values{} and short_values{} tables, respectively.

Option Value Dialogs
--------------------
  For complex option values with multiple moving parts, your option
  definition can specify a dialog() method that returns a custom dialog to
  modify the option.  The dialog method will receive two arguments:  the
  option definition table and the current value of the option.  The dialog
  returned by this method must itself define the following methods:

    :get_value()	Returns the newly set option value in a format
			suitable for placement in config.settings.tome2{},
			or nil if the user canceled out of the dialog.
    :get_display_val()	Returns a short display string representing the
			newly set value for use in the current-value column
			of the Game Options dialog, or nil if the user
			canceled out of the dialog.

  Note also that the dialog's :unload() method will be redefined for use by
  the Game Options dialog, so your dialog should not depend on it; instead,
  your option definition should include an on_change() method, as described
  above.
