stage_add_object
Add 3D objects such as boxes, spheres, cylinders, and mesh placeholders to a scene, configuring their position, rotation, scale, and material for physics-based animations.
Instructions
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
)Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| scene_id | Yes | ||
| object_id | Yes | ||
| object_type | Yes | ||
| position_x | No | ||
| position_y | No | ||
| position_z | No | ||
| rotation_x | No | ||
| rotation_y | No | ||
| rotation_z | No | ||
| rotation_w | No | ||
| scale_x | No | ||
| scale_y | No | ||
| scale_z | No | ||
| size_x | No | ||
| size_y | No | ||
| size_z | No | ||
| radius | No | ||
| height | No | ||
| material_preset | No | plastic-white | |
| color_r | No | ||
| color_g | No | ||
| color_b | No |