3D engine that AI agents drive
name: build-crucible-scene description: Build, light, film and refine 3D scenes through the Crucible MCP server (npm package @codepawlhq/crucible). Use when an agent has the scene_* tools and must model parts, set materials, lights, HDRI, color looks, fog, lens and depth of field, animate a camera, lights, sun, sky and effects, bake light, fix z-fighting or recover from a tool error. Also for "làm cảnh Crucible", "dựng cảnh 3D bằng Crucible", "model bị răng cưa", "ánh sáng cảnh Crucible", "đổ bóng", "sương mù Crucible", "camera Crucible". Explosions, the PS1 retro look, vehicle dents and asking the person with pins or a lasso are covered too. Image and video export is the render-crucible-media skill. license: MIT
Build scenes with Crucible over MCP
You drive Crucible through the scene_* tools of the crucible-mcp server. No checkout is needed.
Start the server with npx --package @codepawlhq/crucible crucible-mcp --backend gpu --assets <abs dir> --jobs <abs dir>
(--assets for GLB, HDR and cube files, --jobs for render jobs, --backend cpu without a GPU).
Loop
scene_capabilities: with no arguments it returns a short index of features, limits and topic names. Passtopic(one name or a list of up to 8) for the field list of a feature (environment,materialFields,geometries,meshEdit.bevel,motion) orexamples.scene_applyfor a complete call of a hard tool. Tool schemas list only common fields, so read the topic before a feature you have not used. Ask for every topic you need in one list call, not one call per topic. In a list, a wrong name does not fail the call: the valid topics answer and the wrong ones come back inunknownwith suggestions.scene_createwith arecipe:{ "format": "crucible.scene", "schemaVersion": 1, "geometries": [], "materials": [], "nodes": [] }plus optionalcamera,environment,effects,shadow,motion,bake,timeline.scene_inspect: node IDs, bounds,diagnostics, currentrevision.scene_look: the PNG. Addlabels: trueto match node names to the image. Judge the image, not the lint. Never submit a render job for a scene you have not looked at (scene_look, orscene_reviewfor several angles).scene_applywith the currentexpectedRevisionand a smalloperationsbatch. A stale revision fails whole.scene_checkpointbefore a risky batch,scene_restoreto undo,scene_release_checkpointafter. Without a checkpoint,scene_restorewithrevisiongoes back to one of the last 4 earlier revisions.scene_export_recipekeeps the result.scene_disposea scene you finished with.
Beside the loop: mesh_inspect, mesh_edit and mesh_stack edit polygon meshes (see the modeling row below), and
scene_walkmap returns a grid of walkable and blocked cells for placing characters and paths. scene_ask_user lets the person
pin notes (or lasso a region) on the view when a change is hard to put in words; scene_export_web with review: true does the
same on a phone. Shared materials, lassos and reviewFile are in effects-and-feedback.md.
sessionId may be left out: the last used scene is meant. With two scenes open, pass it on every call. The server keeps 4 scenes and closes the least recently used (evictedSessions in the create result), and 16 checkpoints per scene, oldest first (evictedCheckpointIds).
Variants: scene_apply with a branch name, compare in one scene_review (a branch per shot), keep one with scene_restore.
Pick the recipe
| Task | Read |
|---|---|
Sky, HDRI, .cube look, tone mapping, fog, exposure, bloom, AO, outlines |
${CLAUDE_SKILL_DIR}/references/look.md |
| Sun, point, spot and area lights, caps, baked bounce light, flush faces | ${CLAUDE_SKILL_DIR}/references/light.md |
| Colour, patterns, glass, clearcoat, water tags, shader hooks, judging a surface | ${CLAUDE_SKILL_DIR}/references/materials.md |
| Spray, dust, sparks, sea foam, particle caps, fog and beams | ${CLAUDE_SKILL_DIR}/references/particles-and-vfx.md |
| Lens, focal length, depth of field, shift, orthographic | ${CLAUDE_SKILL_DIR}/references/camera.md |
| Motion tracks (camera, nodes, lights, sun, sky, effects), shots, timeline | ${CLAUDE_SKILL_DIR}/references/film-and-animation.md |
| A call failed, a diagnostic appeared, the picture is wrong | ${CLAUDE_SKILL_DIR}/references/errors-and-recovery.md |
Explosion, material.retro, vehicle damage, pins and lasso from the person, review page, splat palette |
${CLAUDE_SKILL_DIR}/references/effects-and-feedback.md |
| A playable game: animate a placed, retargeted character (idle, walk, run), web export | ${CLAUDE_SKILL_DIR}/references/game.md |
| Polygon modeling: extrude, inset, bevel, booleans, mirror, array | ${CLAUDE_SKILL_DIR}/references/mesh-modeling.md |
| Scene code against the npm library, not MCP | ${CLAUDE_SKILL_DIR}/references/scene-contract.md |
Defaults that save work
- Start from the default look:
environment.setupdaylight, AO off.studiosuits products,overcastsoft light,sunsetwarm low light. Do not hand-tune key, fill and ambient first. - The preview draws a floor with a contact shadow under the lowest geometry.
environment.ground: falseremoves it, so never add a floor node only for the shadow. - Sizes:
boxis a unit cube;cylinderandspherehave radius 1, so node scale x/z (cylinder) or scale (sphere) is the radius, not the diameter. A 6-segment cylinder has flats on Z (1.732 x scale apart) and corners on X. - Stack parts from numbers: write each part's bottom and top Y first, adding the Y of the surface it stands on (a height "above
the slab" is measured from the slab's top, not from Y = 0). After building, compare
scene_inspectbounds with the task's numbers. - A real-world object (vehicle, tree, furniture, character, prop): look in
scene_asset_catalogfirst and place the GLB with theassetnode field. Build it from primitives or a mesh recipe only when the catalog has nothing usable, and say what you searched for. Do not stack boxes and cylinders for something that exists as a model. - Never guess a field or a range: read the
scene_capabilitiestopic for it first. Do not setenvironment.ground: falseor hand-frame a camera for a skinned GLB: since #1976 the auto-frame and the floor use its posed bounds. - Reuse one geometry ID for repeated parts and move them with node transforms.
- To place a part by a face height ("upper surface at 0.5"), use
relations: [{ "kind": "level", "at": "top", "y": 0.5 }](bottomorcentertoo) instead of adding half the thickness to a centre; Y is where that face lands, in world metres. - Put parts against each other with node
relations(attach,gap,flush,align,centered) so oneset-noderesizes the body and the handle follows. - Surfaces without UVs: material
pattern(wood, bricks, marble, metal, fabric). Glass:transmissionwith a nonzerothickness. Details are inscene_capabilities. - Hide a node with
visible: false;castShadow,receiveShadow,holdoutandshadowCatcherare node flags too; a window pane takesrayVisibility: 'glass'so the path tracer lets sun and sky through (the last two need a transparent canvas, so they matter for exported composites, notscene_look). - Characters and creatures: recipe
armaturesplusskinper mesh node,motion.ik, imported GLBs through theassetnode field andscene_asset_catalog. Physics, cloth, particles and hair are recipe sections.scene_inspectreports their results; read those instead of guessing from a picture. - A catalog GLB ID is the file's SHA-256 and changes on a re-export. Place by name instead:
asset: { "name": "sheep_body.glb" }(assetNameinscene_create_asset); passidorname, not both. - A folder of more than 256 numbered images appears once under
sequencesinscene_asset_catalog. Usemap: { sequence: { catalog: "frame_####.png", fps } }on a material, not aframeslist. - Third-party controller or camera kinds exist only when the server owner started it with
--addonsand--allow-addon: readscene_capabilitiestopicaddonsfor the names, then setgame.player.controllerorgame.camerato one. You cannot load an addon from a tool. - A GLB for Blender:
scene_export_glb(needs--jobs), it returns a path.
Finish
Deliver the recipe, one scene_look image and any limit you hit. Say what you measured (counts, bounds, seconds)
apart from what you judged by eye. Do not claim Blender parity or general speed over three.js. Build scenes with these tools, not with a bare three.js script.
Changes, including unreleased and breaking ones: https://crucible.codepawl.com/changelog.json.
A Crucible bug: gh issue create -R codepawl/crucible with the steps, the recipe and a still; no local paths.