From: Ian Jackson Date: Sun, 23 May 2021 13:38:31 +0000 (+0100) Subject: docs: piece specs wip X-Git-Tag: otter-0.6.0~20 X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=commitdiff_plain;h=a8dafdf83056dfe67b546460dc98476efeaf1708;p=otter.git docs: piece specs wip Signed-off-by: Ian Jackson --- diff --git a/docs/gamespec.rst b/docs/gamespec.rst index db657cbd..8271867c 100644 --- a/docs/gamespec.rst +++ b/docs/gamespec.rst @@ -26,10 +26,179 @@ level: table. When a piece is being loaded, an alias xxxx grep for where referred to - * ``pieces``: Array of _`Piece spec`. Defines the initial pieces + * ``pieces``: Array of `Piece Specs`_. Defines the initial pieces and their layout. Each entry is a piece spec sub-table. Piece Specs ----------- -XXX todo +A piece spec is a table defining one or more pieces. When part of a +game spec, it appears as an entry in the top-level ``pieces`` array, +and defines the location(s) on the table to place the pieces, too. + +There is a mandatory key ``type``, a string. This determines how the +rest of the table is intesrpreted. + +Umiversal parameters +```````````````````` + + * ``type``: Piece type or piece spec type. One of the types listed + in the sections below. [string, enum, mandatory] + + * ``pos``:Position, in game coordinates, of + the centre of the piece. The origin is at the top left. + [2-element array, default ``[20,20]``] + + * `count` [number, default=1]. Place multiple copies of this piece. + + * `posd` [2-element array]. Position delta. When a spec + specifies multiple pieces, each successive piece will be shifted by + this amount. Default: `[5,5]`. + + * `face` [number, default=0]. Initial face to show (ie, "which way + up" the piece starts). The default face for most pieces is the + front, and this is usually a good choice. + + * `pinned` [boolean]. Whether the piece is pinned to the table. + (Players can pin and unpin pieces during the game; this is the + initial state.) + + * `angle` [number 0..7]. Initial rotation of the piece. The + specified value is multiplied by 45 degrees, increasing values + rotating anticlockwise. + + +``"Lib"`` +````````` + +A single shape from a piece library. + + * `lib` [string, mandatory]: The library name. + + * `item` [string, mandatory]: The item name within that library. + + +`LibList` +````````` + +Multiple shapes from a piece library. Cannot be used with the `count` +universal parameter. + + * `lib` [string, mandatory]: The library name. + + * `items` [array of strings, mandatory]: The item names. + + * `prefix`, `suffix` [strings]: Prepended and appended to each + entry in `items`. Useful for abbreviating. + + +`ChessClock` +```````````` + +A chess clock. Additional parameters: + + * `time` [number, in seconds; mandatory]. Initial time for each + player. + + * `per_move` [number, in seconds]. Time to add per moove. + +(The clock settings cannot be reconfigured via the game UI.) + + +`PickupDeck` +```````````` + +A pickup or play deck. This can occult the pieces (eg, cards) you put +on it, shuffling them and hiding their identity. + +Requires `face` and `shape`. Only `shape.type="Rect"` is supported. + +Honours `edges`, `edge_width`. + +Honours `label`, displaying the number of of pieces in (on) this deck. + + +`Hand` +`````` + +A player hand. When active, arranges for only that player to be able +tos see the contents. The other players see the occulted view (eg, +the backs of cards). + +Requires `colour` and `shape`. Only `shape.type="Rect"` is supported. + +Honours `edge`, `edge_width`. + +Honours `label`, displaying the player whose hand this is, when +active. + + +`PlayerLabel` +````````````` + +A simple label which can display a player name. + +Requires `colour` and `shape`. Only `shape.type="Rect"` is supported. + +Honours `edge`, `edge_width`. + +Honours `label`. + + +`Rect` +`````` + +A plain rectangular piece. + + * `size` [array of 1 or 2 numbers]: Size and shape. + +Requires `faces`. + +Honours `itemname`, `edges` and `edge_width`. + + +`Disc` +`````` + +A plain circular piece. + + * `diam` [number, mandatory]. + +Requires `faces`. + +Honours `itemname`, `edges` and `edge_width`. + + +Common parameters +````````````````` + + * `colour` [string, colour]. The fill colour For a piece which + supports only one face. + + * `faces` [array of string(s), colours, mandatory]. The main fill + colour. + + * `edge` [string, colour]. The edge colour to draw for a piece with + supports only one face. Default is not to draw edges. + + * `edges` [array of string(s), colours]. The colours of edges to + draw. Default is not to draw edges. Must either be a 1-element + array, or as long as `faces` (specifying a different edge colour + for each face). + + * `edge_width` [number]. Default is 0.2 if `edge` or `edges` is + specified. + + * `label` [table]. Displays a label with informationa about the + in-game state. There are two sub-keys: + * `colour` [string, defaults to the edge colour]. + * `place` [string]: One of `BottomLeft` (default), `TopLeft`, + `BottomLeftOutside`, `TopLeftOutside`. + + * `shape` [table]. The shape of a piece. There are two sub-keys: + * `type`, [string, `Circle` or `Rect` ]. + * Either `size` [array of 1 or 2 numbers] (for a square + or rectangle) or `diam` [number] (for a circle). + + * `itemname` [string]. Used when other parts of the game want to + refer to this one.