docs: wip document shapelibs, move from shapelib-toml

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

diff --git a/docs/shapelibs.rst b/docs/shapelibs.rst
index e20bfe546040511c74a73e540c5d4bb3f1d4f356..581ce95a283489cdea420b2bfafaf0c99cbd88b6 100644 (file)
--- a/docs/shapelibs.rst
+++ b/docs/shapelibs.rst
@@ -240,3 +240,29 @@ Parameters
    exaclty once; it will be replaced with the description calculated
    according to the other rules.  (``_desc`` substitution happens
    after ``_colour`` substitution.)
+
+ * ``occulted`` [table, contents depend on ``occulted.method``].  If
+   specified, these pieces be occulted.  For example, when a player
+   has them in their hand and the hand is active and owned by them,
+   only the occulted view (eg, the back of a playing card) will be
+   shown.  This a table whose other contents depend on its key
+   ``method``, which must be a string:
+
+  * ``"ByColour"``: Occult by displaying a particular recolouring of
+    this piece.  The sub-key ``colour`` names a recolouring - one of
+    the keys of the ``colours`` group parameter.  When the piece is
+    occulted it will show that colour, instead of its actual colour.
+    In the description, ``_colour`` will be elided rather than
+    substitued (along with up to one of any spaces either side of it).
+
+  * ``"ByBack"``: Occult by displaying the back of this piece, as
+    specified by the ``back`` group parameter.  The ``occulted`` table
+    must also contain a sub-entry ``ilk``, a string.  Pieces which
+    have the same ``ilk`` display identically when occulted, even if
+    the different piece definitions imply different backs.  (Whichever
+    pieces are first loaded define what the backs of a particular ilk
+    look.)
+
+    For pieces that are like cards, the ilk should be different for
+    cards which have different backs in the game.  Generally, standard
+    playing cards should all specify ``card-back``.

diff --git a/src/shapelib-toml.rs b/src/shapelib-toml.rs
index b05f43eba424ec1132f5ccc1d163d2a5f6cd1609..bd8e502c31315acfb15820ddef044c25f669a907 100644 (file)
--- a/src/shapelib-toml.rs
+++ b/src/shapelib-toml.rs
@@ -29,8 +29,6 @@ pub struct GroupDetails {
   #[serde(default="num_traits::identities::One::one")] pub scale: f64,
   #[serde(default)] pub colours: HashMap<String, RecolourData>,
   pub desc_template: Option<String>,
-
-  /// If specified, pieces in this group can be occulted.
   pub occulted: Option<OccultationMethod>,
 
   /// One of `"Circle"` or `"Rect"`, to define the outline shape.
@@ -41,16 +39,9 @@ pub struct GroupDetails {
   #[serde(flatten)] pub outline: Box<dyn shapelib::OutlineDefn>,
 }
 
-/// How pieces may be occulted.  Currently only one supported way.
 #[derive(Deserialize,Clone,Debug)]
 #[serde(tag="method")]
 pub enum OccultationMethod {
-  /// When occulted, display as a piece of a particular colour.
-  /// `colour` refers to one of the entries in
-  /// `GroupDetails::colours`.
-  ///
-  /// The description will be different too: `_colour` will be elided,
-  /// along with up to one of any spaces either side of it.
   ByColour {
     colour: ColourSpec,
   },