phys.advance

Fast-forward the physics simulation: run it a stated number of fixed steps, or a stated span of simulated seconds, as fast as the machine computes them, and answer once the last step has run. It is how to measure a physics outcome over many simulated seconds (an acceleration run, a braking distance, a settle time, a lap, a bridge under load) in less wall time than the seconds it covers, and how to run exactly N steps from a paused start and read the state after each with Physics.onAfterStep.

Every step is the step real-time play runs, at the same dt: the step hooks, held forces, contact and impact events, joint breaks and fixedUpdate all run once per step, so from the same state a run driven from the step hooks and fixedUpdate reaches the state the same steps reach at wall-clock rate. Per-frame code (update, task.wait, animation) keeps the frame clock, so drive a measured run from the step hooks or fixedUpdate. It runs from a paused clock, which stays paused afterwards, or a running one; run it in play for a measurement, so leaving play puts the scene back. Each frame steps for at most frameBudgetMs of wall time (default 100), so the engine keeps drawing and answering while it runs. Returns { steps, firstStep, lastStep, simulatedSeconds, wallSeconds, steppingSeconds, frames, tickRate }. Wraps Physics.advance.