crucible README

项目的 README,来自 github.com/codepawl/crucible。合并为一个 markdown 文件:README.md。

Crucible

The 3D engine your AI agent drives

npm version License: MIT Node.js 20.19 or later MCP server for agents

Website · Docs · Showcase · Guide for agents · Changelog · Discussions

A sunlit classroom with wooden desks and chairs, a chalkboard and tall windows with blinds, path traced by Crucible
Classroom by Christophe Seux, CC0, from the Blender demo files, path traced in Crucible with Cook

A gold and steel gyroscope with a glowing teal core, turning, rendered by Crucible A low camera pan over a warehouse floor with yellow lines and racks, drawn without flicker The native path tracer focusing from a red sphere in front to a gold and a purple sphere behind it

Crucible is a 3D engine for JavaScript with an MCP server for AI agents. It makes 3D easy to understand and easy to do.

67js → Crucible. 67js is the old name. The @codepawlhq/67js package is deprecated: install @codepawlhq/crucible instead. Old 67js.codepawl.com links redirect here.

The agent knows every part of Crucible and carries the heavy steps. It builds the scene, lights it, checks the preview and renders the result. You keep the creative choices and stay in the loop, because the agent shows previews and asks when a matter of taste is open.

Scenes built with Crucible open live in the browser on the showcase.

Airport ramp, rendered by Crucible Container port, rendered by Crucible A monastery courtyard with a stone well, seen from a desk with an open book, path traced by Cook A robot model in the object studio, rendered by Crucible

What it is

Crucible is a 3D engine for AI agents and for pages. It has a real-time rasterizer, a path tracer, addons for terrain, vegetation, characters, liquid, vehicles and media export, and an MCP server. A scene is plain data: each part has a geometry, a matrix and a material.

An agent builds and changes a scene through the MCP server, looks at PNG previews and renders stills or MP4 video. The goal is to be as capable as Blender and as light as three.js. docs/goal.md defines each part. See the documentation, the guide for agents and the FAQ.

Install

Let your agent do it. Paste this prompt into Claude Code, Codex, Cursor, Gemini CLI or OpenCode. The agent installs the package, reads the guide and connects the MCP server.

Install Crucible from npm as `crucible@npm:@codepawlhq/crucible` and connect its MCP server with `npx crucible-mcp`. Read
https://crucible.codepawl.com/llms.txt first and follow it.

Claude Code plugin. One command adds the MCP server and both skills.

/plugin marketplace add codepawl/crucible
/plugin install crucible@crucible

By hand

npm install crucible@npm:@codepawlhq/crucible

The registry name is @codepawlhq/crucible, and the alias crucible keeps imports short. The package is ESM and needs Node.js 20.19 or later. Glaze and the WebGL2 path tracer need a WebGL2 browser, and the WebGPU backends need WebGPU.

A new minor version ships about once a week. Before 1.0, a minor version can change the API, and CHANGELOG.md lists each change. npx keeps the copy it downloaded first. To update, run npm install crucible@npm:@codepawlhq/crucible@latest or npx -y -p @codepawlhq/crucible@latest crucible-mcp.

Quick start

import { CrucibleRenderer, box, sphere } from 'crucible';

// Column-major 4x4 matrix: scale, then move.
const placed = ([x, y, z], [width, height, depth] = [1, 1, 1]) =>
  new Float32Array([width, 0, 0, 0, 0, height, 0, 0, 0, 0, depth, 0, x, y, z, 1]);

const parts = [
  {
    name: 'Floor',
    geometry: box(),
    matrix: placed([0, 0, 0], [8, 0.1, 8]),
    material: { color: [0.4, 0.42, 0.45], metallic: 0, roughness: 0.9, emission: 0 },
  },
  {
    name: 'Ball',
    geometry: sphere(48, 24),
    matrix: placed([0, 1, 0]),
    material: { color: [0.8, 0.3, 0.2], metallic: 0, roughness: 0.35, emission: 0 },
  },
];

const canvas = document.querySelector('canvas');
const renderer = new CrucibleRenderer(canvas, parts, { samples: 4, memoryBudgetMiB: 256 });
renderer.render({ eye: [4, 3, 6], target: [0, 1, 0] });

