record_trajectory
Track a body's motion over time to generate animation data for physics simulations, recording position, orientation, and velocity at specified intervals.
Instructions
Record the trajectory of a specific body over time.
Steps the simulation and records position/orientation/velocity at each
timestep for one body. Perfect for generating animation data for R3F.
Args:
sim_id: Simulation ID
body_id: ID of the body to track
steps: Number of timesteps to record
dt: Optional timestep override. If None, uses config default.
Returns:
TrajectoryResponse containing:
- body_id: Tracked body identifier
- frames: List of trajectory frames with time, position, orientation, velocity
- total_time: Total simulated time in seconds
- num_frames: Number of frames recorded
Tips for LLMs:
- Each frame has: time, position [x,y,z], orientation [x,y,z,w], velocity [x,y,z]
- Frames are evenly spaced in time (every dt seconds)
- Output is R3F-compatible: use position/orientation directly in Three.js
- For 60 FPS video: record at dt=1/60 ≈ 0.0167
- Typical recording: 100-1000 frames (1.6-16 seconds at 60 FPS)
Example:
# Record 5 seconds of a falling ball
traj = await record_trajectory(
sim_id=sim_id,
body_id="ball",
steps=300 # 300 × 0.016 ≈ 5 seconds
)
# Use traj.frames in React Three Fiber for animationInput Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sim_id | Yes | ||
| body_id | Yes | ||
| steps | Yes | ||
| dt | No |