Evaluate and simulate

Evaluation answers "where is everything at 1.5 seconds" with numbers. Simulation runs physics once and writes the result into the document as recorded motion, so playback never depends on the simulator again.

#Evaluate

puni scene evaluate --file scene.json --time 1.5 --json
puni scene evaluate --file scene.json --time 1.5 --ids body,lid --json

The answer lists up to 64 objects with their transform, visibility and property values at that time, after every clip, behavior and binding has been applied. The time must be inside the scene's duration.

Over MCP the same call is evaluate_frame, on a saved revision.

#What evaluation proves

It proves the document's arithmetic. It does not draw, load fonts, compile shaders or decode sound. A scene can evaluate perfectly and look wrong. Use a render for the picture.

#Simulate

puni scene simulate --file scene.json --ids ball,crate --output motion.json --settings physics.json

--ids selects 1–32 top-level scene objects. physics.json contains only simulation settings: duration, height, restitution, spin, mass and collider. Puni builds the collision bodies from those objects. For example:

{
  "duration": 3,
  "height": 200,
  "restitution": 0.2,
  "spin": 0,
  "mass": 0.2,
  "collider": "convex-hull"
}

Choose a duration within the scene timeline, up to 30 seconds. height is a lift in millimetres and mass is in kilograms. collider accepts convex-hull or box.

A full physics recipe instead contains gravity, a ground plane, nonempty collision bodies and impulses. Save that JSON as recipe.json and pass it through --recipe, without --ids or --settings:

puni scene simulate --file scene.json --recipe recipe.json --output motion.json --json

To obtain a recipe from your scene first, add --recipe-output recipe.json to the --ids command. Keep body IDs matched to the scene objects when editing the recipe.

The command records each body's position and rotation at 120 samples per second and writes a rigid-body action per object. The action carries the input's SHA-256 and the engine version, so a recorded motion can always be traced to what produced it.

Over MCP the same recipe goes to simulate_scene on a saved revision, where the deployment has a solver. It saves the recorded motion as a new revision with a checkpoint named by your label.

In the studio the same thing is the Physics dialog on a selected object.

Read Portable projects for carrying a scene and its assets between places.