advancePhysics static method

@visibleForTesting double advancePhysics({ required PhysicsWorld world, required void fixedUpdateWalk(double fixedDt), required double accumulator, required double frameDt, })

Fixed-step substepping driver. Adds frameDt to accumulator, takes up to PhysicsWorld.maxSubsteps fixed steps to consume it (walking fixedUpdateWalk then world.step each step), drops leftover time when the renderer falls far behind, and finishes by calling world.interpolateTransforms with the residual fraction.

Returns the new accumulator value. Exposed as a static method so the loop can be exercised without constructing a Scene (which otherwise requires a live Flutter GPU context).

Implementation

@visibleForTesting
static double advancePhysics({
  required PhysicsWorld world,
  required void Function(double fixedDt) fixedUpdateWalk,
  required double accumulator,
  required double frameDt,
}) {
  accumulator += frameDt;
  final fixed = world.fixedTimestep;
  var steps = 0;
  while (accumulator >= fixed && steps < world.maxSubsteps) {
    fixedUpdateWalk(fixed);
    world.step(fixed);
    accumulator -= fixed;
    steps++;
  }
  if (accumulator > fixed * world.maxSubsteps) {
    // Drop unconsumed time to avoid spiralling when the renderer is
    // running far behind the physics rate.
    accumulator = 0;
  }
  final alpha = (accumulator / fixed).clamp(0.0, 1.0);
  world.interpolateTransforms(alpha);
  return accumulator;
}