Skip to content

Latest commit

 

History

History
512 lines (499 loc) · 16 KB

settings.md

File metadata and controls

512 lines (499 loc) · 16 KB

Settings

This document details the project settings exposed by this extension as well as which of the default project settings are relevant.

⚠️ Make sure you enable "Advanced Settings" in the top-right corner of the project settings window in order to see the settings listed here.

Table of Contents

Common

These settings are part of Godot"s default project settings and can be found under "Physics" - "Common".

Category Name Supported Notes
- Physics Ticks per Second Yes -
- Max Physics Steps per Frame Yes -
- Enable Object Picking Yes -

3D

These settings are part of Godot"s default project settings and can be found under "Physics" - "3D".

Category Name Supported Notes
- Run on Separate Thread No -
- Physics Engine Yes -
- Default Gravity Yes -
- Default Gravity Vector Yes -
- Default Linear Damp Yes -
- Default Angular Damp Yes -
- Sleep Threshold Linear No See extension settings below.
- Sleep Threshold Angular No See extension settings below.
- Time Before Sleep No See extension settings below.
Solver Solver Iterations No See extension settings below.
Solver Contact Recycle Radius No -
Solver Contact Max Separation No -
Solver Contact Max Allowed Penetration No See extension settings below.
Solver Default Contact Bias No -

Jolt 3D

These settings are exposed by Godot Jolt and can be found under "Physics" - "Jolt 3D".

Category Name Description Notes
Sleep Enabled Whether bodies are allowed to go to sleep. -
Sleep Velocity Threshold The point velocity on a body"s bounding box below which a body can be considered sleeping. -
Sleep Time Threshold Time spent below the velocity threshold after which a body can be considered sleeping. -
Collisions Use Shape Margins Whether or not the margin property on Shape3D should be respected for the applicable convex shape types. When disabled this will force a shape margin of 0, trading in performance for accuracy, which can make things like collision normals more intuitive.

This only applies to BoxShape3D, CylinderShape3D and ConvexPolygonShape3D. Other shape types do not utilize margins.
Collisions Use Enhanced Internal Edge Removal Whether or not to enable the enhanced internal edge removal for RigidBody3D, which means that extra effort will be made to try to remove collisions with internal edges of another physics body. This makes physics bodies move smoother over certain shapes, at the cost of performance. -
Collisions Areas Detect Static Bodies Whether or not Area3D is able to detect overlaps with StaticBody3D and RigidBody3D frozen with FREEZE_MODE_STATIC. ⚠️ This can come at a heavy performance and memory cost if you allow many/large areas to overlap with complex static geometry, such as ConcavePolygonShape3D or HeightMapShape3D.

It is strongly recommended that you set up your collision layers and masks in such a way that only a few small Area3D can detect static bodies.
Collisions Report All Kinematic Contacts Whether or not a RigidBody3D frozen with FREEZE_MODE_KINEMATIC is able to collide with (and thus reports contacts for) other kinematic/static bodies. ⚠️ Much like the "Areas Detect Static Bodies" setting, this setting can come at a heavy performance and memory cost if you allow many/large frozen kinematic bodies with a non-zero max_contacts_reported to overlap with complex static geometry, such as ConcavePolygonShape3D or HeightMapShape3D.

It is strongly recommended that you set up your collision layers and masks in such a way that only a few small such kinematic bodies can detect static bodies.
Collisions Soft Body Point Margin How much of a margin to add to the soft body points. This can keep soft bodies (like cloth) from laying perfectly flush against other surfaces, thereby preventing Z-fighting. -
Collisions Body Pair Cache Enabled Whether the body pair cache is enabled, which removes the need for potentially expensive collision detection when the relative orientation between two bodies didn"t change. -
Collisions Body Pair Cache Distance Threshold The maximum relative distance by which a body pair can move and still reuse the collision results from the previous physics tick. -
Collisions Body Pair Cache Angle Threshold The maximum relative angle by which a body pair can move and still reuse the collision results from the previous physics tick. -
Joints World Node Which of the two nodes should become the "world node" when omitting one of the nodes. ⚠️ The default value for this setting, "Node A", differs from how this behaves in Godot Physics, where this is effectively "Node B" instead.

