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 intesrpreted.
  41
  42 Umiversal parameters
  43 ````````````````````
  44
  45  * ``type``: Piece type or piece spec type.  One of the types listed
  46    in the sections below.  [string, enum, mandatory]
  47
  48  * ``pos``:Position, in game coordinates, of
  49    the centre of the piece.  The origin is at the top left.
  50    [2-element array, default ``[20,20]``]
  51
  52  * `count` [number, default=1].  Place multiple copies of this piece.
  53
  54  * `posd` [2-element array].  Position delta.  When a spec
  55    specifies multiple pieces, each successive piece will be shifted by
  56    this amount.  Default: `[5,5]`.
  57
  58  * `face` [number, default=0].  Initial face to show (ie, "which way
  59    up" the piece starts).  The default face for most pieces is the
  60    front, and this is usually a good choice.
  61
  62  * `pinned` [boolean].  Whether the piece is pinned to the table.
  63    (Players can pin and unpin pieces during the game; this is the
  64    initial state.)
  65
  66  * `angle` [number 0..7].  Initial rotation of the piece.  The
  67    specified value is multiplied by 45 degrees, increasing values
  68    rotating anticlockwise.
  69
  70
  71 ``"Lib"``
  72 `````````
  73
  74 A single shape from a piece library.
  75
  76  * `lib` [string, mandatory]: The library name.
  77
  78  * `item` [string, mandatory]: The item name within that library.
  79
  80
  81 `LibList`
  82 `````````
  83
  84 Multiple shapes from a piece library.  Cannot be used with the `count`
  85 universal parameter.
  86
  87  * `lib` [string, mandatory]: The library name.
  88
  89  * `items` [array of strings, mandatory]: The item names.
  90
  91  * `prefix`, `suffix` [strings]: Prepended and appended to each
  92    entry in `items`.  Useful for abbreviating.
  93
  94
  95 `ChessClock`
  96 ````````````
  97
  98 A chess clock.  Additional parameters:
  99
 100  * `time` [number, in seconds; mandatory].  Initial time for each
 101    player.
 102
 103  * `per_move` [number, in seconds].  Time to add per moove.
 104
 105 (The clock settings cannot be reconfigured via the game UI.)
 106
 107
 108 `PickupDeck`
 109 ````````````
 110
 111 A pickup or play deck.  This can occult the pieces (eg, cards) you put
 112 on it, shuffling them and hiding their identity.
 113
 114 Requires `face` and `shape`.  Only `shape.type="Rect"` is supported.
 115
 116 Honours `edges`, `edge_width`.
 117
 118 Honours `label`, displaying the number of of pieces in (on) this deck.
 119
 120
 121 `Hand`
 122 ``````
 123
 124 A player hand.  When active, arranges for only that player to be able
 125 tos see the contents.  The other players see the occulted view (eg,
 126 the backs of cards).
 127
 128 Requires `colour` and `shape`.  Only `shape.type="Rect"` is supported.
 129
 130 Honours `edge`, `edge_width`.
 131
 132 Honours `label`, displaying the player whose hand this is, when
 133 active.
 134
 135
 136 `PlayerLabel`
 137 `````````````
 138
 139 A simple label which can display a player name.
 140
 141 Requires `colour` and `shape`.  Only `shape.type="Rect"` is supported.
 142
 143 Honours `edge`, `edge_width`.
 144
 145 Honours `label`.
 146
 147
 148 `Rect`
 149 ``````
 150
 151 A plain rectangular piece.
 152
 153  * `size` [array of 1 or 2 numbers]: Size and shape.
 154
 155 Requires `faces`.
 156
 157 Honours `itemname`, `edges` and `edge_width`.
 158
 159
 160 `Disc`
 161 ``````
 162
 163 A plain circular piece.
 164
 165  * `diam` [number, mandatory].
 166
 167 Requires `faces`.
 168
 169 Honours `itemname`, `edges` and `edge_width`.
 170
 171
 172 Common parameters
 173 `````````````````
 174
 175  * `colour` [string, colour].  The fill colour For a piece which
 176    supports only one face.
 177
 178  * `faces` [array of string(s), colours, mandatory].  The main fill
 179    colour.
 180
 181  * `edge` [string, colour].  The edge colour to draw for a piece with
 182    supports only one face.  Default is not to draw edges.
 183
 184  * `edges` [array of string(s), colours].  The colours of edges to
 185    draw.  Default is not to draw edges.  Must either be a 1-element
 186    array, or as long as `faces` (specifying a different edge colour
 187    for each face).
 188
 189  * `edge_width` [number].  Default is 0.2 if `edge` or `edges` is
 190    specified.
 191
 192  * `label` [table].  Displays a label with informationa about the
 193    in-game state.  There are two sub-keys:
 194     * `colour` [string, defaults to the edge colour].
 195     * `place` [string]: One of `BottomLeft` (default), `TopLeft`,
 196       `BottomLeftOutside`, `TopLeftOutside`.
 197
 198  * `shape` [table].  The shape of a piece.  There are two sub-keys:
 199     * `type`, [string, `Circle` or `Rect` ].
 200     * Either `size` [array of 1 or 2 numbers] (for a square
 201       or rectangle) or `diam` [number] (for a circle).
 202
 203  * `itemname` [string].  Used when other parts of the game want to
 204    refer to this one.