Each assembly in the Roblox engine corresponds to a single rigid body. The position and velocity of each rigid body describe where it's located and how fast it's moving, and one of the primary engine tasks is to update the positions and velocities of each assembly.
Assemblies can be connected together with mechanical constraints and mover constraints to form mechanisms such as cars or airplanes. As the number of assemblies and constraints in a mechanism increases, the time required to simulate the mechanism also increases. Fortunately, this increase is offset when the sleep system determines that the engine can skip simulation of non‑moving assemblies.
Sleep States
Each assembly can be in one of three states: awake, sleep‑checking, or sleeping.
Awake
An awake assembly is moving or accelerating, and is therefore simulated. Assemblies enter this state from situations outlined in sleep‑checking and sleeping, as well as additional wake situations.
Sleep-Checking
A non-moving assembly that shares a constraint with at least one awake neighboring assembly is put into the sleep-checking state and is not simulated. On each worldstep, a sleep-checking assembly checks whether:
- The position deviation of a neighboring assembly is greater than the Neighbor Displacement threshold.
- The product of a neighboring assembly's acceleration and current timestep size is greater than the Neighbor Angular Velocity and/or Neighbor Linear Velocity threshold.
If either of these conditions is true, or under any of the additional wake situations, the sleep-checking assembly enters the awake state.
Sleeping
A sleeping assembly is neither moving nor accelerating, and is therefore not simulated.
An assembly is determined to be non-moving by checking its position deviation, calculated as the maximum deviation from the average position of the point furthest from its center of mass over the most recent set of worldsteps. If this deviation is greater than the Displacement threshold, the assembly enters the awake state.
In some cases, simply checking for non-movement would cause an assembly to incorrectly enter the sleeping state. For example, if a ball is thrown straight up, its position barely changes for a number of worldsteps as it approaches its maximum height, making it a candidate to sleep and never fall back down. To handle such cases, the engine monitors whether the product of the assembly's acceleration and current timestep size exceeds the Linear Velocity and/or Angular Velocity threshold.
If an assembly falls asleep when you expect it to remain awake, it's commonly because the assembly is moving too slowly. In addition to automatic checks outlined in sleep‑checking and sleeping, you can forcibly wake up an assembly through the conditions outlined in additional wake situations.
Threshold Reference
The following table provides the various displacement and velocity thresholds used to determine if an assembly is moving or accelerating.
| Threshold | Value | State Change |
|---|---|---|
| Neighbor Displacement | 0.01 studs | sleep-checking ⟩ awake |
| Neighbor Linear Velocity | 0.2 studs/s | sleep-checking ⟩ awake |
| Neighbor Angular Velocity | 0.2 radians/s | sleep-checking ⟩ awake |
| Displacement | 0.001 studs | sleeping ⟩ awake |
| Linear Velocity | 0.1 studs/s | sleeping ⟩ awake |
| Angular Velocity | 0.1 radians/s | sleeping ⟩ awake |
Additional Wake Situations
In addition to situations outlined in sleep‑checking and sleeping, an assembly enters the awake state when:
It collides with another assembly.
Any physics-related property of any BasePart within the assembly changes, including:
A non-zero impulse is applied to any BasePart within the assembly via ApplyImpulse(), ApplyImpulseAtPosition(), or ApplyAngularImpulse().
Any physics-related property changes on the Workspace that would affect the assembly, including:
A new Constraint is created with an Attachment that is parented to a BasePart within the assembly.
Any property changes for a Constraint with an Attachment that is parented to a BasePart within the assembly.
The CurrentAngle property changes for a Motor that is connected to a BasePart within the assembly.
The assembly contains a VehicleSeat with a seated player character.
The assembly is within the BlastRadius of an Explosion.
Debugging Visualization
During playtesting, you can visualize assembly sleep states by toggling on Awake parts from the Visualization Options widget in the upper‑right corner of the 3D viewport.
Once enabled, simulated parts will be outlined by their current sleep state, with awake parts outlined in red, sleep‑checking parts outlined in orange, and sleeping parts un‑outlined.