classref: Sync with current upstream master branch

classes/class_rigidbody.rst

@@ -1,5 +1,6 @@
 .. Generated automatically by doc/tools/makerst.py in Godot's source tree.
-.. DO NOT EDIT THIS FILE, but the doc/base/classes.xml source instead.
+.. DO NOT EDIT THIS FILE, but the RigidBody.xml source instead.
+.. The source is found in doc/classes or modules/<name>/doc_classes.
 
 .. _class_RigidBody:
 
@@ -13,7 +14,7 @@ RigidBody
 Brief Description
 -----------------
 
-Rigid body node.
+Physics Body whose position is determined through physics simulation in 3D space.
 
 Member Functions
 ----------------
@@ -21,7 +22,7 @@ Member Functions
 +--------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+
 | void                           | :ref:`_integrate_forces<class_RigidBody__integrate_forces>`  **(** :ref:`PhysicsDirectBodyState<class_physicsdirectbodystate>` state  **)** virtual |
 +--------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+
-| void                           | :ref:`apply_impulse<class_RigidBody_apply_impulse>`  **(** :ref:`Vector3<class_vector3>` pos, :ref:`Vector3<class_vector3>` impulse  **)**          |
+| void                           | :ref:`apply_impulse<class_RigidBody_apply_impulse>`  **(** :ref:`Vector3<class_vector3>` position, :ref:`Vector3<class_vector3>` impulse  **)**     |
 +--------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+
 | :ref:`float<class_float>`      | :ref:`get_angular_damp<class_RigidBody_get_angular_damp>`  **(** **)** const                                                                        |
 +--------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -122,23 +123,24 @@ Emitted when the body changes its sleeping state. Either by sleeping or waking u
 Member Variables
 ----------------
 
-- :ref:`float<class_float>` **angular_damp**
-- :ref:`Vector3<class_vector3>` **angular_velocity**
-- :ref:`int<class_int>` **axis_lock**
-- :ref:`float<class_float>` **bounce**
-- :ref:`bool<class_bool>` **can_sleep**
-- :ref:`bool<class_bool>` **contact_monitor**
-- :ref:`int<class_int>` **contacts_reported**
-- :ref:`bool<class_bool>` **continuous_cd**
-- :ref:`bool<class_bool>` **custom_integrator**
-- :ref:`float<class_float>` **friction**
-- :ref:`float<class_float>` **gravity_scale**
-- :ref:`float<class_float>` **linear_damp**
-- :ref:`Vector3<class_vector3>` **linear_velocity**
-- :ref:`float<class_float>` **mass**
-- :ref:`int<class_int>` **mode**
-- :ref:`bool<class_bool>` **sleeping**
-- :ref:`float<class_float>` **weight**
+- :ref:`float<class_float>` **angular_damp** - Damps RigidBody's rotational forces.
+- :ref:`Vector3<class_vector3>` **angular_velocity** - RigidBody's rotational velocity.
+- :ref:`int<class_int>` **axis_lock** - Locks the rotational forces to a particular axis, preventing rotations on other axes.
+- :ref:`float<class_float>` **bounce** - RigidBody's bounciness.
+- :ref:`bool<class_bool>` **can_sleep** - If [code]true[/code] the RigidBody will not calculate forces and will act as a static body while there is no movement. It will wake up when forces are applied through other collisions or when the [code]apply_impulse[/code] method is used.
+- :ref:`bool<class_bool>` **contact_monitor** - If true, the RigidBody will emit signals when it collides with another RigidBody.
+- :ref:`int<class_int>` **contacts_reported** - The maximum contacts to report. Bodies can keep a log of the contacts with other bodies, this is enabled by setting the maximum amount of contacts reported to a number greater than 0.
+- :ref:`bool<class_bool>` **continuous_cd** - If [code]true[/code] continuous collision detection is used.
+			Continuous collision detection tries to predict where a moving body will collide, instead of moving it and correcting its movement if it collided. Continuous collision detection is more precise, and misses less impacts by small, fast-moving objects. Not using continuous collision detection is faster to compute, but can miss small, fast-moving objects.
+- :ref:`bool<class_bool>` **custom_integrator** - If [code]true[/code] internal force integration will be disabled (like gravity or air friction) for this body. Other than collision response, the body will only move as determined by the [method _integrate_forces] function, if defined.
+- :ref:`float<class_float>` **friction** - The body friction, from 0 (frictionless) to 1 (max friction).
+- :ref:`float<class_float>` **gravity_scale** - This is multiplied by the global 3D gravity setting found in "Project > Project Settings > Physics > 3d" to produce RigidBody's gravity. E.g. a value of 1 will be normal gravity, 2 will apply double gravity, and 0.5 will apply half gravity to this object.
+- :ref:`float<class_float>` **linear_damp** - RigidBody's linear damp. Default value: -1, cannot be less than -1. If this value is different from -1, any linear damp derived from the world or areas will be overridden.
+- :ref:`Vector3<class_vector3>` **linear_velocity** - RigidBody's linear velocity. Can be used sporadically, but [b]DON'T SET THIS IN 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.
+- :ref:`float<class_float>` **mass** - RigidBody's mass.
+- :ref:`int<class_int>` **mode** - The body mode from the MODE_* enum. Modes include: MODE_STATIC, MODE_KINEMATIC, MODE_RIGID, and MODE_CHARACTER.
+- :ref:`bool<class_bool>` **sleeping** - If [code]true[/code] RigidBody is sleeping and will not calculate forces until woken up by a collision or the [code]apply_impulse[/code] method.
+- :ref:`float<class_float>` **weight** - RigidBody's weight based on its mass and the global 3D gravity. Global values are set in "Project > Project Settings > Physics > 3d".
 
 Numeric Constants
 -----------------
