Skip to content

README.md

Latest commit

 

History

History
129 lines (94 loc) · 4.83 KB

README.md

File metadata and controls

129 lines (94 loc) · 4.83 KB
Raw

Mistboard

CI License: AGPL-3.0

Mistboard screenshot showing the same Fog of War chess position from White and Black perspectives

Mistboard is a free, open-source platform for original strategy games, built for serious play. It hosts server-enforced board games and variants across chess, xiangqi, shogi, Jungle, and related families, including both open-information games and hidden-information games such as dark chess.

The project goal is to build the trustworthy open-source place to play, study, rank, and build engines for original strategy games.

Mistboard is independent. It is not affiliated with lichess, chess.com, or any other chess platform.

Features

  • Low-friction PvP rooms with shareable room links and account-optional play.
  • Postgame replay from either player's perspective or full truth.
  • Public game links with PGN and JSON export.
  • Rules references and interactive examples for Mistboard games and their base rulesets.
  • A first-party engine track that uses the same redacted EngineTurnRequest boundary available to any third-party engine.

Live games are playable at mistboard.com. For active work and known issues, see the GitHub issue tracker.

Development

Prerequisite: Node.js 22 or newer.

npm install
npm run dev

Open http://localhost:3000.

npm run dev is persistent by default: it starts a local Postgres in Docker, applies migrations, and runs the server + web pair with the live product variants. Use npm run dev:lab for parked variant work. No Docker? Run npm run dev:memory or npm run dev:lab:memory for the in-memory path (DB-backed pages like /watch and profiles are dark).

Useful checks:

npm test
npm run typecheck
npm run verify -- --changed

Load the product-shaped local QA fixtures (public profiles, watch feed, live variant sample games, plus an admin account, inbox threads, and a seeded xiangqi ladder):

npm run db:seed:qa

See CONTRIBUTING.md for the contributor workflow, local test matrix, and pull request expectations.

Code

Mistboard is a small TypeScript npm workspace:

packages/game           Pure game logic: types, rules, visibility, variants
packages/board-render   Shared SVG and browser board rendering primitives
apps/server             WebSocket rooms, clocks, event log, HTTP API
apps/web                Vite browser client, game screens, replay, learning UI

The server owns canonical GameState. Clients receive only a PlayerView, the seat-scoped projection produced by the rules package. This is the core hidden-information boundary: hidden pieces, hidden opponent moves, and live truth state must never be sent to the wrong consumer.

The browser client is a no-framework Vite build using chessground for board interaction and chessops for chess primitives. The server is a Node.js WebSocket process with Postgres for the event log and game history.

See docs/ARCHITECTURE.md for the full data flow and state model.

Documentation

Use GitHub issues for bug reports and feature requests.

Contributing

See CONTRIBUTING.md, CODE_OF_CONDUCT.md, and SECURITY.md.

License

AGPL-3.0-or-later. See LICENSE.

For uses that require terms other than AGPL, such as closed-source distribution, reach out via mistboard.com/contact.

Governance

Mistboard is founder-led. The code is open source, but the official project identity, mistboard.com, hosted service, roadmap, and production infrastructure remain controlled project assets.

See GOVERNANCE.md, TRADEMARK.md, and docs/project-direction.md.