3D engine that AI agents drive
Data-only packs
A pack is a folder of material sets, recipes, looks, HDRIs and GLB models with a manifest and no code. Someone shares it as a zip, you unzip it into a local folder, and Crucible checks it when the MCP server starts. Nothing in a pack runs, and nothing is downloaded by a tool call.
Make a pack
my-pack/
crucible-pack.json
models/crate.glb
textures/brick.png
looks/warm.cube
hdri/studio.hdr
materials/rusty-metal.json
recipes/workshop.json
previews/workshop.png
crucible-pack.json at the root:
{
"format": "crucible.pack", "schemaVersion": 1,
"name": "my-pack", "version": "1.0.0", "engines": { "crucible": ">=0.19.0" },
"license": "CC0-1.0", "author": "Your Name", "description": "One line about the pack.",
"contents": {
"assets": [{ "id": "crate", "file": "models/crate.glb" }],
"images": [{ "id": "brick-albedo", "file": "textures/brick.png" }],
"looks": [{ "id": "warm", "file": "looks/warm.cube" }],
"environments": [{ "id": "studio", "file": "hdri/studio.hdr" }],
"materials": [{ "id": "rusty-metal", "file": "materials/rusty-metal.json" }],
"recipes": [{ "id": "workshop", "file": "recipes/workshop.json", "preview": "previews/workshop.png" }]
}
}
| Kind | Files | What it is |
|---|---|---|
assets |
.glb |
Self-contained GLB, the same files --assets takes |
images |
.png .jpg .jpeg .webp |
Map images and sequence frames |
looks |
.cube |
3D colour look (LUT_3D_SIZE) |
environments |
.hdr |
Radiance HDRI |
materials |
.json |
One material object, the fields of a materials entry in a recipe |
recipes |
.json |
A full recipe, as scene_create takes it; preview is an optional image |
Rules, all checked at load:
- Keys are known ones only.
nameand ids are kebab-case; ids are unique per kind.versionis three numbers.engines["crucible"]is a range of space-separated comparators (>=,>,<,<=,=,^,~, such as>=0.19.0 <1) that the installed Crucible satisfies. A prerelease or build suffix on the running version (0.21.0-rc.1) is ignored when comparing. - Paths are relative, with forward slashes, inside the pack: no
.., no absolute or drive paths, no backslashes, only letters, digits,.,_and-in each part. Every listed file must exist and have the extension of its kind. - No symbolic links. A pack folder holds only these files, anywhere in it:
crucible-pack.json; the files listed incontents(and a recipepreview); and text documents namedLICENSE,LICENCE,README,NOTICE,CHANGELOGorAUTHORS(any case, with an optional.mdor.txt) that are valid UTF-8 without NUL bytes and at most 1 MiB. Any other file, including a script or program (.js,.html,.svg,.wasm,.exe,.sh,.py), a file with no extension and a dotfile, refuses the whole pack: list it incontentsor remove it.crucible-pack.jsoncannot be listed as content. Listed binaries must start with the signature of their kind (glTF, PNG, JPEG, WebP,#?RADIANCEor#?RGBE), so a script renamed to.pngis refused. - Limits (
src/pack-manifest.js): 256 files, 256 MiB in total, 64 MiB per file, 1 MiB per JSON file, 64 items per kind; at most 32 packs load at once. Image files incontents.imagesfollow the catalog frame limits (1024 pixels a side), an.hdris at most 8 MiB and a.cube4 MiB; a larger one refuses the pack. A recipepreviewimage skips the pixel limit. - Recipe and material JSON nests at most 64 levels of objects and lists. They contain no remote URL, in a value or a key (
http:,https:,ftp:,//host,/\host, a scheme split by a tab or line break, adata:URL that is not a PNG, JPEG or WebP image). A recipe has"format": "crucible.scene".npm run pack:checkalso runs the validatorscene_createuses (a material is checked as the only material of an empty scene); the server leaves that toscene_createandscene_apply, which run it when the agent uses the item.
An error names the pack, the file and the field, and says what to pass instead.
Validate
npm run pack:check -- path/to/my-pack
It runs the same checks as the server and prints ok or FAIL with the error. The repository ships packs/example-starter/ (CC0) as a template to copy.
Install
The Marketplace page lists the published packs with a checksum. Unzip each pack into its own subfolder of one packs folder and start the server with that folder:
crucible-mcp --packs /absolute/path/to/packs
A pack that fails the checks is skipped and listed with its error under packs.rejected in scene_asset_catalog; the others still load. Changed files need a server restart, like --assets.
Use from an agent
scene_asset_catalog lists each pack's name, version, license, author, description and item ids. GLBs, images, looks and HDRIs carry the same SHA-256 assetId as --assets files (they also appear in the main assets list), so scene_create_asset, the look and hdri fields and texture sequences use them unchanged. For a material or recipe, call scene_asset_catalog with { "pack": "my-pack", "recipe": "workshop" } or { "pack": "my-pack", "material": "rusty-metal" } to read its JSON, then pass it to scene_create or use it as a materials entry. scene_capabilities topic packs has the limits.
Publish
Zip the pack folder with crucible-pack.json at the top of the archive, name the zip name-version.zip and host it anywhere, such as a GitHub release. State the license of every file in license and in a LICENSE file; Crucible does not check licenses. Run npm run pack:check first, and say which Crucible versions you tested.