Metadata-Version: 2.5
Name: magmacrunch-backgammon
Version: 0.1.0
Summary: Backgammon against the computer. Terminal version.
Project-URL: Homepage, https://magmacrunch.com/arcade/backgammon/
Author: magmacrunch media
License-Expression: PolyForm-Noncommercial-1.0.0
License-File: LICENSE
License-File: NOTICE
Keywords: arcade,backgammon,board,games,terminal,tui
Requires-Python: >=3.10
Requires-Dist: magmacrunch>=0.7.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Requires-Dist: websockets>=14.0; extra == 'dev'
Provides-Extra: online
Requires-Dist: websockets>=14.0; extra == 'online'
Description-Content-Type: text/markdown

# Backgammon (terminal)

Backgammon against the computer, in a terminal. It is the second version of
the game, beside `web/`. It runs on the
[magmacrunch](https://github.com/magmacrunch-media/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

| key | |
|---|---|
| `←` `↑` `↓` `→` (or `h` `j` `k` `l`) | move the cursor along the points, and between the top and bottom rows |
| `ENTER` | pick up the checker under the cursor; on a marked point, play that step |
| `Esc` | put the checker back; then take back the last step; then go to the title (and from there, the arcade) |
| `D` | double, before you move |
| `R` | new game |
| `Q` | quit |

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`.
