From: Ian Jackson Date: Sat, 22 May 2021 23:10:11 +0000 (+0100) Subject: docs: wip document bundles X-Git-Tag: otter-0.6.0~49 X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=commitdiff_plain;h=3e114fbf9ba34af4c9212f25f63637b068713f90;p=otter.git docs: wip document bundles Signed-off-by: Ian Jackson --- diff --git a/docs/bundles.rst b/docs/bundles.rst new file mode 100644 index 00000000..523da1f4 --- /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 ccb8b1bd..14b812c8 100644 --- 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