Collider

Colliders can be used to define the shape of the object that needs to be physically collided with, and different geometries have different properties. Colliders are usually classified as follows:

1. Basic Colliders. The common ones include Box, Sphere, Cylinder, Cone and Capsule.
2. Composite Colliders. You can easily simulate game object shapes by adding one or more base colliders to a node, while keeping the performance overhead low.
3. MeshCollider. Generate colliders based on object mesh information, fully fitting the mesh.
4. SimplexCollider. Provide point, line, triangular surface, tetrahedron collision.
5. PlaneCollider. Can represent an infinite plane or half-space. This shape can only be used for static, non-moving objects.
6. TerrainCollider. A special support for concave terrain.

NOTE: In some (e.g. Bullet) physics backends, very high scaled sizes should be avoided due to floating point inaccuracy, here it is recommended to be below 1000. e.g. a certain box collider with a Y value of 40 and a Z value of 0.01 for its Size property, at this point they have a Y, Z ratio of more than 1000, at which case there may be inaccurate floating point calculations.

Add Collider Component

Here we will take the example of adding BoxCollider component.

Add via Editor

1. Create a new 3D object Cube, click the + Create button in the top left corner of Hierachy panel, then select Create -> 3D Object -> Cube.

   

2. Select the Cube created in Hierachy panel, click the Add Component button at the bottom of the Inspector panel on the right, and select Physics -> BoxCollider to add a collider component.

   

Add by Code

import { BoxCollider } from 'cc'
const boxCollider = this.node.addComponent(BoxCollider);

Collider Common Properties

Please note the following points for getting rigid body.

• This attribute returns null if the node itself does not have a RigidBody component.
• The real attribute corresponding to Attached is called attachedRigidBody, which is a read-only attribute and cannot be modified.

let collider = this.node.addComponent(BoxCollider)!;
let rigidbody = collider.attachedRigidBody;

To editing Colliders, please refer to: Collider Gizmo.

Note: Please check Different physical back-end collision shape support before using colliders to make sure the physics engine you are currently using supports it.

Colliders

Basic Colliders

BoxCollider

The BoxCollider is a rectangular shape based collider that can be used to achieve collision of wooden boxes, walls, and other objects. It can be used to combine into composite shapes.

Please refer to BoxCollider API for details.

SphereCollider

SphereCollider is a sphere-based collider.

Please refer to SphereCollider API for details.

CapsuleCollider

CapsuleCollider is a collider based on the shape of a capsule.

Note: cannon.js does not support capsule components, it is recommended to use two spheres and a cylinder to collocate.

Please refer to CapsuleCollider API for more details.

CylinderCollider

CylinderCollider is a cylinder-based collider.

Please refer to CylinderCollider API for details.

ConeCollider

ConeCollider is a collider based on a cone.

Please refer to ConeCollider API for details.

Composite Colliders

A composite collider is not a single collider component type, but a combination of multiple base colliders that can easily simulate the shape of complex game objects.

PlaneCollider

PlaneCollider is a collider that belongs to a planar model. Planes can be created by right-clicking Create -> 3D Objects -> Plane in the Hierarchy panel.

Please refer to PlaneCollider API for details.

MeshCollider

MeshCollider is a collider based on the model mesh.

Notes:

1. cannon.js has poor support for mesh collider components, allowing detection with only a few colliders (spheres, planes).
2. Convex functionality is currently only supported in the ammo.js backend.

MeshCollider interface please refer to MeshCollider API.

SimplexCollider

SimplexCollider is a point, line, face and tetrahedron based collider.

Please refer to SimplexCollider API for the interface to the simplex collider component.

Note: cannon.js support for lines and triangles is currently imperfect.

TerrainCollider

TerrainCollider is a collider generated by a terrain surface, with the same specific shape as the object it is attached to in the Terrain asset.

See TerrainCollider API for the Terrain Collider component interface.

Auto Scaling

Each component is bound to a node, and some components will dynamically update data based on the bound node. Among them, the collider component will automatically update the corresponding shape data based on the node information, so that the collider can fit the rendered model more closely. Take the model component as an example.

The model component will automatically update the model’s world matrix based on the bound nodes, thus enabling changes to the node’s position, scaling, rotation, and other information, which can make the rendered model have the corresponding affine transformation.

However, there are some properties of colliders that cause scaling to be handled less differently.

• Colliders are generally described in terms of geometric structures
• Colliders are mostly of convex packet type

These properties restrict transformations such as tangent, non-uniform scaling, etc. Take the sphere as an example.

Assuming that the scaling information of the bound node is (1,2,1) (non-uniform scaling), since the model and the collider describe different structures, the sphere model uses multiple base elements (such as triangular surfaces) to describe, and after scaling will be shaped into a pebble-like shape; while the sphere collider is described according to the radius size, scaling will take the dimension with the largest value to scale the radius (this is to encircle the model as much as possible with the collider), but it is still a sphere after scaling, so it cannot precisely encircle the pebble-like size of the sphere model.

Non-standard Shapes

For non-standard shapes like pebbles, you can use MeshCollider to replace the base colliders.

Note: If you need to support kinmetaic rigid bodies, you must enable the convex function.

Composite Colliders

For a single node it is easy to see if there is a physical element, but in the case of a node chain (a physical element consisting of a tree of nodes) it is difficult to see which nodes and which components the physical element is composed of.

For the case of node chains, there are currently two usage options.

1. Each node in the node chain is an element as long as it has a physical component, so that there is no dependency between the components of the parent and child nodes. If the node needs more than one collider shape, just add the corresponding Collider component to that node.

   

   Disadvantages:

   • Hierarchical structure is not intuitive enough, multiple shapes can only be added to one node, while displaying shapes requires adding sub-node models and makes it difficult to support local rotation of collision bodies.
   • When adjusting the parameters of the node chain, two places need to be adjusted at the same time: the position information of the child nodes and the data information of the corresponding Collider component on the parent node.

2. If you find a RigidBody component, you bind your own Collider component to that node, otherwise the Collider components in the whole chain will share a single RigidBody component, and the node corresponding to the element is the node corresponding to the top-level Collider component.

   Disadvantages:

   • Increases node coupling, and when nodes are updated, the corresponding dependent nodes need to be updated.
   • More content needs to be maintained when the node chain is broken, and the node chain needs to handle complex logic when it is repeatedly broken.

Note: Currently Cocos Creator is using scheme 1, subsequent versions may also be adjusted, please pay attention to the version update announcement.