DOCS // SPATIAL.COMPILER 0.1.0

Spatial Compiler docs

Headless GPU compilation for 3D geometry and physics. Turn raw AI-generated meshes into production-ready, simulation-ready assets with one API call, delivered natively via MCP and REST. Its pyro module bakes fire, smoke, explosion and dust flipbooks for Godot 4.

What Spatial Compiler does

Spatial Compiler is Applied Manifold's flagship GPU execution engine. Send raw .glb or CAD geometry over MCP or REST and get back decimated, UV-packed, physics-ready assets with structured telemetry.

Applied Manifold built it from the metal up as a headless, stateless Vulkan compute kernel wrapped in a memory-safe Rust gateway. It has no windows or GUI overhead, so software and AI agents can call it in a tight loop.

  • The kernel is headless C++20 on Vulkan 1.3, with a persistent Buffer Device Address (BDA) arena kept warm in VRAM.
  • The gateway is memory-safe Rust and speaks MCP over stdio, MCP over HTTP at https://mcp.spatialcompiler.dev, and REST at https://api.spatialcompiler.dev.
  • A SHA-256 content-addressed cache makes results deterministic, so the same input gets the same key and the same output.
  • Every compilation returns typed JSON telemetry (triangle counts, draw-call reductions, VRAM footprint) that your agent verifies in code.

The same core library, spatial_kernel, also runs as a local program, spatial-compiler (short name sc), that a Claude plugin drives. Each module makes one kind of asset, and the pyro module bakes fire, smoke, explosion and dust flipbook sheets from spec files named *.pyro.toml.

  • The program has no window or editor, so an agent runs each command and checks the result from files.
  • stdout carries the report JSON and nothing else, and logs go to stderr.
  • A misspelled key fails and names the nearest valid key, and spatial-compiler schema prints every field, range and default.
  • The same spec, seed, version and machine give the same bytes.

Install via MCP

Give Claude Code, Cursor or your CI/CD pipeline a GPU co-processor for 3D space. Spatial Compiler runs as a hosted MCP server at https://mcp.spatialcompiler.dev and as a local MCP server, the npm package @spatial-compiler/mcp, that runs over stdio through npx.

Hosted MCP server

Add the server URL to your MCP client. The hosted server uses an OAuth 2.1 browser login to your Applied Manifold account, with PKCE (S256), so the config holds no key:

mcp.json
{
  "mcpServers": {
    "spatial-compiler": {
      "type": "http",
      "url": "https://mcp.spatialcompiler.dev"
    }
  }
}

In Claude Code you can register it from the command line:

terminal
claude mcp add --transport http spatial-compiler https://mcp.spatialcompiler.dev

Local MCP server

The local server reads your API key from the SPATIAL_API_KEY environment variable and runs no login flow:

terminal
SPATIAL_API_KEY=sk_test_spatial_sandbox npx -y @spatial-compiler/mcp

Most MCP clients (Claude Desktop, Cursor and others) accept the same JSON config block:

mcp.json
{
  "//": "Local MCP server config (stdio via npx, credential in SPATIAL_API_KEY). Rendered at <!-- @mcp-json --> on /docs/#mcp and returned by the WebMCP get_mcp_config tool. The hosted config is derived from site.config.json MCP_URL (build/site.mjs hostedMcpConfig).",
  "mcpServers": {
    "spatial-compiler": {
      "command": "npx",
      "args": [
        "-y",
        "@spatial-compiler/mcp"
      ],
      "env": {
        "SPATIAL_API_KEY": "sk_test_spatial_sandbox"
      }
    }
  }
}

In Claude Code you can register it from the command line:

terminal
claude mcp add spatial-compiler -e SPATIAL_API_KEY=sk_test_spatial_sandbox -- npx -y @spatial-compiler/mcp

Replace the example key sk_test_spatial_sandbox with your own API key. Sandbox keys include 500 free credits.

MCP tools

One endpoint handles the entire last-mile pipeline:

