From: Ian Jackson Date: Sun, 23 May 2021 13:54:37 +0000 (+0100) Subject: docs: piece specs wip X-Git-Tag: otter-0.6.0~19 X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=commitdiff_plain;h=4a2b25d26084eb2a979a7887fdb07d070db8495d;p=otter.git docs: piece specs wip Signed-off-by: Ian Jackson --- diff --git a/docs/gamespec.rst b/docs/gamespec.rst index 8271867c..495d7715 100644 --- a/docs/gamespec.rst +++ b/docs/gamespec.rst @@ -37,85 +37,174 @@ 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. +rest of the table is interpreted. It is one of the `Piece Spec +Types`_. -Umiversal parameters +Universal parameters ```````````````````` +These apply regardless of the value of ``type``. + * ``type``: Piece type or piece spec type. One of the types listed - in the sections below. [string, enum, mandatory] + in `Piece Spec Types`_. [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. + * ``count``: Place multiple identical copies of this piece. [number] - * `posd` [2-element array]. Position delta. When a spec - specifies multiple pieces, each successive piece will be shifted by - this amount. Default: `[5,5]`. + * ``posd``: Position delta. When a spec specifies multiple pieces, + each successive piece will be shifted by this amount. [2-element + array, 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. + * ``face``: Initial face to show (ie, "which way up" the piece + starts). The default face is ``0``. For most pieces that is the + front, and is usually a good choice. [number] - * `pinned` [boolean]. Whether the piece is pinned to the table. - (Players can pin and unpin pieces during the game; this is the - initial state.) + * ``pinned``: Whether the piece is pinned to the table. Players can + pin and unpin pieces during the game; this is the initial state. + [boolean] - * `angle` [number 0..7]. Initial rotation of the piece. The + * ``angle``: Initial orientation of the piece. The specified value is multiplied by 45 degrees, increasing values - rotating anticlockwise. + rotating anticlockwise. So for example ``6`` would mean to rotate + 90 degrees clockwise. [integer 0..7] + + +Common parameters +````````````````` + +Depending on the ``type``, some of these parameters will be honoured. +This is discussed in the descriptions for each piece spec type. + + * `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. + + +Piece Spec Types +```````````````` ``"Lib"`` ````````` A single shape from a piece library. - * `lib` [string, mandatory]: The library name. + * ``lib``: The library name. [string, mandatory] - * `item` [string, mandatory]: The item name within that library. + * ``item``: The item name within that library. [string, mandatory] +Example:: -`LibList` -````````` + [[pieces]] + pos = [150,100] + type = "Lib" + lib = "edited" + item = "chess-board" + pinned = true + + +``"LibList"`` +````````````` Multiple shapes from a piece library. Cannot be used with the `count` universal parameter. - * `lib` [string, mandatory]: The library name. + * ``lib``: The library name. [string, mandatory] - * `items` [array of strings, mandatory]: The item names. + * ``items``: The item names. [array of strings, mandatory] - * `prefix`, `suffix` [strings]: Prepended and appended to each - entry in `items`. Useful for abbreviating. + * ``prefix``, ``suffix``: Prepended and appended to each + entry in ``items``. Useful for abbreviating. [strings] +Example:: -`ChessClock` -```````````` + [[pieces]] + pos = [150, 84] + type = "LibList" + lib = "cards-oxymoron" + prefix = "card-oxymoron-" + suffix = "-s" + items = [ + "2","3","4","5","6","7","8","9","T","J","Q","K","A", + "2","3","4","5","6","7","8","9","T","J","Q","K","A", + "2","3","4","5","6","7","8","9","T","J","Q","K","A", + ] + posd = [0, 0] + + +``"ChessClock"`` +```````````````` A chess clock. Additional parameters: - * `time` [number, in seconds; mandatory]. Initial time for each - player. + * ``time``: Initial time for each player. [number, in seconds; + mandatory] + + * ``per_move``: Time to add per moove. [number, in seconds] - * `per_move` [number, in seconds]. Time to add per moove. +(These clock settings cannot be reconfigured via the game UI.) -(The clock settings cannot be reconfigured via the game UI.) +Example:: + [[pieces]] + pos = [240, 100] + type = "ChessClock" + time = 900 + per_move = 30 -`PickupDeck` -```````````` + +``"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. +Requires ``face`` and ``shape``. Only ``shape.type="Rect"`` is supported. + +Honours ``edges``, ``edge_width``. -Honours `edges`, `edge_width`. +Honours ``label``, displaying the number of of pieces in (on) this deck. -Honours `label`, displaying the number of of pieces in (on) this deck. +Example:: + + [[pieces]] + pos = [136,115] + type = "PickupDeck" + faces = ["lightblue", "grey"] + edges = ["black", "white"] + label.colour = "black" + label.place = "BottomLeftOutside" + shape.type = "Rect" + shape.xy = [25,30] `Hand` @@ -125,80 +214,58 @@ 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. +Requires ``colour`` and ``shape``. Only ``shape.type="Rect"`` is +supported. -Honours `edge`, `edge_width`. +Honours ``edge``, ``edge_width``. -Honours `label`, displaying the player whose hand this is, when +Honours ``label``, displaying the player whose hand this is, when active. -`PlayerLabel` -````````````` +``"PlayerLabel"`` +````````````````` A simple label which can display a player name. -Requires `colour` and `shape`. Only `shape.type="Rect"` is supported. +Requires ``colour`` and ``shape``. Only ``shape.type="Rect"`` is supported. -Honours `edge`, `edge_width`. +Honours ``edge``, ``edge_width``. -Honours `label`. +Honours ``label``. -`Rect` -`````` +``"Rect"`` +`````````` A plain rectangular piece. - * `size` [array of 1 or 2 numbers]: Size and shape. + * ``size``: Size and shape [array of 1 or 2 numbers, mandatory] -Requires `faces`. +Requires ``faces``. -Honours `itemname`, `edges` and `edge_width`. +Honours ``itemname``, ``edges`` and ``edge_width``. +Exammple:: -`Disc` -`````` - -A plain circular piece. + [[pieces]] + pos = [20, 85] + type = "Rect" + faces = ["yellow","#f4f"] + posd = [10, 0] + size = [7,7] + count = 8 - * `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. +``"Disc"`` +`````````` - * `edge` [string, colour]. The edge colour to draw for a piece with - supports only one face. Default is not to draw edges. +A plain circular piece. - * `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). + * ``diam`` [number, mandatory]. - * `edge_width` [number]. Default is 0.2 if `edge` or `edges` is - specified. +Requires ``faces``. - * `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`. +Honours ``itemname``, ``edges`` and ``edge_width``. - * `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.