2D RigidBody

RigidBody is the basic object that composite the physics world.

The built-in 2D physics system only has collision detection capabilities, the rigid body is not available to the built-in 2D physics system. This setting is available only for other 2D physics systems.

RigidBody properties

Mass

The mass of a RigidBody is automatically calculated by the density and size of the PhysicsCollider Component. This property may be needed when calculating how much force the object should be subjected to.

  1. // Get the mass of the rigidbody
  2. const mass = rigidbody.getMass();

Velocity

  1. // Get the velocity of the move
  2. const velocity = rigidbody.linearVelocity;
  3. // Set the velocity of the move
  4. rigidbody.linearVelocity = velocity;

Linear Damping is used to simulate the air friction and other damping effects, it will make the current velocity decrease over time.

  1. // Get the moving speed attenuation factor
  2. const damping = rigidbody.linearDamping;
  3. // Set the moving speed attenuation factor
  4. rigidbody.linearDamping = damping;

To get the velocity of a point on a RigidBody, such as a box that rotates forward and touches the wall. It may be desirable to get the velocity of the box at the point of the collision. You can get it by getLinearVelocityFromWorldPoint.

  1. const velocity = rigidbody.getLinearVelocityFromWorldPoint(worldPoint);

Or, pass in a cc.Vec2 object as the second argument to get the return value in order to use the cached object to store this value. This avoids creating too many objects to improve performance.

Note: the get method of RigidBody provides an out parameter to receive the function return value.

  1. const velocity = cc.v2();
  2. rigidbody.getLinearVelocityFromWorldPoint(worldPoint, velocity);

Angular Velocity

  1. // Get the angular velocity
  2. const velocity = rigidbody.angularVelocity;
  3. // Set the angular velocity
  4. rigidbody.angularVelocity = velocity;

Travel speed decay coefficient, the larger the value the slower the object moves, and can be used to simulate effects such as air friction.

  1. // Get the angular damping
  2. const damping = rigidbody.angularDamping;
  3. // Set the angular damping
  4. rigidbody.angularDamping = damping;

Rotation, position and scaling

Rotation, position and scaling are the most commonly used transform in game development, and almost every node has these properties set. In the physics system, the system will automatically synchronize these properties of the node to Box2D corresponding properties.

Notes:

  1. There is only rotation and position in Box2D and there is no scaling, so if you set the scale properties of the node, all the colliders of the RigidBody are reconstructed. One way to avoid this is to take the renderer node as a child node of the RigidBody node, and to scale only the renderer node, to avoid scaling the RigidBody nodes as much as possible.
  2. At the end of each update of the physics system (which is updated in postUpdate), all rigid body information is synchronized to the corresponding node. all RigidBody information is synchronized to the corresponding node. In the performance considerations, the node information will be synchronized to the rigid body only if the developer sets the display properties of the node where the rigid body is located, and the rigid body will only monitor the node where it is located, i.e. if the rotation shift of the node’s parent node is modified, the information will not be synchronized.

Fixed rotation

When making a platform action game usually we do not want the player character to rotate due to physics forces. Since it will lead to the player character to lean and even fall in the process of moving around, then the fixedRotation of the rigid body can be set to true to fix the rotation.

  1. rigidbody.fixedRotation = true;

Enable Contact Listener

Only when the RigidBody’s contact listener is enabled, it will send callback to component attach to the node when collision happens.

  1. Rigidbody.enabledContactListener = true;

RigidBody type

There are three types of Box2d’s native RigidBody: Static, Dynamic, Kinematic. We added a forth type in Cocos Creator‘s physics system: Animated.

Animated is derived from the Kinematic type, the general RigidBody type changes rotate or position by setting the properties directly, but Animated type will lerp the property values between current property and target property, and assign it to the corresponding property.

Animated type is invented mainly to prevent the weird behavior such as penetration when making movement animation on RigidBody node.

  • cc.RigidBodyType.Static

    Static RigidBody, zero mass, zero velocity, that is not affected by gravity or force, but can set its position to move.

  • cc.RigidBodyType.Dynamic

    Dynamic RigidBody, with mass, its velocity can be set, will be affected by gravity.

  • cc.RigidBodyType.Kinematic

    Kinematic RigidBody, zero mass, its velocity can be set, will not be affected by gravity, but can move by setting the velocity.

  • cc.RigidBodyType.Animated

    Animated RigidBody, previously mentioned above, is derived from Kinematic type, mainly used for RigidBody and animation in combination.

RigidBody API

Get or convert the rotation and position property

Using these api to get the rotation and position in the world coordinate system will be faster than getting the relevant properties through the node, because the nodes also need to get the results through the matrix operation, and these api gives you the direct result.

Local coordinates and world coordinate transformation

  1. // world coordinates to local coordinates
  2. const localPoint = rigidbody.getLocalPoint(worldPoint);
  3. // or
  4. localPoint = cc.v2();
  5. rigidbody.getLocalPoint(worldPoint, localPoint);
  1. // local coordinates to world coordinates
  2. const worldPoint = rigidbody.getWorldPoint(localPoint);
  3. // or
  4. worldPoint = cc.v2();
  5. rigidbody.getLocalPoint(localPoint, worldPoint);
  1. // local vector to world vector
  2. const worldVector = rigidbody.getWorldVector(localVector);
  3. // or
  4. worldVector = cc.v2();
  5. rigidbody.getWorldVector(localVector, worldVector);
  1. const localVector = rigidbody.getLocalVector(worldVector);
  2. // or
  3. localVector = cc.v2();
  4. rigidbody.getLocalVector(worldVector, localVector);

Get the RigidBody mass center

When force is applied to a RigidBody, the mass center of the RigidBody is generally chosen as the point of application of the force, which ensures that the force does not affect the rotation value.

  1. // Get the mass center in the local coordinate system
  2. const localCenter = rigidbody.getLocalCenter();
  4. // or through the parameters to receive the return value
  5. localCenter = cc.v2();
  6. rigidbody.getLocalCenter(localCenter);
  8. // Get the mass center in the world coordinate system
  9. const worldCenter = rigidbody.getWorldCenter();
  11. // or through the parameters to receive the return value
  12. worldCenter = cc.v2();
  13. rigidbody.getWorldCenter(worldCenter);

Force and impulse

There are two ways to move an object:

  1. Apply a force or impulse to the object. The force will slowly change the velocity of the object over time, and the impulse will immediately modify the velocity of the object.
  2. It is possible to directly modify the location of the object, but this does not give you the real physics simulation, you should try to use force or impulse to move a RigidBody to make the physics world more consistent.
  1. // Apply a force to the point specified on the RigidBody, this point is a point in the world coordinate system
  2. rigidbody.applyForce(force, point);
  4. // or apply force directly to the mass of the rigid body
  5. rigidbody.applyForceToCenter(force);
  7. // Apply a punch to the point specified on the rigid body, this point is a point in the world coordinate system
  8. rigidbody.applyLinearImpulse(impulse, point);

Force and impulse can also affect the rotation only, this kind of force is called torque.

  1. // Apply torque to RigidBody. because it only affects the rotation, so no longer need to specify a point
  2. rigidbody.applyTorque(torque);
  4. // Apply the impulse on the rotating shaft to the RigidBody
  5. rigidbody.applyAngularImpulse(impulse);

Other Information

Sometimes you need to get the velocity of a RigidBody at a certain point, you can get by getLinearVelocityFromWorldPoint API, such as when the object collides with a platform, we need to determine whether the object is colliding from top or bottom of the platform according to the velocity of the collision point relative to the platform.

  1. rigidbody.getLinearVelocityFromWorldPoint(worldPoint);