Mistboard

Bring people together across cultures through Chinese chess and the world's classic strategy games.

Mistboard is a free, open-source site for playing and studying Chinese chess, in English, Simplified Chinese and Traditional Chinese.

On the site

• Games. Xiangqi, Jieqi and Banqi lead. Beside them: Duck Xiangqi, Fog Xiangqi, Crazyhouse Xiangqi, Xiangqi Mahjong, Jungle Chess, Flip Jungle and Fog Chess. Rules for each are at mistboard.com/rules.
• Play. Link games with no account, a lobby, rated play, correspondence, and computer opponents at eight levels.
• Study. Puzzles from real games, a beginner course, studies, an analysis board and a games database.
• Watch. Live games, tournament broadcasts and replays of every finished game.
• Engines. Engine authors challenge for titles in public matches. The engine protocol defines what an engine is sent.

Run it locally

Needs Node.js 22 or newer, and Docker for the default database.

npm install
npm run dev          # Postgres in Docker, migrations, server and web
npm run dev:memory   # no Docker; database-backed pages stay empty

Open http://localhost:3000. Check your work with npm test and npm run typecheck.

Dev pairs listen on 127.0.0.1 by default. For phone testing on the same network, run MISTBOARD_DEV_LAN=1 npm run dev (or npm run dev:memory with the same prefix) and open http://<your-Mac-LAN-address>:3000 on the phone. The same opt-in applies to the standalone web and agent dev commands.

Run npm run db:seed:qa to fill the local home and index surfaces. Its db:seed:volume step adds ten fictional games per public product variant, eight forum topics with replies, six public studies and six lobby chat messages. The forum and study counts match the homepage's fetch windows; News already uses the committed announcements. No production player data is fetched.

The volume step accepts only a loopback Postgres URL and can be re-run across worktrees: it refreshes its own fixtures under a transaction lock and preserves other data. Games use deterministic legal play with a resignation at the move cap. Two games per variant with stored analysis support have synthetic advantage scores for layout QA, not engine evaluations. Review examples: /jieqi/game/jq_qa_volume_00, /xiangqi/game/xq_qa_volume_00, and /banqi/game/bq_qa_volume_00. The seed prints all chart review paths.

Run the production probes locally before deploying:

npm run release:local-smoke
# Or reuse a batch's running, production-shaped HTTP origin:
npm run smoke:local -- --base http://127.0.0.1:3099

The managed command builds both apps, ensures Postgres, migrates, starts a local server serving the built web app on port 3099, runs the probes, and stops its server on success or failure. Use -- --port 3119 for another worktree. The existing-origin command requires an explicit loopback URL; inherited production URLs cannot redirect a probe. Use the built app served by the server, rather than Vite: these probes check production framing headers and prerendered pages.

Both commands run the site, correspondence and builtin-engine checks, the seven main variant PvE smokes (Fog Xiangqi, Duck, Xiangqi, Jieqi, Banqi, Jungle and Flip Jungle), and every ceval backend. They require the local variant engine binaries, the browser engine assets (including the pinned Pikafish net), Postgres, and Playwright Chromium. A missing engine or failed search fails the gate; all probes run sequentially so an early failure cannot hide a ceval regression. Install Chromium with npx playwright install chromium when preparing the machine.

release:prod runs this gate before draining or pushing a deploy, reusing the build only when its preceding gate built both apps. For a batch runner, append npm run smoke:local -- --base <batch-local-origin> after starting that batch's built local pair. --plan prints the probes without running them. Choosing an automatic gate for the broader tests/e2e/ suite remains a separate step.

Code

packages/game           Rules, visibility, variants, clocks, replay
packages/board-render   Shared SVG board rendering
apps/server             WebSocket rooms, clocks, event log, HTTP API
apps/web                Vite browser client

The server holds every game's full state and sends each player only what they may see. docs/ARCHITECTURE.md has the data flow, and docs/README.md lists the rest of the documentation.

Contributing

Read CONTRIBUTING.md and the Code of Conduct. Report security problems privately, as SECURITY.md describes. Bugs and requests go to GitHub issues.

License

AGPL-3.0-or-later; see LICENSE. For other terms, such as closed-source use, write to mistboard.com/contact. The project name and hosted service are covered in GOVERNANCE.md, and credits are at mistboard.com/thanks.