Call renderer.updateParts(parts) to move or recolour parts without a new upload. Call renderer.resize() after the canvas changes size, and renderer.dispose() before you replace the renderer. The guide covers cameras, lights, effects and every material field. To save a PNG from a script, use the render-from-a-script recipe.

For agents

The package includes an MCP server that connects an agent to a persistent browser renderer. The server needs a local Chrome installation.

npx crucible-mcp --backend gpu --memory 192

--backend gpu renders with hardware WebGL2 through Chrome. Use --backend cpu on a machine without a GPU. With bun, bunx crucible-mcp takes the same flags; CI runs the packaged server under bun on every pull request. An agent authors a JSON recipe, sets lights and fog, imports GLB assets and adds motion. It gets PNG previews back, compares up to four views in a review grid and runs render jobs for stills and MP4 video. The server accepts no arbitrary code and no remote asset URLs. The MCP reference lists its tools.

Two skills teach an agent to drive the MCP tools: build-crucible-scene for scenes and materials, and render-crucible-media for image and video export. For a plain-text guide, give the agent llms.txt.

viz3d uses Crucible. It is a skill that turns places, systems and events into 3D apps and films, and it renders its films and stills in Crucible. To add it in Claude Code, run /plugin marketplace add codepawl/viz3d, then /plugin install visualize-in-3d@codepawl.

Render images and video

The render command exports a scene to PNG or MP4 through headless Chrome, on the GPU or on the CPU.

npm run render -- --kind image --scene nature --backend gpu --preset high --output artifacts/nature.png

Video export streams one frame at a time, so a film never sits in memory. The render skill lists every preset and flag.

Addons

Each addon is a separate import, so a page loads only what it uses.

Area Import Guide
Lighting crucible/addons/hdri Image-based lighting from .hdr files
Terrain crucible/addons/terrain, crucible/addons/texture-set Chunked terrain with scanned ground layers
Vegetation crucible/addons/vegetation, crucible/addons/grass, crucible/addons/clutter Trees, grass and ground clutter with wind and level of detail
Characters crucible/addons/gltf, crucible/addons/retarget, crucible/addons/skeleton-pose glTF import, clip retargeting and pose layers with IK
Liquid crucible/addons/spume Baked liquid playback with refraction and spray
Vehicles crucible/addons/vehicle Wheeled vehicles on a path
Physics crucible/addons/physics Rapier contacts and joints recorded into a timeline
Live games crucible/addons/runtime Game loop with fixed or variable steps and pluggable systems
Live games crucible/addons/input Input: keyboard, mouse, gamepad, touch, device motion, replay and custom sources mapped to named actions and axes
Live games crucible/addons/streaming Streaming: loader plugins, distance and request loading, a byte budget with LRU eviction and LOD with hysteresis
Live games crucible/addons/netcode Netcode: server or host authority, pluggable transports, delta snapshots, client prediction with reconciliation and remote interpolation
Live games crucible/addons/physics-runtime Live physics: a physics world stepped in the game loop, contact and sensor events, ray, shape and overlap queries
Live games crucible/addons/physics-jolt Jolt engine: a second engine for live physics, with the same events and queries; needs the optional jolt-physics package
Live games crucible/addons/audio Spatial audio: sounds on nodes, played from contacts, markers and input, with buses and a limiter
Live games crucible/addons/animation-graph Animation graph: states, 1D and 2D blend spaces, parameter transitions with crossfades and masked layers for any rig
Live games crucible/addons/player Player: character, vehicle and flight controllers, follow, first-person, top-down, orbit, chase and side-scroller camera rigs with wall pull-in, custom kinds, swappable at runtime
Live games crucible/addons/game-rules Game rules: a JSON rule document of variables, triggers and actions, played as a runtime system
Live games crucible/addons/game Game: a scene recipe with a game section played in a page, and the scene_export_web MCP tool that writes it as a static web build
Modeling crucible/addons/mesh, crucible/addons/modeling, crucible/addons/sculpt Mesh editing, modeling and sculpt brushes
Offline light crucible/addons/path-tracer, crucible/addons/light-bake Path-traced stills and baked lightmaps
Post passes crucible/addons/user-pass Your own full-screen GLSL passes: dither, pixel downscale, quantise
Agents crucible/addons/agent-scene, crucible/addons/agent-asset Scene sessions with revisions and checkpoints

