Vitric

English | 中文

The AI game engine for shipping commercial games — not demos.

核心宗旨：让 AI 有能力独立完成商业闭环游戏，而非止步于 demo。

↑ AI-generated pixel art, dynamic 2D lighting, particles, camera follow — every frame captured headlessly by an AI driving the game through the control plane.

Most "AI game" tools stop at prompt-to-prototype. Vitric is built around an agent API so an AI can autonomously carry a game the whole way to shippable: run the game → observe pixels and state → assert → modify → repeat, no human in the loop. Existing engines were designed for a human in front of an editor; to an AI they are black boxes — state invisible, bugs unreproducible, "done" is a claim, not a fact. Vitric inverts that: every piece of engine state is visible, operable, and verifiable, and because the simulation is bit-exact deterministic, the engine can prove things about a game — that a recording clears it, that a swarm of agents can't soft-lock it. Two complete games in games/ have already passed the delivery gate.

Contents

• Quick start · The agent API · Automated playtesting
• Features · Architecture · Examples · Docs
• MCP & multi-agent · Status · Roadmap · Contributing · License

Quick start

cargo build --release
BIN=./target/release/vitric

# Validate a project — errors come with paths, stable codes, and fix hints, all at once
$BIN check examples/coin-run

# Run it (headless + AI control plane on port 6173)
$BIN run examples/coin-run --port 6173

# Auto-playtest: a swarm of deterministic agents plays the game and reports what's broken
$BIN playtest examples/coin-run --sessions 16 --html report.html

# Delivery gate: replay a winning recording bit-exactly and require the win event
$BIN gate examples/spire

Prebuilt binaries for Linux and Windows are on the releases page.

The agent API

The engine runs headless and exposes an HTTP JSON-RPC control plane. An agent drives the game the same way a player would, but through data:

