Skip to content

Commit 302bba3

Browse files
committed
Improve documentation on "physics spiral of death" in ProjectSettings
- Link to Troubleshooting physics issues documentation page in various locations in the class reference.
1 parent db66bd3 commit 302bba3

12 files changed

+21
-1
lines changed

doc/classes/AnimatableBody2D.xml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,8 @@
88
When [AnimatableBody2D] is moved, its linear and angular velocity are estimated and used to affect other physics bodies in its path. This makes it useful for moving platforms, doors, and other moving objects.
99
</description>
1010
<tutorials>
11+
<link title="Physics introduction">$DOCS_URL/tutorials/physics/physics_introduction.html</link>
12+
<link title="Troubleshooting physics issues">$DOCS_URL/tutorials/physics/troubleshooting_physics_issues.html</link>
1113
</tutorials>
1214
<members>
1315
<member name="sync_to_physics" type="bool" setter="set_sync_to_physics" getter="is_sync_to_physics_enabled" default="true">

doc/classes/AnimatableBody3D.xml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,8 @@
88
When [AnimatableBody3D] is moved, its linear and angular velocity are estimated and used to affect other physics bodies in its path. This makes it useful for moving platforms, doors, and other moving objects.
99
</description>
1010
<tutorials>
11+
<link title="Physics introduction">$DOCS_URL/tutorials/physics/physics_introduction.html</link>
12+
<link title="Troubleshooting physics issues">$DOCS_URL/tutorials/physics/troubleshooting_physics_issues.html</link>
1113
<link title="3D Physics Tests Demo">https://godotengine.org/asset-library/asset/2747</link>
1214
<link title="Third Person Shooter (TPS) Demo">https://godotengine.org/asset-library/asset/2710</link>
1315
<link title="3D Voxel Demo">https://godotengine.org/asset-library/asset/2755</link>

doc/classes/CharacterBody2D.xml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,8 @@
88
For game objects that don't require complex movement or collision detection, such as moving platforms, [AnimatableBody2D] is simpler to configure.
99
</description>
1010
<tutorials>
11+
<link title="Physics introduction">$DOCS_URL/tutorials/physics/physics_introduction.html</link>
12+
<link title="Troubleshooting physics issues">$DOCS_URL/tutorials/physics/troubleshooting_physics_issues.html</link>
1113
<link title="Kinematic character (2D)">$DOCS_URL/tutorials/physics/kinematic_character_2d.html</link>
1214
<link title="Using CharacterBody2D">$DOCS_URL/tutorials/physics/using_character_body_2d.html</link>
1315
<link title="2D Kinematic Character Demo">https://godotengine.org/asset-library/asset/2719</link>

doc/classes/CharacterBody3D.xml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,8 @@
88
For game objects that don't require complex movement or collision detection, such as moving platforms, [AnimatableBody3D] is simpler to configure.
99
</description>
1010
<tutorials>
11+
<link title="Physics introduction">$DOCS_URL/tutorials/physics/physics_introduction.html</link>
12+
<link title="Troubleshooting physics issues">$DOCS_URL/tutorials/physics/troubleshooting_physics_issues.html</link>
1113
<link title="Kinematic character (2D)">$DOCS_URL/tutorials/physics/kinematic_character_2d.html</link>
1214
<link title="3D Kinematic Character Demo">https://godotengine.org/asset-library/asset/2739</link>
1315
<link title="3D Platformer Demo">https://godotengine.org/asset-library/asset/2748</link>

doc/classes/PhysicsBody2D.xml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@
88
</description>
99
<tutorials>
1010
<link title="Physics introduction">$DOCS_URL/tutorials/physics/physics_introduction.html</link>
11+
<link title="Troubleshooting physics issues">$DOCS_URL/tutorials/physics/troubleshooting_physics_issues.html</link>
1112
</tutorials>
1213
<methods>
1314
<method name="add_collision_exception_with">

doc/classes/PhysicsBody3D.xml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@
99
</description>
1010
<tutorials>
1111
<link title="Physics introduction">$DOCS_URL/tutorials/physics/physics_introduction.html</link>
12+
<link title="Troubleshooting physics issues">$DOCS_URL/tutorials/physics/troubleshooting_physics_issues.html</link>
1213
</tutorials>
1314
<methods>
1415
<method name="add_collision_exception_with">

