3D engine that AI agents drive
Game: a playable scene from a recipe
A scene recipe can carry a game section. It names the node the player controls, the controller, camera and input preset, and a game rules document. 67js/addons/game plays it in a page, and the MCP tool scene_export_web writes it as a static web build. The section is plain data: there is no script, so an agent can create and edit it without running anything it wrote.
Build one through MCP
scene_createwith the scene. The player is a node (a group is fine: its children move with it).scene_applywith{ "type": "set-game", "game": { ... } }.nullclears it. A wrong field is refused with its name and the values to use;scene_capabilitieswithtopic: "game"lists every field and one small example.scene_export_webwith an optionaltitle. The result has the path ofindex.html. It needs--jobs, likescene_export_glb.
{
"type": "set-game",
"game": {
"player": { "node": "creature", "footOffset": 0.5 },
"camera": "follow",
"input": "keyboard",
"rules": {
"version": 1,
"variables": { "score": 0 },
"zones": [
{ "id": "coin-zone-1", "shape": "sphere", "center": [0, 0.5, -3], "radius": 1.2 },
{ "id": "goal-zone", "shape": "box", "center": [0, 1, -12], "size": [3, 4, 2] }
],
"parts": [{ "id": "creature", "tags": ["player"] }, { "id": "coin-1", "tags": ["coin"] }],
"rules": [
{ "once": true, "when": { "type": "enter", "zone": "coin-zone-1", "tag": "player" }, "do": [{ "type": "add", "variable": "score", "value": 1 }, { "type": "hide", "part": "coin-1" }] },
{ "when": { "type": "enter", "zone": "goal-zone", "tag": "player" }, "if": [">=", "score", 1], "do": [{ "type": "win" }] }
]
}
}
}
Fields
| Field | Default | Meaning |
|---|---|---|
player.node |
required | A node of the scene. The rules part with the same id follows the player |
player.controller |
character |
character (character controller) or vehicle (arcade car: W throttle, S reverse, A/D steer, Space brakes; walkSpeed, runSpeed and jumpSpeed are ignored) |
player.walkSpeed, runSpeed, jumpSpeed |
3, 6, 7 | Metres per second, 0 to 100 |
player.maximumSpeed |
20 | Top speed of a vehicle, metres per second, 0 to 100 |
player.footOffset |
0 | Metres from the node origin down to the feet. Zone checks use the feet |
camera |
follow |
follow, first-person, top-down or chase (behind the player, swinging round to its heading: use it with a vehicle), the camera rigs |
input |
keyboard |
keyboard (WASD move, arrows look, Space jump, Shift run), gamepad (adds the first pad) or touch (adds a left-half stick and tap to jump) |
player.animation |
none | An animation graph for the player, see Animation and NPCs |
npcs |
none | Up to 16 characters that walk a path through their own graph, see Animation and NPCs |
physics |
false |
true plays the recipe's physics section live, see Physics |
ground |
0 | Height of the walkable ground in metres |
rules |
none | A game rules document, checked when it is set |
A rules part named like a scene node is hidden and shown with it, which is how a coin disappears. Yaw 0 faces -Z, and W moves forward. Removing the player node while a game uses it fails with the field to fix.
The web build
scene_export_web writes one folder: index.html, game.json (the recipe) and engine/ (the built 67js modules, found by following the imports from build/game.js). It runs from any static host with no server code, and the folder is bounded: the engine stays under 12 MiB, the recipe under 1 MiB, and the newest four builds are kept. Placed catalog assets (and the assets whose clips a character retargets) are copied to assets/<id>.glb, up to 64 MiB together; grown vegetation is refused with the fix. The page shows the variables and the verdict in a corner label and exposes the running game as window.__game (rules.state, controller.state, scene, runtime).
index.html?replay=name.json plays a recording (recordInput, see input) from the same folder instead of the keyboard. scripts/smoke-game-web.mjs builds a creature that collects 3 coins and reaches a goal through the MCP tools, exports it, and wins it from a replay in headless Chrome, with a head-bob animation graph that the page must play. node scripts/smoke-game-web.mjs bin/67js-mcp.mjs puzzle plays the physics puzzle. node scripts/smoke-game-web.mjs bin/67js-mcp.mjs drive does the same for a car that passes 3 gates and reaches a finish line under a chase camera. The character sample walks a placed, retargeted humanoid (idle and walk clips of another file) to a goal, and checks that the page loads assets/<id>.glb and the character's limbs move.
From code
import { startGame } from '67js/addons/game';
const game = await startGame(canvas, recipe, { replay, showStatus: true });
game.dispose();
startGame loads the scene modules the recipe needs, builds the scene and renderer, and runs input, controller, camera rig and rules as runtime systems. Each frame it moves the player node with set-node, so a large scene pays a scene update per frame. Not yet in the web build: sound and post effects.
Physics
game.physics: true plays the recipe's physics section (the set-physics bodies, with the limits of physics) live. startGame loads game-physics.js and the Jolt engine only for such a recipe, so other games and exports do not grow. The engine steps in the fixed update of the runtime at 60 Hz, after the controller and before the rules, and each dynamic body's node follows it through set-node. The same recipe gives the same poses on every run in the same engine build; window.__game.physics is the physics system (getPose, stepCount, applyImpulse, queries).
- The player node can be a
kinematicbody (shapecapsule,boxorball): the controller drives it, so the player pushes dynamic bodies and is never pushed back. - A rules part named like a dynamic body reports that body's position, so a zone, a tag and
enterwork on crates and balls. - Give every fixed body
shape: "box"(orball,capsule,convex): the defaulttrimeshis not built. Joints, ragdolls, trimesh and compound shapes are refused with the field to change, andphysics.durationis only the length of the recorded film. - The web export copies
jolt-physics.wasm.jsand its.wasmfile toengine/physics/(about 3 MiB) and gives the page their URL, so Jolt fetches the wasm from beside the page. Nothing loads from another origin: aphysicsUrlon another origin is refused. Thejolt-physicspackage must be installed to export.
The puzzle sample of scripts/smoke-game-web.mjs is two plank crates, two marble plates in brick pockets and an iron gate on a stone floor (pattern materials). The player walks into the first crate and pushes it onto its plate, crosses over and pushes the second; when both plates are pressed the gate part is hidden and the game is won. The smoke checks that the page loads only its own files, that the wasm comes from engine/physics/, that both crates moved, and that an export without physics carries no engine/physics/ folder.
Animation and NPCs
player.animation and each npcs[].animation hold a clip set and an animation graph as plain data. The player or NPC node is the character, and its child nodes are the parts the clips move: a body, legs, arms. The web build plays them with the same graph, root motion and path follower as the code API.
{
"player": {
"node": "walker", "walkSpeed": 1.4,
"animation": {
"clips": {
"idle": { "duration": 1, "tracks": [{ "target": "body", "property": "translation", "keyframes": [{ "time": 0, "value": [0, 0, 0] }, { "time": 1, "value": [0, 0, 0] }] }] },
"walk": { "duration": 1, "tracks": [{ "target": "body", "property": "translation", "keyframes": [{ "time": 0, "value": [0, 0, 0] }, { "time": 1, "value": [0, 0, 1.4] }] }] }
},
"parameters": { "speed": { "type": "number" } },
"rootMotion": { "bone": "body" },
"layers": [{ "name": "base", "states": [{ "name": "move", "blend": { "parameter": "speed", "motions": [{ "clip": "idle", "threshold": 0 }, { "clip": "walk", "threshold": 1.4 }] } }] }]
}
},
"npcs": [{ "node": "guard", "path": [[4, -6], [8, -6]], "cruiseSpeed": 1.4, "animation": { "...": "same shape; tracks target the guard's child nodes" } }]
}
clips: 1 to 16, each{ duration, loop (true), tracks }with up to 64 tracks of up to 256 keyframes. A tracktargetis a child node of the character (never the character itself, which the controller or follower moves) andpropertyistranslationorrotation(a quaternion), in the parent's space.parameters,boneGroups,layersandrootMotionare the graph definition with every field and limit of animation-graph: 1D and 2D blend spaces, transitions, layers with masks. Clip names refer toclips; mask joints are child node ids.drive(player only) maps a graph parameter to a controller value:speed,intentSpeedorairborne. The default setsspeedfromintentSpeedwhen there isrootMotion(the clips then move the player by the travel of the last step) and fromspeedotherwise.- An NPC needs
rootMotionand a number parameterspeed. Its path follower setsspeed, so idle, walk and run blend; it moves by the root motion, turns at corners and stops at the last of up to 256[x, z]waypoints, wherespeedreturns to 0.cruiseSpeedis 2.2 by default;yawandfootOffsetwork as for the player. Each NPC node is separate from the player and the other NPCs. - Root travel along +Z works as written; for clips whose root travels -Z set
rootMotion.facingto"-z".
A wrong field is refused with its path and the values to use, for example player.animation.clips.walk.tracks[0].target names "Ghost", which is not a child node of the character. window.__game.animation and window.__game.npcs expose the graphs.
A placed character
When the player or an NPC node is a placed catalog asset (asset: { id }), animation.clips names clips of asset files instead of keyed tracks: { "walk": { "from": { "asset": "<catalog id>", "clip": 1 }, "loop": true, "scale": 1 } }. Leave out from.asset for a clip of the character's own file; a clip of another humanoid is retargeted onto the character's skeleton by the humanoid bone map, as in an asset recipe's motion.layers. rootMotion.bone, boneGroups and mask joints name joints of the character's skeleton, such as Hips. The game turns the node half a circle because a glTF model faces +Z while yaw 0 faces -Z. The bone map, clip indexes and graph are checked when the game starts, and the error names the field. Pass assets (a Map keyed by assetCopyKey(id, copy)) to startGame, or assetUrls (asset id to GLB URL), which the web export fills in. A character animates through scene.setAssetPose, so it takes its own decoded copy of the asset and counts toward the 16 animated placements.