rpc() { curl -s -X POST http://127.0.0.1:6173/rpc -d "$1"; echo; }
rpc '{"method":"sim/pause"}'
rpc '{"method":"input/inject","params":{"action":"right"}}'
rpc '{"method":"sim/step","params":{"ticks":60}}'                  # deterministic frame-by-frame stepping
rpc '{"method":"world/get","params":{"entity":"@player"}}'         # read any entity's state
rpc '{"method":"render/describe"}'                                 # semantic view: what's on screen, where, who overlaps whom
rpc '{"method":"render/screenshot","params":{"path":"shot.png"}}'  # headless screenshot, no GPU needed
rpc '{"method":"events/recent"}'                                   # the causal chain: collision → coin-collected → game-won

render/describe is built for a model to read: alongside the entity list it gives ego-centric spatial relations to the camera's focal entity (direction / distance / line-of-sight), an ASCII map of the level, the declared input actions, and a frame-to-frame diff of what changed since the last call.

Full method reference: docs/agent-guide.en.md (中文).

Automated playtesting

vitric playtest runs a swarm of deterministic agents through a game and aggregates a structured report — the kind of mechanical QA that's slow and incomplete by hand. It clears the floor (mechanical correctness and balance), not the ceiling (fun, feel, art — those still need a human).

What the swarm reports:

• Clear rate & reachability — can it be beaten at all? Which declared endings does no run reach?
• Soft-locks — input orderings that strand a run in an unwinnable state, clustered and replayable.
• Dead content — items, abilities, or actions no run ever uses.
• Pacing — where runs stall; difficulty spikes.
• Number breakage — economy runaway / collapse, overflow.
• Dominant strategy — one action or build that makes every other choice meaningless.
• Clarity / continuity — optional LLM playtesters flag "I couldn't tell what to do" or "this dialogue contradicts an earlier scene."

Two properties of the engine make this work and set it apart:

• Lookahead search. Because the sim is deterministic with exact snapshot/restore, an agent can speculatively try an action, roll forward a few ticks, score the result, and roll back — actually playing skill-based games instead of flailing randomly. (--strategy lookahead.)
• Certificates as seeds. A vitric gate clearing recording is both a proof the game is beatable and a seed for the swarm: it perturbs the known solution (reorder, branch, drop a step) to find what breaks it — the tractable way to test puzzle and narrative games.

Playtest thresholds — no soft-locks, a minimum clear rate, no unreachable endings — can be declared as a delivery gate (gates.playtest in vitric.json), so "the swarm couldn't break it" becomes part of the contract. Reports render to a self-contained HTML page. See docs/design-agent-playtest.md.

vitric balance closes the loop from report to fix: point it at one numeric knob (<file>#<json-pointer>) and a target clear-rate band, and it binary-searches the value by re-running the playtest swarm on throwaway copies of the project — the original is never written.

Features

Determinism & verification

• Fixed timestep, seeded PCG32 RNG (one stream shared across Rust and JS), input recording.
• vitric replay re-runs a recording and verifies checkpoint hashes bit-exactly — any bug replays to the exact frame it broke.
• vitric gate turns a winning recording into an unforgeable delivery certificate: bit-exact replay + a required terminal event + assertions evaluated every tick. "Done" is decided by the machine, not claimed by the agent.

Everything is data

• Scenes, entities, rules, and every frame of the world are strongly-schema'd JSON — validated on write, queryable at runtime, round-trippable. Saves are full snapshots; there is no state hiding inside an editor binary.
• Snapshot/restore is exact, which is what makes save/load, replay, and lookahead search all fall out of one primitive.

Authoring

• Rules first. ~80% of gameplay is declarative when X then Y rules (deliberately not Turing-complete; cascade loops are a hard error).
• Scripts with a seatbelt. The rest is JS/TS systems that must declare the components they read and write — undeclared writes are rejected, so the engine always knows the blast radius of every system. TypeScript compiles via esbuild (an external binary: esbuild on PATH or ESBUILD_BIN; only needed for .ts scripts — the examples/ are all plain .js); hot reload supported.
• One animation owner. Declarative clips + an Anim component; the engine has exclusive write access to Sprite.image, so "my animation got interrupted by another system" cannot happen.

Rendering (CPU rasterizer is the deterministic truth source; wgpu GPU path mirrors it)

• 2D dynamic lighting (ambient + point/spot/directional) with zero-config normal-mapped relief (hero.png + hero_n.png), 2D shadow casting, and a bloom post-effect.
• On-screen text described semantically (no OCR); built-in bitmap font, or a TTF for proportional anti-aliased vector text including CJK.
• Headless screenshots are byte-for-byte deterministic and can be asserted on — no GPU, window, or display session required.
• Frame-animation pipeline (vitric assets --frames): dedupe, trim, atlas, palette, and BC7 texture compression — runtime VRAM for the texture atlas drops ~4× on BC-capable GPUs (measure it on your own GPU with vitric gpu-probe).

AI-generated art

• vitric assets harmonizes a project's PNGs onto one shared palette (deterministic median-cut), and generates normal maps procedurally or via image-to-image.

Errors for LLMs

• Every error carries a precise path, a stable code, and a fix hint — all reported at once, not one at a time.

Architecture

crates/
  vitric-ecs       deterministic, introspectable ECS (components = JSON, ordered iteration, snapshots/hashing)
  vitric-data      declarative data layer (schema validation, scene instantiation, project loading)
  vitric-rules     when-X-then-Y rule engine (triggers/conditions/actions/cascade protection)
  vitric-script    QuickJS scripting (enforced read/write declarations, deterministic RNG, hot reload, TS via esbuild)
  vitric-sim       fixed-timestep simulation (PCG32, record/replay, snapshot/restore, motion + collision)
  vitric-render    CPU rasterizer (world→PNG headless, lighting/shadows/bloom, semantic describe)
  vitric-control   AI control plane (HTTP JSON-RPC: query/mutate/inject input/time control/asserts/screenshots)
  vitric-playtest  agent swarm playtesting (scene view, strategies incl. lookahead, seed exploration, report)
  vitric-cli       vitric check / run / replay / playtest / balance / gate / bundle / run-embedded / assets / team / turf / gpu-probe (+ window, inspector, audio, wgpu GPU mirror)

Examples

examples/ holds runnable sample games, each validated in CI by vitric check (cargo test -p vitric-cli --test examples_check): coin-run (rules + scripts + animation + audio), jump (a platformer in pure rules, zero scripts), cave-gen (recipe-generated levels), spire, glow (dynamic lighting), ui-menu/ui-gallery, intro (the timeline/sequence system), rpg-mini (7-module RPG closed loop), rpg-full (12-module flagship RPG with save/load), and more.

modules/ is a library of 12 reusable gameplay modules — drop them into any project via includes and compose them with zero glue code: inventory, quest, dialogue, game-flow, combat, progression, loot, shop, equipment, status-effects, skills, crafting. The rpg-full example composes all 12 into a complete RPG with persistence.

games/ holds two complete, delivery-gated games: echo (a card-battle RPG with 6 scenes, 13 sound effects, multiple enemy types) and frontier (a colony survival game with 20 rule files, 15 systems, multi-faction AI). Both have passed vitric gate — bit-exact replay of a winning recording.

Docs

• Agent API reference (中文) · Error catalog · Art pipeline
• Cookbook — 21 recipes covering all engine capabilities: 12 gameplay modules, save/load, procedural generation, frame animation, audio, and UI. Each recipe has copy-paste patterns, component schemas, and integration test references.
• Design records: agent playtesting, UI, frame animation, tween/sequence
• llms.txt for agents reading the repo.

MCP & multi-agent

mcp/ ships an official MCP server: any MCP client (Claude Code / Cursor / Codex …) can validate, launch, observe, drive, and assert on a Vitric game out of the box.

{ "mcpServers": { "vitric": { "command": "node", "args": ["<repo>/mcp/index.js"], "env": { "VITRIC_BIN": "<repo>/target/release/vitric" } } } }

The engine also carries a multi-agent team harness: role work tickets (team/), a coordination blackboard (vitric team), and turf enforcement (vitric turf), so an agent platform can run a multi-agent game team off the engine itself. See the team playbook.

Status

Pre-1.0 and under active development; the API may change. The core is real and tested (650+ tests in CI, including an end-to-end run where an agent beats a game over HTTP and the recording replays hash-identically). Determinism, replay, gates, headless rendering, lighting/shadows/bloom, rules + TypeScript, save/load, scene flow, GPU presentation, audio, asset harmonization, frame animation, the playtest swarm, the MCP server, and a 12-module gameplay library with 21 cookbook recipes are all in place. Binaries ship for Linux and Windows.

Roadmap

Near-term

• Web playground (WASM) — compile the engine to WebAssembly so anyone can play coin-run in a browser without installing Rust. Why: the project has zero stars because no one can try it in 30 seconds; a one-click demo is the single highest-leverage fix.
• Benchmark suite — deterministic sim throughput vs. other Rust 2D engines (Bevy 2D, Macroquad, Fyrox). Why: "deterministic" is the core selling point but currently unquantified; a number on a chart is what makes the claim credible to engine shoppers.
• Cookbook — 21 recipes covering 12 gameplay modules, save/load, procgen, animation, audio, and UI. Done: docs/cookbook.md.
• Hot-reload for rules & scenes — reload rule and scene data without restarting the sim (scripts already support it). Why: the inner loop of game development is edit → run → edit; cold-restart kills iteration speed, which kills adoption among game devs.

Long-term engine capabilities

Pipelines

• Render pipeline — post-processing chain, multi-pass, custom shader injection. Why: lighting/bloom/shadows exist but are hardcoded passes; exposing them as a composable pipeline unlocks stylized looks without forking the engine.
• Asset pipeline — end-to-end import → compress → pack → hot-update. Why: BC7/frame-atlas/palette pieces exist today but are scattered CLI commands; a unified pipeline is what separates an engine from a library.
• Build pipeline — one-command multi-target packaging (Windows / macOS / Linux / Web). Why: cross-platform shipping is a baseline expectation for any 2D engine; today only Linux/Windows binaries ship.
• AI pipeline — closed loop of agent playtest → report → auto-fix. Why: the control plane + swarm + gate are in place, but they're manual tools; closing the loop (agent finds bug → agent patches rules/scripts → gate re-runs) is the unique bet of this engine.

Hardening

• Determinism hardening — fuzz testing, cross-platform byte-identical verification, edge-case coverage. Why: determinism is the contract that everything else (replay, multiplayer, gates) rests on; one silent violation invalidates every clear certificate.
• Performance hardening — sim/render profiling, hot-path optimization, memory budget. Why: "deterministic" must not mean "slow"; without numbers, "fast enough" is a guess.
• Stability hardening — crash recovery, error handling, logging/diagnostics. Why: an engine that crashes takes the game down with it; production use needs graceful degradation, not panics.
• Security hardening — script sandbox lockdown, asset validation, injection prevention. Why: scripts come from untrusted sources (LLM-generated, user-authored); the sandbox is the engine's security perimeter.

New platforms

• Mobile target (iOS / Android) — compile + input + audio + GPU for mobile. Why: 2D games ship on phones; without mobile, the engine can't reach where most players are.
• Deterministic multiplayer — snapshot/diff-based netcode over the deterministic sim. Why: determinism + replay already gives the raw material for rollback netcode; multiplayer is the highest-leverage capability built on what the engine already does well.

Contributing

Issues and pull requests are welcome. cargo test --workspace and cargo clippy --workspace --all-targets should pass clean (CI enforces both). New engine systems should keep the determinism rules: all state JSON-serializable, all iteration ordered, no wall-clock or undeclared randomness in the simulation.

License

MIT © 2026 BlackBearCC