Deterministic Mode

Deterministic Mode is a setting meant to bypass nondeterminism in the physics simulation introduced by hardware-related variations in computation time. Because video games are rendered at variable frame rates, and the simulation is advanced based on the time between those frames, multiple simulations of the same scenario can vary slightly due them being paced at nondeterministic rates. Deterministic Mode makes that rate constant, eliminating that source of randomness at the cost of possibly choppier graphics output.

This mode does not (yet) lead to deterministic simulation for every scenario, as there are other sources of nondeterminism that need to be tackled.

Usage

The Lua functions which can enable deterministic mode by decoupling the physics and graphics steps are:


be:setPhysicsSpeedFactor(factor)

Sets the physics timing between frames.

Args:

factor(int): The factor to set. Which mode the physics are running in are determined by the exact value passed. It boils down to:

  • -1: Run 1000/fpslimit ms of physics per frame
  • 0: Simulate physics time based on wallclock delta to the last frame
  • n: Simulate n * 50ms of physics per frame (for any positive n)

Any nonzero input will make physics deterministic, as the times between steps is made constant and not tied to rendering times. Any positive input to the function decouples physics and graphics frames, meaning the simulation will not be real-time anymore (it can be either faster or slower, depending on the settings and performance). be:setPhysicsSpeedFactor(-1) will keep the simulation real-time as long as the framerate is constantly reaching fpslimit.

Returns:

nil


be:setPhysicsDeterministic(deterministic)

Sets the deterministic physics mode.

Args:

deterministic(bool): If true, enables the deterministic physics mode.

Returns:

nil

This function also decouples the graphics and physics frames and simulates physicsfps / 20 steps per graphics step. The physics steps per second is 2000 by default, but it can be changed using a command-line argument .


Note: Deterministic Mode is still work in progress. While the above settings will make physics deterministic, there can be other sources of nondeterminism specific to other aspects of the simulation.

Faster than Real-Time Simulation

You can use the deterministic mode to run the simulation faster-than-realtime if the system can run the physics fast enough. You can either run the physics as fast as possible with time-varying speedup, or set a “maximum constant factor speedup” using the graphics frame limiter. This section describes both approaches.

As Fast as Possible

Simply run be:setPhysicsDeterministic(true). For maximum possible speedup, also disable the frame limiter.

Maximum Constant Factor

This mode is useful if you want to run the simulation at say 2x speed of real-time, or any other constant factor.

This mode requires the frame limiter to be enabled. To do so, you can either use the Lua code provided below, or set the limit in the settings. For the latter, navigate to Options > Display > Limit framerate and set it to a desired value. You should use a value that your system can handle rendering:

FPS Limiter FPS Limiter

You have to calculate the amount of 50ms iterations that need to be run for the maximum constant factor speedup. The following code does that:

fpslimit = 40 -- set to a value that your PC can handle and also 20 / fpslimit * factor has to be an integer
factor = 2 -- maximum speed up factor
Engine.setFPSLimiter(fpslimit)
Engine.setFPSLimiterEnabled(true)
iterations = 20 / fpslimit * factor -- this has to be an integer!
be:setPhysicsSpeedFactor(iterations)

Limitations:

  • The factor is the upper limit of the speedup. If the framerate is lower than what is set in the frame limiter, the speedup will be lower than the factor.
  • 20 / fpslimit * factor has to be an integer and fpslimit should be at least 20. Examples: For 2x speedup, this means the frame limiter has to be set to either 20 or 40. For 3x speedup, the possible values are 20, 30 and 60.
Last modified: February 17, 2025

Any further questions?

Join our discord
Our documentation is currently incomplete and undergoing active development. If you have any questions or feedback, please visit this forum thread.