@@ -147,11 +149,23 @@ Numeric Constants
 - **MODE_KINEMATIC** = **3** --- Kinematic body. The body behaves like a :ref:`KinematicBody<class_kinematicbody>`, and can only move by user code.
 - **MODE_RIGID** = **0** --- Rigid body. This is the "natural" state of a rigid body. It is affected by forces, and can move, rotate, and be affected by user code.
 - **MODE_CHARACTER** = **2** --- Character body. This behaves like a rigid body, but can not rotate.
+- **AXIS_LOCK_DISABLED** = **0**
+- **AXIS_LOCK_X** = **1**
+- **AXIS_LOCK_Y** = **2**
+- **AXIS_LOCK_Z** = **3**
 
 Description
 -----------
 
-Rigid body node. This node is used for placing rigid bodies in the scene. It can contain a number of shapes, and also shift mode between regular Rigid body, Kinematic, Character or Static.
+This is the node that implements full 3D physics. This means that you do not control a RigidBody directly. Instead you can apply forces to it (gravity, impulses, etc.), and the physics simulation will calculate the resulting movement, collision, bouncing, rotating, etc.
+
+This node can use custom force integration, for writing complex physics motion behavior per node.
+
+This node can shift state between regular Rigid body, Kinematic, Character or Static.
+
+Character mode forbids this node from being rotated.
+
+As a warning, don't change 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 will yield strange behavior.
 
 Member Function Description
 ---------------------------
@@ -164,7 +178,7 @@ Called during physics processing, allowing you to read and safely modify the sim
 
 .. _class_RigidBody_apply_impulse:
 
-- void  **apply_impulse**  **(** :ref:`Vector3<class_vector3>` pos, :ref:`Vector3<class_vector3>` impulse  **)**
+- void  **apply_impulse**  **(** :ref:`Vector3<class_vector3>` position, :ref:`Vector3<class_vector3>` impulse  **)**
 
 Apply a positioned impulse (which will be affected by the body mass and shape). This is the equivalent of hitting a billiard ball with a cue: a force that is applied once, and only once. Both the impulse and the offset from the body origin are in global coordinates.