crucible

# Crucible

> A 3D engine that AI agents drive. Glaze draws real-time scenes on WebGL2, and Cook path traces stills on the CPU or WebGL2, and on Vulkan with the optional Cook package. PNG, MP4 and GLB output comes from the same scene.

Crucible has an MCP server (`crucible-mcp`, 25 tools) that builds, edits, looks at and renders scenes from JSON recipes.
The same engine is a JavaScript library for pages and Node. The library API is in the guide below.
Scenes are plain data with stable IDs, so an agent can edit by ID and check each change with a rendered image.

## Renderers

- Glaze (`CrucibleRenderer`) is the real-time rasterizer. It runs on WebGL2 only.
- Cook is the path tracer. Its backends are cpu (the default), gpu (WebGL2), webgpu (a software BVH in WGSL compute) and native (Vulkan ray queries, from the optional Cook package, `@codepawlhq/cook`).
- An experimental real-time path tracer runs on WebGPU with a WebGL2 fallback. The MCP server does not expose it. MCP render jobs take the cpu, gpu and native backends of Cook.
- In the MCP server, `--backend gpu` means hardware WebGL2 in Chrome, and `--backend cpu` means software rendering.
- `scene_render_submit` takes `settings.quality` (draft, realtime, realtime-high, final) and falls back one tier when a tier cannot run; the tiers are in [Render quality](https://crucible.codepawl.com/mcp.md#render-quality).
- Planned, not shipped: Glaze on WebGPU, the real-time path tracer behind `realtime-high`, and refine at rest. The roadmap is [issue 890](https://github.com/codepawl/crucible/issues/890).

## Connect

- npm package: `@codepawlhq/crucible`. The MCP server is its `crucible-mcp` binary. Node.js 20.19 or newer and an installed Chrome are required.
- Claude Code plugin, which adds the server and both skills: `/plugin marketplace add codepawl/crucible`, then `/plugin install crucible@crucible`.
- Any other MCP client: `npm install crucible@npm:@codepawlhq/crucible`, then run Node on `node_modules/crucible/bin/crucible-mcp.mjs --backend gpu --memory 192` over stdio. Use the absolute path.
- Setup, flags and client notes: [mcp.md](https://crucible.codepawl.com/mcp.md).
- Skills in the package: `skills/build-crucible-scene` (build and light) and `skills/render-crucible-media` (stills and video).

## Start

1. Call `scene_capabilities`. It reports the recipe fields, limits and budgets, and it is the source for field detail.
2. Create a scene, call `scene_inspect` for IDs and the revision, edit in small batches, and call `scene_look` after each batch.
3. Checkpoint before a risky change. Restore it if the picture is worse. Call `scene_dispose` when finished.

## To do X, call Y

- Create a scene: `scene_capabilities`, then `scene_create` with a JSON recipe, or `scene_asset_catalog` and `scene_create_asset` for a GLB. [Docs](https://crucible.codepawl.com/agent-scene.md)
- Edit parts, transforms and the camera: `scene_inspect` for stable IDs and the revision, then `scene_apply` with `expectedRevision`. [Docs](https://crucible.codepawl.com/agent-scene.md)
- Shape geometry: `mesh_inspect`, `mesh_edit`, `mesh_stack`. [Docs](https://crucible.codepawl.com/mesh.md)
- Materials, looks, HDRI, fog, effects: `scene_apply` with `set-material`, `set-environment`, `set-effects`, `set-shadow`; `scene_asset_catalog` lists HDRI and look IDs. [Docs](https://crucible.codepawl.com/agent-look.md)
- Lights and shadows: `scene_apply` with `set-environment` (sun, sky, point lights) and `set-shadow`. [Docs](https://crucible.codepawl.com/lighting.md)
- Camera and lens: `scene_apply` with `set-camera`; check the framing with `scene_look` or `scene_review`. [Docs](https://crucible.codepawl.com/camera-path.md)
- Animation: `scene_apply` with `set-motion`; preview with `scene_look` and `motionTime`. [Docs](https://crucible.codepawl.com/agent-motion.md)
- Imported character motion: `scene_inspect` with `kind: hierarchy`, then `scene_apply` with `set-asset-node`. [Docs](https://crucible.codepawl.com/agent-character-motion.md)
- Bake light: Put `bakes` in the recipe; `scene_capabilities` lists the fields. [Docs](https://crucible.codepawl.com/light-bake.md)
- Review the result: `scene_look` for one PNG, `scene_review` for a labeled grid of up to four views. [Docs](https://crucible.codepawl.com/agent-review.md)
- Render a still or a video: `scene_render_submit`, poll `scene_render_status`, read `scene_render_result`, then `scene_render_release`. [Docs](https://crucible.codepawl.com/agent-render-jobs.md)
- Export a model: `scene_export_glb`, or `scene_export_recipe` for the JSON recipe. [Docs](https://crucible.codepawl.com/export-glb.md)
- Make a playable game: `scene_apply` with `set-game` (topic `game` in `scene_capabilities`), then `scene_export_web` for a static folder. [Docs](https://crucible.codepawl.com/game.md)
- Recover from an error: `scene_restore` to a `scene_checkpoint`, or `scene_inspect` for the current revision and retry; every error names its next step. [Docs](https://crucible.codepawl.com/mcp.md)

## All tools

- `scene_capabilities`: Index of supported recipe features and runtime budgets; pass topic for the detail of one.
- `scene_create`: Create a render scene from a JSON recipe; the result has its sessionId.
- `scene_asset_catalog`: List content-bound GLB, image, HDRI and look IDs from the asset directory and installed packs.
- `scene_create_asset`: Create the active scene from a catalog GLB and editable asset recipe.
- `scene_inspect`: Read revision, counts and selected nodes.
- `scene_walkmap`: Walkable map on a grid: rows of . walkable, x blocked, # no surface.
- `mesh_inspect`: Check recipe geometries as polygon meshes: vertex, edge and face counts, triangles/quads/n-gons, connected and closed parts, face tags...
- `mesh_edit`: Append edits to a recipe mesh geometry or an imported asset part such as mesh-0 (or replace its edit log), atomically like scene_apply:...
- `mesh_stack`: Set the non-destructive modifier stack of a recipe mesh geometry (ops and fields: scene_capabilities meshModifiers), evaluated after its...
- `scene_apply`: Atomically edit transforms, look, camera or materials.
- `scene_look`: Render the active scene as a bounded PNG, optionally with part labels.
- `scene_ask_user`: Open the view in the browser so the person pins points with notes; waits for Send.
- `scene_review`: Compare one to four independent camera or motion samples in one labeled PNG grid.
- `scene_checkpoint`: Save a private recipe snapshot.
- `scene_restore`: Restore a checkpoint atomically using the current revision.
- `scene_release_checkpoint`: Release one checkpoint slot.
- `scene_export_recipe`: Read a detached canonical JSON recipe for reproduction.
- `scene_export_glb`: Write the active scene as a GLB file in the configured jobs folder, under a server-chosen name (the result has the path, byte count and...
- `scene_export_web`: Write the scene with its game as a static web build in the jobs folder: index.html, game.json and engine/, which any static host serves...
- `scene_dispose`: Dispose the active scene and its checkpoints, releasing renderer resources.
- `scene_render_submit`: Start one asynchronous snapshot job in the configured private job store.
- `scene_render_status`: Read render job state and durable frame progress.
- `scene_render_cancel`: Request cancellation of one job.
- `scene_render_result`: Read completed local output paths, MIME types, byte counts, SHA-256 digests and measured render metrics.
- `scene_render_release`: Delete the owned files and record for a terminal job, freeing store quota.

Call `scene_capabilities` for field detail. This list is generated from the server's tool registry by `scripts/generate-llms.mjs`.

## If you know three.js

Models write three.js from memory. The section "If you know three.js" of the [complete guide](https://crucible.codepawl.com/guide.md) maps each common three.js idiom to the Crucible call. The optional addon `@codepawlhq/crucible-three-compat` (folder `packages/three-compat`, not on npm yet: import it from a source checkout) accepts the common three.js shapes (`Scene`, `Mesh`, `MeshStandardMaterial`, `PerspectiveCamera`, the light classes, `GLTFLoader`, `setAnimationLoop`) and builds Crucible parts from them. It throws an error that names the Crucible call when you use a name it does not support.

## Docs

- [Complete plain-text guide](https://crucible.codepawl.com/guide.md): renderer, parts, materials, cameras, animation, export and troubleshooting.
- [MCP server](https://crucible.codepawl.com/mcp.md), [scene recipes](https://crucible.codepawl.com/agent-scene.md), [look and lighting](https://crucible.codepawl.com/agent-look.md), [motion](https://crucible.codepawl.com/agent-motion.md), [review](https://crucible.codepawl.com/agent-review.md), [render jobs](https://crucible.codepawl.com/agent-render-jobs.md), [imported assets](https://crucible.codepawl.com/agent-asset.md).
- [GLB contract](https://crucible.codepawl.com/gltf.md): supported assets and conversion limits.
- [Release metadata](https://crucible.codepawl.com/release.json): package name, version, install command and commit.
- [Changelog data](https://crucible.codepawl.com/changelog.json): every release and the unreleased changes with issue numbers and breaking flags. Read it before relying on a feature the docs describe.