magmacrunch-backgammon 0.1.0__py3-none-any.whl

backgammon/__main__.py

@@ -0,0 +1,31 @@
+"""``python -m backgammon`` -- play backgammon against the computer in a terminal."""
+
+from __future__ import annotations
+
+import argparse
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="backgammon", description="Backgammon against the computer.")
+    parser.add_argument("--play", action="store_true", help="skip the title screen")
+    parser.add_argument("--online", action="store_true",
+                        help="go straight to PLAY ONLINE (needs the [online] extra)")
+    parser.add_argument("--server", metavar="URL",
+                        help="the multiplayer server for PLAY ONLINE, e.g. "
+                             "ws://127.0.0.1:8771 for a web/server.py on this machine")
+    parser.add_argument(
+        "--ascii", action="store_true", dest="ascii_only",
+        help="draw with plain ASCII instead of block and box glyphs. Detected "
+             "automatically from the terminal's encoding; this forces it. "
+             "MAGMACRUNCH_ASCII=1 says the same for every cabinet.",
+    )
+    args = parser.parse_args()
+
+    from backgammon.app import run
+
+    run(args.play, args.ascii_only, server=args.server, online=args.online)
+
+
+if __name__ == "__main__":
+    main()

backgammon/app.py

@@ -0,0 +1,73 @@
+"""Wiring -- how the screens reach each other.
+
+Everything that draws lives in :mod:`backgammon.scenes`; everything that
+decides lives in :mod:`backgammon.rules`. **The terminal is not owned here**:
+it belongs to a ``TuiHost``, which is what lets this run as its own command or
+be seated by the arcade. There is no score table: the page keeps none for
+backgammon.
+"""
+
+from __future__ import annotations
+
+import random
+from collections.abc import Callable
+from typing import Any
+
+from backgammon.arcade import INFO
+from backgammon.scenes import GameScene, TitleScene
+
+
+class BackgammonApp:
+    def __init__(self, host: Any, rand: Callable[[], float] | None = None,
+                 server: str | None = None):
+        self.host = host
+        #: Where PLAY ONLINE connects; None for the arcade's public server.
+        self.server = server
+        #: Stands in for the page's Math.random. Tests pass a seeded one.
+        self.rand = rand or random.random
+        self.root_scene = TitleScene(self)
+
+    @property
+    def renderer(self):
+        return self.host.renderer
+
+    def start_game(self) -> None:
+        self.host.push_scene(GameScene(self))
+
+    def play_online(self) -> None:
+        from backgammon.online import DEFAULT_SERVER
+        from backgammon.online_scenes import OnlineLobbyScene
+
+        self.host.push_scene(OnlineLobbyScene(self, self.server or DEFAULT_SERVER))
+
+    def show_rules(self) -> None:
+        from backgammon.scenes import RulesScene
+
+        self.host.push_scene(RulesScene(self))
+
+    def to_title(self) -> None:
+        self.host.pop_scene()
+
+    def leave(self) -> None:
+        self.host.pop_scene()
+
+    @property
+    def scene(self):
+        return self.host.scene
+
+
+def run(skip_title: bool = False, ascii_only: bool = False, server: str | None = None,
+        online: bool = False) -> None:
+    """Play backgammon as its own command."""
+    from magmacrunch.engine.core.tui_host import TuiHost
+    from magmacrunch.engine.ui.glyphs import Glyphs
+
+    host = TuiHost(title=INFO.title, fps=INFO.fps, hold_ms=INFO.hold_ms,
+                   glyphs=Glyphs.detect(ascii_only=ascii_only))
+    app = BackgammonApp(host, server=server)
+    host.push_scene(app.root_scene)
+    if online:
+        app.play_online()
+    elif skip_title:
+        host.push_scene(GameScene(app))
+    host.run()

backgammon/arcade.py

