-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.
-Right now Otter is in an alpha state.
+So it's something like a "tabletop simulator" (but it does not have
+any 3D, or a physics engine, or anything like that).
+This means that with Otter:
-BUILDING
-========
+ * Supporting a new game, that Otter doesn't know about yet, would
+ usually not involve writing or modifying any computer programs.
-Otter is not so easy to build. You will want to start with the git
-branch
- https://salsa.debian.org/iwj/otter
+ * 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.
-You cannot build it just with `cargo`, you must use `make`.
+ * 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.
-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.
+ * House rules are no problem, since the computer isn't enforcing the
+ rules - you and your friends are.
-Dependencies
-------------
+ * 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.)
- * Rust Nightly (sorry)
+We have played successful and fun online games of both Penultima and
+Mao with Otter.
- * `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.
+Playing a game with Otter
+-------------------------
- * `wasm-pack`, a program for manipulating WebAssembly files. This
- too likes to run cargo and do god knows what.
+The Otter game environment is accessed from a web browser running
+JavaScript, using a magic https link obtained from joining the game.
- * `resvg`, a program for manipulating SVG files.
+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.
- * `bundle-rust-sources`, an un-released Rust package for publishing
- source code of Rust projects.
+Most relatively modern desktop browsers should be able to work with Otter.
+(The most advanced feature needed is support for WebAssembly.)
-Weirdnesses:
- * `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.
+Predefined games and pieces currently available
+-----------------------------------------------
- * 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.
+Otter currently has, in its pieces library:
- * 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:
+ * Ingredients for chess, including fairy chess. So there's a board,
+ pieces, including many fairy chess pieces, and a chess clock.
-```
-[target.x86_64-unknown-linux-musl]
-rustflags = ["-C", "target-feature=+crt-static"]
-# ^ from https://stackoverflow.com/questions/31770604/how-to-generate-statically-linked-executables
-```
+ * 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.
+
+ * Mao. This can be used to play any game of roughly that shape.
+
+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.
+
+
+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.
+
+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.
+
+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.
+
+
+Free software, and user freedom
+-------------------------------
+
+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 `:-)`.
+
+I would love contributions, particularly to address the limitations I
+mention above, and to improve the user experience.
+
+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 Otter software project is hosted on Debian's GitLab, at
+<https://salsa.debian.org/iwj/otter>.
+
+Merge requests (accompanied by a `Signed-off-by` indicating sign-off
+of the Developer Certificate of Origin) would be very welcome.
+
+
+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)
~ianmdlvl / otter.git / blobdiff