Document Jolt built-in module in 4.4

Author: skyace65

tutorials/physics/index.rst

@@ -10,6 +10,7 @@ Physics
    :name: toc-learn-features-physics
 
    physics_introduction
+   using_jolt_physics
    rigid_body
    using_area_2d
    using_character_body_2d

tutorials/physics/using_jolt_physics.rst

@@ -0,0 +1,288 @@
+.. _doc_using_jolt_physics:
+
+Using Jolt Physics
+==================
+
+Overview
+--------
+
+The Jolt physics engine was added as an alternative to the existing GodotPhysics3D
+physics engine in 4.4. Jolt is developed by Jorrit Rouwe with a focus on games and
+VR applications. Previously it was available as a extension but is now built into
+Godot.
+
+It is important to note that the built in Jolt Physics module is considered
+**not finished**, **experimental**, and **lacks feature partiy** with both
+GodotPhysics3D, and the Jolt Extension. Behavior may change as it is developed
+further, please keep that in mind when choosing what to use for your project. A
+roadmap of this module can be found at the bottom of this page.
+
+The existing extension is now considered in maintenance mode. That means bug fixes
+will be merged, and it will be kept compatible with new versions of Godot until
+the built-in module has feature parity with the extension. The extension can be
+found `here on GitHub <https://github.com/godot-jolt/godot-jolt>`_ and in Godot's asset
+library.
+
+To change the 3D physics engine to the Jolt module go to
+:ref:`**Project Settings > Physics > 3D > Physics Engine**<class_ProjectSettings_property_physics/3D/Physics_Engine>`
+and select ``Jolt Physics`` from the dropdown menu. Once you've done that click the
+``Save & Restart`` button, when the editor opens again 3D scenes should now be using
+Jolt for physics.
+
+Notable differences to Godot Physics
+------------------------------------
+
+There are many differences between the existing GodotPhysics3D engine and Jolt.
+
+Area3D and static bodies
+~~~~~~~~~~~~~~~~~~~~~~~~
+When using Jolt, :ref:`class_Area3D` will not detect overlaps with :ref:`class_StaticBody3D`
+(nor a :ref:`class_RigidBody3D` frozen with ``FREEZE_MODE_STATIC``) by default, for
+performance reasons. If you have many/large :ref:`class_Area3D` overlapping with
+complex static geometry, such as :ref:`class_ConcavePolygonShape3D` or
+:ref:`class_HeightMapShape3D`, you can end up wasting a significant amount of CPU
+performance without realizing it.
+
+For this reason this behavior is opt-in through the project setting
+:ref:`physics/jolt_physics_3d/simulation/areas_detect_static_bodies<class_ProjectSettings_property_physics/jolt_physics_3d/simulation/areas_detect_static_bodies>`,
+with the recommendation that you set up your collision layers/masks in such a way that only
+the relevant :ref:`class_Area3D` are able to detect collisions with static bodies.
+
+Joint properties
+~~~~~~~~~~~~~~~~
+
+The current interfaces for the 3D joint nodes don't quite line up with the interface
+of Jolt's own joints. As such, there are a number of joint properties that are not
+supported, mainly ones related to configuring the joint's soft limits.
+
+The unsupported properties are:
+
+- PinJoint3D: ``bias``, ``damping``, ``impulse_clamp``
+- HingeJoint3D: ``bias``, ``softness``, ``relaxation``
+- SliderJoint3D: ``angular_\*``, ``\*_limit/softness``, ``\*_limit/restitution``, ``\*_limit/damping``
+- ConeTwistJoint3D: ``bias``, ``relaxation``, ``softness``
+- Generic6DOFJoint3D: ``*_limit_*/softness``, ``*_limit_*/restitution``, ``*_limit_*/damping``, ``*_limit_*/erp``
+
+Currently an error is emitted if you set these properties to anything but their
+default values.
+
+Single-body joints
+~~~~~~~~~~~~~~~~~~
+
+You can, in Godot, omit one of the joint bodies for a two-body joint and effectively
+have "the world" be the other body. However, the node path that you assign your body
+to (node_a vs node_b) is ignored. Godot Physics will always behave as if you
+assigned it to node_a, and since node_a is also what defines the frame of reference
+for the joint limits, you end up with inverted limits and a potentially strange
+limit shape, especially if your limits allow both linear and angular degrees of
+freedom.
+
+Jolt will behave as if you assigned the body to node_b instead, with node_a
+representing "the world". There is a project setting called :ref:`physics/jolt_physics_3d/joints/world_node<class_ProjectSettings_property_physics/jolt_physics_3d/joints/world_node>`
+that lets you toggle this behavior, if you need compatibility for an existing project.
+
+Collision margins
+~~~~~~~~~~~~~~~~~
+
+Jolt (and other similar physics engines) uses something that Jolt refers to as
+"convex radius" to help improve the performance and behavior of the types of
+collision detection that Jolt relies on for convex shapes. Other physics engines
+(Godot included) might refer to these as "collision margins" instead. Godot exposes
+these as the margin property on every Shape3D-derived class, as a leftover from the
+Bullet integration in Godot 3, but Godot Physics itself does not use them for
+anything.
+
+What these collision margins sometimes do in other engines (as described in Godot's
+documentation) is effectively add a "shell" around the shape, slightly increasing
+its size while also rounding off any edges/corners. In Jolt however, these margins
+are first used to shrink the shape, and then the "shell" is applied, resulting in
+edges/corners being similarly rounded off, but without increasing the size of the
+shape.
+
+To prevent having to tweak this margin property manually, since its default value
+can be problematic for smaller shapes, this module exposes a project setting called
+:ref:`physics/jolt_physics_3d/collisions/collision_margin_fraction<class_ProjectSettings_property_physics/jolt_physics_3d/collisions/collision_margin_fraction>`
+which is multiplied with the smallest axis of the shape's AABB to calculate the
+actual margin. The margin property of the shape is then instead used as an upper
+bound.
+
+These margins should, for most use-cases, be more or less transparent, but can
+sometimes result in odd collision normals when performing shape queries. You can
+lower the above mentioned project setting to mitigate some of this, including
+setting it to ``0``, but too small of a margin can also cause odd collision results,
+so is generally not recommended.
+
+Baumgarte stabilization
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Jolt employs a technique in its solver called Baumgarte stabilization, which is
+meant to mitigate constraint drift within the simulation, resulting in a more stable
+simulation. This technique can however result in some artifacts, like piles of
+bodies not separating as quickly as one might expect.
+
+The strength of this stabilization can be tweaked using the project setting
+:ref:`physics/jolt_physics_3d/simulation/baumgarte_stabilization_factor<class_ProjectSettings_property_physics/jolt_physics_3d/simulation/baumgarte_stabilization_factor>`.
+Setting this project setting to ``1.0`` will resolve penetration in 1 simulation
+step, resulting in a simulation that more closely resembles Godot Physics, but which
+is also more unstable.
+
+Ghost collisions
+~~~~~~~~~~~~~~~~
+
+Jolt employs two techniques to mitigate ghost collisions, meaning collisions with
+internal edges of shapes/bodies.
+
+The first technique, called "active edge detection", marks edges of triangles in
+:ref:`class_ConcavePolygonShape3D` or :ref:`class_HeightMapShape3D` as either "active" or "inactive", based on
+the angle to the neighboring triangle. When a collision happens with an inactive
+edge the collision normal will be replaced with the triangle's normal instead, to
+lessen the effect of ghost collisions.
+
+The angle threshold for this active edge detection is configurable through the
+project setting :ref:`physics/jolt_physics_3d/collisions/active_edge_threshold<class_ProjectSettings_property_physics/jolt_physics_3d/collisions/active_edge_threshold>`.
+
+The second technique, called "enhanced internal edge removal", instead adds runtime
+checks to detect whether an edge is active or inactive, based on the contact points
+of the two bodies. This has the benefit of applying not only to collisions with
+:ref:`class_ConcavePolygonShape3D` and :ref:`class_HeightMapShape3D`, but also edges between any shapes within
+the same body.
+
+Enhanced internal edge removal can be toggled on and off for the various contexts to
+which it's applied, using the ``physics/jolt_physics_3d/*/use_enhanced_internal_edge_removal``
+project settings.
+
+Memory usage
+~~~~~~~~~~~~
+
+Jolt uses a stack allocator for temporary allocations within its simulation step.
+This stack allocator requires allocating a set amount of memory up front, which can
+be configured using the :ref:`physics/jolt_physics_3d/limits/temporary_memory_buffer_size<class_ProjectSettings_property_physics/jolt_physics_3d/limits/temporary_memory_buffer_size>`
+project setting.
+
+Jolt also makes use of aligned allocations for some of its memory usage, which it
+acquires through function pointers that the implementer assigns. Aligned allocations
+were recently added to Godot in the form of ``Memory::alloc_aligned_static``,
+``Memory::realloc_aligned_static``, and ``Memory::free_aligned_static``, which have all been
+hooked up to Jolt. However, these aligned allocation functions don't currently touch
+``Memory::mem_usage``, which means that some of Jolt's memory won't be tracked, and thus
+the performance monitors in Godot won't be accurate.
+
+Ray-Cast face index
+~~~~~~~~~~~~~~~~~~~
+
+The face_index property returned in the results of intersect_ray and RayCast3D will
+by default always be ``-1`` with Jolt, the project setting :ref:`physics/jolt_physics_3d/queries/enable_ray_cast_face_index<class_ProjectSettings_property_physics/jolt_physics_3d/queries/enable_ray_cast_face_index>`
+will enable them. The reason for this being that Jolt does not store these indices,
+and for them to be stored per-triangle userdata must be enabled, which adds about
+25% extra memory usage to the underlying Jolt implementation of :ref:`class_ConcavePolygonShape3D`.
+
+Kinematic RigidBody3D contacts
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When using Jolt, a :ref:`class_RigidBody3D` frozen with ``FREEZE_MODE_KINEMATIC`` will by default not
+report contacts from collisions with other static/kinematic bodies, for performance
+reasons, even when setting a non-zero max_contacts_reported. If you have many/large
+kinematic bodies overlapping with complex static geometry, such as :ref:`class_ConcavePolygonShape3D`
+or :ref:`class_HeightMapShape3D`, you can end up wasting a significant amount of CPU
+performance without realizing it.
+
+For this reason this behavior is opt-in through the project setting
+:ref:`physics/jolt_physics_3d/simulation/generate_all_kinematic_contacts<class_ProjectSettings_property_physics/jolt_physics_3d/simulation/generate_all_kinematic_contacts>`.
+
+Contact impulses
+~~~~~~~~~~~~~~~~
+
+Jolt is not able to provide any impulse as part of its contact data, due to how it
+orders its simulation step, and instead provides a helper function for estimating
+what the impulse would be based on various parameters. While this is fine for most
+use cases, like emitting a sound based on how hard something collided, it won't be
+accurate if a body is colliding with multiple bodies during a simulation step.
+
+Area3D and SoftBody3D
+~~~~~~~~~~~~~~~~~~~~~
+
+This module does not currently support any interactions between :ref:`class_SoftBody3D`
+and :ref:`class_Area3D`, such as overlap events, or the wind properties found on
+:ref:`class_Area3D`. Support for this has been added to Jolt recently, but it is not
+currently part of the built-in Jolt module.
+
+WorldBoundaryShape3D
+~~~~~~~~~~~~~~~~~~~~
+
+:ref:`class_WorldBoundaryShape3D`, which is meant to represent an infinite plane, is
+implemented a bit differently in Jolt compared to Godot Physics. Both engines have
+an upper limit for how big the effective size of this plane can be, but this size is
+much smaller when using Jolt, in order to avoid precision issues.
+
+You can configure this size using the :ref:`physics/jolt_physics_3d/limits/world_boundary_shape_size<Class_ProjectSettings_Property_physics/jolt_physics_3d/limits/world_boundary_shape_size>`
+project setting.
+
+Notable differences to Godot Jolt
+---------------------------------
+
+While this module is largely a straight port of the Godot Jolt extension, with a lot
+of cosmetic changes, there are a few things that are different.
+
+Project Settings
+~~~~~~~~~~~~~~~~
+
+All project settings have been moved from the ``physics/jolt_3d`` category to
+``physics/jolt_physics_3d``.
+
+On top of that, there's been some renaming and refactoring of the individual project
+settings as well. These include:
+
+- ``sleep/enabled`` is now ``simulation/allow_sleep.``
+- ``sleep/velocity_threshold`` is now ``simulation/sleep_velocity_threshold.``
+- ``sleep/time_threshold`` is now ``simulation/sleep_time_threshold.``
+- ``collisions/use_shape_margins`` is now ``collisions/collision_margin_fraction``,
+  where a value of 0 is equivalent to disabling it.
+- ``collisions/use_enhanced_internal_edge_removal`` is now ``simulation/use_enhanced_internal_edge_removal.``
+- ``collisions/areas_detect_static_bodies`` is now ``simulation/areas_detect_static_bodies.``
+- ``collisions/report_all_kinematic_contacts`` is now ``simulation/generate_all_kinematic_contacts.``
+- ``collisions/soft_body_point_margin`` is now ``simulation/soft_body_point_radius.``
+- ``collisions/body_pair_cache_enabled is now simulation/body_pair_contact_cache_enabled.``
+- ``collisions/body_pair_cache_distance_threshold`` is ``now simulation/body_pair_contact_cache_distance_threshold.``
+- ``collisions/body_pair_cache_angle_threshold is now simulation/body_pair_contact_cache_angle_threshold.``
+- ``continuous_cd/movement_threshold`` is now ``simulation/continuous_cd_movement_threshold``,
+  but expressed as a fraction instead of a percentage.
+- ``continuous_cd/max_penetration`` is now ``simulation/continuous_cd_max_penetration``,
+  but expressed as a fraction instead of a percentage.
+- ``kinematics/use_enhanced_internal_edge_removal`` is now ``motion_queries/use_enhanced_internal_edge_removal.``
+- ``kinematics/recovery_iterations`` is now ``motion_queries/recovery_iterations``,
+  but expressed as a fraction instead of a percentage.
+- ``kinematics/recovery_amount`` is now ``motion_queries/recovery_amount.``
+- ``queries/use_legacy_ray_casting`` has been removed.
+- ``solver/position_iterations`` is now ``simulation/position_steps.``
+- ``solver/velocity_iterations`` is now ``simulation/velocity_steps.``
+- ``solver/position_correction`` is now ``simulation/baumgarte_stabilization_factor``,
+  but expressed as a fraction instead of a percentage.
+- ``solver/active_edge_threshold`` is now ``collisions/active_edge_threshold.``
+- ``solver/bounce_velocity_threshold`` is now ``simulation/bounce_velocity_threshold.``
+- ``solver/contact_speculative_distance`` is now ``simulation/speculative_contact_distance.``
+- ``solver/contact_allowed_penetration`` is now ``simulation/penetration_slop.``
+- ``limits/max_angular_velocity`` is now stored as radians instead.
+- ``limits/max_temporary_memory`` is now ``limits/temporary_memory_buffer_size.``
+
+There might be some discussion to be had with regards to migrating the settings
+values for projects who have previously been relying on the extension.
+
+Joint Nodes
+~~~~~~~~~~~
+
+The joint nodes that are exposed in the Godot Jolt extension (JoltPinJoint3D,
+JoltHingeJoint3D, JoltSliderJoint3D, JoltConeTwistJoint3D, and JoltGeneric6DOFJoint)
+have not been included with this module.
+
+Thread Safety
+~~~~~~~~~~~~~
+
+Unlike the Godot Jolt extension, this module does have experimental thread-safety,
+including support for the :ref:`physics/3d/run_on_separate_thread<class_ProjectSettings_Property_physics/3d/run_on_separate_thread>`
+project setting. This is achieved by utilizing the same wrapper server that's used
+by Godot Physics, called ``PhysicsServer3DWrapMT``, as well as introducing a mutex
+around the rebuilding of shapes, since concurrent shape-casts could otherwise
+trigger a race condition.
+
+This has however not been tested very thoroughly, so should be considered
+experimental.