Plan for the technical foundation. Built fresh in this repo; the PoC (ygo-ai) is a reference only. Parts are ported only where they hold up to review.
Decisions
- Online: host-authoritative co-op. The teammate joins with a room code via a small relay server.
- Client: browser first, with its own design system. Built so a Tauri desktop wrapper fits later on Windows, macOS and Linux.
- Duel format: 2 players vs 1 AI on one shared field. Turn order as the engine gives it: P1 → AI → P2 → AI.
- Personal LP: tracked by the game harness (rules below).
- Solo mode: later.
- Repo: fresh monorepo here.
Architecture
Guest browser ──ws──▶ Relay (room codes, no game logic) ◀──ws── Host app
│
Host browser ───────────────── ws (localhost) ──────────┤
├─ Game layer (run, map, nodes, rewards, saves)
├─ Duel worker process ──▶ libocgcore + Lua scripts
└─ AI layer ──▶ player's own AI provider
- Host app: Python. Runs the engine, the AI calls (on the host's own subscription or API key), the run state and the save files. Serves the client locally.
- Guest: only needs a browser. Opens the game URL, enters the room code, done.
- Relay: forwards messages between host and guest. No game logic, no secrets, no stored game data.
Online
- Server-authoritative: the host decides everything. Clients only send intents ("play this card", "pick this node") and receive state.
- Protocol: typed, versioned messages. Defined once (Pydantic) with TypeScript types generated for the client. Same protocol over localhost and over the relay; the relay is just a transport.
- Per-player views: each client only receives what that player may see (opponent hand hidden).
- Reconnect: every message has a sequence number. On reconnect the client gets a snapshot and continues from there.
- Host disconnect: the game pauses. Autosave after every node and every duel turn, so nothing is lost.
- Relay hosting (proposal): Cloudflare Workers + Durable Objects (one object per room, WebSocket hibernation). Costs a few euros a month at most. The static client is served from the same place (Cloudflare Pages).