-OTTER - ONLINE TABLE TOP ENVIRONMENT RENDERER
-=============================================
+Introduction
+============
-Otter is an online "table simulator" intended to be suitable for board
-games and similar.
+Otter, the Online Table Top Environment Renderer, is an online game
+system.
-It is accessed from a web browser running JavaScript. The server runs
-on a convenationl Unix host. Currently, joining a game requires a
-unix shell account on the server.
+But it is not like most online game systems. It does not know (nor
+does it need to know) the rules of the game you are playing. Instead,
+it lets you and your friends play with common tabletop/boardgame
+elements such as hands of cards, boards, and so on.
-The game does not have a built-in text chat system, nor any other
-communication other than via moving the game pieces. I expect it to
-be used with a concurrent voice chat, or perhaps a concurrent text
-chat program. Right now the arrangements for the chat must be agreed
-by the players without help from the Otter server.
+So it's something like a "tabletop simulator" (but it does not have
+any 3D, or a physics engine, or anything like that).
-Right now Otter is in an alpha state.
+This means that with Otter:
+ * Supporting a new game, that Otter doesn't know about yet, would
+ usually not involve writing or modifying any computer programs.
-CREATING A GAME
-===============
+ * If Otter already has the necessary game elements (cards, say) all
+ you need to do is write a spec file saying what should be on the
+ table at the start of the game. For example, most Whist variants
+ that start with a standard pack of 52 cards are already playable.
-otter reset --reset-table local-users :test demo
- /^^^^^^^^^^^ ^^^\ ^^^^'~ game spec
- `table spec game name
+ * You can play games where the rules change as the game goes along,
+ or are made up by the players, or are too complicated to write as a
+ computer program.
-Here "local-users" refers to the file "local-users.table.spec" in the
-Otter specs directory (/volatile/Otter/specs on chiark). The table
-spec file handles access control (and some other global properties)
-This particular file says that all local shell account users may join
-the game.
+ * House rules are no problem, since the computer isn't enforcing the
+ rules - you and your friends are.
-":test" is the game name. It starts with a colon, which means
-implicitly "unix:<whoami>::test". Other people have to name the game
-with the full name, with all three colons in it.
+ * Everyone can interact with different items on the game table, at
+ any time. (Otter doesn't know about your game's turn-taking, so
+ doesn't know whose turn it might be.)
-"demo" refers to the file "demo.game.spec". The "game spec" says what
-shape table is and what pieces there are. This is a simple demo game.
-There is also "penultima" which is a work-in-progress set of pieces
-suitable for fairy chess etc.
+We have played successful and fun online games of both Penultima and
+Mao with Otter.
-See otter --help for some more options.
+Playing a game with Otter
+-------------------------
-MAKING YOUR OWN GAME
-====================
+The Otter game environment is accessed from a web browser running
+JavaScript, using a magic https link obtained from joining the game.
-If you want to use existing piece shapes that Otter already knows
-about, you can do this by providing a game.spec.toml file. The format
-of these files is a TOML document representing a GameSpec as found in
-src/spec.rs in the Otter source code.
+You will need to be able to talk to your friends about the game, while
+you play. Otter works well when used together with a voice chat - we
+have had success with Jitsi in voice-only mode.
-todo: use rustdoc to provide this somewhere.
+Most relatively modern desktop browsers should be able to work with Otter.
+(The most advanced feature needed is support for WebAssembly.)
-Adding shapes
--------------
-Otter uses SVGs. The sources for the SVGs are all in the otter source
-tree, in the library/ directory.
+Predefined games and pieces currently available
+-----------------------------------------------
-Some of these SVGs were scraped from Wikimedia. The scraper machinery
-can perhaps be adapted to scrape SVGs from elsewhere.
+Otter currently has, in its pieces library:
-You can also add your own SVGs in the library/edited/ directory.
-If you do that, please make sure to include the actual source code.
-If you copied or adapted an SVG from somewhere, provide details.
+ * Ingredients for chess, including fairy chess. So there's a board,
+ pieces, including many fairy chess pieces, and a chess clock.
-Contributions should be via git branch, eg a merge request on Salsa:
- https://salsa.debian.org/iwj/otter
+ * Ingredients for card games. So, a deck of 52 standard playing
+ cards, plus two kinds of joker. Special "hand" and "deck" pieces
+ for player hands and a pickup deck.
+Currently there are game definitions for:
+ * Penultima. This can be used directly to play standard chess and
+ some fairy chess variants.
-BUILDING
-========
+ * Mao. This can be used to play any game of roughly that shape.
-Otter is not so easy to build. You will want to start with the git
-branch
- https://salsa.debian.org/iwj/otter
+Defining new games using the existing pieces from the library is
+fairly easy. It is also possible to add elements from the library
+ad-hoc, even while a game is in progress.
-You cannot build it just with `cargo`, you must use `make`.
-You will also need various other utilities and dependencies - in some
-cases, un-released dependencies or locally patched versions. See
-`Cargo.nail` and `Makefile`. On my own laptop deployment is done with
-`make deploy` which copies all the relevant sources into the
-`bundled-sources` directory, which is accessible via the Otter web UI.
+Limitations
+-----------
-Dependencies
-------------
+Currently, joining a game requires a unix shell account on the server
+host (or help from a shell account user).
- * Rust Nightly (sorry)
+There is not currently a publicly available server. The server code
+is Free Software and if you have a suitable vm or server you are
+encouraged to build and run it yourself, for you and your friends.
- * `cargo` and a willingness to let it download all the dependencies
- and run them, from crates.io. You can use my `Cargo.lock.example`
- if you like. I use a privsep scheme to avoid running stuff from
- cargo in my main account on my laptop. Using the not properly
- released `nailing-cargo` program.
+Mobile phones are not really suitable for playing on Otter because
+their screens are too small. Tablets and other touchscreen based
+systems could be made to work, but don't work well right now.
- * `tsc`, Microsoft's Typescript compiler. The version in Debian
- buster will do.
+Otter does not currently have even a built-in text chat facility. It
+does have a way to share a URL for a voice chat.
- * `wasm-pack`, a program for manipulating WebAssembly files. This
- too likes to run cargo and do god knows what.
- * `resvg`, a program for manipulating SVG files.
+Free software, and user freedom
+-------------------------------
- * `bundle-rust-sources`, an un-released Rust package for publishing
- source code of Rust projects.
+Otter is Free Software. I wrote it to liberate game players from the
+need to encode their game rules as computer programs and thus from the
+tyranny of programmers `:-)`.
-Weirdnesses:
+I would love contributions, particularly to address the limitations I
+mention above, and to improve the user experience.
- * `Cargo.nail` contains a list of sibling directories of my Otter
- source tree, which on my machine is called `server`. For several
- of these I sent patches upstream which have generally been
- accepted, but I need to tidy this up to switch to the upstream
- version.
+I am also working to make it possible to let users define their own
+games (including their own pieces, cards, boards, and so on) without
+having to install them on the server.
- * The Rocket dependency in `Cargo.toml` is completely mad due
- to Cargo being awful. I am hoping I can switch to an upstream
- Rocket now.
+The Otter software project is hosted on Debian's GitLab, at
+<https://salsa.debian.org/iwj/otter>.
- * For running on chiark I build with the Rust target
- `x86_64-unknown-linux-musl` which on my system is configured to
- produce a completely statically linked bionary:
+Merge requests (accompanied by a `Signed-off-by` indicating sign-off
+of the Developer Certificate of Origin) would be very welcome.
-```
-[target.x86_64-unknown-linux-musl]
-rustflags = ["-C", "target-feature=+crt-static"]
-# ^ from https://stackoverflow.com/questions/31770604/how-to-generate-statically-linked-executables
-```
+
+References
+----------
+
+ * [Source repository on Salsa, Debian's GitLab](https://salsa.debian.org/iwj/otter)
+ * [This documentation, online copy](https://www.chiark.greenend.org.uk/~ianmdlvl/otter/docs/)
+ * Mailing lists for [annoucements](https://www.chiark.greenend.org.uk/mailman/listinfo/sgo-software-announce) and [discussion](https://www.chiark.greenend.org.uk/mailman/listinfo/sgo-software-discuss)