Skip to content

Latest commit

 

History

History
473 lines (460 loc) · 14.2 KB

settings.md

File metadata and controls

473 lines (460 loc) · 14.2 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, which means that extra effort will be made to try to remove collisions with internal edges of ConcavePolygonShape3D and HeightMapShape3D. This makes physics bodies move smoother over such shapes, at the cost of performance. Note that this applies to RigidBody3D as well as queries like get_rest_info, move_and_collide and move_and_slide.

Also note that enabling this setting will leave the "Active Edge Threshold" setting unused.
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 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 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 the "Use Enhanced Internal Edge Removal" setting.
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.