README.md

   1 OTTER - ONLINE TABLE TOP ENVIRONMENT RENDERER
   2 =============================================
   3
   4 Otter is an online "table simulator" intended to be suitable for board
   5 games and similar.
   6
   7 It is accessed from a web browser running JavaScript.  The server runs
   8 on a convenationl Unix host.  Currently, joining a game requires a
   9 unix shell account on the server.
  10
  11 The game does not have a built-in text chat system, nor any other
  12 communication other than via moving the game pieces.  I expect it to
  13 be used with a concurrent voice chat, or perhaps a concurrent text
  14 chat program.  Right now the arrangements for the chat must be agreed
  15 by the players without help from the Otter server.
  16
  17 Right now Otter is in an alpha state.
  18
  19
  20 JOINING A GAME
  21 ==============
  22
  23 In the simplest case:
  24   otter join-game unix:<user>::<game-name>
  25
  26 See otter --help for further options, including setting your nick.
  27
  28 Currently when a new player joins a game (with the `otter` command),
  29 all the other players must restart.
  30
  31
  32 CREATING A GAME
  33 ===============
  34
  35 otter reset --reset-table local-users :test demo
  36                          /^^^^^^^^^^^  ^^^\ ^^^^'~ game spec
  37                          `table spec       game name
  38
  39 Here "local-users" refers to the file "local-users.table.spec" in the
  40 Otter specs directory (/volatile/Otter/specs on chiark).  The table
  41 spec file handles access control (and some other global properties)
  42 This particular file says that all local shell account users may join
  43 the game.
  44
  45 ":test" is the game name.  It starts with a colon, which means
  46 implicitly "unix:<whoami>::test".  Other people have to name the game
  47 with the full name, with all three colons in it.
  48
  49 "demo" refers to the file "demo.game.spec".  The "game spec" says what
  50 shape table is and what pieces there are.  This is a simple demo game.
  51 There is also "penultima" which is a work-in-progress set of pieces
  52 suitable for fairy chess etc.
  53
  54 See otter --help for some more options.
  55
  56
  57 MAKING YOUR OWN GAME
  58 ====================
  59
  60 If you want to use existing piece shapes that Otter already knows
  61 about, you can do this by providing a game.spec.toml file.  The format
  62 of these files is a TOML document representing a GameSpec as found in
  63 src/spec.rs in the Otter source code.
  64
  65 todo: use rustdoc to provide this somewhere.
  66
  67 Adding shapes
  68 -------------
  69
  70 Otter uses SVGs.  The sources for the SVGs are all in the otter source
  71 tree, in the library/ directory.
  72
  73 Some of these SVGs were scraped from Wikimedia.  The scraper machinery
  74 can perhaps be adapted to scrape SVGs from elsewhere.
  75
  76 You can also add your own SVGs in the library/edited/ directory.
  77 If you do that, please make sure to include the actual source code.
  78 If you copied or adapted an SVG from somewhere, provide details.
  79
  80 Contributions should be via git branch, eg a merge request on Salsa:
  81   https://salsa.debian.org/iwj/otter
  82
  83
  84
  85 BUILDING
  86 ========
  87
  88 Otter is not so easy to build.  You will want to start with the git
  89 branch
  90   https://salsa.debian.org/iwj/otter
  91
  92 You cannot build it just with `cargo`, you must use `make`.
  93
  94 You will also need various other utilities and dependencies.  See
  95 below.  On my own laptop deployment is done with `make deploy` which
  96 copies all the relevant sources into the `bundled-sources` directory,
  97 which is accessible via the Otter web UI.  See the code in `Makefile`.
  98
  99 Dependencies
 100 ------------
 101
 102  * Rust Nightly (sorry)
 103
 104  * `cargo` and a willingness to let it download all the dependencies
 105    and run them, from crates.io.  You can use my `Cargo.lock.example`
 106    if you like.  I use a privsep scheme to avoid running stuff from
 107    cargo in my main account on my laptop.  Using the not properly
 108    released `nailing-cargo` program.
 109
 110  * `tsc`, Microsoft's Typescript compiler.  The version in Debian
 111    buster will do.
 112
 113  * `wasm-pack`, a program for manipulating WebAssembly files.  This
 114    too likes to run cargo and do god knows what.
 115
 116  * `resvg`, a program for manipulating SVG files.
 117
 118  * `bundle-rust-sources`, an un-released Rust package for publishing
 119    source code of Rust projects.
 120
 121 Weirdnesses:
 122
 123  * For running on chiark I build with the Rust target
 124    `x86_64-unknown-linux-musl` which on my system is configured to
 125    produce a completely statically linked bionary:
 126
 127 ```
 128 [target.x86_64-unknown-linux-musl]
 129 rustflags = ["-C", "target-feature=+crt-static"]
 130 # ^ from https://stackoverflow.com/questions/31770604/how-to-generate-statically-linked-executables
 131 ```