From 3227a23031bc2eef1dfd0f1c259f8e3eeafd9eb3 Mon Sep 17 00:00:00 2001 From: MJacred Date: Sat, 20 May 2023 18:48:34 +0200 Subject: [PATCH] Warn against using non-uniform scale for 3D physics (in class reference only) partial backport of #67847 fixes #56824 --- doc/classes/Area.xml | 1 + doc/classes/CollisionObject.xml | 1 + doc/classes/CollisionPolygon.xml | 1 + doc/classes/CollisionShape.xml | 1 + doc/classes/KinematicBody.xml | 1 + doc/classes/PhysicsBody.xml | 1 + doc/classes/RigidBody.xml | 1 + doc/classes/StaticBody.xml | 5 +++-- doc/classes/VehicleBody.xml | 1 + modules/skeleton_3d/doc_classes/PhysicalBone.xml | 1 + 10 files changed, 12 insertions(+), 2 deletions(-) diff --git a/doc/classes/Area.xml b/doc/classes/Area.xml index e5b3f197f..dbd443b61 100644 --- a/doc/classes/Area.xml +++ b/doc/classes/Area.xml @@ -7,6 +7,7 @@ 3D area that detects [CollisionObject] nodes overlapping, entering, or exiting. Can also alter or override local physics parameters (gravity, damping) and route audio to a custom audio bus. To give the area its shape, add a [CollisionShape] or a [CollisionPolygon] node as a [i]direct[/i] child (or add multiple such nodes as direct children) of the area. [b]Warning:[/b] See [ConcavePolygonShape] (also called "trimesh") for a warning about possibly unexpected behavior when using that shape for an area. + [b]Warning:[/b] With a non-uniform scale this node will probably not function as expected. Please make sure to keep its scale uniform (i.e. the same on all axes), and change the size(s) of its collision shape(s) instead. https://godotengine.org/asset-library/asset/125 diff --git a/doc/classes/CollisionObject.xml b/doc/classes/CollisionObject.xml index 54306b62f..7c0de97bf 100644 --- a/doc/classes/CollisionObject.xml +++ b/doc/classes/CollisionObject.xml @@ -5,6 +5,7 @@ CollisionObject is the base class for physics objects. It can hold any number of collision [Shape]s. Each shape must be assigned to a [i]shape owner[/i]. The CollisionObject can have any number of shape owners. Shape owners are not nodes and do not appear in the editor, but are accessible through code using the [code]shape_owner_*[/code] methods. + [b]Warning:[/b] With a non-uniform scale this node will probably not function as expected. Please make sure to keep its scale uniform (i.e. the same on all axes), and change the size(s) of its collision shape(s) instead. diff --git a/doc/classes/CollisionPolygon.xml b/doc/classes/CollisionPolygon.xml index 319c5160e..25dba639b 100644 --- a/doc/classes/CollisionPolygon.xml +++ b/doc/classes/CollisionPolygon.xml @@ -5,6 +5,7 @@ Allows editing a collision polygon's vertices on a selected plane. Can also set a depth perpendicular to that plane. This class is only available in the editor. It will not appear in the scene tree at run-time. Creates a [Shape] for gameplay. Properties modified during gameplay will have no effect. + [b]Warning:[/b] A non-uniformly scaled CollisionPolygon3D node will probably not function as expected. Please make sure to keep its scale uniform (i.e. the same on all axes), and change its [member polygon]'s vertices instead. diff --git a/doc/classes/CollisionShape.xml b/doc/classes/CollisionShape.xml index 94068a1d3..f1897a79e 100644 --- a/doc/classes/CollisionShape.xml +++ b/doc/classes/CollisionShape.xml @@ -6,6 +6,7 @@ Editor facility for creating and editing collision shapes in 3D space. Set the [member shape] property to configure the shape. [b]IMPORTANT[/b]: this is an Editor-only helper to create shapes, use [method CollisionObject.shape_owner_get_shape] to get the actual shape. You can use this node to represent all sorts of collision shapes, for example, add this to an [Area] to give it a detection shape, or add it to a [PhysicsBody] to create a solid object. + [b]Warning:[/b] A non-uniformly scaled CollisionShape3D node will probably not function as expected. Please make sure to keep its scale uniform (i.e. the same on all axes), and change the size of its [member shape] resource instead. $DOCS_URL/tutorials/physics/physics_introduction.html diff --git a/doc/classes/KinematicBody.xml b/doc/classes/KinematicBody.xml index 2baa15cb0..9b7db6c9f 100644 --- a/doc/classes/KinematicBody.xml +++ b/doc/classes/KinematicBody.xml @@ -7,6 +7,7 @@ Kinematic bodies are special types of bodies that are meant to be user-controlled. They are not affected by physics at all; to other types of bodies, such as a character or a rigid body, these are the same as a static body. However, they have two main uses: [b]Simulated motion:[/b] When these bodies are moved manually, either from code or from an [AnimationPlayer] (with [member AnimationPlayer.playback_process_mode] set to "physics"), the physics will automatically compute an estimate of their linear and angular velocity. This makes them very useful for moving platforms or other AnimationPlayer-controlled objects (like a door, a bridge that opens, etc). [b]Kinematic characters:[/b] KinematicBody also has an API for moving objects (the [method move_and_collide] and [method move_and_slide] methods) while performing collision tests. This makes them really useful to implement characters that collide against a world, but don't require advanced physics. + [b]Warning:[/b] With a non-uniform scale this node will probably not function as expected. Please make sure to keep its scale uniform (i.e. the same on all axes), and change the size(s) of its collision shape(s) instead. $DOCS_URL/tutorials/physics/kinematic_character_2d.html diff --git a/doc/classes/PhysicsBody.xml b/doc/classes/PhysicsBody.xml index 71e9d25d3..54e28a6ee 100644 --- a/doc/classes/PhysicsBody.xml +++ b/doc/classes/PhysicsBody.xml @@ -5,6 +5,7 @@ PhysicsBody is an abstract base class for implementing a physics body. All *Body types inherit from it. + [b]Warning:[/b] With a non-uniform scale this node will probably not function as expected. Please make sure to keep its scale uniform (i.e. the same on all axes), and change the size(s) of its collision shape(s) instead. $DOCS_URL/tutorials/physics/physics_introduction.html diff --git a/doc/classes/RigidBody.xml b/doc/classes/RigidBody.xml index 2d85a0252..2cec4ee6d 100644 --- a/doc/classes/RigidBody.xml +++ b/doc/classes/RigidBody.xml @@ -9,6 +9,7 @@ [b]Note:[/b] Don't change a RigidBody's position every frame or very often. Sporadic changes work fine, but physics runs at a different granularity (fixed Hz) than usual rendering (process callback) and maybe even in a separate thread, so changing this from a process loop may result in strange behavior. If you need to directly affect the body's state, use [method _integrate_forces], which allows you to directly access the physics state. If you need to override the default physics behavior, you can write a custom force integration function. See [member custom_integrator]. With Bullet physics (the default), the center of mass is the RigidBody3D center. With GodotPhysics, the center of mass is the average of the [CollisionShape] centers. + [b]Warning:[/b] With a non-uniform scale this node will probably not function as expected. Please make sure to keep its scale uniform (i.e. the same on all axes), and change the size(s) of its collision shape(s) instead. $DOCS_URL/tutorials/physics/physics_introduction.html diff --git a/doc/classes/StaticBody.xml b/doc/classes/StaticBody.xml index c1e4b0acb..4b4923bae 100644 --- a/doc/classes/StaticBody.xml +++ b/doc/classes/StaticBody.xml @@ -7,8 +7,9 @@ Static body for 3D physics. A static body is a simple body that doesn't move under physics simulation, i.e. it can't be moved by external forces or contacts but its transformation can still be updated manually by the user. It is ideal for implementing objects in the environment, such as walls or platforms. In contrast to [RigidBody], it doesn't consume any CPU resources as long as they don't move. They have extra functionalities to move and affect other bodies: - [b]Static transform change:[/b] Static bodies can be moved by animation or script. In this case, they are just teleported and don't affect other bodies on their path. - [b]Constant velocity:[/b] When [member constant_linear_velocity] or [member constant_angular_velocity] is set, static bodies don't move themselves but affect touching bodies as if they were moving. This is useful for simulating conveyor belts or conveyor wheels. + [i]Static transform change:[/i] Static bodies can be moved by animation or script. In this case, they are just teleported and don't affect other bodies on their path. + [i]Constant velocity:[/i] When [member constant_linear_velocity] or [member constant_angular_velocity] is set, static bodies don't move themselves but affect touching bodies as if they were moving. This is useful for simulating conveyor belts or conveyor wheels. + [b]Warning:[/b] With a non-uniform scale this node will probably not function as expected. Please make sure to keep its scale uniform (i.e. the same on all axes), and change the size(s) of its collision shape(s) instead. https://godotengine.org/asset-library/asset/675 diff --git a/doc/classes/VehicleBody.xml b/doc/classes/VehicleBody.xml index eef7a63ab..81d0b41de 100644 --- a/doc/classes/VehicleBody.xml +++ b/doc/classes/VehicleBody.xml @@ -7,6 +7,7 @@ This node implements all the physics logic needed to simulate a car. It is based on the raycast vehicle system commonly found in physics engines. You will need to add a [CollisionShape] for the main body of your vehicle and add [VehicleWheel] nodes for the wheels. You should also add a [MeshInstance] to this node for the 3D model of your car but this model should not include meshes for the wheels. You should control the vehicle by using the [member brake], [member engine_force], and [member steering] properties and not change the position or orientation of this node directly. [b]Note:[/b] The origin point of your VehicleBody will determine the center of gravity of your vehicle so it is better to keep this low and move the [CollisionShape] and [MeshInstance] upwards. [b]Note:[/b] This class has known issues and isn't designed to provide realistic 3D vehicle physics. If you want advanced vehicle physics, you will probably have to write your own physics integration using another [PhysicsBody] class. + [b]Warning:[/b] With a non-uniform scale this node will probably not function as expected. Please make sure to keep its scale uniform (i.e. the same on all axes), and change the size(s) of its collision shape(s) instead. https://godotengine.org/asset-library/asset/524 diff --git a/modules/skeleton_3d/doc_classes/PhysicalBone.xml b/modules/skeleton_3d/doc_classes/PhysicalBone.xml index 7375d333d..2a8cb41bc 100644 --- a/modules/skeleton_3d/doc_classes/PhysicalBone.xml +++ b/modules/skeleton_3d/doc_classes/PhysicalBone.xml @@ -3,6 +3,7 @@ + [b]Warning:[/b] With a non-uniform scale this node will probably not function as expected. Please make sure to keep its scale uniform (i.e. the same on all axes), and change the size(s) of its collision shape(s) instead.