docs/bundles.rst

   1 Bundles - uploadable game materials
   2 ===================================
   3
   4 Otter supports uploading game materials (pieces, and game specs) to
   5 the server.  That way you can play games with pieces that you have
   6 designed yourself without having to share them publicly or get them
   7 incorporated into Otter itself.
   8
   9 These **bundles** are per-game.  They are accessible to the players
  10 but not made public.  The usual way to use bundles is to specify them
  11 on the ``otter reset`` command line:
  12
  13 ::
  14
  15   otter --game unix:myself:: reset stoat-fest stoaty-games.zip
  16               /^^^^^^^^^^^^^      /^^^^^^^^^^ ^^^^^^^^^^^^^^^^\
  17      game (instance) name     game spec name       bundle file'
  18
  19 The zipfile will be uploaded to the server, and then Otter will look for
  20 the game spec ``stoat-fest`` amongst its builtin games and also in the
  21 zipfile.  Probably, ``stoat-fest`` is ``specs/stoat-fest.game.toml`` in
  22 the zipfile, and it will refer to piece elements also found there.
  23
  24 Bundle format
  25 -------------
  26
  27 Bundles are zipfiles.  They can contain:
  28
  29  * ``otter.toml`` at the toplevel, with some basic metadata.
  30    This file is required.
  31
  32  * ``specs/GAME.game.toml``:  Description of what a particular
  33    game looks like: what shape and colour the table is, what pieces
  34    the game contains (at least initially), and where they start.
  35    ``GAME`` is the game spec name (e.g., ``stoat-fest`` above.)
  36
  37  * ``library/LIB.toml``: Description of a piece shape library,
  38    for a library named ``LIB``.  See :doc:`shapelibs`.
  39
  40 These ``.toml`` files are all in TOML format.  TOML is an
  41 INI-file-like format designed for human editing and flexibility.  See
  42 the `TOML documentation <https://toml.io/en/>`_ for information about
  43 the syntax.
  44
  45 The TOML specification has confusing terminology.  In this manual we
  46 use "dictionary" (or "dict") for a mapping from (string) keys to
  47 values (what TOML calls a "table").  "Array" is an array or list of
  48 (more or less similar) values.
  49
  50 Any unrecognised files which might be present in the zipfile are
  51 ignored.  (Future versions of Otter might define a meaning for them.)
  52
  53 Character set and case-sensitivity
  54 ``````````````````````````````````
  55
  56 Everything in Otter is UTF-8.
  57
  58 All filenames in bundles are treated case-insensitively (according to
  59 Unicode).  So a bundle cannot have game specs, or piece image files,
  60 which differ ony in the case of their name.
  61
  62 Note, however, that library item names, TOML config file keys, and,
  63 indeed everything else *except* filenames within the zipfiles, are
  64 case-sensitive.
  65
  66 Library names in bundles are treated as lowercase, no matter the case
  67 in the zipfile.  So when piece specs refer to a bundle library, they
  68 must refer to it in lowercase.
  69
  70 ``otter.toml`` bundle top-level metadata
  71 ----------------------------------------
  72
  73 The top-level ``otter.toml`` contains the following keys:
  74
  75  * ``title`` identifying the bundle.  This is useful because the
  76    zipfile's name is not stored in the server.
  77    [string, mandatory]
  78
  79  * ``format``.  Identifies which version of this specification
  80    the bundle was written to.  This is also used as a default for
  81    further TOML files which are found in the bundle.
  82    The current format version is ``1``.
  83    [integer]
  84    See `bundle compatibility`_.
  85
  86 Newer versions of Otter may assign meanings to other keys.
  87
  88 Bundle management
  89 -----------------
  90
  91 Each game on the server can contain multiple bundles.  They are
  92 ordered and numbered, in order of upload.
  93
  94 When Otter needs to look for a game spec or a piece, the bundles are
  95 searched in reverse order: from most recent, to least recent.  So a
  96 game might contain elements from multiple bundles.
  97
  98 Usually, the right approach is to pass all the needed bundle filenames
  99 to ``otter reset``.  The right set of bundles will automatically be
 100 uploaded as necessary.
 101
 102 When a library piece is added to a game, its appearance is fixed.  You
 103 cannot retrospectively update existing pieces.  You can only delete
 104 them and replace them with a new versions (perhaps as part of ``otter
 105 reset``).
 106
 107 It is not possible to delete or replace individual bundles, only to
 108 clear out all the bundles of an empty game.  When developing a bundle,
 109 new versions can be uploaded to the server by hand with ``otter
 110 upload-bundle`` and their contents will be found first.  But ``otter
 111 reset`` will usually be less trouble and will avoid cluttering the
 112 game (and the server) with previous versions.
 113
 114 Examples
 115 --------
 116
 117 There are two examples of bundles:
 118
 119  * `test-bundle.zip <examples/test-bundle.zip>`__: A small test
 120    bundle, containing three yellow objects and one game spec.
 121
 122  * `big-bundle.zip <examples/big-bundle.zip>`__: The Otter builtin
 123    shape libraries automatically massaged into Otter bundle format,
 124    and one massaged game spec.
 125
 126 There are also several game spec examples, such as:
 127
 128  * `mao.game.toml <examples/mao.game.toml>`__ Mao, or many other
 129    similar card games.  Three decks, 9 jokers.
 130
 131  * `penultima.game.toml <examples/penultima.game.toml>`__ Penultima,
 132    with an assortment of additional pieces in addition to the basic
 133    chess pieces.  Suitable for Penultima, chess and some fairy chess
 134    variants.
 135
 136  * `vatikan.game.toml <examples/vatikan.game.toml>`__ Manipulation
 137    Rummy variants with two decks.
 138
 139 Consult the `webserver directory listing <examples/>`__ for a complete
 140 list.
 141
 142
 143 .. _bundle-compatibility:
 144
 145 Bundle compatibility
 146 ---------------------
 147
 148 The ``format`` key at the toplevel of many of Otter's TOML files
 149 declares which version of the Otter data formats and specifications
 150 the file adheres to.
 151 This allows old files to keep working, even as Otter evolves.
 152
 153 If no format is specified for a file in a bundle, the bundle's
 154 overall format is taken.  However,
 155 it is a good idea for each file to contain its own ``format=``
 156 setting, so that the file doesn't change meaning when put into a
 157 different bundle with a different overall format version.
 158
 159 The current version is ``format=2``.
 160
 161 This table gives the format versions,
 162 and the corresponding versions of Otter.
 163 For full details of the earlier formats,
 164 follow the link to the latest published documentation for that format.
 165
 166 .. list-table::
 167   :widths: 8 15 11 66
 168   :header-rows: 1
 169
 170   * - ``format``
 171     - Otter :ref:`[1] <bundle-compatibility-otter-footnote>`
 172     - Status
 173     - Changes
 174
 175   * - ``2``
 176     - unreleased
 177     - unreleased
 178     - Handling of the ``size``, ``scale`` and ``outline``
 179       of library pieces overhauled.  ``size`` is now the in-game
 180       size, and the SVG size is obtained from the SVG.
 181       Library catalogues must be overhauled.
 182
 183       Handling of the ``angle`` parameter in game specs is now
 184       much more sensible, and also accurately documented.
 185
 186       Shape library escaping in text strings now uses ``${subst}``
 187       (while in filenames and item names, still ``_c`` since that
 188       appears literally in filenames).
 189
 190   * - ``1``
 191     - 0.x - `1.0.0 <https://www.chiark.greenend.org.uk/~ianmdlvl/otter/1.0.0/docs/README.html>`_
 192     - supported
 193     - First release.
 194       Note that ``format`` may be omitted in this version.
 195
 196 .. _bundle-compatibility-otter-footnote:
 197
 198 [1] The earliest version of Otter that supports this format,
 199 and the newest version which uses it as the primary format.
 200 (Currently, newer versions of Otter can read files in any older format.)