Package com.victorvalentim.zividomelive

Class SimulationTimeline

java.lang.Object
com.victorvalentim.zividomelive.SimulationTimeline
public final class SimulationTimeline extends Object
Bounded fixed-step simulation timeline.

The timeline converts real frame seconds into arbitrary simulation units through rate. It executes at most maxSubSteps callbacks per frame and drops excess whole steps after a stall, preventing an unbounded catch-up spiral.

The scene owns simulation rate, position, fixed step, and pause policy. The runtime owns the activation that contains this timeline but does not impose units or a global step size.

API stability: Advanced Stable.

Since:
2.0.0

  • Method Details

    • advance

      public int advance(double realDeltaSeconds, DoubleConsumer stepper)
      Advances this timeline using a bounded number of fixed steps.
      Parameters:
      realDeltaSeconds - non-negative real frame time in seconds
      stepper - callback invoked synchronously once for each fixed simulation step, on the caller's thread
      Returns:
      number of fixed steps executed

    • resetAccumulator

      public void resetAccumulator()
      Clears only the partial-step accumulator and dropped-unit telemetry.

    • reset

      public void reset()
      Resets position, accumulator, telemetry, and pause state without changing configuration.

    • setPosition

      public void setPosition(double position)
      Moves the logical position without executing simulation callbacks.
      Parameters:
      position - finite position in the caller's simulation units

    • jump

      public void jump(double units)
      Adds simulation units without executing callbacks.
      Parameters:
      units - finite amount to add to the current position

    • setRate

      public void setRate(double rate)
      Sets simulation units advanced per real second.
      Parameters:
      rate - finite non-negative simulation rate

    • setFixedStep

      public void setFixedStep(double fixedStep)
      Sets the fixed simulation step size.
      Parameters:
      fixedStep - finite positive step in simulation units

    • setMaxSubSteps

      public void setMaxSubSteps(int maxSubSteps)
      Sets the maximum number of callbacks allowed during one frame.
      Parameters:
      maxSubSteps - positive per-frame callback budget

    • pause

      public void pause()
      Pauses fixed-step callback execution without changing position.

    • resume

      public void resume()
      Resumes fixed-step callback execution.

    • isPaused

      public boolean isPaused()
      Returns:
      whether fixed-step execution is paused

    • getPosition

      public double getPosition()
      Returns:
      current logical position in simulation units

    • getRate

      public double getRate()
      Returns:
      simulation units advanced per real second

    • getFixedStep

      public double getFixedStep()
      Returns:
      configured fixed step in simulation units

    • getMaxSubSteps

      public int getMaxSubSteps()
      Returns:
      maximum fixed-step callbacks allowed per frame

    • getAccumulator

      public double getAccumulator()
      Returns:
      accumulated sub-step remainder in simulation units

    • getDroppedUnits

      public double getDroppedUnits()
      Returns:
      simulation units dropped by bounded catch-up