threejs-studio

Initialize a new scene folder with scene.json (default lights, camera, grid) and a compiled index.html. Also records a row in threejs_scenes state. Output goes to <cwd>/<slug>/.

Return a compact summary of the scene DSL — node ids/types, material summary, camera, background. Pass full:true for the raw scene.json. Always call this at the start of a specialist turn.

Snapshot the current scene.json into snapshots/ with a timestamped filename. Cheap and reversible; use before large destructive edits.

Add a node (mesh, group, light, helper, instanced, points, line, gltf, sprite) to the scene. Returns { id, type, html_path }.

Patch position/rotation/scale on a node.

Move a node under a different parent (or the scene root).

Remove a node (and by default its descendants).

Align or distribute a set of nodes along an axis.

Approximate axis-aligned bounds for one or more nodes (from primitive geometry params + transforms).

Define a material in scene.materials. type defaults to "standard" (PBR). Extra fields include roughness, metalness, emissive, opacity, transparent, clearcoat, transmission, and texture map paths.

Patch fields on an existing material.

Bind a material to one or more nodes (materialId).

Add or replace a light node. Supported types: ambient, directional, point, spot, hemisphere, rectarea.

Set scene background — either an HDRI path (for IBL lighting) or a solid color.

Set tone mapping mode and exposure.

Configure camera type, framing, controls.

Auto-position the camera to frame all (or specified) nodes with the given padding, azimuth, and elevation.

Text→3D via the configured mesh provider (env THREEJS_MESH_PROVIDER=meshy|local). Local fallback writes a placeholder primitive .gltf so the tool chain always completes. By default also registers a `gltf` node in the scene.

Text→image via the configured texture provider (env THREEJS_TEXTURE_PROVIDER=fal|local). Local fallback writes a solid-color PNG matched to keyword palette. Optionally applies the texture as the `map` slot of an existing material.

Register an existing .glb / .gltf asset (URL or local path) into the scene folder and, by default, add a node that references it.

Search a curated catalog of free assets (Poly Haven HDRIs, Khronos sample glTF models). Returns downloadable URLs suitable for import_gltf / set_environment.

Record a decimation intent (target triangle count) on an asset. v0.3 records intent only; actual polygon reduction is Phase 3.

List assets registered in scene.assets for a scene.

Attach a cannon-es rigid body to a node. Emits CANNON.World + stepping in the compiled HTML. Use mass 0 for static (floor/walls).

Attach a sandboxed JS snippet to a node's tick / click / hover event. Variables in scope: target, scene, dt (tick), hit (click/hover), THREE.

High-level shortcut for common interactions (toggle_visible, hide, show, swap_material, translate, rotate, log). Generates a script under the hood; prefer this over hand-writing add_script.

Add or extend a keyframe animation clip on a node. Emits AnimationMixer + KeyframeTrack in the compiled HTML.

Attach a common tick-driven procedural motion (spin, orbit, oscillate, bob). Cheaper than keyframes for unbounded loops.

Capture PNGs of the scene from N camera angles using puppeteer (headless Chromium). Falls back to a shot-plan when puppeteer is not installed so the critic can still run in DSL-only mode.

Critique a scene via the configured VLM provider (env THREEJS_VLM_PROVIDER=anthropic|local). Optionally captures screenshots first when none are supplied. Local heuristic fallback still catches "no lights", "empty scene", "missing materials" without any API call.

Fallback — write a raw self-contained Three.js HTML scene from a JS snippet. Bypasses the DSL. Use only for scenes where custom loops, shaders, or physics make the DSL an obstacle. The compiled HTML is NOT regenerated on subsequent DSL mutations.

Record a completed (or failed) scene on the plugin's shared state. Reviewer calls this after inspecting the finished HTML.

List saved Three.js scenes and outcomes from durable state.

Persist the user/director approval gate before compositional work starts. Call this after the user explicitly approves, rejects, or requests changes to the plan.

Build an evidence report for a scene or workspace: saved source, approvals, render outcomes, paths, readiness, and failures.

Export a Three.js HTML scene to an MP4 video via headless Chromium (puppeteer) + ffmpeg. Supports auto-orbit / orbit / static presets and l/m/h quality tiers. Returns a render_command to launch as a background shell job.