troubleshooting_physics_issues.rst 11 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208
  1. .. _doc_troubleshooting_physics_issues:
  2. Troubleshooting physics issues
  3. ==============================
  4. When working with a physics engine, you may encounter unexpected results.
  5. While many of these issues can be resolved through configuration, some of them
  6. are the result of engine bugs. For known issues related to the physics engine,
  7. see
  8. `open physics-related issues on GitHub <https://github.com/godotengine/godot/issues?q=is%3Aopen+is%3Aissue+label%3Atopic%3Aphysics>`__.
  9. Looking through `closed issues
  10. <https://github.com/godotengine/godot/issues?q=+is%3Aclosed+is%3Aissue+label%3Atopic%3Aphysics>`__
  11. can also help answer questions related to physics engine behavior.
  12. Objects are passing through each other at high speeds
  13. -----------------------------------------------------
  14. This is known as *tunneling*. Enabling **Continuous CD** in the RigidBody
  15. properties can sometimes resolve this issue. If this does not help, there are
  16. other solutions you can try:
  17. - Make your static collision shapes thicker. For example, if you have a thin
  18. floor that the player can't get below in some way, you can make the collider
  19. thicker than the floor's visual representation.
  20. - Modify your fast-moving object's collision shape depending on its movement
  21. speed. The faster the object moves, the larger the collision shape should
  22. extend outside of the object to ensure it can collide with thin walls more
  23. reliably.
  24. - Increase :ref:`Physics Ticks per Second<class_ProjectSettings_property_physics/common/physics_ticks_per_second>`
  25. in the advanced Project Settings. While
  26. this has other benefits (such as more stable simulation and reduced input
  27. lag), this increases CPU utilization and may not be viable for mobile/web
  28. platforms. Multipliers of the default value of ``60`` (such as ``120``, ``180``
  29. or ``240``) should be preferred for a smooth appearance on most displays.
  30. Stacked objects are unstable and wobbly
  31. ---------------------------------------
  32. Despite seeming like a simple problem, stable RigidBody simulation with stacked
  33. objects is difficult to implement in a physics engine. This is caused by
  34. integrating forces going against each other. The more stacked objects are
  35. present, the stronger the forces will be against each other. This eventually
  36. causes the simulation to become wobbly, making the objects unable to rest on top
  37. of each other without moving.
  38. Increasing the physics simulation rate can help alleviate this issue. To do so,
  39. increase :ref:`Physics Ticks per Second<class_ProjectSettings_property_physics/common/physics_ticks_per_second>`
  40. in the advanced Project Settings. Note
  41. that increases CPU utilization and may not be viable for mobile/web platforms.
  42. Multipliers of the default value of ``60`` (such as ``120``, ``180`` or ``240``)
  43. should be preferred for a smooth appearance on most displays.
  44. In 3D, switching the physics engine from the default GodotPhysics to Jolt
  45. can also improve stability. See :ref:`doc_using_jolt_physics` for more information.
  46. Scaled physics bodies or collision shapes do not collide correctly
  47. ------------------------------------------------------------------
  48. Godot does not currently support scaling of physics bodies or collision shapes.
  49. As a workaround, change the collision shape's extents instead of changing its
  50. scale. If you want the visual representation's scale to change as well, change
  51. the scale of the underlying visual representation (Sprite2D, MeshInstance3D, …)
  52. and change the collision shape's extents separately. Make sure the collision
  53. shape is not a child of the visual representation in this case.
  54. Since resources are shared by default, you'll have to make the collision shape
  55. resource unique if you don't want the change to be applied to all nodes using
  56. the same collision shape resource in the scene. This can be done by calling
  57. ``duplicate()`` in a script on the collision shape resource *before* changing
  58. its size.
  59. Thin objects are wobbly when resting on the floor
  60. -------------------------------------------------
  61. This can be due to one of two causes:
  62. - The floor's collision shape is too thin.
  63. - The RigidBody's collision shape is too thin.
  64. In the first case, this can be alleviated by making the floor's collision shape
  65. thicker. For example, if you have a thin floor that the player can't get below
  66. in some way, you can make the collider thicker than the floor's visual
  67. representation.
  68. In the second case, this can usually only be resolved by increasing the physics
  69. simulation rate (as making the shape thicker would cause a disconnect between
  70. the RigidBody's visual representation and its collision).
  71. In both cases, increasing the physics simulation rate can also help alleviate
  72. this issue. To do so, increase
  73. :ref:`Physics Ticks per Second<class_ProjectSettings_property_physics/common/physics_ticks_per_second>`
  74. in the advanced
  75. Project Settings. Note that this increases CPU utilization and may not be viable
  76. for mobile/web platforms. Multipliers of the default value of ``60`` (such as
  77. ``120``, ``180`` or ``240``) should be preferred for a smooth appearance on most
  78. displays.
  79. Cylinder collision shapes are unstable
  80. --------------------------------------
  81. Switching the physics engine from the default GodotPhysics to Jolt
  82. should make cylinder collision shapes more reliable.
  83. See :ref:`doc_using_jolt_physics` for more information.
  84. During the transition from Bullet to GodotPhysics in Godot 4, cylinder collision
  85. shapes had to be reimplemented from scratch. However, cylinder collision shapes
  86. are one of the most difficult shapes to support, which is why many other physics
  87. engines don't provide any support for them. There are several known bugs with
  88. cylinder collision shapes currently.
  89. If you are sticking to GodotPhysics, we recommend using box or capsule collision
  90. shapes for characters for now. Boxes generally provide the best reliability,
  91. but have the downside of making the character take more space diagonally.
  92. Capsule collision shapes do not have this downside, but their shape can make
  93. precision platforming more difficult.
  94. VehicleBody simulation is unstable, especially at high speeds
  95. -------------------------------------------------------------
  96. When a physics body moves at a high speed, it travels a large distance between
  97. each physics step. For instance, when using the 1 unit = 1 meter convention in
  98. 3D, a vehicle moving at 360 km/h will travel 100 units per second. With the
  99. default physics simulation rate of 60 Hz, the vehicle moves by ~1.67 units each
  100. physics tick. This means that small objects may be ignored entirely by the
  101. vehicle (due to tunneling), but also that the simulation has little data to work
  102. with in general at such a high speed.
  103. Fast-moving vehicles can benefit a lot from an increased physics simulation
  104. rate. To do so, increase
  105. :ref:`Physics Ticks per Second<class_ProjectSettings_property_physics/common/physics_ticks_per_second>`
  106. in the advanced Project
  107. Settings. Note that this increases CPU utilization and may not be viable for
  108. mobile/web platforms. Multipliers of the default value of ``60`` (such as
  109. ``120``, ``180`` or ``240``) should be preferred for a smooth appearance on most
  110. displays.
  111. Collision results in bumps when an object moves across tiles
  112. ------------------------------------------------------------
  113. This is a known issue in the physics engine caused by the object bumping on a
  114. shape's edges, even though that edge is covered by another shape. This can occur
  115. in both 2D and 3D.
  116. The best way to work around this issue is to create a "composite" collider. This
  117. means that instead of individual tiles having their collision, you create a
  118. single collision shape representing the collision for a group of tiles.
  119. Typically, you should split composite colliders on a per-island basis (which
  120. means each group of touching tiles gets its own collider).
  121. Using a composite collider can also improve physics simulation performance in
  122. certain cases. However, since the composite collision shape is much more
  123. complex, this may not be a net performance win in all cases.
  124. .. tip::
  125. In Godot 4.5 and later, creating a composite collider is automatically done
  126. when using a TileMapLayer node. The chunk size (``16`` tiles on each axis
  127. by default) can be set using the **Physics Quadrant Size** property in the
  128. TileMapLayer inspector. Larger values provide more reliable collision,
  129. at the cost of slower updates when the TileMap is changed.
  130. Framerate drops when an object touches another object
  131. -----------------------------------------------------
  132. This is likely due to one of the objects using a collision shape that is too
  133. complex. Convex collision shapes should use a number of shapes as low as
  134. possible for performance reasons. When relying on Godot's automatic generation,
  135. it's possible that you ended up with dozens if not hundreds of shapes created
  136. for a single convex shape collision resource.
  137. In some cases, replacing a convex collider with a couple of primitive collision
  138. shapes (box, sphere, or capsule) can deliver better performance.
  139. This issue can also occur with StaticBodies that use very detailed trimesh
  140. (concave) collisions. In this case, use a simplified representation of the level
  141. geometry as a collider. Not only this will improve physics simulation
  142. performance significantly, but this can also improve stability by letting you
  143. remove small fixtures and crevices from being considered by collision.
  144. In 3D, switching the physics engine from the default GodotPhysics to Jolt
  145. can also improve performance. See :ref:`doc_using_jolt_physics` for more information.
  146. Framerate suddenly drops to a very low value beyond a certain amount of physics simulation
  147. ------------------------------------------------------------------------------------------
  148. This occurs because the physics engine can't keep up with the expected
  149. simulation rate. In this case, the framerate will start dropping, but the engine
  150. is only allowed to simulate a certain number of physics steps per rendered
  151. frame. This snowballs into a situation where framerate keeps dropping until it
  152. reaches a very low framerate (typically 1-2 FPS) and is called the *physics
  153. spiral of death*.
  154. To avoid this, you should check for situations in your project that can cause
  155. excessive number of physics simulations to occur at the same time (or with
  156. excessively complex collision shapes). If these situations cannot be avoided,
  157. you can increase the **Max Physics Steps per Frame** project setting and/or
  158. reduce **Physics Ticks per Second** to alleviate this.
  159. Physics simulation is unreliable when far away from the world origin
  160. --------------------------------------------------------------------
  161. This is caused by floating-point precision errors, which become more pronounced
  162. as the physics simulation occurs further away from the world origin. This issue
  163. also affects rendering, which results in wobbly camera movement when far away
  164. from the world origin. See :ref:`doc_large_world_coordinates` for more
  165. information.