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