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 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
 141
 142
 143
 144
 145
 146 You will want to start with the git branch
 147
 148
 149 You must use "make" to build the whole thing, although you can run
 150 "cargo build" to build the
 151
 152 You cannot build it just with `cargo`, you must use `make`.
 153
 154 You will also need various other utilities and dependencies.  See
 155 below.  On my own laptop deployment is done with `make deploy` which
 156 copies all the relevant sources into the `bundled-sources` directory,
 157 which is accessible via the Otter web UI.  See the code in `Makefile`.
 158
 159 Dependencies
 160 ------------
 161
 162  * Rust Nightly (sorry)
 163
 164  * `cargo` and a willingness to let it download all the dependencies
 165    and run them, from crates.io.  You can use my `Cargo.lock.example`
 166    if you like.  I use a privsep scheme to avoid running stuff from
 167    cargo in my main account on my laptop.  Using the not properly
 168    released `nailing-cargo` program.
 169
 170  * `tsc`, Microsoft's Typescript compiler.  The version in Debian
 171    buster will do.
 172
 173  * `wasm-pack`, a program for manipulating WebAssembly files.  This
 174    too likes to run cargo and do god knows what.
 175
 176  * `resvg`, a program for manipulating SVG files.
 177
 178  * `bundle-rust-sources`, an un-released Rust package for publishing
 179    source code of Rust projects.
 180
 181 Weirdnesses:
 182
 183  * For running on chiark I build with the Rust target
 184    `x86_64-unknown-linux-musl` which on my system is configured to
 185    produce a completely statically linked bionary:
 186
 187 ```
 188 [target.x86_64-unknown-linux-musl]
 189 rustflags = ["-C", "target-feature=+crt-static"]
 190 # ^ from https://stackoverflow.com/questions/31770604/how-to-generate-statically-linked-executables
 191 ```