docs/user.rst

   1 Using Otter as a player or game host
   2 ====================================
   3
   4 Basics; joining a game
   5 ----------------------
   6
   7 To join a game, you run a command like this on the server host:
   8
   9 ::
  10
  11   otter [--nick <nick>] --game unix:ijackson::test join-game
  12                                     /^^^^^^^  ^^^^\
  13                           game owner             game name
  14
  15
  16 This will print a URL.  You cut and paste that URL into your browser.
  17 It is not usually necessary to explicitly leave a game, although
  18 a ``leave-game`` subcommand is available.
  19
  20 You can have the same URL open in multiple browsers if you wish.  The
  21 browser you use must support JavaScript and WebAssembly.  Cookies are
  22 not used; anyone with your link can see your view of the game.
  23
  24 Game UI
  25 -------
  26
  27 The main Otter UI is fairly sparse and is dominated by the game table
  28 area.  In that area are various elements such as cards, boards, chess
  29 pieces, or whatever.
  30
  31 You can pick up and move those pieces about with the mouse.  When you
  32 move an object (henceforth, a "piece"), everyone else will see it move
  33 too.
  34
  35 Only one player at once may "grasp" a piece.  If you and someone else
  36 both try to manipulate a piece at the same time, only one of your
  37 manipulations will take effect.  For example, if you both try to pick
  38 up and drag a piece right at the same time, whichever of you got to it
  39 last will see the piece "jump" out of your grasp.
  40
  41 But in general different players can manipulate separate pieces (eg,
  42 separate cards) concurrently.
  43
  44 There are two layouts.  You can switch with the controls near the zoom
  45 adjustment.  (What you see will depend on what the game is, of
  46 course.)
  47
  48 Portrait
  49 ````````
  50
  51 .. image:: portrait.png
  52
  53 Landscape
  54 `````````
  55
  56 .. image:: landscape.png
  57
  58 Keyboard commands and special functions
  59 ---------------------------------------
  60
  61 Otter makes use of keyboard commands for many functions.  The UI will
  62 display a list of the currently-valid keyboard commands.  Note that
  63 the set of valid commands can depend on what you have selected, and
  64 what state it is in.
  65
  66
  67 Hidden information - secrets, card shuffling, etc.
  68 --------------------------------------------------
  69
  70 Otter supports what is known in gaming terms as "hidden information".
  71
  72 This is achieved by special "pieces" which are capable of hiding, or
  73 scrambling, other pieces.  In Otter this is called "occultation".
  74
  75 For example, a draw pile deck contains cards but maintains them
  76 shuffled and shows everyone only the backs of the cards.  Each time
  77 anyone draws a card, it is chosen randomly from whatever cards are in
  78 that draw pile.
  79
  80 There are also occulters which treat different players differently.
  81 For example, there are "hand repositories".  When you have "claimed" a
  82 hand repository (with the keyboard command), it becomes "your hand".
  83 Any cards you put in it are identifable only by you.  You see the
  84 fronts of the cards, and their precise positions (and orientations).
  85 The other players see only a simplified view, showing the backs of
  86 cards in predetermined locations.  Another player can select a card
  87 from your hand, but their view of even which card is which is
  88 scrambled, so if they pick a card from your hand they get one selected
  89 at random.
  90
  91 These special occulting pieces need to be activated before they do
  92 their thing.  This is done by selecting the occulter, and issuing
  93 keyboard commands.
  94
  95
  96 UI features
  97 -----------
  98
  99 The UI has a number of features intended to ease play of various
 100 games.  It can be worth experimenting with the UI in a test game, to
 101 see how things work.  The information presented by the game interface
 102 itself is meant as prompts and hints rather than full documentation.
 103
 104 Notable features you might otherwise overlook include these:
 105
 106 Pressing ``h`` repeatedly cycles through various amounts of history
 107 view (the overlaid yellow arrows showing what recently happened).
 108
 109 Typing numbers will get you into a multiple selection mode, which you
 110 can use (for example) to draw yourself a hand of multiple cards.
 111 Typing just ``1`` will let you select the first available card, even if
 112 it's not the one on top (eg because you want to draw a card and
 113 someone is holding onto the deck).
 114
 115 Typing a zero will get you into a special selection mode for selecting
 116 the lowermost piece.  This can useful to grasp a hand or pickup deck
 117 if it is covered in cards so you can't see it.
 118
 119 Hands have an organise function, which lets you neaten the layout of
 120 the cards, or even sort them.  Select the hand and look for the ``o``
 121 and ``O`` keyboard commands.
 122
 123 There is a Wresting mode for making exceptional changes to the game
 124 state, such as forcibly grasping a piece out of another player's
 125 grasp, or moving the chessboard.  Don't forget to exit Wresting mode
 126 when you're finished with it.
 127
 128
 129 Bugs and errors
 130 ---------------
 131
 132 Sometimes, bugs can cause things to mess up; in particular, you can
 133 see error messages on the screen in your browser.  They typically
 134 appear at the top, and they say "reloading may help".
 135
 136 If this happens, do try simply reloading the page in your browser.
 137 Typically this will improve matters.  Hopefully the game state on the
 138 server side is not too badly affected.
 139
 140 If you can reproduce a bug, please file a bug report;
 141 https://salsa.debian.org/iwj/otter/-/issues/new .
 142
 143 Of course you might want to reload the Otter game page if you have
 144 trouble with your network or web browser.  The state is all on the
 145 server, so you can reload or reconnect whenever you like.
 146
 147
 148 Adding pieces to a game in progress
 149 -----------------------------------
 150
 151 Using the `otter library-list` and `otter library-add` commands, you can
 152 add pieces to a game while it is in progress.
 153
 154 Currently only shape library pieces (builtin, or from bundles) can be
 155 added this way.
 156
 157 You may want to refer to the builtin shape library preview ("Shapelib"
 158 link in the game UI).
 159
 160
 161 Game administration
 162 -------------------
 163
 164 Creating and modifying games is done via the ``otter`` command line
 165 utility.  See its ``--help`` message for full details.
 166
 167 The most usual game-creation command looks something like this:
 168
 169 ::
 170
 171   otter -g unix:ijackson::test reset --reset-table local-users demo
 172           /~^^^^^^^^^^^^^^^^^'                    /^^^^^^^^^^^ '^^^\
 173           `game name                   table spec'         game spec'
 174
 175 Here ``local-users`` refers to the file ``local-users.table.toml`` in the
 176 Otter specs directory (``/volatile/Otter/specs`` on chiark).  The table
 177 spec file handles access control (and some other global properties)
 178 This particular file says that all local shell account users may join
 179 the game.
 180
 181 ``demo`` refers to the file ``demo.game.toml``.  The "game spec" says what
 182 shape the table is and what pieces there are.  This is a simple demo game.
 183
 184 Currently there are also ``penultima`` and ``mao`` game specs.
 185
 186 After a game has finished and you want to play again, you can put
 187 everything back to the starting state (or, even, the starting state
 188 for a different game) with something like this:
 189
 190 ::
 191
 192   otter -g unix:ijackson::test reset demo
 193           /^^^^^^^^^^^^^^^^^^'       '^^^\
 194           `game name                      `game spec
 195
 196 The ``otter`` command line tool has further subcommands for
 197 adding/removing players, for ad-hoc addition of pieces from the
 198 library to an existing game, and so on.
 199
 200
 201 Defining your own game
 202 ``````````````````````
 203
 204 If you want to use existing piece shapes that Otter already knows
 205 about, you can do this by providing a ``GAME.game.toml`` file,
 206 in :doc:`Game Spec <gamespec>` format.
 207
 208 You can also define your own shapes by providing a :doc:`bundle
 209 <bundles>`.