diff options
Diffstat (limited to 'doc/classes/RigidBody3D.xml')
| -rw-r--r-- | doc/classes/RigidBody3D.xml | 180 |
1 files changed, 60 insertions, 120 deletions
diff --git a/doc/classes/RigidBody3D.xml b/doc/classes/RigidBody3D.xml index 8d92c8b066..f4299335bf 100644 --- a/doc/classes/RigidBody3D.xml +++ b/doc/classes/RigidBody3D.xml @@ -5,7 +5,7 @@ </brief_description> <description> This is the node that implements full 3D physics. This means that you do not control a RigidBody3D directly. Instead, you can apply forces to it (gravity, impulses, etc.), and the physics simulation will calculate the resulting movement, collision, bouncing, rotating, etc. - A RigidBody3D has 4 behavior [member mode]s: Rigid, Static, Character, and Kinematic. + A RigidBody3D has 4 behavior [member mode]s: Dynamic, Static, DynamicLocked, and Kinematic. [b]Note:[/b] Don't change a RigidBody3D'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 [CollisionShape3D] centers. @@ -17,115 +17,75 @@ </tutorials> <methods> <method name="_integrate_forces" qualifiers="virtual"> - <return type="void"> - </return> - <argument index="0" name="state" type="PhysicsDirectBodyState3D"> - </argument> + <return type="void" /> + <argument index="0" name="state" type="PhysicsDirectBodyState3D" /> <description> 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"> - <return type="void"> - </return> - <argument index="0" name="force" type="Vector3"> - </argument> + <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]. </description> </method> <method name="add_force"> - <return type="void"> - </return> - <argument index="0" name="force" type="Vector3"> - </argument> - <argument index="1" name="position" type="Vector3" default="Vector3( 0, 0, 0 )"> - </argument> + <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. </description> </method> <method name="add_torque"> - <return type="void"> - </return> - <argument index="0" name="torque" type="Vector3"> - </argument> + <return type="void" /> + <argument index="0" name="torque" type="Vector3" /> <description> Adds a constant rotational force (i.e. a motor) without affecting position. </description> </method> <method name="apply_central_impulse"> - <return type="void"> - </return> - <argument index="0" name="impulse" type="Vector3"> - </argument> + <return type="void" /> + <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]. </description> </method> <method name="apply_impulse"> - <return type="void"> - </return> - <argument index="0" name="impulse" type="Vector3"> - </argument> - <argument index="1" name="position" type="Vector3" default="Vector3( 0, 0, 0 )"> - </argument> + <return type="void" /> + <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. </description> </method> <method name="apply_torque_impulse"> - <return type="void"> - </return> - <argument index="0" name="impulse" type="Vector3"> - </argument> + <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. </description> </method> - <method name="get_axis_lock" qualifiers="const"> - <return type="bool"> - </return> - <argument index="0" name="axis" type="int" enum="PhysicsServer3D.BodyAxis"> - </argument> - <description> - Returns [code]true[/code] if the specified linear or rotational axis is locked. - </description> - </method> <method name="get_colliding_bodies" qualifiers="const"> - <return type="Array"> - </return> + <return type="Array" /> <description> Returns a list of the bodies colliding with this one. Requires [member contact_monitor] to be set to [code]true[/code] and [member contacts_reported] to be set high enough to detect all the collisions. [b]Note:[/b] The result of this test is not immediate after moving objects. For performance, list of collisions is updated once per frame and before the physics step. Consider using signals instead. </description> </method> - <method name="get_inverse_inertia_tensor"> - <return type="Basis"> - </return> + <method name="get_inverse_inertia_tensor" qualifiers="const"> + <return type="Basis" /> <description> Returns the inverse inertia tensor basis. This is used to calculate the angular acceleration resulting from a torque applied to the [RigidBody3D]. </description> </method> - <method name="set_axis_lock"> - <return type="void"> - </return> - <argument index="0" name="axis" type="int" enum="PhysicsServer3D.BodyAxis"> - </argument> - <argument index="1" name="lock" type="bool"> - </argument> - <description> - Locks the specified linear or rotational axis. - </description> - </method> <method name="set_axis_velocity"> - <return type="void"> - </return> - <argument index="0" name="axis_velocity" type="Vector3"> - </argument> + <return type="void" /> + <argument index="0" name="axis_velocity" type="Vector3" /> <description> Sets an axis velocity. The velocity in the given vector axis will be set as the given vector length. This is useful for jumping behavior. </description> @@ -134,31 +94,13 @@ <members> <member name="angular_damp" type="float" setter="set_angular_damp" getter="get_angular_damp" default="-1.0"> Damps RigidBody3D's rotational forces. + See [member ProjectSettings.physics/3d/default_angular_damp] for more details about damping. </member> - <member name="angular_velocity" type="Vector3" setter="set_angular_velocity" getter="get_angular_velocity" default="Vector3( 0, 0, 0 )"> + <member name="angular_velocity" type="Vector3" setter="set_angular_velocity" getter="get_angular_velocity" default="Vector3(0, 0, 0)"> RigidBody3D's rotational velocity. </member> - <member name="axis_lock_angular_x" type="bool" setter="set_axis_lock" getter="get_axis_lock" default="false"> - Lock the body's rotation in the X axis. - </member> - <member name="axis_lock_angular_y" type="bool" setter="set_axis_lock" getter="get_axis_lock" default="false"> - Lock the body's rotation in the Y axis. - </member> - <member name="axis_lock_angular_z" type="bool" setter="set_axis_lock" getter="get_axis_lock" default="false"> - Lock the body's rotation in the Z axis. - </member> - <member name="axis_lock_linear_x" type="bool" setter="set_axis_lock" getter="get_axis_lock" default="false"> - Lock the body's movement in the X axis. - </member> - <member name="axis_lock_linear_y" type="bool" setter="set_axis_lock" getter="get_axis_lock" default="false"> - Lock the body's movement in the Y axis. - </member> - <member name="axis_lock_linear_z" type="bool" setter="set_axis_lock" getter="get_axis_lock" default="false"> - Lock the body's movement in the Z axis. - </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]. - [b]Note:[/b] A RigidBody3D will never enter sleep mode automatically if its [member mode] is [constant MODE_CHARACTER]. It can still be put to sleep manually by setting its [member sleeping] property to [code]true[/code]. </member> <member name="contact_monitor" type="bool" setter="set_contact_monitor" getter="is_contact_monitor_enabled" default="false"> If [code]true[/code], the RigidBody3D will emit signals when it collides with another RigidBody3D. See also [member contacts_reported]. @@ -179,8 +121,9 @@ </member> <member name="linear_damp" type="float" setter="set_linear_damp" getter="get_linear_damp" default="-1.0"> The body's linear damp. Cannot be less than -1.0. If this value is different from -1.0, any linear damp derived from the world or areas will be overridden. + See [member ProjectSettings.physics/3d/default_linear_damp] for more details about damping. </member> - <member name="linear_velocity" type="Vector3" setter="set_linear_velocity" getter="get_linear_velocity" default="Vector3( 0, 0, 0 )"> + <member name="linear_velocity" type="Vector3" setter="set_linear_velocity" getter="get_linear_velocity" default="Vector3(0, 0, 0)"> The body's linear velocity. Can be used sporadically, but [b]don't set this every frame[/b], because physics may run in another thread and runs at a different granularity. Use [method _integrate_forces] as your process loop for precise control of the body state. </member> <member name="mass" type="float" setter="set_mass" getter="get_mass" default="1.0"> @@ -196,51 +139,48 @@ <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. </member> - <member name="weight" type="float" setter="set_weight" getter="get_weight" default="9.8"> - The body's weight based on its mass and the global 3D gravity. Global values are set in [b]Project > Project Settings > Physics > 3d[/b]. - </member> </members> <signals> <signal name="body_entered"> - <argument index="0" name="body" type="Node"> - </argument> + <argument index="0" name="body" type="Node" /> <description> - Emitted when a body enters into contact with this one. Requires [member contact_monitor] to be set to [code]true[/code] and [member contacts_reported] to be set high enough to detect all the collisions. + Emitted when a collision with another [PhysicsBody3D] or [GridMap] occurs. Requires [member contact_monitor] to be set to [code]true[/code] and [member contacts_reported] to be set high enough to detect all the collisions. [GridMap]s are detected if the [MeshLibrary] has Collision [Shape3D]s. + [code]body[/code] the [Node], if it exists in the tree, of the other [PhysicsBody3D] or [GridMap]. </description> </signal> <signal name="body_exited"> - <argument index="0" name="body" type="Node"> - </argument> + <argument index="0" name="body" type="Node" /> <description> - Emitted when a body shape exits contact with this one. Requires [member contact_monitor] to be set to [code]true[/code] and [member contacts_reported] to be set high enough to detect all the collisions. + Emitted when the collision with another [PhysicsBody3D] or [GridMap] ends. Requires [member contact_monitor] to be set to [code]true[/code] and [member contacts_reported] to be set high enough to detect all the collisions. [GridMap]s are detected if the [MeshLibrary] has Collision [Shape3D]s. + [code]body[/code] the [Node], if it exists in the tree, of the other [PhysicsBody3D] or [GridMap]. </description> </signal> <signal name="body_shape_entered"> - <argument index="0" name="body_id" type="int"> - </argument> - <argument index="1" name="body" type="Node"> - </argument> - <argument index="2" name="body_shape" type="int"> - </argument> - <argument index="3" name="local_shape" type="int"> - </argument> - <description> - Emitted when a body enters into contact with this one. Requires [member contact_monitor] to be set to [code]true[/code] and [member contacts_reported] to be set high enough to detect all the collisions. - This signal not only receives the body that collided with this one, but also its [RID] ([code]body_id[/code]), the shape index from the colliding body ([code]body_shape[/code]), and the shape index from this body ([code]local_shape[/code]) the other body collided with. + <argument index="0" name="body_rid" type="RID" /> + <argument index="1" name="body" type="Node" /> + <argument index="2" name="body_shape" type="int" /> + <argument index="3" name="local_shape" type="int" /> + <description> + Emitted when one of this RigidBody3D's [Shape3D]s collides with another [PhysicsBody3D] or [GridMap]'s [Shape3D]s. Requires [member contact_monitor] to be set to [code]true[/code] and [member contacts_reported] to be set high enough to detect all the collisions. [GridMap]s are detected if the [MeshLibrary] has Collision [Shape3D]s. + [code]body_id[/code] the [RID] of the other [PhysicsBody3D] or [MeshLibrary]'s [CollisionObject3D] used by the [PhysicsServer3D]. + [code]body[/code] the [Node], if it exists in the tree, of the other [PhysicsBody3D] or [GridMap]. + [code]body_shape[/code] the index of the [Shape3D] of the other [PhysicsBody3D] or [GridMap] used by the [PhysicsServer3D]. + [code]local_shape[/code] the index of the [Shape3D] of this RigidBody3D used by the [PhysicsServer3D]. + [b]Note:[/b] Bullet physics cannot identify the shape index when using a [ConcavePolygonShape3D]. Don't use multiple [CollisionShape3D]s when using a [ConcavePolygonShape3D] with Bullet physics if you need shape indices. </description> </signal> <signal name="body_shape_exited"> - <argument index="0" name="body_id" type="int"> - </argument> - <argument index="1" name="body" type="Node"> - </argument> - <argument index="2" name="body_shape" type="int"> - </argument> - <argument index="3" name="local_shape" type="int"> - </argument> - <description> - Emitted when a body shape exits contact with this one. Requires [member contact_monitor] to be set to [code]true[/code] and [member contacts_reported] to be set high enough to detect all the collisions. - This signal not only receives the body that stopped colliding with this one, but also its [RID] ([code]body_id[/code]), the shape index from the colliding body ([code]body_shape[/code]), and the shape index from this body ([code]local_shape[/code]) the other body stopped colliding with. + <argument index="0" name="body_rid" type="RID" /> + <argument index="1" name="body" type="Node" /> + <argument index="2" name="body_shape" type="int" /> + <argument index="3" name="local_shape" type="int" /> + <description> + Emitted when the collision between one of this RigidBody3D's [Shape3D]s and another [PhysicsBody3D] or [GridMap]'s [Shape3D]s ends. Requires [member contact_monitor] to be set to [code]true[/code] and [member contacts_reported] to be set high enough to detect all the collisions. [GridMap]s are detected if the [MeshLibrary] has Collision [Shape3D]s. + [code]body_id[/code] the [RID] of the other [PhysicsBody3D] or [MeshLibrary]'s [CollisionObject3D] used by the [PhysicsServer3D]. [GridMap]s are detected if the Meshes have [Shape3D]s. + [code]body[/code] the [Node], if it exists in the tree, of the other [PhysicsBody3D] or [GridMap]. + [code]body_shape[/code] the index of the [Shape3D] of the other [PhysicsBody3D] or [GridMap] used by the [PhysicsServer3D]. + [code]local_shape[/code] the index of the [Shape3D] of this RigidBody3D used by the [PhysicsServer3D]. + [b]Note:[/b] Bullet physics cannot identify the shape index when using a [ConcavePolygonShape3D]. Don't use multiple [CollisionShape3D]s when using a [ConcavePolygonShape3D] with Bullet physics if you need shape indices. </description> </signal> <signal name="sleeping_state_changed"> @@ -251,17 +191,17 @@ </signal> </signals> <constants> - <constant name="MODE_RIGID" value="0" enum="Mode"> - Rigid body mode. This is the "natural" state of a rigid body. It is affected by forces, and can move, rotate, and be affected by user code. + <constant name="MODE_DYNAMIC" value="0" enum="Mode"> + Dynamic body mode. This is the default mode of a rigid body. It is affected by forces, and can move, rotate, and be affected by user code. </constant> <constant name="MODE_STATIC" value="1" enum="Mode"> - Static mode. The body behaves like a [StaticBody3D], and can only move by user code. + Static body mode. The body behaves like a [StaticBody3D], and can only move by user code. </constant> - <constant name="MODE_CHARACTER" value="2" enum="Mode"> - Character body mode. This behaves like a rigid body, but can not rotate. + <constant name="MODE_DYNAMIC_LOCKED" value="2" enum="Mode"> + Locked dynamic body mode. Similar to [constant MODE_DYNAMIC], but the body can not rotate. </constant> <constant name="MODE_KINEMATIC" value="3" enum="Mode"> - Kinematic body mode. The body behaves like a [KinematicBody3D], and can only move by user code. + Kinematic body mode. The body behaves like a [StaticBody3D] with [member StaticBody3D.kinematic_motion] enabled, and can only move by user code. </constant> </constants> </class> |