chuk-mcp-stage

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

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 )

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" )

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 )

Args: scene_id: Scene identifier shot_id: Shot identifier Returns: GetShotResponse with shot data

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" )

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")

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

Returns the full scene definition including all objects, shots, animations, and configuration. Args: scene_id: Scene identifier Returns: GetSceneResponse with complete Scene object