The documentation page lists every guide.

Renderers

Name What it is Runs on
Glaze (CrucibleRenderer) The real-time rasterizer WebGL2
Cook The path tracer, one still per job CPU (default), WebGL2, Vulkan ray queries through the optional Cook package (@codepawlhq/cook), and WebGPU (opt-in, library only)
Real-time path tracer A hybrid tracer with a radiance cache and a temporal denoiser. It is experimental, and the MCP server does not expose it WebGPU, with a WebGL2 fallback
Light bake Baked lightmaps CPU, WebGL2 and WebGPU

The WebGPU backend of Cook traces a BVH in WGSL compute, because browsers have no hardware ray tracing. MCP render jobs take the Cook backends cpu, gpu and native only.

Quality tiers

The roadmap in issue 890 groups the renderers into four tiers. The tier names are working names. The quality setting that picks a tier ships: scene_render_submit takes settings.quality (Render quality). Refine-at-rest is planned (issue 903). The path tracer planned for realtime-high does not exist yet (issue 901 and issue 902).

Six scenes at 960x540, medians over 3 interleaved runs on an idle card. FLIP is the error against a Cycles 4096-sample reference, and lower is better. Every value is the range of the per-scene medians across the six scenes. The full per-scene tables are in the bench/tiers folder. They land with pull request 931, after pull request 921 and before this one.

Tier For Runs on Trade-off Crucible measured Blender measured FLIP vs Cycles
draft A quick look while editing Glaze, 0.5 render scale, 1 sample, light shading, 8 bit target Aliased edges, no environment lookup, a quarter of the pixels enlarged 0.54 to 1.04 ms a frame with the pixel read; 0.26 to 0.33 ms queued back to back EEVEE 5.3, 1 sample: 56 to 59 ms a render call Glaze 0.045 to 0.188, EEVEE 0.041 to 0.562
realtime Interactive use Glaze, default settings Indirect light is approximate 0.77 to 0.98 ms a frame with the pixel read; 0.35 to 0.50 ms queued back to back EEVEE 5.3, 64 samples: 288 to 363 ms a render call Glaze 0.030 to 0.197, EEVEE 0.042 to 0.562
realtime-high Better interactive frames Planned: Glaze on WebGPU with a GI cache and upscaling (issue 901, issue 902) More VRAM not measurable yet none none
final Finished stills Cook native, 256 samples (Vulkan ray queries, the optional @codepawlhq/cook package) More samples than Cycles for the same noise 1.73 to 4.24 ms a sample; 0.71 to 1.32 s for 256 samples with setup Cycles 5.3 OptiX: 6.81 to 26.41 ms a sample; 3.43 to 8.46 s for 256 samples with setup Cook native 0.019 to 0.080, Cycles 0.010 to 0.039
final Finished stills Cook webgpu, 256 samples (WGSL compute, software BVH, library only) Slower per sample than native, same image 5.88 to 17.33 ms a sample; 1.94 to 4.86 s for 256 samples with setup same Cycles Same as native: FLIP between the two images 0.0000 to 0.0003

Glaze runs the realtime tier in under about 1 ms a frame at 960x540 on these scenes (0.77 to 0.98 ms), measured with a pixel read. The EEVEE times are one full background render call, including scene sync, with EEVEE ray tracing off and no global illumination. They are not a frame rate comparison. The draft tier is not faster than realtime here. At 960x540 a Glaze frame costs about as much as the browser pixel read, so the queued figures are the ones that differ.

Cook native draws a sample 3.8 to 6.2 times faster than Cycles 5.3 OptiX, but needs more samples for the same noise. On the three noise-limited scenes (lit-interior, spot-area and light-linking) it needs 6.6 to 19.0 times Cycles' samples for the same error. That makes it 1.05 to 4.02 times Cycles' time for the sampling alone, and 0.87 to 2.52 times with setup included.

On metal, glass and outdoor-hdri the error falls slower than 1/N between 256 and 1024 samples, which points to bias. Cook does not reach Cycles' error there, so no equal-error ratio is given. Cook webgpu draws a sample 3.3 to 4.1 times slower than native.

Cook gpu (WebGL2) and Cook cpu are not in this run. Cook cpu needs no card, so VRAM does not apply. docs/cycles-parity.md has the Cook against Cycles method on one scene.

