From 565d99b3328c3320e53de12ee648dc69f62d024f Mon Sep 17 00:00:00 2001 From: Ian Jackson Date: Wed, 25 May 2022 01:26:25 +0100 Subject: [PATCH] docs: Document library magic items Signed-off-by: Ian Jackson --- docs/shapelibs.rst | 52 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 52 insertions(+) diff --git a/docs/shapelibs.rst b/docs/shapelibs.rst index d212dca7..5747399f 100644 --- a/docs/shapelibs.rst +++ b/docs/shapelibs.rst @@ -155,6 +155,8 @@ Currently the extra fields supported are: * ``sort``: Specifies the sort key. See the ``sort`` group parameter. + * ``x...``: Can be referenced by templates in `"Magic" items`_. + The values for these extra fields come just before the ``DWSCRIPTION``, after the other whitespace-delimited fields, in the same order as specified in the ``:`` heading line. @@ -280,6 +282,56 @@ Parameters for defining faces occultable, you must also specify ``occulted``. ``back`` is not compatible with ``flip``. +"Magic" items +````````````` + +The shape library primarily defines inert image pieces. But it is +also possible to define, as part of a library, a non-inert behaviour +to go with an image. (These could be defined directly, in game spec +files, but library items are more convenient to reuse, since the +necessary parameters do not need to be recapitulated for each use.) + +Magic items are produced by a ``magic`` section in the group. This is +applied once for each item (ie, once for each entry in ``files``). +The ``magic`` section generates an additional item in the library for +each ordinary item defined by the group via its ``files``. + +The magic item is typically defined using a non-library piece spec type, +and usually references the corresponding ordinary (base) item. + +The magic section in the group may contain: + + * ``magic.item_prefix``, ``magic.item_suffix`` + [strings, default ``""``]. + Defines the magic item name. The item name to define is assembled + the same way as the base image item name, only with these prefix + and suffix instead of the main ones in the group. + + * ``template``. Template which will generate TOML defining the magic + piece. The string value has variables ``${...}`` expanded, and + is then reparsed as a new piece of nested TOML. The resulting + dictionary must be a valid :ref:`Piece Spec ` + Substitution variables are (in precedence order): + + - ``${CVAR}``, the value of ``colours.COLOUR.substs.CVAR`` + for the current ``COLOUR``, and for each ``SVAR`` defined there. + + - ``${SVAR}``, the value of ``magic.substs.SVAR`` for each + any ``SVAR`` defined there. + + - ``${x...}``, values of extra fields in the ``files`` list + (but only those starting with an ``x``). + + - ``${image}`` a TOML in-line dictionary for the piece + spec for the base item. (The substitution references the + containing library by name, so it is possible that later-loaded + libraries might intercept this reference.) + + - ``${colour}``, the recolouring name from the ``colours`` + group parameter. + + * ``substs``: Extra substitutions for the template. + Other group parameters ``````````````````````` -- 2.30.2