compile_3d_asset Geometry & Materials
Welds non-manifold edges, decimates to exact triangle budgets via meshoptimizer, packs non-overlapping xatlas UV atlases, and bakes channel-packed ORM textures in a single VRAM pass.
simulate_fx_vat Physics
Runs parallel GPU XPBD cloth and Voronoi rigid-body fracture rollouts, exporting zero-CPU-cost Vertex Animated Textures (VATs) and drop-in engine shaders.
bake, check, schema, sweep, wire pyro
One typed tool per command of the spatial-compiler program, covered in Bake and wire. Each returns the same JSON report as the command.

REST overview

The Rust gateway exposes the same operations over REST. Authenticate with your API key as a bearer token in the Authorization header, and send the mesh as multipart form data with a JSON options field.

terminal
curl -X POST https://api.spatialcompiler.dev/v1/compile \
  -H "Authorization: Bearer sk_test_spatial_sandbox" \
  -F "file=@model.glb" \
  -F 'options={"target_tris":15000,"dry_run":true}'
The OpenAPI description of POST https://api.spatialcompiler.dev/v1/compile is at /openapi/spatial-compiler.json.

Operations reference

target_tris and dry_run are the core options. Other options in the examples on this site are illustrative.

weld compile_3d_asset

Welds non-manifold edges so downstream decimation, UV packing and baking operate on clean topology.

decimate compile_3d_asset · meshoptimizer

Decimates to an exact triangle budget (target_tris) using meshoptimizer. Telemetry reports triangles in and out.

lod_chain compile_3d_asset · optional

Optionally emits a chain of levels of detail: the same source decimated to several triangle budgets, with telemetry for each level.

uv_pack compile_3d_asset · xatlas

Packs non-overlapping UV atlases with xatlas, so the asset can carry baked textures.

orm_bake compile_3d_asset

Bakes channel-packed ORM textures (ambient occlusion, roughness, metallic in one texture) in the same VRAM pass as decimation and UV packing.

convex_hulls physics-ready output

Generates convex collision hulls so the compiled asset is physics-ready for engines and simulators.

xpbd_cloth simulate_fx_vat

Runs GPU-native XPBD (extended position-based dynamics) cloth rollouts in parallel on the GPU.

voronoi_fracture simulate_fx_vat

Splits a mesh into Voronoi cells and runs rigid-body fracture rollouts on the GPU.

vat_export simulate_fx_vat

Exports simulation rollouts as Vertex Animated Textures (VATs) with drop-in engine shaders, so playback costs zero CPU at runtime.

dry_run, cache and limits

dry_run: true
Every tool call supports a pre-flight estimate that costs 0 credits.
SHA-256 content-addressed cache
Results are keyed by a SHA-256 hash of the input. When an agent re-runs unchanged geometry it gets a cache hit, and cache hits cost 0 credits.
Per-key hourly velocity limits
Each API key has an hourly velocity limit, so a runaway agent loop cannot drain your credits.

Telemetry fields

Every compilation returns structured JSON with these fields, so your agent can verify the result in code.

FieldMeaning
statusOutcome of the call, e.g. ok.
dry_runWhether this was a zero-cost pre-flight estimate.
tris_inTriangle count of the input mesh.
target_trisRequested triangle budget.
tris_outTriangle count of the compiled mesh.
draw_callsDraw calls before → after compilation.
vram_bytesVRAM footprint of the compiled asset.
elapsed_msWall time of the compilation.
cacheHIT or MISS on the SHA-256 content-addressed cache.
credits_estEstimated credits: 5 for a standard compile (1 credit = $0.01), 0 for dry runs and cache hits. See how credits work.

Add it to Claude

To run Spatial Compiler as a local program, add the Claude plugin. The Spatial Compiler repository is a Claude plugin marketplace, and the plugin carries the pyro guide and the six examples. In Claude Code, run:

claude code
/plugin marketplace add applied-manifold/spatial-compiler
/plugin install spatial-compiler@applied-manifold

The plugin looks for the program in $SPATIAL_COMPILER_BIN, then for spatial-compiler on PATH, then in ~/.spatial-compiler/bin. Build the program once from source, as described next.

Build from source

The build runs on Windows with Visual Studio 2022 (the C++ workload) and Python 3. From a clone of the repository, run:

cmd
python scripts\fetch_third_party.py
scripts\build.bat
scripts\install.bat

