docs/shapelibs.rst

   1 Shape libaries
   2 ==============
   3
   4 Most pieces in a game in Otter will be from a shape library.
   5
   6 Introduction; general structure
   7 -------------------------------
   8
   9 A shape library is a set of named pieces.  Mostly, it defines their
  10 appearance.
  11
  12 Shape library pieces can have more or more sides (**faces**), and they
  13 can also have an **occulted view** which is used when the identity of
  14 the piece is to be hidden (possibly from only some of the players).
  15
  16 For example:
  17
  18 Playing cards have two faces: one is the front, which identifies the
  19 card, and the other is the back, which is a generic card back.  Cards
  20 also have an occulted view: again, the back.
  21
  22 Chess pieces usually have only one face.  The Knight has two faces,
  23 because it is not symmetrical: the first face looks to the right, and
  24 the other face to the left.  Chess pieces can be occulted, but when
  25 they are occulted they reveal their shape but not their colour.  The
  26 occulted view of a chess piece is a grey version of the piece.
  27
  28 A library has a **library name**.  This is a string.  For a library in
  29 a bundle, it's the ``LIB`` part of the filename
  30 ``libraries/LIB.toml``.
  31
  32 Each piece in a library has an **item name**.  Item names are unique
  33 within a library.  The item name is used within Otter to refer to the
  34 piece (for example, with ``otter library-add``).
  35
  36 Item names do not need to be unique within a game, but there are
  37 places where a piece is found *just* by the item name, so pieces
  38 should have the same item name (only) if they are in some sense
  39 equivalent.  The item name is a string but may contain only ASCII
  40 alphanumerics, plain ASCII spaces, and the punctuation characters
  41 ``-._``.
  42
  43 Pieces in shape libraries cannot have "behaviours": they can't do
  44 anything "special" like react to being moved or clicked on.  Pieces
  45 with special functionality do exist, but they are built into Otter.
  46 (See _`Piece specs` for all the kinds of piece.)
  47
  48 A library consists of a **catalogue**, and a set of **image files**
  49 which contain the actual appearances.  When a library is in a bundle
  50 the catalogue is ``libraries/LIB.toml`` and the image files are in a
  51 directory ``libraries/LIB.toml``.  The layout of Otter's builtin
  52 libraries is similar.
  53
  54 Catalogue
  55 ---------
  56
  57 The catalogue defines what pieces the library contains.  For each
  58 piece it defines each face looks like, how big it is on the screen,
  59 whether and how the piece can be occulted, and what source image files
  60 are to be used to display it.
  61
  62 The catalogue is a TOML file.  Its main contents is a table
  63 ``groups``, mapping each group name to a sub-table of parameters:
  64
  65 Each catalogue is organised into named **groups**.  Each group defines
  66 some pieces.  It specifies various **parameters**, and also gives a
  67 list of indvidual image files which should be processed according to
  68 those parameters.
  69
  70 For example::
  71
  72   [group.dried]
  73   outline = "Circle"
  74   size = [14]
  75   orig_size = [64, 48]
  76   centre = [32,24]
  77
  78   files = """
  79   dried-lemon   -       a dried lemon
  80   """
  81
  82 This defines a group ``dried``, with parameters such as ``size`` and
  83 ``outline``.  The ``files`` entry defines the list of pieces.
  84
  85 The group names are not visible when using the library, but they can
  86 be used within the library using the ``inherit`` feature.
  87
  88 The builtin catalogues also have a toplevel table ``scraper``, which
  89 controls how the builtin shape data is processed during the build, and
  90 how it is to be updated.  (Downloads are never automatically run
  91 during the build.  If you updated the catalougue in a way that means
  92 files should be re-downloaded, you should re-run ``./media-scraper
  93 library/LIB.toml``.)
  94
  95 Files entry
  96 -----------
  97
  98 Each group has a table key ``files``.  This is a string, which is
  99 treated as a series of lines (so it is best to use the TOML multi-line
 100 string syntax).
 101
 102 Each line of which has (normally) three fields (the leading ones
 103 terminated by whitespace).  ``#`` comment lines are supported and
 104 blank lines are ignored.
 105
 106 Each non-empty non-comment line in ``files`` specifies a single piece,
 107 like this::
 108
 109    ITEM-SPEC SRC DESCRIPTION...
 110
 111 The **item name** of the piece will be ``ITEM-SPEC`` sandwiched
 112 between the ``item_prefix`` and ``item_suffix`` parameters (see
 113 below).
 114
 115 The **image filename** is derived from ``SRC`` or the item name, as
 116 follows: ``library/LIB/SRC.svg`` or ``.png``.  If ``SRC`` is ``-``
 117 then the item name is used for ``SRC``.  (Builtin libraries: these
 118 support SVG only; and the ``SRC`` is not used at runtime, or when
 119 loading shapes --- rather, only when scraping or building.)
 120
 121 ``DESCRIPTION`` is the **description**, a string which will be used to
 122 describe the piece (eg in in-game log messages).  In English, it
 123 should contain an article.  Eg, ``the black queen``, ``a white pawn``.
 124 It will be HTML-escaped, so it should be plain text, not HTML.
 125
 126 It is also possible to specify additional data for each piece by
 127 adding fields to each line in ``files``.  This is done by adding a
 128 line at the start starting with ``:`` listing the extra fields, and
 129 then additng one additional whitespace separated value on each data
 130 line.  Values given for unknown field are ignored.
 131
 132 Currently the extra fields supported are:
 133
 134  * ``sort``: Specifies the sort key.  See the ``sort`` group
 135    parameter.
 136
 137 The values for these extra fields come just before the
 138 ``DWSCRIPTION``, after the other whitespace-delimited fields, in the
 139 same order as specified in the ``:`` heading line.
 140
 141 Item names
 142 ``````````
 143
 144 Item names are conventionally structured using a hierarchical name
 145 with ``-`` between the components.  Do not put ``/`` in item names use
 146 ``_`` only as a word separator within ``-``-separated parts.
 147
 148 See the existing examples to see what item names usually look like.
 149
 150 Parameters
 151 ----------
 152
 153  * ``inherit`` [string: group name].  Causes this group to inherit
 154    every parameter (except ``files``) from the group named by
 155    ``inherit`` (recursively, if applicable).
 156
 157    When inheritance is happening, there is of course a difference
 158    between leaving a value unspecified, and specifying it to have
 159    the usual default value: the latter would override any inherited
 160    setting.
 161
 162  * ``size`` [mandatory; 1- or 2-element array of numbers: width and height].
 163    The size at which the piece will show up in the game, in nominal
 164    game coordinate units.  For reference: the builtin library's chess
 165    pieces are 9.5 units; the builtin playing cards are 9.65,17.125.
 166    NB, this value can be affected by ``scale``.
 167
 168  * ``item_prefix``, ``item_suffix`` [strings, default ``""``].
 169    Prepaended and appended to ``ITEM-SPEC`` in ``files`` to
 170    produce the item name.
 171
 172  * ``sort`` [string].
 173    The sort key (used for item sorting in hands).
 174
 175    If neither the group parameter, nor the ``files`` extra field, are
 176    specified, the item name is used as the sort key.
 177
 178    If both are specified, the group parameter is used as a template.
 179    ``_s`` is replaced by the sort extra field from the ``files`` list
 180    ``_c`` is replaced by the colour, if applicable.
 181
 182  * ``flip`` [boolean, default: false].  Whether this piece can "flip".
 183    If true, the piece will have two faces, one of which is a mirror
 184    image of the other.  The default face will be un-reflected version;
 185    the other face is the same image, but flipped left-to-right.  It
 186    doesn't make sense to enable this for pieces with a symmetrical
 187    appearance.  (It is a bad idea to have the game contain state which
 188    is not visible to the players.)  Not compatible with ``back``.
 189
 190  * ``back``: [_`Piece spec`].  The back of this piece looks like some
 191    other piece (typically, another library item such as a card back).
 192    If specified, the piece will have two faces: the one implied by its
 193    ``files`` entry, and a 2nd face looking like ``back``.  If you want
 194    to make the piece be occultable, you must also specify
 195    ``occulted``.  ``back`` is not compatible with ``flip``.
 196
 197  * ``orig_size`` [1- or 2-element array, or (default) empty array]: If
 198    non-empty, the supplied image is first scaled from ``orig_size``
 199    to ``size``.  If both ``size`` and ```orig_size`` are 2 elements,
 200    this can scale by different amounts in x and y, distorting the
 201    image.
 202
 203  * ``centre`` [2-element array].  The centre of the image, measured
 204    from the top left in the image's own internal units.  If not
 205    supplied, calculated from the size.
 206
 207  * ``scale`` [number, default=1].  Scale the image by a factor (in
 208    both x and y).  ``size`` and ``centre`` are in the image file's
 209    own internal coordinate system, not the Otter scaled coordinates
 210    which result from multiplying by by this scale factor.
 211
 212  * ``colorus`` [table].
 213    If specified and non-empty, specifies that this group should be
 214    instantiated multiple times, for different colours.
 215
 216    For each entry in the ``colours`` table, a separate piece is
 217    generated for each item in the ``files`` list.  The keys of the
 218    ``colours`` are recolouring names, and the values are sub-tables.
 219
 220    Every effective item name (i.e., after the prefix and suffix have
 221    been added) must contain the substring ``_c`` exactly once, and
 222    every item description must contain the substring ``_colour``
 223    exactly once.  ``_c`` will be replaced with the value of the
 224    recoluring's ``abbrev``, and ``_colour`` with the recolouring name
 225    (the key of the ``colours`` table).
 226
 227    For libraries in bundles, a separate image file must be supplied
 228    for each recolouring.  If ``SRC`` is not ``-``, it also must
 229    contain ``_c`` which will be substitued with ``abbrev`` to find the
 230    colour-specific image file.
 231
 232    For builtin libraries, the Otter build system will do the
 233    recolouring automatically at build time.  Each recolouring should
 234    hae a ``map`` entry which is a sub-sub-table mapping inputcolours
 235    (strings in ``#rrggbb`` format) to output colours.
 236
 237  * ``desc``: [string: template].  If specified, provides a template
 238    for the description, to allow formulaic descriptions of pieces in
 239    thisf group.  The string specified ``desc`` must contain ``_desc``
 240    exaclty once; it will be replaced with the description calculated
 241    according to the other rules.  (``_desc`` substitution happens
 242    after ``_colour`` substitution.)
 243
 244  * ``occulted`` [table, contents depend on ``occulted.method``].  If
 245    specified, these pieces be occulted.  For example, when a player
 246    has them in their hand and the hand is active and owned by them,
 247    only the occulted view (eg, the back of a playing card) will be
 248    shown.  This a table whose other contents depend on its key
 249    ``method``, which must be a string:
 250
 251   * ``"ByColour"``: Occult by displaying a particular recolouring of
 252     this piece.  The sub-key ``colour`` names a recolouring - one of
 253     the keys of the ``colours`` group parameter.  When the piece is
 254     occulted it will show that colour, instead of its actual colour.
 255     In the description, ``_colour`` will be elided rather than
 256     substitued (along with up to one of any spaces either side of it).
 257
 258   * ``"ByBack"``: Occult by displaying the back of this piece, as
 259     specified by the ``back`` group parameter.  The ``occulted`` table
 260     must also contain a sub-entry ``ilk``, a string.  Pieces which
 261     have the same ``ilk`` display identically when occulted, even if
 262     the different piece definitions imply different backs.  (Whichever
 263     pieces are first loaded define what the backs of a particular ilk
 264     look.)
 265
 266     For pieces that are like cards, the ilk should be different for
 267     cards which have different backs in the game.  Generally, standard
 268     playing cards should all specify ``card-back``.