An AI-legible 3D experience engine: a deterministic headless simulation kernel, a three.js
rendering client, and a development loop an agent can drive end to end without a browser.
Molen is not a game. It is a kernel plus capability layers you build games, visualizations and
interactive experiences on top of. Its design constraint is that an agent can author, validate,
simulate, assert and screenshot a complete experience entirely through text.
Molen agent tooling: molen CLI and MCP server over a shared ops library
2026-10-28
星标
—
工具
—
可用率
—
molen validate scene.json # cheap, run it constantly
molen sim run scene.json --ticks 30 --assert checks.json --hash
molen shot scene.json --ticks 30 --camera 0,6,16 --out shot.png
Try it
Play first, with nothing to install: every sample runs in the browser at
molen.dev/play, including three complete games.
Then build your own from npm. Node 22.13 or newer:
npx @bendyline/molen-tooling new my-experience
cd my-experience
npm install # the engine, the molen CLI, TypeScript and Vite
npx playwright install chromium # once per machine; only screenshots need a browser
That scaffolds a runnable project: a scene manifest, two scene scripts, a setup module, an
entity type registry, assertions and a Vite app. From inside it, the whole inner loop runs
headless:
npx molen validate scenes/main.scene.json # ✓ scenes/main.scene.json is a valid scene
npx molen types check # ✓ types check passed
npx molen scripts check # ✓ 2 scripts type-check clean
npx molen sim run main --ticks 30 --commands cmds.json --assert checks.json --hash
# ✓ 4/4 assertions passed
npx molen shot main --ticks 30 --out shot.png
npm run dev # the same scene in the browser
Use the scoped name the first time: the unscoped molen package on npm is unrelated. Inside the
project, npx molen runs the CLI the project installed.
Every one of those loop commands is also an MCP tool with the same input and output contract
(npx molen mcp starts the server over stdio), so an agent drives the engine without reading its
source. molen describe prints the contracts, and molen docs search <query> searches the
shipped guides offline. The guides are also at molen.dev, and the whole
bundle, version-locked, is node_modules/@bendyline/molen-tooling/dist/docs-src/llms.txt in any
project that installs the tooling.
To start from one of the samples instead, copy it with --template. The templates ship inside
the tooling package, version-locked to the engine, and keep each sample's scripts, checks, replay
fixture and tests:
Shared content (entity models, the default building style pack, Earth catalogs, the star table)
never ships in npm packages. It comes as content packs:
npx molen pack fetch https://molen.dev/packs/index.json downloads them into a project and pins
them in project.json.
You do not need this repository to build on Molen. It is for working on the engine itself; see
Contributing.
What makes it different
Determinism is a tested contract, not a slogan. Same seed, same commands and same build
produce the same state hash. Randomness routes through a seeded world RNG and math through a deterministic dmath,
enforced by a lint over kernel code. A recorded replay does not just say "something changed"; it
names the first tick that diverged.
A complete game can be data. Entities, prefabs, commands with their own JSON Schema payloads,
input bindings, camera and physics are declared JSON, validated with pinpointed errors and
did-you-mean suggestions. Game rules are scene scripts in the manifest. The Skybound platformer
sample's entire rule set is 119 lines.
Headless from the start. Validate, simulate, assert and screenshot without a browser. Every
sample is simultaneously a demo and a regression fixture, so behaviour is checkable in CI.
The simulation is separated from rendering by a message boundary. The kernel has no DOM and no
three.js, runs in a Worker in the browser and in Node for tests, and speaks to the client over a
documented protocol.
The molen CLI and the MCP server over one shared ops library.
Capability packages layer on top and are opt-in. Each splits into a deterministic /kernel half
and a render-only /client half: terrain,
worldgen, worldgen-earth,
figures, plus physics-rapier,
pathfinding and the entities asset library.
pack builds and reads content packs: zip files of models and documents that an
app hosts wherever it likes. earth composes terrain, worldgen, navigation,
vehicles and markers into an embeddable real-world view behind one mountEarthView call.
Status
Molen is pre-release. Version 0.x, ESM only, Node 22.13 or newer, three.js 0.184 to 0.186 as a peer dependency.
The formats are beta. A breaking change bumps the version in the envelope
(molen/scene@3) rather than shipping a migration.
Determinism has levels, and they are stated per subsystem. The built-in kinematics and
platformer physics are cross-platform deterministic. Rapier rigid-body physics is deterministic
on the same build and platform only, so a replay recorded on one machine may diverge on another.
Vehicles, aircraft and figures reach transcendental math, which makes them same-JS-engine.
Materials, worldgen geometry and rendering never enter the state hash at all. The full table,
with what breaks each level and what is not promised, is in
the determinism guide.
Upgrading does not invalidate your saves unless the state format changed. Keyframe
compatibility and the state hash gate on a STATE_FORMAT constant, not on the package version,
which rides along as metadata. See
Upgrades and save files.
Scene scripts run with the authority of their host process. The script sandbox exists to
make simulation deterministic, not to contain hostile code. Treat a scene manifest like source
code: only run manifests you would run as a program. See
the scripting guide.
The five packages in the table above are the engine. The capability packages are younger and
their surfaces are more likely to move.
Documentation
Quickstart — zero to cubes, in Node and in the browser.
The agent loop — author, validate, simulate, assert,
screenshot, with copy-paste commands.
Scripting — game logic as scene data, the verb set, and the
determinism rules.
Determinism — what reproduces and at what level, what
breaks it, what STATE_FORMAT means for saves, and what is not promised.
Browser mount — the kernel in a Worker, the page on top.
Schema reference — every format with its JSON Schema and a
valid example, generated from the registry the validator uses.
llms.txt — the whole documentation bundle as a flat, version-locked
index for agents. It also ships inside the tooling package and is searchable offline.
Contributing
Code contributions are not accepted. We do welcome issue reports and proposal-only pull requests:
read Contributing and the specs/ guide before opening one.
Participation is subject to the Code of Conduct. For help, see
Support; report vulnerabilities privately through the
Security Policy.
To build the engine itself from a clone, start at AGENTS.md for the architecture and
CONVENTIONS.md for the house rules.
pnpm install && pnpm assets:fetch && pnpm -r build # restore GLBs, then build packages
pnpm dev # the samples gallery, reusing prepared content packs
pnpm dev:packages # rebuild every package's dist on change (for a linked host app)
node packages/tooling/dist/cli.mjs --help
For app development, pnpm install && pnpm dev:prepare prepares the local assets and browser
packs once. Subsequent pnpm dev launches compile engine code and reuse those packs without
running model generators. After importing asset changes, run pnpm dev:content to refresh the
browser packs explicitly.
One invariant matters more than the rest: build before you typecheck or test, because packages
consume each other's dist. The root scripts encode it.
GLBs are build outputs of the generators in this repository, pinned byte for byte by
asset-lock.json. pnpm assets:fetch downloads the snapshot CI built and published;
pnpm assets:build builds the same bytes from source. See repository GLBs.
pnpm verify # lint, typecheck, docs:check, test:unit, production audit — also the release gate
pnpm test:golden # browser and image tests
pnpm all # everything above, in order, from a clean install
Use Conventional Commits for release notes and version
bumps. See Releases for the publishing flow. Generated files — the
schema docs, the site, script declarations — come from generators; change the source and regenerate
rather than editing them.
The repository also carries third-party data and assets that are not MIT: OpenStreetMap-derived
map tiles under ODbL, public-domain elevation data with a required courtesy line, and source
business-identification data that refers to names belonging to their respective owners. Their
licenses and required attribution are
recorded in NOTICE. If you redistribute this repository or the sample data in it, those
terms travel with the data.