docs/gamespec.rst

   1 Game specs
   2 ==========
   3
   4 A game spec defines the starting layout for a game: **which pieces start
   5 on the table, and where**.
   6
   7 It also defines some ancillary information about the game and its
   8 layout.  It does not contain information about the players.
   9 Players join a game as permitted by the game access control list,
  10 which is specified in a *table specification* (sadly not currently
  11 properly documented, but look at the Rustdoc for ``TableSpec``).
  12
  13 General
  14 -------
  15
  16 A game spec is a TOML file.  It has the following entries at the top
  17 level:
  18
  19  * ``table_size`` [array of 2 numbers].  Size of the table playing
  20    area, in Otter internal units.  The default is ``[300,200]``.
  21
  22  * ``table_colour`` [string: colour].  Table backdrop colour.
  23    Only certain colour syntaxes are supported.  Default: ``green``.
  24
  25  * ``pcaliases``: [table, values are Piece spec table].  Piece alias
  26    table.  When a piece is being loaded, an alias  xxxx grep for where
  27    referred to
  28
  29  * ``pieces``: Array of `Piece Specs`_.  Defines the initial pieces
  30    and their layout.  Each entry is a piece spec sub-table.
  31
  32 Piece Specs
  33 -----------
  34
  35 A piece spec is a table defining one or more pieces.  When part of a
  36 game spec, it appears as an entry in the top-level ``pieces`` array,
  37 and defines the location(s) on the table to place the pieces, too.
  38
  39 There is a mandatory key ``type``, a string.  This determines how the
  40 rest of the table is interpreted.  It is one of the `Piece Spec
  41 Types`_.
  42
  43 Universal parameters
  44 ````````````````````
  45
  46 These apply regardless of the value of ``type``.
  47
  48  * ``type``: Piece type or piece spec type.  One of the types listed
  49    in `Piece Spec Types`_.  [string, enum, mandatory]
  50
  51  * ``pos``:Position, in game coordinates, of
  52    the centre of the piece.  The origin is at the top left.
  53    [2-element array, default ``[20,20]``]
  54
  55  * ``count``: Place multiple identical copies of this piece.  [number]
  56
  57  * ``posd``: Position delta.  When a spec specifies multiple pieces,
  58    each successive piece will be shifted by this amount.  [2-element
  59    array, default ``[5,5]``]
  60
  61  * ``face``: Initial face to show (ie, "which way up" the piece
  62    starts).  The default face is ``0``.  For most pieces that is the
  63    front, and is usually a good choice.  [number]
  64
  65  * ``pinned``: Whether the piece is pinned to the table.  Players can
  66    pin and unpin pieces during the game; this is the initial state.
  67    [boolean]
  68
  69  * ``angle``: Initial orientation of the piece.  The
  70    specified value is multiplied by 45 degrees, increasing values
  71    rotating anticlockwise.  So for example ``6`` would mean to rotate
  72    90 degrees clockwise.  [integer 0..7]
  73
  74
  75 Common parameters
  76 `````````````````
  77
  78 Depending on the ``type``, some of these parameters will be honoured.
  79 This is discussed in the descriptions for each piece spec type.
  80
  81  * `colour` [string, colour].  The fill colour For a piece which
  82    supports only one face.
  83
  84  * `faces` [array of string(s), colours, mandatory].  The main fill
  85    colour.
  86
  87  * `edge` [string, colour].  The edge colour to draw for a piece with
  88    supports only one face.  Default is not to draw edges.
  89
  90  * `edges` [array of string(s), colours].  The colours of edges to
  91    draw.  Default is not to draw edges.  Must either be a 1-element
  92    array, or as long as `faces` (specifying a different edge colour
  93    for each face).
  94
  95  * `edge_width` [number].  Default is 0.2 if `edge` or `edges` is
  96    specified.
  97
  98  * `label` [table].  Displays a label with informationa about the
  99    in-game state.  There are two sub-keys:
 100     * `colour` [string, defaults to the edge colour].
 101     * `place` [string]: One of `BottomLeft` (default), `TopLeft`,
 102       `BottomLeftOutside`, `TopLeftOutside`.
 103
 104  * `shape` [table].  The shape of a piece.  There are two sub-keys:
 105     * `type`, [string, `Circle` or `Rect` ].
 106     * Either `size` [array of 1 or 2 numbers] (for a square
 107       or rectangle) or `diam` [number] (for a circle).
 108
 109  * `itemname` [string].  Used when other parts of the game want to
 110    refer to this one.
 111
 112
 113 Piece Spec Types
 114 ````````````````
 115
 116 ``"Lib"``
 117 `````````
 118
 119 A single shape from a piece library.
 120
 121  * ``lib``: The library name.  [string, mandatory]
 122
 123  * ``item``: The item name within that library.  [string, mandatory]
 124
 125 Example::
 126
 127   [[pieces]]
 128   pos = [150,100]
 129   type = "Lib"
 130   lib = "edited"
 131   item = "chess-board"
 132   pinned = true
 133
 134
 135 ``"LibList"``
 136 `````````````
 137
 138 Multiple shapes from a piece library.  Cannot be used with the `count`
 139 universal parameter.
 140
 141  * ``lib``: The library name. [string, mandatory]
 142
 143  * ``items``: The item names. [array of strings, mandatory]
 144
 145  * ``prefix``, ``suffix``: Prepended and appended to each
 146    entry in ``items``.  Useful for abbreviating.  [strings]
 147
 148 Example::
 149
 150   [[pieces]]
 151   pos = [150, 84]
 152   type = "LibList"
 153   lib = "cards-oxymoron"
 154   prefix = "card-oxymoron-"
 155   suffix = "-s"
 156   items = [
 157       "2","3","4","5","6","7","8","9","T","J","Q","K","A",
 158       "2","3","4","5","6","7","8","9","T","J","Q","K","A",
 159       "2","3","4","5","6","7","8","9","T","J","Q","K","A",
 160   ]
 161   posd = [0, 0]
 162
 163
 164 ``"ChessClock"``
 165 ````````````````
 166
 167 A chess clock.  Additional parameters:
 168
 169  * ``time``: Initial time for each player. [number, in seconds;
 170    mandatory]
 171
 172  * ``per_move``: Time to add per moove.  [number, in seconds]
 173
 174 (These clock settings cannot be reconfigured via the game UI.)
 175
 176 Example::
 177
 178   [[pieces]]
 179   pos = [240, 100]
 180   type = "ChessClock"
 181   time = 900
 182   per_move = 30
 183
 184
 185 ``"PickupDeck"``
 186 ````````````````
 187
 188 A pickup or play deck.  This can occult the pieces (eg, cards) you put
 189 on it, shuffling them and hiding their identity.
 190
 191 Requires ``face`` and ``shape``.  Only ``shape.type="Rect"`` is supported.
 192
 193 Honours ``edges``, ``edge_width``.
 194
 195 Honours ``label``, displaying the number of of pieces in (on) this deck.
 196
 197 Example::
 198
 199   [[pieces]]
 200   pos = [136,115]
 201   type = "PickupDeck"
 202   faces = ["lightblue", "grey"]
 203   edges = ["black", "white"]
 204   label.colour = "black"
 205   label.place = "BottomLeftOutside"
 206   shape.type = "Rect"
 207   shape.xy = [25,30]
 208
 209
 210 `Hand`
 211 ``````
 212
 213 A player hand.  When active, arranges for only that player to be able
 214 tos see the contents.  The other players see the occulted view (eg,
 215 the backs of cards).
 216
 217 Requires ``colour`` and ``shape``.  Only ``shape.type="Rect"`` is
 218 supported.
 219
 220 Honours ``edge``, ``edge_width``.
 221
 222 Honours ``label``, displaying the player whose hand this is, when
 223 active.
 224
 225
 226 ``"PlayerLabel"``
 227 `````````````````
 228
 229 A simple label which can display a player name.
 230
 231 Requires ``colour`` and ``shape``.  Only ``shape.type="Rect"`` is supported.
 232
 233 Honours ``edge``, ``edge_width``.
 234
 235 Honours ``label``.
 236
 237
 238 ``"Rect"``
 239 ``````````
 240
 241 A plain rectangular piece.
 242
 243  * ``size``: Size and shape  [array of 1 or 2 numbers, mandatory]
 244
 245 Requires ``faces``.
 246
 247 Honours ``itemname``, ``edges`` and ``edge_width``.
 248
 249 Exammple::
 250
 251   [[pieces]]
 252   pos = [20, 85]
 253   type = "Rect"
 254   faces = ["yellow","#f4f"]
 255   posd = [10, 0]
 256   size = [7,7]
 257   count = 8
 258
 259
 260 ``"Disc"``
 261 ``````````
 262
 263 A plain circular piece.
 264
 265  * ``diam`` [number, mandatory].
 266
 267 Requires ``faces``.
 268
 269 Honours ``itemname``, ``edges`` and ``edge_width``.
 270
 271