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 e.g.
  26   otter join-game unix:ijackson::test
  27
  28 See otter --help for further options, including setting your nick.
  29
  30 Currently when a new player joins a game (with the `otter` command),
  31 all the other players must reload the page.
  32
  33
  34 CREATING A GAME
  35 ===============
  36
  37 otter reset --reset-table local-users :test demo
  38                          /^^^^^^^^^^^  ^^^\ ^^^^'~ game spec
  39                          `table spec       game name
  40
  41 Here "local-users" refers to the file "local-users.table.spec" in the
  42 Otter specs directory (/volatile/Otter/specs on chiark).  The table
  43 spec file handles access control (and some other global properties)
  44 This particular file says that all local shell account users may join
  45 the game.
  46
  47 ":test" is the game name.  It starts with a colon, which means
  48 implicitly "unix:<whoami>::test".  Other people have to name the game
  49 with the full name, with all three colons in it.
  50
  51 "demo" refers to the file "demo.game.spec".  The "game spec" says what
  52 shape table is and what pieces there are.  This is a simple demo game.
  53 There is also "penultima" which is a work-in-progress set of pieces
  54 suitable for fairy chess etc.
  55
  56 See otter --help for some more options.
  57
  58 Currently, resetting a game (or otherwise adding or removing pieces)
  59 will mean all the players will get errors until they reload the page.
  60
  61
  62 MAKING YOUR OWN GAME
  63 ====================
  64
  65 If you want to use existing piece shapes that Otter already knows
  66 about, you can do this by providing a game.spec.toml file.  The format
  67 of these files is a TOML document representing a GameSpec as found in
  68 src/spec.rs in the Otter source code.
  69
  70 todo: use rustdoc to provide this somewhere.
  71
  72 Adding shapes
  73 -------------
  74
  75 Otter uses SVGs.  The sources for the SVGs are all in the otter source
  76 tree, in the library/ directory.
  77
  78 Some of these SVGs were scraped from Wikimedia.  The scraper machinery
  79 can perhaps be adapted to scrape SVGs from elsewhere.
  80
  81 You can also add your own SVGs in the library/edited/ directory.
  82 If you do that, please make sure to include the actual source code.
  83 If you copied or adapted an SVG from somewhere, provide details.
  84
  85 Contributions should be via git branch, eg a merge request on Salsa:
  86   https://salsa.debian.org/iwj/otter
  87
  88
  89
  90 BUILDING AND TESTING
  91 ====================
  92
  93 These instructions have been tested on Debian buster.
  94
  95 Setup
  96 -----
  97
  98 You will need about 6Gby of disk space.
  99
 100 1.
 101    sudo apt install build-essential cpio git curl pkg-config libssl-dev node-typescript
 102
 103 2. Install Rust.  This is most easily done with rustup:
 104
 105    curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
 106
 107 and then follow the instructions about your PATH.  If this rune alarms
 108 you, see below about Rust privsep.
 109
 110 3. Switch your Rust install to use Rust Nightly and add the WASM
 111 target:
 112
 113    rustup default nightly
 114    rustup target add wasm32-unknown-unknown
 115
 116 4. Install some build tools:
 117
 118    cargo install usvg
 119    cargo install bundle-sources
 120
 121 This will put them in ~/.cargo/bin, which the rustup curl rune above
 122 will have arranged to put on your PATH.
 123
 124 5. Install the version of wasm-pack with the option I need, which
 125 upstream haven't taken (or refused) the MR for:
 126
 127   git clone https://github.com/ijackson/wasm-pack.git -b cargo-opts
 128   cd wasm-pack
 129   cargo install
 130
 131 NB that wasm-pack will itself download and install more stuff when it
 132 is run by the otter Makefile.
 133
 134
 135 Build
 136 -----
 137
 138   git clone https://salsa.debian.org/iwj/otter
 139   cd otter
 140   make -j8 all bundled-sources
 141
 142
 143 Test
 144 ----
 145
 146 In one shell:
 147
 148    target/debug/daemon-otter server-test.toml
 149
 150 The server does not daemonise, and the default config there makes it
 151 quite verboxe.  So, in another shell:
 152
 153    target/debug/otter --account server: --config server-test.toml --spec-dir=specs reset --reset-table test server::test demo
 154
 155    target/debug/otter --account server: --config server-test.toml --spec-dir=specs join-game server::test
 156
 157 The URL printed, something like:
 158
 159   http://localhost:18056/?KRRUu7FosWe4WxvcyMoTEsgjHJ8p4Qf17aKHUIcApEQj0ialrX2gJJsjvGRBRATz
 160
 161 can be visited in a local browser.
 162
 163
 164
 165
 166 Dependencies
 167 ------------
 168
 169  * Rust Nightly (sorry)
 170
 171  * `cargo` and a willingness to let it download all the dependencies
 172    and run them, from crates.io.  You can use my `Cargo.lock.example`
 173    if you like.  I use a privsep scheme to avoid running stuff from
 174    cargo in my main account on my laptop.  Using the not properly
 175    released `nailing-cargo` program.
 176
 177  * `tsc`, Microsoft's Typescript compiler.  The version in Debian
 178    buster will do.
 179
 180  * `wasm-pack`, a program for manipulating WebAssembly files.  This
 181    too likes to run cargo and do god knows what.
 182
 183  * `resvg`, a program for manipulating SVG files.
 184
 185  * `bundle-rust-sources`, an un-released Rust package for publishing
 186    source code of Rust projects.
 187
 188 Weirdnesses:
 189
 190  * For running on chiark I build with the Rust target
 191    `x86_64-unknown-linux-musl` which on my system is configured to
 192    produce a completely statically linked bionary:
 193
 194 ```
 195 [target.x86_64-unknown-linux-musl]
 196 rustflags = ["-C", "target-feature=+crt-static"]
 197 # ^ from https://stackoverflow.com/questions/31770604/how-to-generate-statically-linked-executables
 198 ```