Digital Boardgame Framework

Foundation library for turn-based digital boardgames. Provides the small set of plumbing that converged across multiple boardgame ports (Innovation, Impulse, Star Wars Rebellion):

• Deterministic seeded RNG (serializable)
• Turn-boundary state codec
• Structured append-only log (pause/resume for AI rollouts)
• Pause/resume effect context (the ChoiceRequest protocol)
• IPlayerController + RandomAI + ScriptedController
• GameServer — async multiplayer (turn-based, per-player redacted views, shareable URLs)
• Bug report transport — agent-friendly triage endpoints, public-read snapshots
• Storage adapters (filesystem for dev, Supabase for production)
• Email notifications via Resend
• React useGame hook

The library is deliberately small. Game-specific concerns (phase machine, card registry, combat sub-machine, UI) are NOT here — they're recipes in docs/decisions.md instead.

Quick start

npm install
npm run build
npm test

To hook an existing game in, see docs/integration-guide.md. The smallest possible working integration is in examples/tic-tac-toe/.

What you implement per game

Four functions. That's it.

interface GameAdapter<State, Action, PlayerId> {
  applyAction(state: State, action: Action, actor: PlayerId): State;
  legalActions(state: State, actor: PlayerId): Action[];
  currentActor(state: State): PlayerId | null;
  viewFor(state: State, viewer: PlayerId): State;   // redact opponent hidden info
}

The framework handles everything else: persistence, turn validation, per-player views, snapshots, bug reports, email notifications.

Repo layout

src/
  core/       Pure modules (rng, codec, log, effects, adapter, controller)
  server/     GameServer, SnapshotStore, store adapters, notifiers
  client/     React useGame hook
supabase/
  schema.sql  Apply this to your Supabase project
examples/
  tic-tac-toe/  Minimal working integration
docs/
  integration-guide.md  How to hook an existing game in
  adapter-spec.md       The GameAdapter interface in detail
  decisions.md          Recipes for things NOT in the library

Status

v0.1 — usable but unproven. No game has been ported yet; the integration guide is theory plus the tic-tac-toe demo. Treat the API as not-yet-stable.

Feedback & contributions

The most useful thing you can send is an in-game problem report — the report button inside the game. Filed while you're playing, it captures the game state and context that make an issue reproducible, which helps far more than a code change.

Pull requests generally won't be merged. This is a solo-maintained project, and reviewing and integrating outside code costs more than it saves. If you open a PR, it'll be read as a well-specified bug report or feature request and implemented here rather than merged — so it's a fine way to describe a change you'd like, just please don't expect it to land as-is.

The whole codebase is MIT-licensed — fork it and do whatever you want: change the rules, reskin it, build and ship your own version. No permission needed; that's the point of the license.