Collider

Collider (Collider) is a component used to detect and respond to physical collisions. The engine provides the following types of colliders:

Collider components are used to define the physical properties and collision behavior of objects. The Galacean physics system provides three types of colliders:

1. Dynamic Collider
   Dynamic colliders can move freely and are affected by physical forces, suitable for movable objects that require physical simulation, such as projectiles and pushable boxes.

2. Static Collider
   Static colliders are fixed in the scene and do not move, typically used to create fixed physical obstacles such as ground and walls.

3. Character Controller
   Character controllers are colliders specifically designed for character movement, supporting features such as walking on slopes and climbing steps, suitable for character control in first-person or third-person games.

Basic Concepts

All collider types have the following common features:

1. Shape Management: Each collider can contain multiple collision shapes (character controllers can only add one). For detailed instructions on collision shapes, please refer to the Collision Shape documentation.

Currently, four types of collision shapes are supported, but the support varies among different backend physics packages, as shown below:

2. Transform Synchronization:

   • Colliders automatically synchronize the world transform of the entity, including position, rotation, and scale
   • Collision shapes can be set with local offsets and rotations relative to the entity

3. Collision/Trigger Events: Colliders can generate collision and trigger events when interacting with other colliders. For detailed information on these events and how to handle them, please refer to the Collision Events documentation.

4. Collision Layer: Each collider can be assigned to a collision layer (Layer0 to Layer31), which is used to control collision relationships between different objects. By setting collision layers, you can flexibly control which objects can collide with each other and which cannot. For more information, please refer to the Collision Layer documentation.

Best Practices

1. Reasonable Use of Shapes

• Minimize the number of collision shapes, adding additional shapes only when necessary to reduce performance overhead
• Avoid using too many collision shapes
• Use simplified collision shapes instead of precise meshes for complex models
• Capsule shapes are recommended for character controllers as they handle steps and slopes better

2. Performance Optimization

   • Set immovable objects as static colliders
   • Merge adjacent static colliders
   • Adjust the solverIterations of dynamic colliders appropriately to balance performance and accuracy
   • Use CollisionDetectionMode wisely, enabling continuous collision detection only when necessary

3. Dynamic Collider Settings

   • Adjust linearDamping and angularDamping based on the object's mass to avoid unnatural movement
   • Use constraints to restrict unnecessary degrees of freedom and improve stability
   • Set sleepThreshold appropriately to let stationary objects enter sleep mode in time

4. Character Controller Configuration

   • Set an appropriate stepOffset based on the game type to avoid getting stuck or crossing unreasonable steps
   • Set an appropriate slopeLimit considering the slope angles in the game scene
   • Choose a suitable nonWalkableMode considering whether sliding effects are needed
   • Ensure the collision shape matches the character's visual model reasonably

5. Usage Scenarios

   • Static Colliders: Scene boundaries, terrain, buildings, and other fixed objects
   • Dynamic Colliders: Pushable objects, physical props, destructible objects, etc.
   • Character Controllers: Player characters, NPCs, and other objects requiring special movement control

Script Usage

Adding Colliders

// Add a static collider
const staticCollider = entity.addComponent(StaticCollider);
 
// Add a dynamic collider
const dynamicCollider = entity.addComponent(DynamicCollider);
 
// Add a character controller
const characterController = entity.addComponent(CharacterController);

More Information

• Dynamic Collider Documentation
• Static Collider Documentation
• Character Controller Documentation
• Collision Events Documentation
• Collision Layer Documentation