fetch_third_party.py runs once and downloads the pinned third-party code listed in THIRD_PARTY.md. build.bat builds the program, and install.bat copies it to %USERPROFILE%\.spatial-compiler\bin, where the plugin finds it.

Bake and wire

Bake a spec into a folder, then wire the bake into a Godot 4 scene. The scene must sit inside a Godot project, so put the bake folder inside the project first.

terminal
spatial-compiler bake <name>.pyro.toml --out <dir>
spatial-compiler wire <dir> --scene <path>.tscn

wire installs the six-way shader flipbook_6way.gdshader in the project, writes texture import settings and writes a scene sized in meters, with its origin on the ground under the effect.

spatial-compiler schema
Prints every field, range, default, warning and metric as JSON.
spatial-compiler check <spec>
Validates a spec without touching the GPU. Each error names the key and the nearest valid key or the range.
spatial-compiler sweep <spec> --set key=v1,v2 --out <dir>
Bakes variants at draft quality onto one labelled comparison sheet.
spatial-compiler version
Prints the version.

Exit codes are 0 for done, 1 for an invalid spec or arguments, 2 for a GPU failure and 3 for a file error.

The spec file

A spec is a TOML file whose name ends in .pyro.toml. Units are meters, seconds and kelvin; the origin is the center of the box floor, and +Y is up. The sections are [meta], [domain], [[emitters]], [solver], [look], [[views]] and [export].

Every field you leave out takes its default, and an unknown key is an error. This is the shipped fireball example:

fireball.pyro.toml
# A ground burst that swells, rolls and rises. One-shot.
[meta]
name = "fireball"
notes = "Ground burst that swells, rolls and rises"

[domain]
size_m = [12, 16, 12]
voxel_m = 0.08
duration_s = 4.0

[[emitters]]
shape = "sphere"
position_m = [0, 0.7, 0]
size_m = 1.2
start_s = 0.0
end_s = 0.18
fuel = 5
temperature_k = 1900
smoke = 1.5
velocity_mps = 7

[solver]
# Burning needs air, so the ball burns at its rolling surface instead of all at once.
air_limit = 0.88
burn_rate = 10
smoke_fade = 1.1

[export]
pacing = "front"

The pyro module page lists all six examples.

What a bake writes

FileHolds
<view>_pos.pngLit from the right (R), from above (G) and from behind (B), with opacity in A.
<view>_neg.pngLit from the left (R), from below (G) and from the front (B), with flame brightness in A.
<view>_colour.pngFlame color in RGB, with the smoke-to-dust mix in A.
<view>_aux.pngMotion to the next frame (R, G) and depth (B), with temperature in A when asked for.
layout.jsonGrid, tile size, frame times, loop flag, meters per tile, ground anchor and how to decode each channel.
preview_strip.png, preview_contact_sheet.pngStill previews for the agent to open and judge the look.
preview_anim.pngAn animated preview that plays the clip at true speed in any browser.
bake_report.jsonThe report, also written when a run fails.

Sheets are 8 x 8 tiles of 256 px by default. Six-direction lighting lets the game relight the smoke from any sun angle.

The report

Every command prints the same report to stdout and writes it to <out>/bake_report.json.

FieldMeaning
oktrue when the command finished.
errorsEach error has a code, the key at fault and a message.
warningsEach warning has a code, a fix.key to change and a fix.hint.
artifactsEvery file written, with its kind, size and SHA-256.
metricsClip metrics such as life_s, rise_speed_mps and loop_seam, plus per-frame lists.
timings_ms, gpuStage timings, the GPU device and its peak memory.

A shipped effect ends with "ok": true and an empty warnings list.

Verified setup

Spatial Compiler 0.1.0 is verified on one Windows PC with an NVIDIA GeForce RTX 2070 Super, on Vulkan. 19 tests pass there, and the six pyro examples bake at final quality.

Self-host (VPC / air-gapped)

Enterprise and robotics teams deploy the stripped Linux container (libspatial_kernel.so + Rust gateway) directly on their own NVIDIA L4/L40S/H100 hardware with zero external network calls. See Enterprise.

Machine-readable docs

Agents can read this site without rendering it: