From 940f3fde5c5f902b6efd0f35fb6c7d23edd1da14 Mon Sep 17 00:00:00 2001 From: PouleyKetchoupp Date: Tue, 7 Dec 2021 18:09:54 -0700 Subject: Improve RigidDynamicBody force and torque API Makes the API for forces and impulses more flexible, easier to understand and harmonized between 2D and 3D. Rigid bodies now have 3 sets of methods for forces and impulses: -apply_impulse() for impulses (one-shot and time independent) -apply_force() for forces (time dependent) applied for the current step -add_constant_force() for forces that keeps being applied each step Also updated the documentation to clarify the different methods and parameters in rigid body nodes, body direct state and physics servers. --- doc/classes/PhysicsDirectBodyState2D.xml | 79 +++++++++++++++++++++++---- doc/classes/PhysicsDirectBodyState3D.xml | 81 ++++++++++++++++++++++++---- doc/classes/PhysicsServer2D.xml | 92 ++++++++++++++++++++++++++++---- doc/classes/PhysicsServer3D.xml | 92 ++++++++++++++++++++++++++++---- doc/classes/RigidDynamicBody2D.xml | 63 ++++++++++++++++------ doc/classes/RigidDynamicBody3D.xml | 60 ++++++++++++++++----- 6 files changed, 400 insertions(+), 67 deletions(-) (limited to 'doc') diff --git a/doc/classes/PhysicsDirectBodyState2D.xml b/doc/classes/PhysicsDirectBodyState2D.xml index c33bd930be..fbadfd2702 100644 --- a/doc/classes/PhysicsDirectBodyState2D.xml +++ b/doc/classes/PhysicsDirectBodyState2D.xml @@ -11,26 +11,36 @@ $DOCS_URL/tutorials/physics/ray-casting.html - + - + - Adds a constant directional force without affecting rotation. + Adds a constant directional force without affecting rotation that keeps being applied over time until cleared with [code]constant_force = Vector2(0, 0)[/code]. + This is equivalent to using [method add_constant_force] at the body's center of mass. - + - Adds a positioned force to the body. Both the force and the offset from the body origin are in global coordinates. + Adds a constant positioned force to the body that keeps being applied over time until cleared with [code]constant_force = Vector2(0, 0)[/code]. + [code]position[/code] is the offset from the body origin in global coordinates. - + - Adds a constant rotational force. + Adds a constant rotational force without affecting position that keeps being applied over time until cleared with [code]constant_torque = 0[/code]. + + + + + + + Applies a directional force without affecting rotation. A force is time dependent and meant to be applied every physics update. + This is equivalent to using [method apply_force] at the body's center of mass. @@ -38,6 +48,17 @@ Applies a directional impulse without affecting rotation. + An impulse is time-independent! Applying an impulse every frame would result in a framerate-dependent force. For this reason, it should only be used when simulating one-time impacts (use the "_force" functions otherwise). + This is equivalent to using [method apply_impulse] at the body's center of mass. + + + + + + + + Applies a positioned force to the body. A force is time dependent and meant to be applied every physics update. + [code]position[/code] is the offset from the body origin in global coordinates. @@ -45,14 +66,38 @@ - Applies a positioned impulse to the body. An impulse is time-independent! Applying an impulse every frame would result in a framerate-dependent force. For this reason, it should only be used when simulating one-time impacts (use the "_force" functions otherwise). The offset uses the rotation of the global coordinate system, but is centered at the object's origin. + Applies a positioned impulse to the body. + An impulse is time-independent! Applying an impulse every frame would result in a framerate-dependent force. For this reason, it should only be used when simulating one-time impacts (use the "_force" functions otherwise). + [code]position[/code] is the offset from the body origin in global coordinates. + + + + + + + Applies a rotational force without affecting position. A force is time dependent and meant to be applied every physics update. - Applies a rotational impulse to the body. + Applies a rotational impulse to the body without affecting the position. + An impulse is time-independent! Applying an impulse every frame would result in a framerate-dependent force. For this reason, it should only be used when simulating one-time impacts (use the "_force" functions otherwise). + + + + + + Returns the body's total constant positional forces applied during each physics update. + See [method add_constant_force] and [method add_constant_central_force]. + + + + + + Returns the body's total constant rotational forces applied during each physics update. + See [method add_constant_torque]. @@ -144,6 +189,22 @@ Calls the built-in force integration code. + + + + + Sets the body's total constant positional forces applied during each physics update. + See [method add_constant_force] and [method add_constant_central_force]. + + + + + + + Sets the body's total constant rotational forces applied during each physics update. + See [method add_constant_torque]. + + diff --git a/doc/classes/PhysicsDirectBodyState3D.xml b/doc/classes/PhysicsDirectBodyState3D.xml index 7aa46dec2f..58c4294d66 100644 --- a/doc/classes/PhysicsDirectBodyState3D.xml +++ b/doc/classes/PhysicsDirectBodyState3D.xml @@ -11,35 +11,54 @@ $DOCS_URL/tutorials/physics/ray-casting.html - + - Adds a constant directional force without affecting rotation. - This is equivalent to [code]add_force(force, Vector3(0,0,0))[/code]. + Adds a constant directional force without affecting rotation that keeps being applied over time until cleared with [code]constant_force = Vector3(0, 0, 0)[/code]. + This is equivalent to using [method add_constant_force] at the body's center of mass. - + - Adds a positioned force to the body. Both the force and the offset from the body origin are in global coordinates. + Adds a constant positioned force to the body that keeps being applied over time until cleared with [code]constant_force = Vector3(0, 0, 0)[/code]. + [code]position[/code] is the offset from the body origin in global coordinates. - + - Adds a constant rotational force without affecting position. + Adds a constant rotational force without affecting position that keeps being applied over time until cleared with [code]constant_torque = Vector3(0, 0, 0)[/code]. + + + + + + + Applies a directional force without affecting rotation. A force is time dependent and meant to be applied every physics update. + This is equivalent to using [method apply_force] at the body's center of mass. - Applies a single directional impulse without affecting rotation. - This is equivalent to [code]apply_impulse(Vector3(0, 0, 0), impulse)[/code]. + Applies a directional impulse without affecting rotation. + An impulse is time-independent! Applying an impulse every frame would result in a framerate-dependent force. For this reason, it should only be used when simulating one-time impacts (use the "_force" functions otherwise). + This is equivalent to using [method apply_impulse] at the body's center of mass. + + + + + + + + Applies a positioned force to the body. A force is time dependent and meant to be applied every physics update. + [code]position[/code] is the offset from the body origin in global coordinates. @@ -47,14 +66,38 @@ - Applies a positioned impulse to the body. An impulse is time-independent! Applying an impulse every frame would result in a framerate-dependent force. For this reason it should only be used when simulating one-time impacts. The position uses the rotation of the global coordinate system, but is centered at the object's origin. + Applies a positioned impulse to the body. + An impulse is time-independent! Applying an impulse every frame would result in a framerate-dependent force. For this reason, it should only be used when simulating one-time impacts (use the "_force" functions otherwise). + [code]position[/code] is the offset from the body origin in global coordinates. + + + + + + + Applies a rotational force without affecting position. A force is time dependent and meant to be applied every physics update. - Apply a torque impulse (which will be affected by the body mass and shape). This will rotate the body around the vector [code]j[/code] passed as parameter. + Applies a rotational impulse to the body without affecting the position. + An impulse is time-independent! Applying an impulse every frame would result in a framerate-dependent force. For this reason, it should only be used when simulating one-time impacts (use the "_force" functions otherwise). + + + + + + Returns the body's total constant positional forces applied during each physics update. + See [method add_constant_force] and [method add_constant_central_force]. + + + + + + Returns the body's total constant rotational forces applied during each physics update. + See [method add_constant_torque]. @@ -153,6 +196,22 @@ Calls the built-in force integration code. + + + + + Sets the body's total constant positional forces applied during each physics update. + See [method add_constant_force] and [method add_constant_central_force]. + + + + + + + Sets the body's total constant rotational forces applied during each physics update. + See [method add_constant_torque]. + + diff --git a/doc/classes/PhysicsServer2D.xml b/doc/classes/PhysicsServer2D.xml index bfb4ca58ef..624f5e7b17 100644 --- a/doc/classes/PhysicsServer2D.xml +++ b/doc/classes/PhysicsServer2D.xml @@ -208,28 +208,39 @@ Sets the transform matrix for an area. - + - + + Adds a body to the list of bodies exempt from collisions. - + - + - Adds a body to the list of bodies exempt from collisions. + Adds a constant directional force without affecting rotation that keeps being applied over time until cleared with [code]body_set_constant_force(body, Vector2(0, 0))[/code]. + This is equivalent to using [method body_add_constant_force] at the body's center of mass. - + - Adds a positioned force to the applied force and torque. As with [method body_apply_impulse], both the force and the offset from the body origin are in global coordinates. A force differs from an impulse in that, while the two are forces, the impulse clears itself after being applied. + Adds a constant positioned force to the body that keeps being applied over time until cleared with [code]body_set_constant_force(body, Vector2(0, 0))[/code]. + [code]position[/code] is the offset from the body origin in global coordinates. + + + + + + + + Adds a constant rotational force without affecting position that keeps being applied over time until cleared with [code]body_set_constant_torque(body, 0)[/code]. @@ -242,11 +253,13 @@ Adds a shape to the body, along with a transform matrix. Shapes are usually referenced by their index, so you should track which shape has a given index. - + - + + Applies a directional force without affecting rotation. A force is time dependent and meant to be applied every physics update. + This is equivalent to using [method body_apply_force] at the body's center of mass. @@ -254,6 +267,19 @@ + Applies a directional impulse without affecting rotation. + An impulse is time-independent! Applying an impulse every frame would result in a framerate-dependent force. For this reason, it should only be used when simulating one-time impacts (use the "_force" functions otherwise). + This is equivalent to using [method body_apply_impulse] at the body's center of mass. + + + + + + + + + Applies a positioned force to the body. A force is time dependent and meant to be applied every physics update. + [code]position[/code] is the offset from the body origin in global coordinates. @@ -262,7 +288,17 @@ - Adds a positioned impulse to the applied force and torque. Both the force and the offset from the body origin are in global coordinates. + Applies a positioned impulse to the body. + An impulse is time-independent! Applying an impulse every frame would result in a framerate-dependent force. For this reason, it should only be used when simulating one-time impacts (use the "_force" functions otherwise). + [code]position[/code] is the offset from the body origin in global coordinates. + + + + + + + + Applies a rotational force without affecting position. A force is time dependent and meant to be applied every physics update. @@ -270,6 +306,8 @@ + Applies a rotational impulse to the body without affecting the position. + An impulse is time-independent! Applying an impulse every frame would result in a framerate-dependent force. For this reason, it should only be used when simulating one-time impacts (use the "_force" functions otherwise). @@ -320,6 +358,22 @@ Returns the physics layer or layers a body can collide with. + + + + + Returns the body's total constant positional forces applied during each physics update. + See [method body_add_constant_force] and [method body_add_constant_central_force]. + + + + + + + Returns the body's total constant rotational forces applied during each physics update. + See [method body_add_constant_torque]. + + @@ -455,6 +509,24 @@ Sets the physics layer or layers a body can collide with. + + + + + + Sets the body's total constant positional forces applied during each physics update. + See [method body_add_constant_force] and [method body_add_constant_central_force]. + + + + + + + + Sets the body's total constant rotational forces applied during each physics update. + See [method body_add_constant_torque]. + + diff --git a/doc/classes/PhysicsServer3D.xml b/doc/classes/PhysicsServer3D.xml index b264590055..16c195c6dc 100644 --- a/doc/classes/PhysicsServer3D.xml +++ b/doc/classes/PhysicsServer3D.xml @@ -202,27 +202,39 @@ Sets the transform matrix for an area. - + - + + Adds a body to the list of bodies exempt from collisions. - + - + - Adds a body to the list of bodies exempt from collisions. + Adds a constant directional force without affecting rotation that keeps being applied over time until cleared with [code]body_set_constant_force(body, Vector3(0, 0, 0))[/code]. + This is equivalent to using [method body_add_constant_force] at the body's center of mass. - + + Adds a constant positioned force to the body that keeps being applied over time until cleared with [code]body_set_constant_force(body, Vector3(0, 0, 0))[/code]. + [code]position[/code] is the offset from the body origin in global coordinates. + + + + + + + + Adds a constant rotational force without affecting position that keeps being applied over time until cleared with [code]body_set_constant_torque(body, Vector3(0, 0, 0))[/code]. @@ -235,11 +247,13 @@ Adds a shape to the body, along with a transform matrix. Shapes are usually referenced by their index, so you should track which shape has a given index. - + - + + Applies a directional force without affecting rotation. A force is time dependent and meant to be applied every physics update. + This is equivalent to using [method body_apply_force] at the body's center of mass. @@ -247,6 +261,19 @@ + Applies a directional impulse without affecting rotation. + An impulse is time-independent! Applying an impulse every frame would result in a framerate-dependent force. For this reason, it should only be used when simulating one-time impacts (use the "_force" functions otherwise). + This is equivalent to using [method body_apply_impulse] at the body's center of mass. + + + + + + + + + Applies a positioned force to the body. A force is time dependent and meant to be applied every physics update. + [code]position[/code] is the offset from the body origin in global coordinates. @@ -255,7 +282,17 @@ - Gives the body a push at a [code]position[/code] in the direction of the [code]impulse[/code]. + Applies a positioned impulse to the body. + An impulse is time-independent! Applying an impulse every frame would result in a framerate-dependent force. For this reason, it should only be used when simulating one-time impacts (use the "_force" functions otherwise). + [code]position[/code] is the offset from the body origin in global coordinates. + + + + + + + + Applies a rotational force without affecting position. A force is time dependent and meant to be applied every physics update. @@ -263,7 +300,8 @@ - Gives the body a push to rotate it. + Applies a rotational impulse to the body without affecting the position. + An impulse is time-independent! Applying an impulse every frame would result in a framerate-dependent force. For this reason, it should only be used when simulating one-time impacts (use the "_force" functions otherwise). @@ -301,6 +339,22 @@ - + + + + + Returns the body's total constant positional forces applied during each physics update. + See [method body_add_constant_force] and [method body_add_constant_central_force]. + + + + + + + Returns the body's total constant rotational forces applied during each physics update. + See [method body_add_constant_torque]. + + @@ -452,6 +506,24 @@ Sets the physics layer or layers a body can collide with. + + + + + + Sets the body's total constant positional forces applied during each physics update. + See [method body_add_constant_force] and [method body_add_constant_central_force]. + + + + + + + + Sets the body's total constant rotational forces applied during each physics update. + See [method body_add_constant_torque]. + + diff --git a/doc/classes/RigidDynamicBody2D.xml b/doc/classes/RigidDynamicBody2D.xml index b8680b99b3..0026c49651 100644 --- a/doc/classes/RigidDynamicBody2D.xml +++ b/doc/classes/RigidDynamicBody2D.xml @@ -22,26 +22,36 @@ Allows you to read and safely modify the simulation state for the object. Use this instead of [method Node._physics_process] if you need to directly change the body's [code]position[/code] or other physics properties. By default, it works in addition to the usual physics behavior, but [member custom_integrator] allows you to disable the default behavior and write custom force integration for a body. - + - Adds a constant directional force without affecting rotation. + Adds a constant directional force without affecting rotation that keeps being applied over time until cleared with [code]constant_force = Vector2(0, 0)[/code]. + This is equivalent to using [method add_constant_force] at the body's center of mass. - + - Adds a positioned force to the body. Both the force and the offset from the body origin are in global coordinates. + Adds a constant positioned force to the body that keeps being applied over time until cleared with [code]constant_force = Vector2(0, 0)[/code]. + [code]position[/code] is the offset from the body origin in global coordinates. - + - Adds a constant rotational force. + Adds a constant rotational force without affecting position that keeps being applied over time until cleared with [code]constant_torque = 0[/code]. + + + + + + + Applies a directional force without affecting rotation. A force is time dependent and meant to be applied every physics update. + This is equivalent to using [method apply_force] at the body's center of mass. @@ -49,6 +59,17 @@ Applies a directional impulse without affecting rotation. + An impulse is time-independent! Applying an impulse every frame would result in a framerate-dependent force. For this reason, it should only be used when simulating one-time impacts (use the "_force" functions otherwise). + This is equivalent to using [method apply_impulse] at the body's center of mass. + + + + + + + + Applies a positioned force to the body. A force is time dependent and meant to be applied every physics update. + [code]position[/code] is the offset from the body origin in global coordinates. @@ -56,14 +77,24 @@ - Applies a positioned impulse to the body. An impulse is time-independent! Applying an impulse every frame would result in a framerate-dependent force. For this reason it should only be used when simulating one-time impacts (use the "_force" functions otherwise). The position uses the rotation of the global coordinate system, but is centered at the object's origin. + Applies a positioned impulse to the body. + An impulse is time-independent! Applying an impulse every frame would result in a framerate-dependent force. For this reason, it should only be used when simulating one-time impacts (use the "_force" functions otherwise). + [code]position[/code] is the offset from the body origin in global coordinates. + + + + + + + Applies a rotational force without affecting position. A force is time dependent and meant to be applied every physics update. - Applies a rotational impulse to the body. + Applies a rotational impulse to the body without affecting the position. + An impulse is time-independent! Applying an impulse every frame would result in a framerate-dependent force. For this reason, it should only be used when simulating one-time impacts (use the "_force" functions otherwise). @@ -92,12 +123,6 @@ The body's rotational velocity. - - The body's total applied force. - - - The body's total applied torque. - If [code]true[/code], the body can enter sleep mode when there is no movement. See [member sleeping]. @@ -108,6 +133,14 @@ Defines the way the body's center of mass is set. See [enum CenterOfMassMode] for possible values. + + The body's total constant positional forces applied during each physics update. + See [method add_constant_force] and [method add_constant_central_force]. + + + The body's total constant rotational forces applied during each physics update. + See [method add_constant_torque]. + If [code]true[/code], the body will emit signals when it collides with another RigidDynamicBody2D. See also [member contacts_reported]. @@ -159,7 +192,7 @@ If a material is assigned to this property, it will be used instead of any other physics material, such as an inherited one. - If [code]true[/code], the body will not move and will not calculate forces until woken up by another body through, for example, a collision, or by using the [method apply_impulse] or [method add_force] methods. + If [code]true[/code], the body will not move and will not calculate forces until woken up by another body through, for example, a collision, or by using the [method apply_impulse] or [method apply_force] methods. diff --git a/doc/classes/RigidDynamicBody3D.xml b/doc/classes/RigidDynamicBody3D.xml index c75055e0df..3dffdcbf83 100644 --- a/doc/classes/RigidDynamicBody3D.xml +++ b/doc/classes/RigidDynamicBody3D.xml @@ -22,28 +22,36 @@ Called during physics processing, allowing you to read and safely modify the simulation state for the object. By default, it works in addition to the usual physics behavior, but the [member custom_integrator] property allows you to disable the default behavior and do fully custom force integration for a body. - + - Adds a constant directional force (i.e. acceleration) without affecting rotation. - This is equivalent to [code]add_force(force, Vector3(0,0,0))[/code]. + Adds a constant directional force without affecting rotation that keeps being applied over time until cleared with [code]constant_force = Vector3(0, 0, 0)[/code]. + This is equivalent to using [method add_constant_force] at the body's center of mass. - + - Adds a constant directional force (i.e. acceleration). - The position uses the rotation of the global coordinate system, but is centered at the object's origin. + Adds a constant positioned force to the body that keeps being applied over time until cleared with [code]constant_force = Vector3(0, 0, 0)[/code]. + [code]position[/code] is the offset from the body origin in global coordinates. - + - Adds a constant rotational force (i.e. a motor) without affecting position. + Adds a constant rotational force without affecting position that keeps being applied over time until cleared with [code]constant_torque = Vector3(0, 0, 0)[/code]. + + + + + + + Applies a directional force without affecting rotation. A force is time dependent and meant to be applied every physics update. + This is equivalent to using [method apply_force] at the body's center of mass. @@ -51,7 +59,17 @@ Applies a directional impulse without affecting rotation. - This is equivalent to [code]apply_impulse(Vector3(0,0,0), impulse)[/code]. + An impulse is time-independent! Applying an impulse every frame would result in a framerate-dependent force. For this reason, it should only be used when simulating one-time impacts (use the "_force" functions otherwise). + This is equivalent to using [method apply_impulse] at the body's center of mass. + + + + + + + + Applies a positioned force to the body. A force is time dependent and meant to be applied every physics update. + [code]position[/code] is the offset from the body origin in global coordinates. @@ -59,14 +77,24 @@ - Applies a positioned impulse to the body. An impulse is time independent! Applying an impulse every frame would result in a framerate-dependent force. For this reason it should only be used when simulating one-time impacts. The position uses the rotation of the global coordinate system, but is centered at the object's origin. + Applies a positioned impulse to the body. + An impulse is time-independent! Applying an impulse every frame would result in a framerate-dependent force. For this reason, it should only be used when simulating one-time impacts (use the "_force" functions otherwise). + [code]position[/code] is the offset from the body origin in global coordinates. + + + + + + + Applies a rotational force without affecting position. A force is time dependent and meant to be applied every physics update. - Applies a torque impulse which will be affected by the body mass and shape. This will rotate the body around the [code]impulse[/code] vector passed. + Applies a rotational impulse to the body without affecting the position. + An impulse is time-independent! Applying an impulse every frame would result in a framerate-dependent force. For this reason, it should only be used when simulating one-time impacts (use the "_force" functions otherwise). @@ -111,6 +139,14 @@ Defines the way the body's center of mass is set. See [enum CenterOfMassMode] for possible values. + + The body's total constant positional forces applied during each physics update. + See [method add_constant_force] and [method add_constant_central_force]. + + + The body's total constant rotational forces applied during each physics update. + See [method add_constant_torque]. + If [code]true[/code], the RigidDynamicBody3D will emit signals when it collides with another RigidDynamicBody3D. See also [member contacts_reported]. @@ -162,7 +198,7 @@ If a material is assigned to this property, it will be used instead of any other physics material, such as an inherited one. - If [code]true[/code], the body will not move and will not calculate forces until woken up by another body through, for example, a collision, or by using the [method apply_impulse] or [method add_force] methods. + If [code]true[/code], the body will not move and will not calculate forces until woken up by another body through, for example, a collision, or by using the [method apply_impulse] or [method apply_force] methods. -- cgit v1.2.3