@@ -0,0 +1,39 @@
+"""What the arcade needs to know to launch this game. Kept tiny: a menu loads
+one of these per installed game just to draw a card."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from magmacrunch.engine.arcade import GameInfo
+
+from backgammon import theme
+
+INFO = GameInfo(
+    key="backgammon",
+    title="Backgammon",
+    blurb="Against the computer, with the doubling cube.",
+    # Turn-based: the frame rate paces the computer's one-second pause and
+    # the cursor, nothing else. Edge input, so one arrow is one point.
+    fps=20,
+    hold_ms=0,
+    min_cols=theme.MIN_COLS,
+    min_rows=theme.MIN_ROWS,
+    accent=theme.PLAYER,
+)
+
+
+class BackgammonGame:
+    """Satisfies :class:`magmacrunch.engine.arcade.ArcadeGame`."""
+
+    info = INFO
+
+    def start(self, host: Any) -> Any:
+        from backgammon.app import BackgammonApp
+
+        return BackgammonApp(host).root_scene
+
+
+GAME = BackgammonGame()
+
+__all__ = ["GAME", "INFO", "BackgammonGame"]

backgammon/online.py

@@ -0,0 +1,382 @@
+"""Playing a person online, through the arcade's own backgammon server.
+
+**A prototype**, built the way the cribbage and checkers ones are. The rules
+belong to ``web/server.py``, the server behind the page's PLAY ONLINE button.
+Every state it sends carries the mover's legal moves in full, and a move goes
+back as an index into that list. So this client never works out a legal move,
+whose turn it is or who won; it picks from what the server offers. A terminal
+and a browser can share a game: two clients of one referee.
+
+Two halves, so the part with the logic can be tested without a socket:
+
+- :class:`Table` is pure. It reads the server's frames -- room, players, the
+  state -- and builds the frames a choice sends.
+- :class:`Connection` is the socket: a ``websockets`` client on a thread of
+  its own, polled once a frame. It is the cribbage and checkers client's,
+  copied; three copies is the point to move it into the engine.
+
+**Sides.** The first player in the room takes the server's ``player`` seat,
+moving down from 24 and bearing off below 1; the second takes ``ai``, moving
+up. The second is shown the board turned round, as the page does for it, so
+both players see their own checkers in cyan moving down to the bottom right.
+:meth:`Table.mirror` maps a place either way, being its own inverse; every
+board and step this module hands out is already in the viewer's terms, with
+:data:`backgammon.rules.PLAYER` meaning "mine".
+"""
+
+from __future__ import annotations
+
+import json
+import queue
+import threading
+from dataclasses import dataclass, field
+
+from backgammon import rules as R
+from backgammon.scenes import move_name
+
+#: ``mpServerFor('backgammon', 8771)`` on the public site, through nginx on 443.
+DEFAULT_SERVER = "wss://magmacrunch.duckdns.org/backgammon"
+
+#: The sender's "nothing to send this time", distinct from None, which is a
+#: request to close.
+_IDLE = object()
+
+#: The server's phases, as the local game's states.
+PHASE_STATE = {"playing": R.MOVING, "doubling": R.DOUBLING, "game_over": R.GAME_OVER}
+
+
+def mirror(p: int) -> int:
+    """A place on the server's board as the other seat sees it: points turn
+    round, and the two bars and the two trays change places."""
+    if 1 <= p <= 24:
+        return 25 - p
+    return {R.BAR_PLAYER: R.BAR_AI, R.BAR_AI: R.BAR_PLAYER,
+            R.OFF_PLAYER: R.OFF_AI, R.OFF_AI: R.OFF_PLAYER}[p]
+
+
+@dataclass
+class Table:
+    """What this client knows about its room and its game. No I/O."""
+
+    me: str = ""
+    room: str = ""
+    is_host: bool = False
+    players: list[str] = field(default_factory=list)
+    can_start: bool = False
+    #: ``BackgammonGame.get_state()`` from the server, as last sent.
+    state: dict | None = None
+    #: What happened, newest last: (line, whether it was this player). Never
+    #: trimmed, so a screen can follow it by index; a game is a few hundred
+    #: lines at most.
+    log: list[tuple[str, bool]] = field(default_factory=list)
+    rejected: str = ""
+    left: str = ""
+    #: Counts every state received, so a screen can tell one apart from the
+    #: last even when nothing visible changed.
+    version: int = 0
+
+    def receive(self, msg: dict) -> None:
+        kind = msg.get("type")
+        if kind == "welcome":
+            self.me = msg.get("playerName", self.me)
+            self.room = msg.get("room", self.room)
+            self.is_host = bool(msg.get("isHost"))
+            self.rejected = ""
+        elif kind == "lobby_update":
+            self.players = [p.get("name", "") for p in msg.get("players", [])
+                            if isinstance(p, dict)]
+            self.can_start = bool(msg.get("canStart"))
+        elif kind == "rejected":
+            self.rejected = str(msg.get("reason", "rejected"))
+        elif kind == "game_started":
+            self._set(msg.get("state"))
+            first = "You move" if self.my_turn else f"{self.opponent} moves"
+            self._say(f"The game has started. {first} first.", self.my_turn)
+        elif kind == "game_state":
+            self._set(msg.get("state"))
+        elif kind == "game_action":
+            action = msg.get("action") or {}
+            rolled = self.dice           # the state after a move holds the next roll
+            self._set(action.get("state"))
+            self._describe(action, rolled)
+        elif kind == "player_quit":
+            self.left = str(msg.get("playerName", "Your opponent"))
+            self._say(f"{self.left} left the game.", False)
+        elif kind == "system":
+            self._say(str(msg.get("text", "")), False)
+
+    def _set(self, state) -> None:
+        if state:
+            self.state = state
+            self.version += 1
+
+    def _say(self, line: str, mine: bool) -> None:
+        self.log.append((line, mine))
+
+    def _describe(self, a: dict, rolled: list[int]) -> None:
+        mine = a.get("player") == self.me
+        who = "You" if mine else a.get("player", "?")
+        kind = a.get("type")
+        if kind == "move_made":
+            steps = [self._step(s) for s in a.get("moves") or []]
+            self._say(f"{who} {rolled[0]}-{rolled[1]}: {move_name(steps)}", mine)
+            passes = (a.get("state") or {}).get("passes")
+            if passes:
+                # Each side that rolled after this move and had no move.
+                for p in passes:
+                    passer = self._side(p.get("side"))
+                    name = "You" if passer == R.PLAYER else self.opponent
+                    d = p.get("dice") or [0, 0]
+                    self._say(f"{name} {d[0]}-{d[1]}: no move.", passer == R.PLAYER)
+            elif passes is None and a.get("nextTurn") == a.get("player") \
+                    and not a.get("gameOver"):
+                # A server from before passes were reported: the turn came
+                # straight back to the side that just moved.
+                other = self.opponent if mine else "You"
+                self._say(f"{other} had no move.", not mine)
+            if a.get("gameOver"):
+                self._say(self._winner_line(a.get("winner")), a.get("winner") == self.me)
+        elif kind == "double_requested":
+            self._say(f"{who} doubled to {2 * self.cube}.", mine)
+        elif kind == "double_accepted":
+            self._say(f"{who} took. The cube is at {self.cube}.", mine)
+        elif kind == "double_rejected":
+            self._say(f"{who} passed. {self._winner_line(a.get('winner'))}", mine)
+        elif kind == "player_resigned":
+            self._say(f"{who} resigned. {self._winner_line(a.get('winner'))}", mine)
+
+    def _winner_line(self, name) -> str:
+        if not name:
+            return "Neither side can ever move again: no winner."
+        return "You win." if name == self.me else f"{name} wins."
+
+    # -- What the screen asks ------------------------------------------
+
+    @property
+    def _s(self) -> dict:
+        return self.state or {}
+
+    @property
+    def started(self) -> bool:
+        return self.state is not None
+
+    @property
+    def seat(self) -> str:
+        """The server's name for our side, ``player`` or ``ai``."""
+        sides = self._s.get("sides") or {}
+        return next((s for s, name in sides.items() if name == self.me), R.PLAYER)
+
+    @property
+    def mirrored(self) -> bool:
+        return self.seat == R.AI
+
+    def _place(self, p: int) -> int:
+        return mirror(p) if self.mirrored else p
+
+    def _side(self, side) -> str | None:
+        """A server side as ours: :data:`R.PLAYER` is always this client."""
+        if side is None:
+            return None
+        return R.PLAYER if side == self.seat else R.AI
+
+    def _step(self, s: dict) -> R.Step:
+        # Bearing off goes to 0 or 25, the two homes, which swap like the bars.
+        return R.Step(self._place(s["from"]), self._place(s["to"]), s["type"], s["die"])
+
+    @property
+    def board(self) -> list[int]:
+        raw = self._s.get("board") or [0] * R.ARRAY_SIZE
+        if not self.mirrored:
+            return list(raw)
+        out = [0] * R.ARRAY_SIZE
+        for i, v in enumerate(raw):
+            out[mirror(i)] = -v or 0
+        return out
+
+    @property
+    def moves(self) -> list[R.Move]:
+        """Our legal moves, in the server's order, in our terms. Empty when it
+        is not our turn."""
+        if not self.my_turn:
+            return []
+        return [[self._step(s) for s in m] for m in self._s.get("moves") or []]
+
+    @property
+    def dice(self) -> list[int]:
+        return list(self._s.get("dice") or [0, 0])
+
+    @property
+    def phase(self) -> str:
+        return self._s.get("phase", "")
+
+    @property
+    def cube(self) -> int:
+        return int(self._s.get("doublingCube") or 1)
+
+    @property
+    def cube_owner(self) -> str | None:
+        return self._side(self._s.get("doublingOwner"))
+
+    @property
+    def opponent(self) -> str:
+        sides = self._s.get("sides") or {}
+        return next((n for n in sides.values() if n != self.me), "Opponent")
+
+    @property
+    def on_turn(self) -> str | None:
+        """Whose turn it is, in our terms."""
+        return self._side(self._s.get("currentTurnSide"))
+
+    @property
+    def over(self) -> bool:
+        return self.phase == "game_over"
+
+    @property
+    def winner(self) -> str:
+        return self._s.get("winner") or ""
+
+    @property
+    def my_turn(self) -> bool:
+        return self.started and not self.over and self.on_turn == R.PLAYER
+
+    @property
+    def to_answer(self) -> bool:
+        """The other side has doubled, and the answer is ours."""
+        return self.phase == "doubling" and self.on_turn == R.AI
+
+    def can_double(self) -> bool:
+        return (self.my_turn and self.phase == "playing" and self.cube < R.DOUBLING_MAX
+                and self.cube_owner in (None, R.PLAYER))
+
+    # -- What a choice sends -------------------------------------------
+
+    @staticmethod
+    def create_room(name: str) -> dict:
+        return {"type": "create_room", "name": name, "color": None, "room": ""}
+
+    @staticmethod
+    def join_room(name: str, code: str) -> dict:
+        return {"type": "join_room", "name": name, "color": None, "room": code.upper()}
+
+    @staticmethod
+    def start_game() -> dict:
+        return {"type": "start_game"}
+
+    @staticmethod
+    def quit() -> dict:
+        return {"type": "quit"}
+
+    @staticmethod
+    def move(index: int) -> dict:
+        return {"type": "game_action", "action": {"type": "move", "moveIndex": index}}
+
+    @staticmethod
+    def double() -> dict:
+        return {"type": "game_action", "action": {"type": "double"}}
+
+    @staticmethod
+    def answer(take: bool) -> dict:
+        kind = "accept_double" if take else "reject_double"
+        return {"type": "game_action", "action": {"type": kind}}
+
+    @staticmethod
+    def resign() -> dict:
+        return {"type": "game_action", "action": {"type": "resign"}}
+
+
+class Connection:
+    """A WebSocket on its own thread, with a queue each way.
+
+    ``poll`` and ``send`` are safe to call from the game's frame loop and never
+    block it. ``websockets`` is imported here and only here, so a player who
+    never goes online never needs it installed.
+    """
+
+    def __init__(self, url: str):
+        self.url = url
+        self.status = "connecting"
+        self.error = ""
+        self._inbox: queue.Queue[dict] = queue.Queue()
+        self._outbox: queue.Queue[dict | None] = queue.Queue()
+        self._thread = threading.Thread(target=self._run, name="backgammon-online",
+                                        daemon=True)
+        self._thread.start()
+
+    def send(self, msg: dict) -> None:
+        self._outbox.put(msg)
+
+    def poll(self) -> list[dict]:
+        out = []
+        while True:
+            try:
+                out.append(self._inbox.get_nowait())
+            except queue.Empty:
+                return out
+
+    def close(self) -> None:
+        self._outbox.put(None)
+
+    @property
+    def open(self) -> bool:
+        return self.status == "open"
+
+    def _run(self) -> None:
+        import asyncio
+
+        try:
+            asyncio.run(self._main())
+        except Exception as exc:  # noqa: BLE001 - reported to the screen
+            self.status, self.error = "closed", str(exc) or type(exc).__name__
+
+    async def _main(self) -> None:
+        import asyncio
+
+        try:
+            from websockets.asyncio.client import connect
+        except ImportError:
+            self.status = "closed"
+            self.error = 'needs websockets: pip install "magmacrunch-backgammon[online]"'
+            return
+
+        # The full list of legal moves rides in every state. Doubles early in
+        # a game run to thousands of moves, which can pass websockets' default
+        # limit of 1 MiB a frame; the browser has none.
+        async with connect(self.url, open_timeout=10, max_size=16 * 2**20) as ws:
+            self.status = "open"
+
+            async def reader():
+                async for raw in ws:
+                    try:
+                        self._inbox.put(json.loads(raw))
+                    except json.JSONDecodeError:
+                        continue
+
+            read = asyncio.create_task(reader())
+            loop = asyncio.get_running_loop()
+            try:
+                while not read.done():
+                    # A short wait rather than a blocking one, so a server that
+                    # hangs up is noticed within a fifth of a second even when
+                    # the player has nothing to send.
+                    msg = await loop.run_in_executor(None, self._next_out)
+                    if msg is _IDLE:
+                        continue
+                    if msg is None:
+                        break
+                    await ws.send(json.dumps(msg))
+                if read.done() and not read.cancelled() and read.exception():
+                    self.error = str(read.exception())
+            finally:
+                read.cancel()
+        self.status = "closed"
+        if not self.error:
+            self.error = "the server closed the connection"
+
+    def _next_out(self):
+        try:
+            return self._outbox.get(timeout=0.2)
+        except queue.Empty:
+            return _IDLE
+
+
+__all__ = ["DEFAULT_SERVER", "PHASE_STATE", "Connection", "Table", "mirror"]