From 4992f01016f7fcd65ac37951705e64ca3f2d479b Mon Sep 17 00:00:00 2001 From: Hugo Locurcio Date: Fri, 7 Apr 2023 22:47:02 +0200 Subject: [PATCH] Add a page on troubleshooting common physics issues This covers the most commonly encountered physics issues one may encounter while developing a project. --- tutorials/physics/index.rst | 1 + tutorials/physics/large_world_coordinates.rst | 2 + .../troubleshooting_physics_issues.rst | 166 ++++++++++++++++++ 3 files changed, 169 insertions(+) create mode 100644 tutorials/physics/troubleshooting_physics_issues.rst diff --git a/tutorials/physics/index.rst b/tutorials/physics/index.rst index 746082c32..4ba2acd29 100644 --- a/tutorials/physics/index.rst +++ b/tutorials/physics/index.rst @@ -16,3 +16,4 @@ Physics collision_shapes_2d collision_shapes_3d large_world_coordinates + troubleshooting_physics_issues diff --git a/tutorials/physics/large_world_coordinates.rst b/tutorials/physics/large_world_coordinates.rst index 9ebe17c95..2fa5cb2d7 100644 --- a/tutorials/physics/large_world_coordinates.rst +++ b/tutorials/physics/large_world_coordinates.rst @@ -1,3 +1,5 @@ +.. _doc_large_world_coordinates: + Large world coordinates ======================= diff --git a/tutorials/physics/troubleshooting_physics_issues.rst b/tutorials/physics/troubleshooting_physics_issues.rst new file mode 100644 index 000000000..4735814fe --- /dev/null +++ b/tutorials/physics/troubleshooting_physics_issues.rst @@ -0,0 +1,166 @@ +.. _doc_troubleshooting_physics_issues: + +Troubleshooting physics issues +============================== + +When working with a physics engine, you may encounter unexpected results. + +While many of these issues can be resolved through configuration, some of them +are the result of engine bugs. For known issues related to the physics engine, +see +`open physics-related issues on GitHub `__. +Looking through `closed issues +`__ +can also help answer questions related to physics engine behavior. + +Objects are passing through each other at high speeds +----------------------------------------------------- + +This is known as *tunneling*. Enabling **Continuous CD** in the RigidBody +properties can sometimes resolve this issue. If this does not help, there are +other solutions you can try: + +- Make your static collision shapes thicker. For example, if you have a thin + floor that the player can't get below in some way, you can make the collider + thicker than the floor's visual representation. +- Modify your fast-moving object's collision shape depending on its movement + speed. The faster the object moves, the larger the collision shape should + extend outside of the object to ensure it can collide with thin walls more + reliably. +- Increase **Physics Ticks Per Second** in the advanced Project Settings. While + this has other benefits (such as more stable simulation and reduced input + lag), this increases CPU utilization and may not be viable for mobile/web + platforms. Multipliers of the default value of ``60`` (such as ``120``, ``180`` + or ``240``) should be preferred for a smooth appearance on most displays. + +Stacked objects are unstable and wobbly +--------------------------------------- + +Despite seeming like a simple problem, stable RigidBody simulation with stacked +objects is difficult to implement in a physics engine. This is caused by +integrating forces going against each other. The more stacked objects are +present, the stronger the forces will be against each other. This eventually +causes the simulation to become wobbly, making the objects unable to rest on top +of each other without moving. + +Increasing the physics simulation rate can help alleviate this issue. To do so, +increase **Physics Ticks Per Second** in the advanced Project Settings. Note +that increases CPU utilization and may not be viable for mobile/web platforms. +Multipliers of the default value of ``60`` (such as ``120``, ``180`` or ``240``) +should be preferred for a smooth appearance on most displays. + +Scaled physics bodies or collision shapes do not collide correctly +------------------------------------------------------------------ + +Godot does not currently support scaling of physics bodies or collision shapes. +As a workaround, change the collision shape's extents instead of changing its +scale. If you want the visual representation's scale to change as well, change +the scale of the underlying visual representation (Sprite2D, MeshInstance3D, …) +and change the collision shape's extents separately. Make sure the collision +shape is not a child of the visual representation in this case. + +Since resources are shared by default, you'll have to make the collision shape +resource unique if you don't want the change to be applied to all nodes using +the same collision shape resource in the scene. This can be done by calling +``duplicate()`` in a script on the collision shape resource *before* changing +its size. + +Thin objects are wobbly when resting on the floor +------------------------------------------------- + +This can be due to one of two causes: + +- The floor's collision shape is too thin. +- The RigidBody's collision shape is too thin. + +In the first case, this can be alleviated by making the floor's collision shape +thicker. For example, if you have a thin floor that the player can't get below +in some way, you can make the collider thicker than the floor's visual +representation. + +In the second case, this can usually only be resolved by increasing the physics +simulation rate (as making the shape thicker would cause a disconnect between +the RigidBody's visual representation and its collision). + +In both cases, increasing the physics simulation rate can also help alleviate +this issue. To do so, increase **Physics Ticks Per Second** in the advanced +Project Settings. Note that this increases CPU utilization and may not be viable +for mobile/web platforms. Multipliers of the default value of ``60`` (such as +``120``, ``180`` or ``240``) should be preferred for a smooth appearance on most +displays. + +Cylinder collision shapes are unstable +-------------------------------------- + +During the transition from Bullet to GodotPhysics in Godot 4, cylinder collision +shapes had to be reimplemented from scratch. However, cylinder collision shapes +are one of the most difficult shapes to support, which is why many other physics +engines don't provide any support for them. There are several known bugs with +cylinder collision shapes currently. + +We recommend using box or capsule collision shapes for characters for now. Boxes +generally provide the best reliability, but have the downside of making the +character take more space diagonally. Capsule collision shapes do not have this +downside, but their shape can make precision platforming more difficult. + +VehicleBody simulation is unstable, especially at high speeds +------------------------------------------------------------- + +When a physics body moves at a high speed, it travels a large distance between +each physics step. For instance, when using the 1 unit = 1 meter convention in +3D, a vehicle moving at 360 km/h will travel 100 units per second. With the +default physics simulation rate of 60 Hz, the vehicle moves by ~1.67 units each +physics tick. This means that small objects may be ignored entirely by the +vehicle (due to tunneling), but also that the simulation has little data to work +with in general at such a high speed. + +Fast-moving vehicles can benefit a lot from an increased physics simulation +rate. To do so, increase **Physics Ticks Per Second** in the advanced Project +Settings. Note that this increases CPU utilization and may not be viable for +mobile/web platforms. Multipliers of the default value of ``60`` (such as +``120``, ``180`` or ``240``) should be preferred for a smooth appearance on most +displays. + +Collision results in bumps when an object moves across tiles +------------------------------------------------------------ + +This is a known issue in the physics engine caused by the object bumping on a +shape's edges, even though that edge is covered by another shape. This can occur +in both 2D and 3D. + +The best way to work around this issue is to create a "composite" collider. This +means that instead of individual tiles having their collision, you create a +single collision shape representing the collision for a group of tiles. +Typically, you should split composite colliders on a per-island basis (which +means each group of touching tiles gets its own collider). + +Using a composite collider can also improve physics simulation performance in +certain cases. However, since the composite collision shape is much more +complex, this may not be a net performance win in all cases. + +Framerate drops when an object touches another object +----------------------------------------------------- + +This is likely due to one of the objects using a collision shape that is too +complex. Convex collision shapes should use a number of shapes as low as +possible for performance reasons. When relying on Godot's automatic generation, +it's possible that you ended up with dozens if not hundreds of shapes created +for a single convex shape collision resource. + +In some cases, replacing a convex collider with a couple of primitive collision +shapes (box, sphere, or capsule) can deliver better performance. + +This issue can also occur with StaticBodies that use very detailed trimesh +(concave) collisions. In this case, use a simplified representation of the level +geometry as a collider. Not only this will improve physics simulation +performance significantly, but this can also improve stability by letting you +remove small fixtures and crevices from being considered by collision. + +Physics simulation is unreliable when far away from the world origin +-------------------------------------------------------------------- + +This is caused by floating-point precision errors, which become more pronounced +as the physics simulation occurs further away from the world origin. This issue +also affects rendering, which results in wobbly camera movement when far away +from the world origin. See :ref:`doc_large_world_coordinates` for more +information.