| stage_create_scene | Create a new 3D scene for composition. Initializes a new scene workspace backed by chuk-artifacts.
The scene can contain 3D objects, lighting, camera shots, and physics bindings.
Args:
name: Optional scene name (e.g., "pendulum-demo", "f1-silverstone-t1")
author: Optional author name for metadata
description: Optional scene description
Returns:
CreateSceneResponse with scene_id and success message
Tips for LLMs:
- Scene ID is auto-generated (UUID)
- Scenes are stored in USER scope (Google Drive) if authenticated, SESSION scope otherwise
- Use the scene_id for all subsequent operations
- Typical workflow: create_scene → add_objects → add_shots → export
Example:
scene = await stage_create_scene(
name="falling-ball-demo",
author="Claude",
description="Simple gravity demonstration"
)
# Use scene.scene_id for next steps
|
| stage_add_object | Add a 3D object to the scene. Adds primitives (box, sphere, cylinder, etc.) or placeholders for meshes.
Objects can be bound to physics bodies later for animation.
Args:
scene_id: Scene identifier
object_id: Unique object name (e.g., "ground", "ball", "car")
object_type: Object type - "box", "sphere", "cylinder", "capsule", "plane", "mesh"
position_x, position_y, position_z: Position in 3D space
rotation_x, rotation_y, rotation_z, rotation_w: Rotation quaternion
scale_x, scale_y, scale_z: Scale factors
size_x, size_y, size_z: Size for box (width, height, depth)
radius: Radius for sphere/cylinder/capsule
height: Height for cylinder/capsule
material_preset: Material preset - "metal-dark", "glass-blue", "plastic-white", etc.
color_r, color_g, color_b: RGB color (0.0-1.0)
Returns:
AddObjectResponse with object_id confirmation
Tips for LLMs:
- For ground: object_type="plane", large size, static
- For dynamic objects: smaller primitives that match physics bodies
- Quaternion: [0,0,0,1] is identity (no rotation)
- Common materials: "metal-dark", "glass-blue", "plastic-white", "rubber-black"
Example:
# Add ground plane
await stage_add_object(
scene_id=scene_id,
object_id="ground",
object_type="plane",
size_x=20.0,
size_y=20.0,
material_preset="metal-dark"
)
# Add falling sphere
await stage_add_object(
scene_id=scene_id,
object_id="ball",
object_type="sphere",
radius=1.0,
position_y=5.0,
material_preset="glass-blue",
color_r=0.3,
color_g=0.5,
color_b=1.0
)
|
| stage_set_environment | Set scene environment and lighting. Configures the background, ambient lighting, and light sources.
Args:
scene_id: Scene identifier
environment_type: "gradient", "solid", "hdri", or "none"
lighting_preset: "studio", "three-point", "noon", "sunset", "warehouse"
intensity: Overall light intensity (0.0-2.0)
Returns:
SetEnvironmentResponse confirmation
Example:
await stage_set_environment(
scene_id=scene_id,
environment_type="gradient",
lighting_preset="three-point"
)
|
| stage_add_shot | Add a camera shot to the scene. Defines a camera movement path and time range for cinematography.
Args:
scene_id: Scene identifier
shot_id: Unique shot name (e.g., "intro-orbit", "close-up")
camera_mode: "orbit", "static", "chase", "dolly", "flythrough", "crane", "track"
start_time: Shot start time in seconds
end_time: Shot end time in seconds
focus_object: Object ID to focus on (for orbit/chase modes)
orbit_radius: Distance from focus object (orbit mode)
orbit_elevation: Camera elevation angle in degrees (orbit mode)
orbit_speed: Rotation speed in revolutions per second (orbit mode)
static_position_x, static_position_y, static_position_z: Camera position (static mode)
look_at_x, look_at_y, look_at_z: Point to look at
easing: Easing function - "linear", "ease-in-out", "spring", etc.
Returns:
AddShotResponse with shot details
Tips for LLMs:
- Orbit mode: Great for product shots, object inspection
- Static mode: Fixed camera, good for observing motion
- Chase mode: Follow moving objects
- Multiple shots can be sequenced for different camera angles
Example:
# Orbiting shot around falling ball
await stage_add_shot(
scene_id=scene_id,
shot_id="orbit-shot",
camera_mode="orbit",
focus_object="ball",
orbit_radius=8.0,
orbit_elevation=30.0,
orbit_speed=0.1,
start_time=0.0,
end_time=10.0
)
|
| stage_get_shot | Get shot details from a scene. Args:
scene_id: Scene identifier
shot_id: Shot identifier
Returns:
GetShotResponse with shot data
|
| stage_bind_physics | Bind a scene object to a physics body. Links a visual object to a physics simulation body so that
the physics simulation drives the object's animation.
Args:
scene_id: Scene identifier
object_id: Scene object ID
physics_body_id: Physics body ID from chuk-mcp-physics
Format: "rapier://sim-{sim_id}/body-{body_id}"
Example: "rapier://sim-abc123/body-ball"
Returns:
BindPhysicsResponse confirmation
Tips for LLMs:
- Create physics body first using chuk-mcp-physics
- Then create matching scene object with same shape/size
- Bind them together so physics drives visuals
- Use stage_bake_simulation to convert physics → keyframes
Example:
# 1. Create physics simulation (chuk-mcp-physics)
sim = await create_simulation(gravity_y=-9.81)
# 2. Add physics body
await add_rigid_body(
sim_id=sim.sim_id,
body_id="ball",
body_type="dynamic",
shape="sphere",
radius=1.0,
position=[0, 5, 0]
)
# 3. Create scene object
await stage_add_object(
scene_id=scene_id,
object_id="ball",
object_type="sphere",
radius=1.0,
position_y=5.0
)
# 4. Bind them
await stage_bind_physics(
scene_id=scene_id,
object_id="ball",
physics_body_id=f"rapier://{sim.sim_id}/body-ball"
)
|
| stage_bake_simulation | Bake physics simulation to keyframe animations. Converts physics simulation data into keyframes that can be
exported to R3F/Remotion for video rendering.
Args:
scene_id: Scene identifier
simulation_id: Physics simulation ID from chuk-mcp-physics
fps: Frames per second for sampling (default 60)
duration: Duration in seconds to bake (if None, bakes entire simulation)
physics_server_url: Optional Rapier HTTP server URL
If None, defaults to public Rapier service (https://rapier.chukai.io)
Can be overridden with RAPIER_SERVICE_URL environment variable
Returns:
BakeSimulationResponse with frame count and baked object list
Tips for LLMs:
- Run physics simulation first (chuk-mcp-physics step_simulation or record_trajectory)
- Bind objects to physics bodies (stage_bind_physics)
- Bake simulation to convert physics → animation keyframes
- Then export scene to R3F/Remotion with animation data
Example:
# After running simulation and binding objects
result = await stage_bake_simulation(
scene_id=scene_id,
simulation_id=sim.sim_id,
fps=60,
duration=10.0
)
print(f"Baked {result.total_frames} frames for {len(result.baked_objects)} objects")
|
| stage_export_scene | Export scene to R3F, Remotion, or glTF format. Converts the scene definition into code/files that can be used
with React Three Fiber or Remotion for rendering.
Args:
scene_id: Scene identifier
format: Export format - "r3f-component", "remotion-project", "gltf", "json"
output_path: Optional VFS path for output (auto-generated if None)
Returns:
ExportSceneResponse with output paths
Tips for LLMs:
- "r3f-component": Generate React Three Fiber .tsx files
- "remotion-project": Full Remotion project with package.json
- "gltf": Static 3D scene file
- "json": Raw scene JSON data
- Exported files are in the scene's VFS workspace
- Use chuk-artifacts to retrieve exported files
Example:
result = await stage_export_scene(
scene_id=scene_id,
format="remotion-project"
)
print(f"Exported to {result.output_path}")
# Files available at result.artifacts paths
|
| stage_get_scene | Get complete scene data. Returns the full scene definition including all objects, shots,
animations, and configuration.
Args:
scene_id: Scene identifier
Returns:
GetSceneResponse with complete Scene object
|