If you need 1-body joints to behave like they do in Godot Physics then change this to "Node B". Note that this can result in strange and unintuitive behavior when combining linear and angular degrees-of-freedom for the 6DOF joint.
Continuous CD Movement Threshold Percentage of its inner radius a body must move per step to make use of CCD. -
Continuous CD Max Penetration Percentage of its inner radius a body may penetrate another body whilst using CCD. -
Kinematics Use Enhanced Internal Edge Removal Whether or not to enable the enhanced internal edge removal for the kinematic movement methods (move_and_slide, move_and_collide, test_move and body_test_motion) which means that extra effort will be made to try to remove hits with internal edges of whatever physics body they hit, which can help alleviate odd collision normals and thus ghost collisions. -
Kinematics Recovery Iterations The number of iterations to run when resolving penetration during things like move_and_slide. -
Kinematics Recovery Amount How much of the penetration to correct per iteration during things like move_and_slide. -
Queries Use Enhanced Internal Edge Removal Whether or not to enable the enhanced internal edge removal for the shape query methods (collide_shape, intersect_shape, get_rest_info and cast_motion) which means that extra effort will be made to try to remove hits with internal edges of whatever physics body they hit, which can help alleviate odd collision normals. Note that enabling this can result in hits against individual shapes of bodies that have multiple shapes to not be reported at all, so it"s generally only advisable to enable this if you"re using the shape queries for things like kinematic movement and you"re willing to accept this compromise.
Queries Use Legacy Ray Casting Whether to use the ray-casting behavior prior to version 0.14.0-stable, where ray-casts would hit the inside hull of any convex shapes if the hit_back_faces ray-cast parameter was enabled, which it is by default. With this project setting disabled you will instead get the same behavior as with Godot Physics, where hit_back_faces only applies to concave shapes, and only if the backface_collision property of ConcavePolygonShape3D is enabled as well.
Queries Enable Ray Cast Face Index Whether to actually populate the face_index field in the result Dictionary from intersect_ray, also known as get_collision_face_index() in the RayCast3D node. ⚠️ Enabling this can come at a fairly heavy memory cost if you have many (or complex) ConcavePolygonShape3D in your scene, as this roughly adds an additional 25% memory.
Solver Velocity Iterations The number of solver velocity iterations to run during a physics tick. -
Solver Position Iterations The number of solver position iterations to run during a physics tick. -
Solver Position Correction How much of the position error to correct during a physics tick. -
Solver Active Edge Threshold The cut-off angle for the active edge detection. This angle determines whether or not an edge between two triangles in either a ConcavePolygonShape3D or HeightMapShape3D will be considered "active" or "inactive", where contact with an inactive edge will have its normal overridden to instead be the surface normal of the triangle.

Setting this too low can result in ghost collisions. Setting this too high can result in things like RigidBody3D sinking into triangle edges or move_and_slide behaving in weird ways when going over or pressing up against triangle edges.

Note that this setting has no effect when using any of the "Use Enhanced Internal Edge Removal" settings.
Solver Bounce Velocity Threshold The minimum velocity needed before a collision can be elastic. -
Solver Contact Speculative Distance Radius around objects, inside which speculative contact points will be detected. Setting this too high will result in ghost collisions, as speculative contacts are based on the closest points during the collision detection step which may not be the actual closest points by the time the two objects hit.
Solver Contact Allowed Penetration How much bodies are allowed to penetrate eachother. -
Limits World Boundary Shape Size How wide/high/deep a WorldBoundaryShape3D will be. Note that only half of this value will be used for its height.
Limits Max Linear Velocity The maximum linear velocity that a body can reach. Meant to prevent the simulation from exploding if something goes wrong.
Limits Max Angular Velocity The maximum angular velocity that a body can reach. Meant to prevent the simulation from exploding if something goes wrong.
Limits Max Bodies The maximum number of bodies to support, awake or otherwise. When this limit is exceeded a warning is emitted and anything past that point is undefined behavior.

⚠️ This also applies within the editor.
Limits Max Body Pairs The maximum number of body pairs to allow processing of. When this limit is exceeded a warning is emitted and any additional body pairs will be ignored.
Limits Max Contact Constraints The maximum number of contact constraints to allow processing of. When this limit is exceeded a warning is emitted and any additional contacts will be ignored.
Limits Max Temporary Memory The amount of memory to pre-allocate for the stack-allocator used within a physics tick. When this limit is exceeded a warning is emitted and any additional allocations will fall back to a much slower general-purpose allocator.