@rallycry/microgame-core

The generic microgame engine behind Rally Cry's realtime minigames: pure, deterministic game definitions adapted into a uniform session lifecycle with per-viewer redaction.

Install

bun add @rallycry/microgame-core

The main package has no framework dependency. The optional conformance suite at @rallycry/microgame-core/testing/contract requires Vitest 2 or newer.

Usage

Define a game with runtime schemas, adapt it to the shared session contract, then register the adapter with the host:

import {
  createGameAdapter,
  createGameRegistry,
  defineGame,
} from "@rallycry/microgame-core"

const game = defineGame({
  // Game metadata, schemas, state transitions, projections, and outcomes.
})

const adapter = createGameAdapter(game)
const registry = createGameRegistry([adapter])

The package is intentionally host-agnostic. Session persistence, transport, presence, and product-specific game definitions stay in the consuming app.

• Types and adapter: defineGame / createGameAdapter: frames (shared + per-seat secret state), actions, phases, deadlines, cues, and GameStep results; adapters enforce schema validation, seq/idempotency, and projection discipline.
• Redaction: projections are computed per viewer; a viewer can only ever receive bytes projected for them.
• Registry: compose adapters into a lookup the host session layer drives.
• Seeded random: deterministic GameRandom so a session replays.
• Result sealing: seat-keyed outcomes sealed into player-keyed GameResults.
• Public event feed: an ordered, secrets-free, capped record of game happenings kept inside the frame (appendPublicEvent).
• Intent lane vocabulary: the ephemeral (unpersisted) presence/emote event shapes.
• Conformance suite: @rallycry/microgame-core/testing/contract exports describeGameContract, a vitest suite every game definition must pass (vitest is an optional peer dependency, needed only for this subpath).

The published ESM carries explicit .js relative import specifiers, so it loads under bare Node ESM as well as Bun, Vite, vitest, and any bundler-resolution toolchain. The workspace source stays extensionless and the extensions are appended to the emitted dist/ at publish time (packages/microgame-core/scripts/fix-dist-extensions.ts), because Turbopack does not apply TypeScript's extension substitution to workspace package sources.

Game definitions are intentionally NOT part of this package.

Release

Update the package version, then push a matching microgame-core-vX.Y.Z tag. The release workflow validates, builds, and publishes the package to public npm.