docs: piece specs wip

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

diff --git a/docs/gamespec.rst b/docs/gamespec.rst
index db657cbd2767be87cebfbebdacde7ea73922b5b4..8271867cf1f3468c23f041012651ba9651aa398e 100644 (file)
--- 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.