TheGameBlock

TheGameBlock is a browser-first framework and studio for deterministic, agent-editable games. A game is an immutable project tree whose GameModule accepts tick-indexed semantic commands and returns serializable state plus declared effects. The same project runs in the isolated preview, through the remote runtime API, and as a standalone offline export.

The repository includes JavaScript, TypeScript, and AssemblyScript/Wasm paths; JSON-RPC and MCP agent surfaces; revision-scoped audit and replay evidence; exact-hash trust promotion; and six genre-neutral example games.

Quick start

Requires Bun.

bun install --frozen-lockfile
bun run build
bun run serve

Open http://localhost:8787, register an account, and select a starter project. The server stores tenant data under data/ and seeds the built-in examples for a new account.

For development, run the API server and Vite separately:

# Terminal 1: API, WebSocket runtime, and built studio on :8787
bun run serve

# Terminal 2: Vite studio on :5173, proxying /api, /runtime, and /ws to :8787
bun run dev

The development fallback secret is intentionally insecure, and bun run serve defaults to explicit development mode so the local quickstart uses it with a loud warning. Any other invocation refuses to start unless TGB_SECRET is at least 16 characters or the mode is explicitly development/test; production mode always refuses to start without a strong TGB_SECRET. Set TGB_DATA_DIR to move persistent tenant data outside the repository.

Commands

Command	Purpose
bun run dev	Start the Vite development studio on port 5173.
bun run serve	Start the Bun API and built studio on port 8787.
bun run build	Build the studio, browser runtime artifacts, and all example games.
bun run build:wasm	Compile AssemblyScript games to Wasm.
bun run typecheck	Run TypeScript without emitting files.
bun run lint	Run Biome checks.
bun run test	Run the Vitest suite once.

Included games

• card-battler: deterministic decks, turns, content data, and rule graphs
• grid-tactics: tile movement and tactical state
• narrative: branching text and content imports
• physics-toy: AssemblyScript/Wasm runtime path
• platformer: fixed-step movement and hazards
• real-time-action: real-time command and rendering path

Each project contains a manifest, an entry module, JSON Schemas, and any rules or content it needs. bun run build validates all six projects against the same contracts used by the studio and server.

Architecture

Studio / agents
      |
      v
Hono API + scoped JSON-RPC/MCP
      |
      v
Tenant project store -> immutable revisions -> audit + replay evidence -> trust
      |                                                       |
      v                                                       v
Opaque-origin preview iframe                        standalone offline ZIP
      |
      v
Deterministic kernel -> state envelope + effects -> adapters

Key boundaries:

• Kernel: game logic is a pure init/step module over serializable state. The model clock, command log, migrations, schemas, and effects remain explicit.
• Projects: patches name an exact base revision. Successful writes create content-addressed revisions; stale writes return a semantic diff instead of rebasing silently.
• Agents: JSON-RPC and MCP expose allowlisted project, compile, audit, runtime, and export operations. Scoped credentials bind tenant, project, paths, operations, expiry, and nonce.
• Preview: untrusted project code runs in an opaque-origin sandbox="allow-scripts" iframe over one dedicated transferred, authenticated MessagePort; the host DOM and bearer token never enter the iframe.
• Trust: only an owner can promote an exact revision, and only after a clean accessibility audit and deterministic replay have produced revision-bound evidence.
• Export: the studio builds a self-contained ZIP with the selected revision, browser runtime, license notices, content hashes, version pins, and no external network references.

The implementation plan and requirement trace live in docs/plans/2026-07-22-001-feat-agent-native-web-game-framework-plan.md. Build evidence lives under docs/build/.

License

The project-owned framework, studio, adapters, and bundled runtime use the Elastic License 2.0. Third-party components retain their upstream licenses; see NOTICE. Creator game code and assets retain the creator's chosen license, and exports preserve the applicable notices.