doc/classes/ProjectSettings.xml

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2328,7 +2328,8 @@
23282328
Enables [member Viewport.physics_object_picking] on the root viewport.
23292329
</member>
23302330
<member name="physics/common/max_physics_steps_per_frame" type="int" setter="" getter="" default="8">
2331-
Controls the maximum number of physics steps that can be simulated each rendered frame. The default value is tuned to avoid "spiral of death" situations where expensive physics simulations trigger more expensive simulations indefinitely. However, the game will appear to slow down if the rendering FPS is less than [code]1 / max_physics_steps_per_frame[/code] of [member physics/common/physics_ticks_per_second]. This occurs even if [code]delta[/code] is consistently used in physics calculations. To avoid this, increase [member physics/common/max_physics_steps_per_frame] if you have increased [member physics/common/physics_ticks_per_second] significantly above its default value.
2331+
Controls the maximum number of physics steps that can be simulated each rendered frame. The default value is tuned to avoid situations where the framerate suddenly drops to a very low value beyond a certain amount of physics simulation. This occurs because the physics engine can't keep up with the expected simulation rate. In this case, the framerate will start dropping, but the engine is only allowed to simulate a certain number of physics steps per rendered frame. This snowballs into a situation where framerate keeps dropping until it reaches a very low framerate (typically 1-2 FPS) and is called the [i]physics spiral of death[/i].
2332+
However, the game will appear to slow down if the rendering FPS is less than [code]1 / max_physics_steps_per_frame[/code] of [member physics/common/physics_ticks_per_second]. This occurs even if [code]delta[/code] is consistently used in physics calculations. To avoid this, increase [member physics/common/max_physics_steps_per_frame] if you have increased [member physics/common/physics_ticks_per_second] significantly above its default value.
23322333
[b]Note:[/b] This property is only read when the project starts. To change the maximum number of simulated physics steps per frame at runtime, set [member Engine.max_physics_steps_per_frame] instead.
23332334
</member>
23342335
<member name="physics/common/physics_interpolation" type="bool" setter="" getter="" default="false">

doc/classes/RigidBody2D.xml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,8 @@
1111
[b]Note:[/b] Changing the 2D transform or [member linear_velocity] of a [RigidBody2D] very often may lead to some unpredictable behaviors. If you need to directly affect the body, prefer [method _integrate_forces] as it allows you to directly access the physics state.
1212
</description>
1313
<tutorials>
14+
<link title="Physics introduction">$DOCS_URL/tutorials/physics/physics_introduction.html</link>
15+
<link title="Troubleshooting physics issues">$DOCS_URL/tutorials/physics/troubleshooting_physics_issues.html</link>
1416
<link title="2D Physics Platformer Demo">https://godotengine.org/asset-library/asset/2725</link>
1517
<link title="Instancing Demo">https://godotengine.org/asset-library/asset/2716</link>
1618
</tutorials>

doc/classes/RigidBody3D.xml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@
1212
</description>
1313
<tutorials>
1414
<link title="Physics introduction">$DOCS_URL/tutorials/physics/physics_introduction.html</link>
15+
<link title="Troubleshooting physics issues">$DOCS_URL/tutorials/physics/troubleshooting_physics_issues.html</link>
1516
<link title="3D Truck Town Demo">https://godotengine.org/asset-library/asset/2752</link>
1617
<link title="3D Physics Tests Demo">https://godotengine.org/asset-library/asset/2747</link>
1718
</tutorials>

doc/classes/StaticBody2D.xml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,8 @@
99
[StaticBody2D] is useful for completely static objects like floors and walls, as well as moving surfaces like conveyor belts and circular revolving platforms (by using [member constant_linear_velocity] and [member constant_angular_velocity]).
1010
</description>
1111
<tutorials>
12+
<link title="Physics introduction">$DOCS_URL/tutorials/physics/physics_introduction.html</link>
13+
<link title="Troubleshooting physics issues">$DOCS_URL/tutorials/physics/troubleshooting_physics_issues.html</link>
1214
</tutorials>
1315
<members>
1416
<member name="constant_angular_velocity" type="float" setter="set_constant_angular_velocity" getter="get_constant_angular_velocity" default="0.0">

0 commit comments

Comments
 (0)