Backgammon (terminal)

Backgammon against the computer, in a terminal. It is the second version of the game, beside web/. It runs on the magmacrunch engine's terminal backend, either as a cabinet in the magmacrunch arcade or as its own command, and plays the same either way.

pipx install magmacrunch-backgammon
backgammon

For working on it, from this folder:

pip install -e ".[dev]"
python -m backgammon

Keys

You play cyan, ███, moving down the board from 24 to 1 and bearing off at the bottom right. The computer plays pink, ▒▒▒. The two differ by shape as well as colour, so they stay apart under NO_COLOR and --ascii (### and +++). The points you can move from have green numbers. Once a checker is picked up, a ✦ marks where each die can take it: green for a plain step, yellow for a hit. The cursor is an arrow in the middle of the board as well as a shade. The panel shows the dice still to play, the cube, both pip counts and the last few moves. The computer answers after a second, as it does on the page.

Moving one step at a time

Each die is played as its own step. When you put a checker down, the screen asks for the next die. The move is sent once no further step can follow, so you play as much of the roll as the rules allow. Esc takes a step back.

This is how the page plays online. The page's single-player game does something else: a click plays the first whole move in its list that includes that step. With a 6-1, clicking 8 to 7 can also move a different checker from 8 to 2. The rules are the same; only the way you pick among the moves differs.

Playing a person online (a prototype)

PLAY ONLINE on the title, or backgammon --online, connects to the arcade's own multiplayer server, the one behind the page's PLAY ONLINE button, so a terminal and a browser can share a room. Type a name, then press C to create a room and read its four-letter code to your opponent, or J to join one. The host starts the game. Each of you sees your own checkers in cyan, moving down to the bottom right: the second player's board is turned round, as the page does. You move exactly as against the computer, a step at a time. D offers a double; when one is offered to you, Y takes and N passes. X then Y resigns.

pip install "magmacrunch-backgammon[online]"     # websockets, only for this
backgammon --online
backgammon --online --server ws://127.0.0.1:8771  # a web/server.py on this machine

The server keeps the rules, and this client needs none of them. Every state the server sends lists the mover's legal moves in full, and a move goes back as an index into that list. The screen builds your move one step at a time from that list, then sends its index. backgammon/online.py holds the protocol, split into Table (the server's state, turned to your seat, with no I/O) and Connection (the WebSocket, on its own thread). online_scenes.py reuses the computer game's screen: it gets the server's state in place of a local game.

tests/test_online.py runs web/server.py in-process on a free port and plays it over real sockets. It covers:

• a whole game from both seats. After every move, both boards must be mirror images, match a shadow board kept with rules.py, and offer exactly the moves rules.py gives for each player's own view. The game includes hits, entries from the bar, bearing off and turns passed;
• the passes the server reports, the fallback for a server that doesn't, and a game that ends without a winner, read without a socket;
• the cube offered, taken, redoubled and passed;
• out-of-turn and out-of-range moves, which the server ignores;
• a wrong room code;
• an opponent leaving;
• two complete terminal sessions, through the lobby, a move from each seat and a resignation, using keys alone.

It never contacts the live server. By hand, the real page in headless Chromium has played a terminal client in the second, mirrored seat through a whole game to the last checker borne off. The two boards matched, with no page errors.

What a prototype has not done yet:

• Nobody has played the live server from a terminal, only a copy of it run locally. The default address is wss://magmacrunch.duckdns.org/backgammon, which is what mpServerFor('backgammon', 8771) gives the public site.
• No reconnect. A dropped connection says so, and the game is lost.
• No chat, which the browser has.
• States can be large. With doubles early in a game, the list of legal moves runs to thousands, and one state measured 1.9 MB. That is past websockets' default limit of 1 MiB a frame, so this client raises its limit. The browser has no limit. Any other client of this server will need the same.
• Passes come from the server now, but not yet from the live one. When a side has no move, the server rolls for the other side at once. It now lists those passes in the state, and this client logs them with their dice. The live server will only do this once this branch is synced. Until then the client falls back to noticing that the turn came straight back to the side that just moved. The browser doesn't show passes either way.

It is the browser's game, and the browser's opponent

backgammon/rules.py is web/js/board.js, dice.js, ai.js and game.js, ported function for function. Three tests hold it to the other versions:

• tests/test_oracle.py. tools/js_oracle.mjs loads those files unmodified, with Math.random replaced by a seeded generator. It plays 120 games through Game's own API: half against a random player, half against a careful one who wins about half of its games. The test replays every game through the port with the same seed and requires the same state after each of about 10,000 moves: whose turn, the dice, every place on the board, every legal move in the page's order, and the cube.
• tests/test_server_parity.py. It compares the port's move generator with web/server.py's for every roll and both sides, in positions from played games, so single-player and online offer the same moves.
• tests/test_rules.py. It sets up by hand the cases the oracle only reaches by chance.

Two bugs fixed in both, and the quirks kept

Entering onto a blot used to remove both checkers. board.js typed every entry from the bar as an ordinary entry, even onto the other side's blot. The blot was never sent to the bar: the entering checker cancelled it out and both left the game. A side short of 15 checkers can never bear off 15, so 188 of 200 random games could not end. This is fixed in web/js/board.js and here together. web/server.py already got it right, so online play was unaffected.

The computer used to judge its moves on a board with one sign wrong. It scores each step of a move on a scratch board, applying the steps before it. ai.js put its own checker down there in the other side's colour. So after entering onto its blot on 5 to make a point, it saw 5 as empty, and spent the next die breaking the point it had just made. One decision in thirteen was judged this way. Fixed in web/js/ai.js and here together, the computer beats its old self in 63% of 2,000 games.

These quirks are kept, because the oracle requires them:

• The opening is a roll-off of two dice each, and the winner moves with its own pair. Standard backgammon rolls one die each and moves with both.
• The rules never insist on the larger die when only one die can be played. With doubles they offer moves of one to four steps. Here you are asked for every step you can play anyway.
• The cube can be turned after the roll, before you move. The computer always takes and never doubles. A game is worth the cube, and there are no gammons.

There is no high-score table, because the page keeps none for backgammon.

Needs a 74x17 terminal.

Licence

PolyForm Noncommercial 1.0.0, as for the rest of this repository. See LICENSE and NOTICE.