it lets you and your friends play with common tabletop/boardgame
elements such as hands of cards, boards, and so on.
-So it's something like a "tabletop simulater" (but it does not have
+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:
* If Otter already has the necessarily 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 playble.
+ that start with a standard pack of 52 cards are already playable.
* 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
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 you define your own games
-(including your own pieces, cards, boards, and so on) without having
-to install them on the server.
+I am also working to make it possible to let users define their own
+games (including thier 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
+<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.
If you want to use existing piece shapes that Otter already knows
about, you can do this by providing a `<something>.game.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.
+as found in `src/spec.rs` in the Otter source code. Unfortunately
+this is not yet documented.
Adding shapes (pieces, cards, etc.)
`templates/shapelib.html`. As above, this make rune will print the
`file://` url for you.
-See BUILDING AND TESTING for information about how to install the
+See the build instructions for information about how to install the
tools you will need.
Some of these SVGs were scraped from Wikimedia. The scraper machinery
can perhaps be adapted to scrape SVGs from elsewhere.
-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.
+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 there
+too. If you copied or adapted an SVG from somewhere, note the details
+of where you got it (eg, in a git commit message).
Contributions should be via git branch, eg a merge request on Salsa:
[https://salsa.debian.org/iwj/otter](https://salsa.debian.org/iwj/otter)
Typescript. The shape libraries are SVGs and need SVG manipulation
libraries. The main documentation is done with Sphinx.
+You will need at least 6000 megabytes of disk space, or more, and a
+good internet connection. Your computer will be compiling a lot of
+code.
+
+These instructions were once tested on Debian buster.
+
Setup
-----
-BUILDING AND TESTING OTTER
-==========================
+Developing
+==========
Otter is mostly written in Rust.
The web UI frontend is written in Typescript, with a small amount of
Rust support code delivered via WebAssembly.
+The HTML and SVG skeleton is in a templating language called Tera,
+which is a jinja-like but from the Rust community.
-You will need at least 6000 megabytes of disk space, or more, and a
-good internet connection. Your computer will be compiling a lot of
-code.
-These instructions have been tested on Debian buster.
-
-
-Ad-hoc tests
-------------
+Ad-hoc testing, playing about, etc.
+-----------------------------------
In one shell:
```
target/debug/daemon-otter tmp/wdt-simple/server-config.toml
```
-and then play with it at this url:
+and then play with it at these urls:
```
http://localhost:8000/?kmqAKPwK4TfReFjMor8MJhdRPBcwIBpe
+ http://localhost:8000/?ccg9kzoTh758QrVE1xMY7BQWB36dNJTx
```
-
-Final weirdness
----------------
-
- * The `Makefile` `deploy` target is very specific to my setup.
-
- * 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. I have this in my
- `~/.cargo/config` (in the lesser privsep account):
-
-```
-[target.x86_64-unknown-linux-musl]
-rustflags = ["-C", "target-feature=+crt-static"]
-# ^ from https://stackoverflow.com/questions/31770604/how-to-generate-statically-linked-executables
-```
+(Yes, those are a fixed game access links, hardcoded by the tests.
+You can bookmark them.)
user
advanced
build
+ install
dev
--- /dev/null
+Installing
+==========
+
+This is not very polished or well-documented yet.
+
+The `Makefile` has a `deploy` target which shows how things work on
+chiark.
+
+You will need to write a `server-config.toml`. There is not currently
+any documentation for that. But there are some examples. Consider
+looking at `server-test.toml` in the toplevel, or one of the config
+files made by the tests, in `tmp/*/server-config.toml`.
+
+The config is a TOML file, which is read using Rust Serde. You can
+get at least a list of fields by looking at the Rustdoc-generated "API
+doc" for the type `otter::config::ServerConfigSpec`, which is probably
+in `target/doc/otter/config/struct.ServerConfigSpec.html`.
+
+Here a copy of the config file from chiark. As you can see I am
+running Otter as an "application server". My usual Apache
+configuration handles the TLS. (Rocket's TLS is not advertised as
+being suitable for production use.)
+
+```
+http_port = 1323
+public_url = "https://otter.chiark.net"
+sse_wildcard_url = "https://*.sse.otter.chiark.net"
+
+base_dir = "/volatile/Otter"
+
+save_dir = "/home/Otter/save"
+command_socket = "/volatile/Otter/var/command.socket"
+
+[log]
+global_level = 'debug'
+
+[log.modules]
+'hyper::server' = 'info'
+rocket = 'error'
+_ = "error" # rocket
+"game::debugreader" = 'info'
+```
+
+The `*.sse` wildcard domain is to work around a bug in the web
+facility "server-sent events". You will probably want one of those
+too. The SSE bug is documented on MDN
+<https://developer.mozilla.org/en-US/docs/Web/API/EventSource>
+(as referenced by the docs for `rocket::response::Stream::chunked`
+which is the underlying facility used by Otter).
+
+
+Final weirdness
+---------------
+
+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 binary. I have this in my
+`~/.cargo/config` (in the lesser privsep account):
+
+```
+[target.x86_64-unknown-linux-musl]
+rustflags = ["-C", "target-feature=+crt-static"]
+# ^ from https://stackoverflow.com/questions/31770604/how-to-generate-statically-linked-executables
+```
Notable features you might otherwise overlook include these:
Pressuing "h" repeatedly cycles through various amounts of history
-view (the overliad yellow arrows showing what recently happened).
+view (the overlaid yellow arrows showing what recently happened).
Typing numbers will get you into a multiple selection mode, which you
can use (for example) to draw yourself a hand of multiple cards.
There is a Wresting mode for making exceptional changes to the game
state, such as forcibly grasping a piece out of another player's
-grasp. Don't forget to exit Wresting mode when you're finished with
-it.
+grasp, or moving the chessboard. Don't forget to exit Wresting mode
+when you're finished with it.
Bugs and errors
server side is not too badly affected.
If you can reproduce a bug, please file a bug report;
- https://salsa.debian.org/iwj/otter/-/issues/new
+<https://salsa.debian.org/iwj/otter/-/issues/new>.
Of course you might want to reload the Otter game page if you have
trouble with your network or web browser. The state is all on the
-server, so you can reload when you want to.
+server, so you can reload or reconnect whenever you like.
Game administration
~ianmdlvl / otter.git / commitdiff