From 94468e61e03e617b830c5930b0b44a3ba19f4434 Mon Sep 17 00:00:00 2001 From: Eric Dow <618004+ericdow@users.noreply.github.com> Date: Mon, 8 Sep 2025 09:15:42 -0700 Subject: [PATCH 1/4] update sleep docs to reflect improved sleep system --- content/en-us/physics/sleep-system.md | 82 ++++++++++++++++----------- 1 file changed, 50 insertions(+), 32 deletions(-) diff --git a/content/en-us/physics/sleep-system.md b/content/en-us/physics/sleep-system.md index 76543eaba..7b0d775f4 100644 --- a/content/en-us/physics/sleep-system.md +++ b/content/en-us/physics/sleep-system.md @@ -9,36 +9,38 @@ Assemblies can be connected together with [mechanical constraints](../physics/me ## Sleep states -Each assembly can be in one of three states: [awake](#awake), [sleep‑checking](#sleep-checking), or [sleeping](#sleeping). +Each assembly can be in one of three states: [awake](#awake), [sleeping](#sleeping), or [sleep‑checking](#sleep-checking). ### Awake -An **awake** assembly is moving or accelerating, and is therefore simulated. Assemblies enter this state from situations outlined in [sleep‑checking](#sleep-checking) and [sleeping](#sleeping), as well as [additional wake situations](#additional-wake-situations). - -### Sleep-checking - -A non-moving assembly that shares a constraint with at least one [awake](#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-reference) threshold. -- The product of a neighboring assembly's **acceleration** and current timestep size is greater than the [Neighbor Angular Velocity](#threshold-reference) and/or [Neighbor Linear Velocity](#threshold-reference) threshold. - -If either of these conditions is true, or under any of the [additional wake situations](#additional-wake-situations), the sleep-checking assembly enters the [awake](#awake) state. +An **awake** assembly is moving or accelerating, and is therefore simulated. Assemblies enter this state from situations outlined in [sleeping](#sleeping) and [sleep‑checking](#sleep-checking), as well as [additional wake situations](#additional-wake-situations). ### 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-reference) threshold, the assembly enters the [awake](#awake) state. +An assembly is determined to be non-moving by checking its **linear velocity** and **rotational velocity**. If its linear velocity is less than the [Linear Velocity](#threshold-reference) threshold and its rotational velocity is less than the [Rotational Velocity](#threshold-reference) threshold, the assembly is considered to be non-moving. -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](#threshold-reference) and/or [Angular Velocity](#threshold-reference) threshold. +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 velocity approaches zero as it reaches its maximum height, making it a candidate to sleep and never fall back down. To handle such cases, the engine considers an assembly to be accelerating if its **linear acceleration** or **rotational acceleration** are greater than the [Linear Acceleration](#threshold-reference) and [Rotational Acceleration](#threshold-reference) thresholds, respectively, and will prevent the assembly from falling asleep. 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](#sleep-checking) and [sleeping](#sleeping), you can forcibly wake up an assembly through the conditions outlined in [additional wake situations](#additional-wake-situations). +### Sleep-checking + +A non-moving assembly that shares a constraint with at least one [awake](#awake) neighboring assembly is put into the **sleep-checking** state and is not simulated. On each worldstep, a sleep-checking assembly checks whether: + +- Its **linear acceleration** is greater than the [Wake Linear Acceleration](#threshold-reference) threshold. +- Its **rotational acceleration** is greater than the [Wake Rotational Acceleration](#threshold-reference) threshold. +- A neighboring assembly's **linear velocity** is greater than the [Neighbor Linear Velocity](#threshold-reference) threshold. +- A neighboring assembly's **rotational velocity** is greater than the [Neighbor Rotational Velocity](#threshold-reference) threshold. + +If any of these conditions is true, or under any of the [additional wake situations](#additional-wake-situations), the sleep-checking assembly enters the [awake](#awake) state. + ## Threshold reference -The following table provides the various displacement and velocity thresholds used to determine if an assembly is moving or accelerating. +The following table provides the various velocity and acceleration thresholds used to determine if an assembly is moving or accelerating. @@ -50,43 +52,59 @@ The following table provides the various displacement and velocity thresholds us - - - + + + - - - + + + + + + + + - - + + + + + + + - - - + + + - - - + + + - - - + + +
Neighbor Displacement0.01 studs[sleep-checking](#sleep-checking) ⟩ [awake](#awake)Linear Velocity0.33 studs/s[awake](#awake) ⟩ [sleeping](#sleeping)
Neighbor Linear Velocity0.2 studs/s[sleep-checking](#sleep-checking) ⟩ [awake](#awake)Rotational Velocity0.42 studs/s[awake](#awake) ⟩ [sleeping](#sleeping)
Linear Acceleration0.24 studs/s2[awake](#awake) ⟩ [sleeping](#sleeping)
Neighbor Angular Velocity0.2 radians/sRotational Acceleration0.24 studs/s2[awake](#awake) ⟩ [sleeping](#sleeping)
Neighbor Linear Velocity0.48 studs/s [sleep-checking](#sleep-checking) ⟩ [awake](#awake)
Displacement0.001 studs[sleeping](#sleeping) ⟩ [awake](#awake)Neighbor Rotational Velocity0.59 studs/s[sleep-checking](#sleep-checking) ⟩ [awake](#awake)
Linear Velocity0.1 studs/s[sleeping](#sleeping) ⟩ [awake](#awake)Wake Linear Acceleration16.9 studs/s2[awake](#awake) ⟩ [sleeping](#sleeping)
Angular Velocity0.1 radians/s[sleeping](#sleeping) ⟩ [awake](#awake)Wake Rotational Acceleration16.9 studs/s2[awake](#awake) ⟩ [sleeping](#sleeping)
+Rotational velocity and acceleration thresholds reflect the velocity and acceleration of a point located on the assembly bounding sphere (a sphere that contains all of the parts in an assembly) that moves rigidly with the assembly. + + +For a given angular velocity, the rotational velocity of an assembly is proportional to the assembly bounding sphere radius. This means that larger assemblies can rotate at a lower angular velocity without falling asleep. + + ## Additional wake situations In addition to situations outlined in [sleep‑checking](#sleep-checking) and [sleeping](#sleeping), an assembly enters the [awake](#awake) state when: -- It collides with another assembly. +- It collides with another assembly moving faster than 1 studs/s. - Any physics-related property of any `Class.BasePart` within the assembly changes, including: - `Class.BasePart.Anchored|Anchored` From 5b62676e7481f0b4fb20c7897295b7839419403e Mon Sep 17 00:00:00 2001 From: Eric Dow <618004+ericdow@users.noreply.github.com> Date: Mon, 8 Sep 2025 12:11:10 -0700 Subject: [PATCH 2/4] add gif of rotating parts --- .../en-us/assets/physics/assemblies/AngularVelocityGrid.gif | 3 +++ content/en-us/physics/sleep-system.md | 2 ++ 2 files changed, 5 insertions(+) create mode 100644 content/en-us/assets/physics/assemblies/AngularVelocityGrid.gif diff --git a/content/en-us/assets/physics/assemblies/AngularVelocityGrid.gif b/content/en-us/assets/physics/assemblies/AngularVelocityGrid.gif new file mode 100644 index 000000000..94193ceb7 --- /dev/null +++ b/content/en-us/assets/physics/assemblies/AngularVelocityGrid.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:a96b7bbb511dd6fe826f55eed0ffed22662a297c14de24368b622ed113eaf709 +size 16733567 diff --git a/content/en-us/physics/sleep-system.md b/content/en-us/physics/sleep-system.md index 7b0d775f4..34e4ca28a 100644 --- a/content/en-us/physics/sleep-system.md +++ b/content/en-us/physics/sleep-system.md @@ -100,6 +100,8 @@ Rotational velocity and acceleration thresholds reflect the velocity and acceler For a given angular velocity, the rotational velocity of an assembly is proportional to the assembly bounding sphere radius. This means that larger assemblies can rotate at a lower angular velocity without falling asleep. +A grid of rotating parts with different sizes, some of which fall asleep. + ## Additional wake situations In addition to situations outlined in [sleep‑checking](#sleep-checking) and [sleeping](#sleeping), an assembly enters the [awake](#awake) state when: From 4ee16448ac27cde5e9d9ff33ae89e4f530447ae9 Mon Sep 17 00:00:00 2001 From: Eric Dow <618004+ericdow@users.noreply.github.com> Date: Mon, 8 Sep 2025 15:04:31 -0700 Subject: [PATCH 3/4] Revert "add gif of rotating parts" This reverts commit 5b62676e7481f0b4fb20c7897295b7839419403e. --- .../en-us/assets/physics/assemblies/AngularVelocityGrid.gif | 3 --- content/en-us/physics/sleep-system.md | 2 -- 2 files changed, 5 deletions(-) delete mode 100644 content/en-us/assets/physics/assemblies/AngularVelocityGrid.gif diff --git a/content/en-us/assets/physics/assemblies/AngularVelocityGrid.gif b/content/en-us/assets/physics/assemblies/AngularVelocityGrid.gif deleted file mode 100644 index 94193ceb7..000000000 --- a/content/en-us/assets/physics/assemblies/AngularVelocityGrid.gif +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:a96b7bbb511dd6fe826f55eed0ffed22662a297c14de24368b622ed113eaf709 -size 16733567 diff --git a/content/en-us/physics/sleep-system.md b/content/en-us/physics/sleep-system.md index 34e4ca28a..7b0d775f4 100644 --- a/content/en-us/physics/sleep-system.md +++ b/content/en-us/physics/sleep-system.md @@ -100,8 +100,6 @@ Rotational velocity and acceleration thresholds reflect the velocity and acceler For a given angular velocity, the rotational velocity of an assembly is proportional to the assembly bounding sphere radius. This means that larger assemblies can rotate at a lower angular velocity without falling asleep. -A grid of rotating parts with different sizes, some of which fall asleep. - ## Additional wake situations In addition to situations outlined in [sleep‑checking](#sleep-checking) and [sleeping](#sleeping), an assembly enters the [awake](#awake) state when: From d20085b8903fafd1a7a646293632354dddec1914 Mon Sep 17 00:00:00 2001 From: IgnisRBX <43388550+IgnisRBX@users.noreply.github.com> Date: Mon, 8 Sep 2025 15:16:14 -0700 Subject: [PATCH 4/4] Apply suggestions from code review --- content/en-us/physics/sleep-system.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/content/en-us/physics/sleep-system.md b/content/en-us/physics/sleep-system.md index 7b0d775f4..046d8380d 100644 --- a/content/en-us/physics/sleep-system.md +++ b/content/en-us/physics/sleep-system.md @@ -63,12 +63,12 @@ The following table provides the various velocity and acceleration thresholds us Linear Acceleration - 0.24 studs/s2 + 0.24 studs/s² [awake](#awake) ⟩ [sleeping](#sleeping) Rotational Acceleration - 0.24 studs/s2 + 0.24 studs/s² [awake](#awake) ⟩ [sleeping](#sleeping) @@ -83,12 +83,12 @@ The following table provides the various velocity and acceleration thresholds us Wake Linear Acceleration - 16.9 studs/s2 + 16.9 studs/s² [awake](#awake) ⟩ [sleeping](#sleeping) Wake Rotational Acceleration - 16.9 studs/s2 + 16.9 studs/s² [awake](#awake) ⟩ [sleeping](#sleeping)