diff options
author | PouleyKetchoupp <pouleyketchoup@gmail.com> | 2021-12-07 18:09:54 -0700 |
---|---|---|
committer | PouleyKetchoupp <pouleyketchoup@gmail.com> | 2021-12-10 15:55:40 -0700 |
commit | 940f3fde5c5f902b6efd0f35fb6c7d23edd1da14 (patch) | |
tree | 1af330b010e4234cfe2694e94d25756c8e4e3734 /doc/classes | |
parent | e69fa16eb3cd4cf4a591eb4c533b9eff45f79850 (diff) |
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.
Diffstat (limited to 'doc/classes')
-rw-r--r-- | doc/classes/PhysicsDirectBodyState2D.xml | 79 | ||||
-rw-r--r-- | doc/classes/PhysicsDirectBodyState3D.xml | 81 | ||||
-rw-r--r-- | doc/classes/PhysicsServer2D.xml | 92 | ||||
-rw-r--r-- | doc/classes/PhysicsServer3D.xml | 92 | ||||
-rw-r--r-- | doc/classes/RigidDynamicBody2D.xml | 63 | ||||
-rw-r--r-- | doc/classes/RigidDynamicBody3D.xml | 60 |
6 files changed, 400 insertions, 67 deletions
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 @@ <link title="Ray-casting">$DOCS_URL/tutorials/physics/ray-casting.html</link> </tutorials> <methods> - <method name="add_central_force"> + <method name="add_constant_central_force"> <return type="void" /> - <argument index="0" name="force" type="Vector2" /> + <argument index="0" name="force" type="Vector2" default="Vector2(0, 0)" /> <description> - 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. </description> </method> - <method name="add_force"> + <method name="add_constant_force"> <return type="void" /> <argument index="0" name="force" type="Vector2" /> <argument index="1" name="position" type="Vector2" default="Vector2(0, 0)" /> <description> - 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. </description> </method> - <method name="add_torque"> + <method name="add_constant_torque"> <return type="void" /> <argument index="0" name="torque" type="float" /> <description> - 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]. + </description> + </method> + <method name="apply_central_force"> + <return type="void" /> + <argument index="0" name="force" type="Vector2" default="Vector2(0, 0)" /> + <description> + 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. </description> </method> <method name="apply_central_impulse"> @@ -38,6 +48,17 @@ <argument index="0" name="impulse" type="Vector2" /> <description> 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. + </description> + </method> + <method name="apply_force"> + <return type="void" /> + <argument index="0" name="force" type="Vector2" /> + <argument index="1" name="position" type="Vector2" default="Vector2(0, 0)" /> + <description> + 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. </description> </method> <method name="apply_impulse"> @@ -45,14 +66,38 @@ <argument index="0" name="impulse" type="Vector2" /> <argument index="1" name="position" type="Vector2" default="Vector2(0, 0)" /> <description> - 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. + </description> + </method> + <method name="apply_torque"> + <return type="void" /> + <argument index="0" name="torque" type="float" /> + <description> + Applies a rotational force without affecting position. A force is time dependent and meant to be applied every physics update. </description> </method> <method name="apply_torque_impulse"> <return type="void" /> <argument index="0" name="impulse" type="float" /> <description> - 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). + </description> + </method> + <method name="get_constant_force" qualifiers="const"> + <return type="Vector2" /> + <description> + Returns the body's total constant positional forces applied during each physics update. + See [method add_constant_force] and [method add_constant_central_force]. + </description> + </method> + <method name="get_constant_torque" qualifiers="const"> + <return type="float" /> + <description> + Returns the body's total constant rotational forces applied during each physics update. + See [method add_constant_torque]. </description> </method> <method name="get_contact_collider" qualifiers="const"> @@ -144,6 +189,22 @@ Calls the built-in force integration code. </description> </method> + <method name="set_constant_force"> + <return type="void" /> + <argument index="0" name="force" type="Vector2" /> + <description> + Sets the body's total constant positional forces applied during each physics update. + See [method add_constant_force] and [method add_constant_central_force]. + </description> + </method> + <method name="set_constant_torque"> + <return type="void" /> + <argument index="0" name="torque" type="float" /> + <description> + Sets the body's total constant rotational forces applied during each physics update. + See [method add_constant_torque]. + </description> + </method> </methods> <members> <member name="angular_velocity" type="float" setter="set_angular_velocity" getter="get_angular_velocity"> 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 @@ <link title="Ray-casting">$DOCS_URL/tutorials/physics/ray-casting.html</link> </tutorials> <methods> - <method name="add_central_force"> + <method name="add_constant_central_force"> <return type="void" /> <argument index="0" name="force" type="Vector3" default="Vector3(0, 0, 0)" /> <description> - 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. </description> </method> - <method name="add_force"> + <method name="add_constant_force"> <return type="void" /> <argument index="0" name="force" type="Vector3" /> <argument index="1" name="position" type="Vector3" default="Vector3(0, 0, 0)" /> <description> - 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. </description> </method> - <method name="add_torque"> + <method name="add_constant_torque"> <return type="void" /> <argument index="0" name="torque" type="Vector3" /> <description> - 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]. + </description> + </method> + <method name="apply_central_force"> + <return type="void" /> + <argument index="0" name="force" type="Vector3" default="Vector3(0, 0, 0)" /> + <description> + 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. </description> </method> <method name="apply_central_impulse"> <return type="void" /> <argument index="0" name="impulse" type="Vector3" default="Vector3(0, 0, 0)" /> <description> - 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. + </description> + </method> + <method name="apply_force"> + <return type="void" /> + <argument index="0" name="force" type="Vector3" /> + <argument index="1" name="position" type="Vector3" default="Vector3(0, 0, 0)" /> + <description> + 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. </description> </method> <method name="apply_impulse"> @@ -47,14 +66,38 @@ <argument index="0" name="impulse" type="Vector3" /> <argument index="1" name="position" type="Vector3" default="Vector3(0, 0, 0)" /> <description> - 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. + </description> + </method> + <method name="apply_torque"> + <return type="void" /> + <argument index="0" name="torque" type="Vector3" /> + <description> + Applies a rotational force without affecting position. A force is time dependent and meant to be applied every physics update. </description> </method> <method name="apply_torque_impulse"> <return type="void" /> <argument index="0" name="impulse" type="Vector3" /> <description> - 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). + </description> + </method> + <method name="get_constant_force" qualifiers="const"> + <return type="Vector3" /> + <description> + Returns the body's total constant positional forces applied during each physics update. + See [method add_constant_force] and [method add_constant_central_force]. + </description> + </method> + <method name="get_constant_torque" qualifiers="const"> + <return type="Vector3" /> + <description> + Returns the body's total constant rotational forces applied during each physics update. + See [method add_constant_torque]. </description> </method> <method name="get_contact_collider" qualifiers="const"> @@ -153,6 +196,22 @@ Calls the built-in force integration code. </description> </method> + <method name="set_constant_force"> + <return type="void" /> + <argument index="0" name="force" type="Vector3" /> + <description> + Sets the body's total constant positional forces applied during each physics update. + See [method add_constant_force] and [method add_constant_central_force]. + </description> + </method> + <method name="set_constant_torque"> + <return type="void" /> + <argument index="0" name="torque" type="Vector3" /> + <description> + Sets the body's total constant rotational forces applied during each physics update. + See [method add_constant_torque]. + </description> + </method> </methods> <members> <member name="angular_velocity" type="Vector3" setter="set_angular_velocity" getter="get_angular_velocity"> 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. </description> </method> - <method name="body_add_central_force"> + <method name="body_add_collision_exception"> <return type="void" /> <argument index="0" name="body" type="RID" /> - <argument index="1" name="force" type="Vector2" /> + <argument index="1" name="excepted_body" type="RID" /> <description> + Adds a body to the list of bodies exempt from collisions. </description> </method> - <method name="body_add_collision_exception"> + <method name="body_add_constant_central_force"> <return type="void" /> <argument index="0" name="body" type="RID" /> - <argument index="1" name="excepted_body" type="RID" /> + <argument index="1" name="force" type="Vector2" /> <description> - 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. </description> </method> - <method name="body_add_force"> + <method name="body_add_constant_force"> <return type="void" /> <argument index="0" name="body" type="RID" /> <argument index="1" name="force" type="Vector2" /> <argument index="2" name="position" type="Vector2" default="Vector2(0, 0)" /> <description> - 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. + </description> + </method> + <method name="body_add_constant_torque"> + <return type="void" /> + <argument index="0" name="body" type="RID" /> + <argument index="1" name="torque" type="float" /> + <description> + 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]. </description> </method> <method name="body_add_shape"> @@ -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. </description> </method> - <method name="body_add_torque"> + <method name="body_apply_central_force"> <return type="void" /> <argument index="0" name="body" type="RID" /> - <argument index="1" name="torque" type="float" /> + <argument index="1" name="force" type="Vector2" /> <description> + 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. </description> </method> <method name="body_apply_central_impulse"> @@ -254,6 +267,19 @@ <argument index="0" name="body" type="RID" /> <argument index="1" name="impulse" type="Vector2" /> <description> + 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. + </description> + </method> + <method name="body_apply_force"> + <return type="void" /> + <argument index="0" name="body" type="RID" /> + <argument index="1" name="force" type="Vector2" /> + <argument index="2" name="position" type="Vector2" default="Vector2(0, 0)" /> + <description> + 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. </description> </method> <method name="body_apply_impulse"> @@ -262,7 +288,17 @@ <argument index="1" name="impulse" type="Vector2" /> <argument index="2" name="position" type="Vector2" default="Vector2(0, 0)" /> <description> - 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. + </description> + </method> + <method name="body_apply_torque"> + <return type="void" /> + <argument index="0" name="body" type="RID" /> + <argument index="1" name="torque" type="float" /> + <description> + Applies a rotational force without affecting position. A force is time dependent and meant to be applied every physics update. </description> </method> <method name="body_apply_torque_impulse"> @@ -270,6 +306,8 @@ <argument index="0" name="body" type="RID" /> <argument index="1" name="impulse" type="float" /> <description> + 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). </description> </method> <method name="body_attach_canvas_instance_id"> @@ -320,6 +358,22 @@ Returns the physics layer or layers a body can collide with. </description> </method> + <method name="body_get_constant_force" qualifiers="const"> + <return type="Vector2" /> + <argument index="0" name="body" type="RID" /> + <description> + 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]. + </description> + </method> + <method name="body_get_constant_torque" qualifiers="const"> + <return type="float" /> + <argument index="0" name="body" type="RID" /> + <description> + Returns the body's total constant rotational forces applied during each physics update. + See [method body_add_constant_torque]. + </description> + </method> <method name="body_get_continuous_collision_detection_mode" qualifiers="const"> <return type="int" enum="PhysicsServer2D.CCDMode" /> <argument index="0" name="body" type="RID" /> @@ -455,6 +509,24 @@ Sets the physics layer or layers a body can collide with. </description> </method> + <method name="body_set_constant_force"> + <return type="void" /> + <argument index="0" name="body" type="RID" /> + <argument index="1" name="force" type="Vector2" /> + <description> + 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]. + </description> + </method> + <method name="body_set_constant_torque"> + <return type="void" /> + <argument index="0" name="body" type="RID" /> + <argument index="1" name="torque" type="float" /> + <description> + Sets the body's total constant rotational forces applied during each physics update. + See [method body_add_constant_torque]. + </description> + </method> <method name="body_set_continuous_collision_detection_mode"> <return type="void" /> <argument index="0" name="body" type="RID" /> 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. </description> </method> - <method name="body_add_central_force"> + <method name="body_add_collision_exception"> <return type="void" /> <argument index="0" name="body" type="RID" /> - <argument index="1" name="force" type="Vector3" /> + <argument index="1" name="excepted_body" type="RID" /> <description> + Adds a body to the list of bodies exempt from collisions. </description> </method> - <method name="body_add_collision_exception"> + <method name="body_add_constant_central_force"> <return type="void" /> <argument index="0" name="body" type="RID" /> - <argument index="1" name="excepted_body" type="RID" /> + <argument index="1" name="force" type="Vector3" /> <description> - 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. </description> </method> - <method name="body_add_force"> + <method name="body_add_constant_force"> <return type="void" /> <argument index="0" name="body" type="RID" /> <argument index="1" name="force" type="Vector3" /> <argument index="2" name="position" type="Vector3" default="Vector3(0, 0, 0)" /> <description> + 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. + </description> + </method> + <method name="body_add_constant_torque"> + <return type="void" /> + <argument index="0" name="body" type="RID" /> + <argument index="1" name="torque" type="Vector3" /> + <description> + 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]. </description> </method> <method name="body_add_shape"> @@ -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. </description> </method> - <method name="body_add_torque"> + <method name="body_apply_central_force"> <return type="void" /> <argument index="0" name="body" type="RID" /> - <argument index="1" name="torque" type="Vector3" /> + <argument index="1" name="force" type="Vector3" /> <description> + 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. </description> </method> <method name="body_apply_central_impulse"> @@ -247,6 +261,19 @@ <argument index="0" name="body" type="RID" /> <argument index="1" name="impulse" type="Vector3" /> <description> + 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. + </description> + </method> + <method name="body_apply_force"> + <return type="void" /> + <argument index="0" name="body" type="RID" /> + <argument index="1" name="force" type="Vector3" /> + <argument index="2" name="position" type="Vector3" default="Vector3(0, 0, 0)" /> + <description> + 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. </description> </method> <method name="body_apply_impulse"> @@ -255,7 +282,17 @@ <argument index="1" name="impulse" type="Vector3" /> <argument index="2" name="position" type="Vector3" default="Vector3(0, 0, 0)" /> <description> - 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. + </description> + </method> + <method name="body_apply_torque"> + <return type="void" /> + <argument index="0" name="body" type="RID" /> + <argument index="1" name="torque" type="Vector3" /> + <description> + Applies a rotational force without affecting position. A force is time dependent and meant to be applied every physics update. </description> </method> <method name="body_apply_torque_impulse"> @@ -263,7 +300,8 @@ <argument index="0" name="body" type="RID" /> <argument index="1" name="impulse" type="Vector3" /> <description> - 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). </description> </method> <method name="body_attach_object_instance_id"> @@ -301,6 +339,22 @@ - </description> </method> + <method name="body_get_constant_force" qualifiers="const"> + <return type="Vector3" /> + <argument index="0" name="body" type="RID" /> + <description> + 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]. + </description> + </method> + <method name="body_get_constant_torque" qualifiers="const"> + <return type="Vector3" /> + <argument index="0" name="body" type="RID" /> + <description> + Returns the body's total constant rotational forces applied during each physics update. + See [method body_add_constant_torque]. + </description> + </method> <method name="body_get_direct_state"> <return type="PhysicsDirectBodyState3D" /> <argument index="0" name="body" type="RID" /> @@ -452,6 +506,24 @@ Sets the physics layer or layers a body can collide with. </description> </method> + <method name="body_set_constant_force"> + <return type="void" /> + <argument index="0" name="body" type="RID" /> + <argument index="1" name="force" type="Vector3" /> + <description> + 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]. + </description> + </method> + <method name="body_set_constant_torque"> + <return type="void" /> + <argument index="0" name="body" type="RID" /> + <argument index="1" name="torque" type="Vector3" /> + <description> + Sets the body's total constant rotational forces applied during each physics update. + See [method body_add_constant_torque]. + </description> + </method> <method name="body_set_enable_continuous_collision_detection"> <return type="void" /> <argument index="0" name="body" type="RID" /> 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. </description> </method> - <method name="add_central_force"> + <method name="add_constant_central_force"> <return type="void" /> <argument index="0" name="force" type="Vector2" /> <description> - 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. </description> </method> - <method name="add_force"> + <method name="add_constant_force"> <return type="void" /> <argument index="0" name="force" type="Vector2" /> <argument index="1" name="position" type="Vector2" default="Vector2(0, 0)" /> <description> - 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. </description> </method> - <method name="add_torque"> + <method name="add_constant_torque"> <return type="void" /> <argument index="0" name="torque" type="float" /> <description> - 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]. + </description> + </method> + <method name="apply_central_force"> + <return type="void" /> + <argument index="0" name="force" type="Vector2" /> + <description> + 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. </description> </method> <method name="apply_central_impulse"> @@ -49,6 +59,17 @@ <argument index="0" name="impulse" type="Vector2" default="Vector2(0, 0)" /> <description> 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. + </description> + </method> + <method name="apply_force"> + <return type="void" /> + <argument index="0" name="force" type="Vector2" /> + <argument index="1" name="position" type="Vector2" default="Vector2(0, 0)" /> + <description> + 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. </description> </method> <method name="apply_impulse"> @@ -56,14 +77,24 @@ <argument index="0" name="impulse" type="Vector2" /> <argument index="1" name="position" type="Vector2" default="Vector2(0, 0)" /> <description> - 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. + </description> + </method> + <method name="apply_torque"> + <return type="void" /> + <argument index="0" name="torque" type="float" /> + <description> + Applies a rotational force without affecting position. A force is time dependent and meant to be applied every physics update. </description> </method> <method name="apply_torque_impulse"> <return type="void" /> <argument index="0" name="torque" type="float" /> <description> - 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). </description> </method> <method name="get_colliding_bodies" qualifiers="const"> @@ -92,12 +123,6 @@ <member name="angular_velocity" type="float" setter="set_angular_velocity" getter="get_angular_velocity" default="0.0"> The body's rotational velocity. </member> - <member name="applied_force" type="Vector2" setter="set_applied_force" getter="get_applied_force" default="Vector2(0, 0)"> - The body's total applied force. - </member> - <member name="applied_torque" type="float" setter="set_applied_torque" getter="get_applied_torque" default="0.0"> - The body's total applied torque. - </member> <member name="can_sleep" type="bool" setter="set_can_sleep" getter="is_able_to_sleep" default="true"> If [code]true[/code], the body can enter sleep mode when there is no movement. See [member sleeping]. </member> @@ -108,6 +133,14 @@ <member name="center_of_mass_mode" type="int" setter="set_center_of_mass_mode" getter="get_center_of_mass_mode" enum="RigidDynamicBody2D.CenterOfMassMode" default="0"> Defines the way the body's center of mass is set. See [enum CenterOfMassMode] for possible values. </member> + <member name="constant_force" type="Vector2" setter="set_constant_force" getter="get_constant_force" default="Vector2(0, 0)"> + The body's total constant positional forces applied during each physics update. + See [method add_constant_force] and [method add_constant_central_force]. + </member> + <member name="constant_torque" type="float" setter="set_constant_torque" getter="get_constant_torque" default="0.0"> + The body's total constant rotational forces applied during each physics update. + See [method add_constant_torque]. + </member> <member name="contact_monitor" type="bool" setter="set_contact_monitor" getter="is_contact_monitor_enabled" default="false"> If [code]true[/code], the body will emit signals when it collides with another RigidDynamicBody2D. See also [member contacts_reported]. </member> @@ -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. </member> <member name="sleeping" type="bool" setter="set_sleeping" getter="is_sleeping" default="false"> - 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. </member> </members> <signals> 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. </description> </method> - <method name="add_central_force"> + <method name="add_constant_central_force"> <return type="void" /> <argument index="0" name="force" type="Vector3" /> <description> - 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. </description> </method> - <method name="add_force"> + <method name="add_constant_force"> <return type="void" /> <argument index="0" name="force" type="Vector3" /> <argument index="1" name="position" type="Vector3" default="Vector3(0, 0, 0)" /> <description> - 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. </description> </method> - <method name="add_torque"> + <method name="add_constant_torque"> <return type="void" /> <argument index="0" name="torque" type="Vector3" /> <description> - 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]. + </description> + </method> + <method name="apply_central_force"> + <return type="void" /> + <argument index="0" name="force" type="Vector3" /> + <description> + 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. </description> </method> <method name="apply_central_impulse"> @@ -51,7 +59,17 @@ <argument index="0" name="impulse" type="Vector3" /> <description> 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. + </description> + </method> + <method name="apply_force"> + <return type="void" /> + <argument index="0" name="force" type="Vector3" /> + <argument index="1" name="position" type="Vector3" default="Vector3(0, 0, 0)" /> + <description> + 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. </description> </method> <method name="apply_impulse"> @@ -59,14 +77,24 @@ <argument index="0" name="impulse" type="Vector3" /> <argument index="1" name="position" type="Vector3" default="Vector3(0, 0, 0)" /> <description> - 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. + </description> + </method> + <method name="apply_torque"> + <return type="void" /> + <argument index="0" name="torque" type="Vector3" /> + <description> + Applies a rotational force without affecting position. A force is time dependent and meant to be applied every physics update. </description> </method> <method name="apply_torque_impulse"> <return type="void" /> <argument index="0" name="impulse" type="Vector3" /> <description> - 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). </description> </method> <method name="get_colliding_bodies" qualifiers="const"> @@ -111,6 +139,14 @@ <member name="center_of_mass_mode" type="int" setter="set_center_of_mass_mode" getter="get_center_of_mass_mode" enum="RigidDynamicBody3D.CenterOfMassMode" default="0"> Defines the way the body's center of mass is set. See [enum CenterOfMassMode] for possible values. </member> + <member name="constant_force" type="Vector3" setter="set_constant_force" getter="get_constant_force" default="Vector3(0, 0, 0)"> + The body's total constant positional forces applied during each physics update. + See [method add_constant_force] and [method add_constant_central_force]. + </member> + <member name="constant_torque" type="Vector3" setter="set_constant_torque" getter="get_constant_torque" default="Vector3(0, 0, 0)"> + The body's total constant rotational forces applied during each physics update. + See [method add_constant_torque]. + </member> <member name="contact_monitor" type="bool" setter="set_contact_monitor" getter="is_contact_monitor_enabled" default="false"> If [code]true[/code], the RigidDynamicBody3D will emit signals when it collides with another RigidDynamicBody3D. See also [member contacts_reported]. </member> @@ -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. </member> <member name="sleeping" type="bool" setter="set_sleeping" getter="is_sleeping" default="false"> - 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. </member> </members> <signals> |