docs: wip document bundles

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

diff --git a/docs/bundles.rst b/docs/bundles.rst
new file mode 100644 (file)
index 0000000..523da1f
--- /dev/null
+++ b/docs/bundles.rst
@@ -0,0 +1,86 @@
+Bundles - uploadable game materials
+===================================
+
+Otter supports uploading game materials (pieces, and game specs) to
+the server.  That way you can play games with pieces that you have
+designed yourself without having to share them publicly or get them
+incorporated into Otter itself.
+
+These **bundles** are per-game.  They are accessible to the players
+but not made public.  The usual way to use bundles is to specify them
+on the `otter reset` command:
+
+::
+
+  otter--game unix:myself:: reset stoat-fest stoaty-games.zip
+             /^^^^^^^~~~~~~      /~~~~~~~~~' `~~~~~~~~~~~~~~~\
+    game (instance) name     game spec name       bundle file'
+
+The zipfile will be uploaded the server, and then Otter will look for
+the game spec ``stoat-fest`` amongst its builtin games and also in the
+zipfile.  Probably, ``stoat-fest`` is ``specs/stoat-fest.game.toml`` in
+the zipfile, and it will refer to piece elements also found there.
+
+Bundle format
+-------------
+
+Bundles are zipfiles.  They contain:
+
+ * ``otter.toml`` at the toplevel, with some basic metadata.
+   Mandatory.
+
+ * ``specs/``game``.game.toml``:  Description of what a particular
+   game looks like: what shape and colour the table is, what pieces
+   the game contains (at least initially), and where they start.
+
+ * ``library/``lib``.toml``: Description of a piece shape library.
+   See _`Shape libraries`_.
+
+These files are all in TOML format.  TOML an INI-file-like format
+designed for human editing and flexibility.  See the
+_`TOML documentation` for information about the syntax.
+
+_`TOML documentation` = https://toml.io/en/
+
+Case-sensitivity
+````````````````
+
+All filenames in bundles are treated case-insensitively (according to
+Unicode).  So a bundle cannot have game specs which differ ony in the
+case of their name; nor can it have piece image files which differ
+only in the case of their name.
+
+Note, however, that library item names, TOML config file keys, and,
+indeed everything else *except* filenames within the zipfiles, are
+case-sensitive.
+
+``otter.toml`` bundle top-level metadata
+----------------------------------------
+
+The top-level ``otter.toml`` contains a single key ``title``, which
+should be a string.  This is useful because the zipfile's name is not
+stored in the server.
+
+Bundle management
+-----------------
+
+Each game on the server can contain multiple bundles.  They are
+ordered and numbered, in order of upload.
+
+When Otter needs to look for a game spec or a piece, the bundles are
+searched in reverse order: from most recent, to leasy recent.  So a
+game might contain elements from multiple bundles.
+
+Usually, the right approach is to pass all the needed bundle filenames
+to ``otter reset``.  The right set of bundles will automatically be
+uploaded as necessary.
+
+When a library piece is added to a game, its appearance is fixed.  You
+cannot retrospectively update existing pieces.  You can only delete
+them and replace them with a new versions (perhaps as part of ``otter
+reset``).
+
+It is not possible to delete or replace individual bundles, only to
+clear out all the bundles of an empty game.  When developing a bundle,
+new versions can be uploaded to the server by hand with ``otter
+upload-bundle`` and their contents will be found first.

diff --git a/docs/index.rst b/docs/index.rst
index ccb8b1bda33bab4563fc3ec93098ff35d4d1d161..14b812c8845e7b3267624fcb34c0c99f6c3018c7 100644 (file)
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -13,6 +13,7 @@ Otter - Online Table Top Environment Renderer
    README
    user
    advanced
+   bundles
    build
    install
    dev