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 CREATING A GAME
  21 ===============
  22
  23 otter reset --reset-table local-users :test demo
  24                          /^^^^^^^^^^^  ^^^\ ^^^^'~ game spec
  25                          `table spec       game name
  26
  27 Here "local-users" refers to the file "local-users.table.spec" in the
  28 Otter specs directory (/volatile/Otter/specs on chiark).  The table
  29 spec file handles access control (and some other global properties)
  30 This particular file says that all local shell account users may join
  31 the game.
  32
  33 ":test" is the game name.  It starts with a colon, which means
  34 implicitly "unix:<whoami>::test".  Other people have to name the game
  35 with the full name, with all three colons in it.
  36
  37 "demo" refers to the file "demo.game.spec".  The "game spec" says what
  38 shape table is and what pieces there are.  This is a simple demo game.
  39 There is also "penultima" which is a work-in-progress set of pieces
  40 suitable for fairy chess etc.
  41
  42 See otter --help for some more options.
  43
  44
  45 MAKING YOUR OWN GAME
  46 ====================
  47
  48 If you want to use existing piece shapes that Otter already knows
  49 about, you can do this by providing a game.spec.toml file.  The format
  50 of these files is a TOML document representing a GameSpec as found in
  51 src/spec.rs in the Otter source code.
  52
  53 todo: use rustdoc to provide this somewhere.
  54
  55 Adding shapes
  56 -------------
  57
  58 Otter uses SVGs.  The sources for the SVGs are all in the otter source
  59 tree, in the library/ directory.
  60
  61 Some of these SVGs were scraped from Wikimedia.  The scraper machinery
  62 can perhaps be adapted to scrape SVGs from elsewhere.
  63
  64 You can also add your own SVGs in the library/edited/ directory.
  65 If you do that, please make sure to include the actual source code.
  66 If you copied or adapted an SVG from somewhere, provide details.
  67
  68 Contributions should be via git branch, eg a merge request on Salsa:
  69   https://salsa.debian.org/iwj/otter
  70
  71
  72
  73 BUILDING
  74 ========
  75
  76 Otter is not so easy to build.  You will want to start with the git
  77 branch
  78   https://salsa.debian.org/iwj/otter
  79
  80 You cannot build it just with `cargo`, you must use `make`.
  81
  82 You will also need various other utilities and dependencies - in some
  83 cases, un-released dependencies or locally patched versions.  See
  84 `Cargo.nail` and `Makefile`.  On my own laptop deployment is done with
  85 `make deploy` which copies all the relevant sources into the
  86 `bundled-sources` directory, which is accessible via the Otter web UI.
  87
  88 Dependencies
  89 ------------
  90
  91  * Rust Nightly (sorry)
  92
  93  * `cargo` and a willingness to let it download all the dependencies
  94    and run them, from crates.io.  You can use my `Cargo.lock.example`
  95    if you like.  I use a privsep scheme to avoid running stuff from
  96    cargo in my main account on my laptop.  Using the not properly
  97    released `nailing-cargo` program.
  98
  99  * `tsc`, Microsoft's Typescript compiler.  The version in Debian
 100    buster will do.
 101
 102  * `wasm-pack`, a program for manipulating WebAssembly files.  This
 103    too likes to run cargo and do god knows what.
 104
 105  * `resvg`, a program for manipulating SVG files.
 106
 107  * `bundle-rust-sources`, an un-released Rust package for publishing
 108    source code of Rust projects.
 109
 110 Weirdnesses:
 111
 112  * `Cargo.nail` contains a list of sibling directories of my Otter
 113    source tree, which on my machine is called `server`.  For several
 114    of these I sent patches upstream which have generally been
 115    accepted, but I need to tidy this up to switch to the upstream
 116    version.
 117
 118  * The Rocket dependency in `Cargo.toml` is completely mad due
 119    to Cargo being awful.  I am hoping I can switch to an upstream
 120    Rocket now.
 121
 122  * For running on chiark I build with the Rust target
 123    `x86_64-unknown-linux-musl` which on my system is configured to
 124    produce a completely statically linked bionary:
 125
 126 ```
 127 [target.x86_64-unknown-linux-musl]
 128 rustflags = ["-C", "target-feature=+crt-static"]
 129 # ^ from https://stackoverflow.com/questions/31770604/how-to-generate-statically-linked-executables
 130 ```