The experimental real-time path tracer is not the realtime-high tier. These figures come from lit-interior only, measured before the idle gate with the card 17 to 20 percent busy. On the WebGPU backend it draws a frame in 5.6 ms. FLIP drops under 0.20 after 16 frames (0.15 s) and under 0.10 after 64 frames (0.41 s). It ends at 0.056 after 256 frames.

The WebGL2 fallback takes 6.7 ms per frame and 6.1 s for the first frame, which includes shader compile. It runs at 2 bounces against an 8-bounce reference.

Machine: RTX 3060 12 GB (driver 621.14), Intel i7-14700KF, Chrome 157 headless on D3D11, Node 24, Blender 5.3, measured 2026-11-11. The card was idle: each run waited for at most 15 percent utilisation, and 0 of 162 runs were contended.

Performance

Each number below comes from this repository's benchmarks.

docs/verification.md has older results and their limits. They compare matching scenes on the same hardware. They do not show a general speed advantage over three.js or visual parity with Blender.

Run the site locally

  1. Install Node.js 22.12 or later.
  2. Run npm ci.
  3. Run npm run dev. Vite prints the local URL.

Contributing

Read CONTRIBUTING.md before you open a pull request. It covers setup, checks, code style and the release flow. Coding agents start with AGENTS.md, and npm run preflight runs the pull request checks locally. Questions, ideas and what you made go in Discussions. Bug reports: SUPPORT.md.

Sponsors

Crucible is free and MIT licensed. Sponsors pay for GPU time, test hardware and the hours that go into it. Company sponsors get their logo here from $100 a month.

Sponsor CodePawl

Credits

License

MIT © CodePawl


CodePawl
Crucible is made by CodePawl, an independent 3D studio in Vietnam.
X · GitHub · YouTube · Threads

crucible (codepawl/crucible)

正在搜索数据库…

这是什么?67js 是一个可供 AI 智能体操作的 WebGL2 三维引擎。场景就是纯数据,智能体通过 MCP 服务器构建和修改场景,然后查看 PNG 预览图,并渲染静态图或 MP4 视频。
它是独立应用,还是我可以导入自己项目里的库?它是一个库。你可以把它以 ESM 包的形式导入网页,并且只加载你用到的插件。它还附带一个 MCP 服务器,方便智能体替你构建场景。
怎样让它跑起来?最简单的办法是把 README 中的安装提示词粘贴到 Claude Code、Codex、Cursor、Gemini CLI 或 OpenCode 里,让智能体安装包并连接 MCP 服务器。如果手动操作,请安装 @codepawlhq/67js,导入时使用别名 67js。
我需要先准备什么?工具需要 Node.js 20.19 或更高版本,渲染需要支持 WebGL2 的浏览器,MCP 服务器需要本地安装 Chrome。
它能达到 Blender 的水平,还能超过 three.js 吗?尚未得到证实。目标是功能像 Blender 一样全面,同时像 three.js 一样轻量。但 README 中写明,其基准测试并未显示相比 three.js 有普遍的速度优势,也未显示与 Blender 的视觉效果完全一致。
它在哪里运行?通过 WebGL2 在浏览器中运行。MCP 服务器需要在运行它的机器上安装本地 Chrome。
没有 GPU 也能运行吗?可以。在没有 GPU 的机器上,给 MCP 服务器加上 --backend cpu 参数即可。
67js 的核心理念是什么?场景就是纯数据:每个部件都有几何体、矩阵和材质。智能体通过 JSON 配方编辑这些数据,因此服务器既不接受任意代码,也不接受远程资源 URL。
智能体实际能用它做什么?它可以编写 JSON 配方、设置灯光和雾效、导入 GLB 资源、添加运动,并返回 PNG 预览图。它最多可以在审查网格中并排比较四个视角,还能运行渲染任务,生成静态图和 MP4 视频。
这些插件涵盖哪些内容?地形、植被、带重定向和 IK 的 glTF 角色、烘焙液体、轮式车辆、Rapier 物理、网格建模、路径追踪静态图,以及自定义 GLSL 后处理通道。
作者
codepawl
大小
407 MB
星标
752
时长
1个月
提交 · 90 天