-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.
-JOINING 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.
-In the simplest case:
- otter join-game unix:<user>::<game-name>
-e.g.
- otter join-game unix:ijackson::test
+ * 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.
-See otter --help for further options, including setting your nick.
+ * House rules are no problem, since the computer isn't enforcing the
+ rules - you and your friends are.
-Currently when a new player joins a game (with the `otter` command),
-all the other players must reload the page.
+ * 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.)
+We have played successful and fun online games of both Penultima and
+Mao with Otter.
-CREATING A GAME
-===============
-otter reset --reset-table local-users :test demo
- /^^^^^^^^^^^ ^^^\ ^^^^'~ game spec
- `table spec game name
+Playing a game with Otter
+-------------------------
-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.
+The Otter game environment is accessed from a web browser running
+JavaScript, using a magic https link obtained from joining the game.
-":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.
+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.
-"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.
+Most relatively modern desktop browsers should be able to work with Otter.
+(The most advanced feature needed is support for WebAssembly.)
-See otter --help for some more options.
-Currently, resetting a game (or otherwise adding or removing pieces)
-will mean all the players will get errors until they reload the page.
+Predefined games and pieces currently available
+-----------------------------------------------
+Otter currently has, in its pieces library:
-MAKING YOUR OWN GAME
-====================
+ * Ingredients for chess, including fairy chess. So there's a board,
+ pieces, including many fairy chess pieces, and a chess clock.
-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.
+ * 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.
-todo: use rustdoc to provide this somewhere.
+Currently there are game definitions for:
-Adding shapes
--------------
+ * Penultima. This can be used directly to play standard chess and
+ some fairy chess variants.
-Otter uses SVGs. The sources for the SVGs are all in the otter source
-tree, in the library/ directory.
+ * Mao. This can be used to play any game of roughly that shape.
-Some of these SVGs were scraped from Wikimedia. The scraper machinery
-can perhaps be adapted to scrape SVGs from elsewhere.
+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 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.
-Contributions should be via git branch, eg a merge request on Salsa:
- https://salsa.debian.org/iwj/otter
+Limitations
+-----------
+Currently, joining a game requires a unix shell account on the server
+host (or help from a shell account user).
+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.
-BUILDING AND TESTING
-====================
+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.
-These instructions have been tested on Debian buster.
+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.
-Setup
------
-You will need about 6Gby of disk space.
+Free software, and user freedom
+-------------------------------
-1.
- sudo apt install build-essential git curl pkg-config libssl-dev node-typescript
+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 `:-)`.
-2. Install Rust. This is most easily done with rustup:
+I would love contributions, particularly to address the limitations I
+mention above, and to improve the user experience.
- curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+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.
-and then follow the instructions about your PATH. If this rune alarms
-you, see below about Rust privsep.
+The Otter software project is hosted on Debian's GitLab, at
+<https://salsa.debian.org/iwj/otter>.
-3. Switch your Rust install to use Rust Nightly and add the WASM
-target:
+Merge requests (accompanied by a `Signed-off-by` indicating sign-off
+of the Developer Certificate of Origin) would be very welcome.
- rustup default nightly
- rustup target add wasm32-unknown-unknown
-4. Install some build tools:
+References
+----------
- cargo install usvg
- cargo install bundle-sources
-
-This will put them in ~/.cargo/bin, which the rustup curl rune above
-will have arranged to put on your PATH.
-
-5. Install the version of wasm-pack with the option I need, which
-upstream haven't taken (or refused) the MR for:
-
- git clone https://github.com/ijackson/wasm-pack.git -b cargo-opts
- cd wasm-pack
- cargo install
-
-NB that wasm-pack will itself download and install more stuff when it
-is run by the otter Makefile.
-
-
-Build
------
-
- git clone https://salsa.debian.org/iwj/otter
- cd otter
- make -j8
-
-
-
-
-
-You will want to start with the git branch
-
-
-You must use "make" to build the whole thing, although you can run
-"cargo build" to build the
-
-You cannot build it just with `cargo`, you must use `make`.
-
-You will also need various other utilities and dependencies. See
-below. 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. See the code in `Makefile`.
-
-Dependencies
-------------
-
- * Rust Nightly (sorry)
-
- * `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.
-
- * `tsc`, Microsoft's Typescript compiler. The version in Debian
- buster will do.
-
- * `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.
-
- * `bundle-rust-sources`, an un-released Rust package for publishing
- source code of Rust projects.
-
-Weirdnesses:
-
- * 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:
-
-```
-[target.x86_64-unknown-linux-musl]
-rustflags = ["-C", "target-feature=+crt-static"]
-# ^ from https://stackoverflow.com/questions/31770604/how-to-generate-statically-linked-executables
-```
+ * [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)
~ianmdlvl / otter.git / blobdiff