Physics

Collision Shapes

Collision shapes (ColliderShape) define the physical form of colliders. Galacean provides several basic collision shapes that can be combined to create complex collision areas.

Supported Shape Types

Shape Type	Features	Backend Support
BoxColliderShape	Most fundamental collision shape Ideal for box-like objects Size adjustable along all three axes using size property	All physics backends
SphereColliderShape	Perfect for spherical collision detection Single radius parameter for simple configuration	All physics backends
PlaneColliderShape	Infinite plane collision surface Ideal for ground planes	PhysX physics backend only
CapsuleColliderShape	Combination of cylinder and hemispheres Perfect for character controllers Configurable radius and height	PhysX physics backend only

Basic Properties

Transform Properties

position
Local position offset relative to the collider entity.
rotation
Local rotation relative to the collider entity.

Physics Material

material
Defines the physical material properties of the shape. Each collision shape needs a physical material to define its physical characteristics:

Property	Description	Default Value
staticFriction	Friction when the object is stationary. Higher values increase starting resistance	0.6
dynamicFriction	Friction when the object is moving. Higher values increase movement resistance	0.6
bounciness	Controls collision restitution. Range: 0-1 (0 = no bounce, 1 = perfect bounce)	0
bounceCombine	How bounce combines between objects: Average: Mean of both values (default) Minimum: Lower of both values Maximum: Higher of both values Multiply: Product of both values	Average
frictionCombine	How friction combines between objects: Average: Mean of both values (default) Minimum: Lower of both values Maximum: Higher of both values Multiply: Product of both values	Average

Trigger Settings

isTrigger
Enable trigger mode:
- true: Event triggers only, no physics
- false: Normal physical collisions (default)

For detailed information about collision and trigger events, please refer to the Collision Events documentation.

Script Usage

Creating Basic Shapes

// Create box collider
const boxShape = new BoxColliderShape();
boxShape.size = new Vector3(1, 1, 1);
boxShape.position = new Vector3(0, 0.5, 0);
 
// Create sphere collider
const sphereShape = new SphereColliderShape();
sphereShape.radius = 0.5;
sphereShape.position = new Vector3(0, 1, 0);
 
// Create capsule collider
const capsuleShape = new CapsuleColliderShape();
capsuleShape.radius = 0.5;
capsuleShape.height = 2;
 
// Create plane collider
const planeShape = new PlaneColliderShape();

Shape Management

// Get all shapes
const shapes = staticCollider.shapes;
 
// Add a shape
const boxShape = new BoxColliderShape();
staticCollider.addShape(boxShape);
 
// Remove a specific shape
staticCollider.removeShape(boxShape);
 
// Clear all shapes
staticCollider.clearShapes();

Setting Physics Material

// Create and configure physics material
const material = new PhysicsMaterial();
material.staticFriction = 0.6;    // Static friction coefficient
material.dynamicFriction = 0.4;   // Dynamic friction coefficient
material.bounciness = 0.5;        // Restitution coefficient
 
// Set material combine modes
material.frictionCombine = PhysicsMaterialCombineMode.Average;  // Friction combine mode
material.bounceCombine = PhysicsMaterialCombineMode.Maximum;    // Bounce combine mode
 
// Apply material to collision shape
const shape = new BoxColliderShape();
shape.material = material;
 
// Set different materials for different shapes
const iceShape = new BoxColliderShape();
const iceMaterial = new PhysicsMaterial();
iceMaterial.staticFriction = 0.1;
iceMaterial.dynamicFriction = 0.05;
iceMaterial.bounciness = 0;
iceShape.material = iceMaterial;
 
const bounceShape = new SphereColliderShape();
const bounceMaterial = new PhysicsMaterial();
bounceMaterial.bounciness = 0.8;
bounceMaterial.bounceCombine = PhysicsMaterialCombineMode.Maximum;
bounceShape.material = bounceMaterial;
 
// Destroy materials when no longer needed
material.destroy();
iceMaterial.destroy();
bounceMaterial.destroy();

Creating Compound Shapes

// Create an entity with multiple collision shapes
function createCompoundCollider(entity: Entity) {
    const collider = entity.addComponent(DynamicCollider);
    
    // Main shape
    const mainShape = new BoxColliderShape();
    mainShape.size = new Vector3(2, 1, 1);
    collider.addShape(mainShape);
    
    // Top shape
    const topShape = new BoxColliderShape();
    topShape.size = new Vector3(1, 1, 1);
    topShape.position = new Vector3(0, 1, 0);
    collider.addShape(topShape);
    
    return collider;
}

Common Scenarios

Creating Ground

// Create a simple ground
function createGround(width: number, length: number): Entity {
    const entity = new Entity();
    const collider = entity.addComponent(StaticCollider);
    
    const groundShape = new BoxColliderShape();
    groundShape.size = new Vector3(width, 0.1, length);
    
    // Set ground material
    const material = new PhysicsMaterial();
    material.staticFriction = 0.6;
    material.dynamicFriction = 0.6;
    material.bounciness = 0.0;
    groundShape.material = material;
    
    collider.addShape(groundShape);
    return entity;
}
 
// Create an infinite plane ground
function createInfinitePlane(): Entity {
    const entity = new Entity();
    const collider = entity.addComponent(StaticCollider);
    
    const planeShape = new PlaneColliderShape();
    // Set ground material
    const material = new PhysicsMaterial();
    material.staticFriction = 0.6;
    material.dynamicFriction = 0.6;
    planeShape.material = material;
    
    collider.addShape(planeShape);
    return entity;
}

Creating Walls

// Create a configurable wall
function createWall(width: number, height: number, depth: number, friction: number = 0.6): Entity {
    const entity = new Entity();
    const collider = entity.addComponent(StaticCollider);
    
    const wallShape = new BoxColliderShape();
    wallShape.size = new Vector3(width, height, depth);
    
    // Set wall material
    const material = new PhysicsMaterial();
    material.staticFriction = friction;
    material.dynamicFriction = friction;
    material.bounciness = 0.0;
    wallShape.material = material;
    
    collider.addShape(wallShape);
    return entity;
}

Creating Slopes

// Create a slope with friction
function createSlope(width: number, height: number, angle: number): Entity {
    const entity = new Entity();
    const collider = entity.addComponent(StaticCollider);
    
    const slopeShape = new BoxColliderShape();
    slopeShape.size = new Vector3(width, 0.1, height);
    slopeShape.rotation = new Vector3(0, 0, angle);
    
    // Set slope material
    const material = new PhysicsMaterial();
    material.staticFriction = 0.8;  // Higher friction to prevent sliding
    material.dynamicFriction = 0.8;
    material.bounciness = 0.0;
    slopeShape.material = material;
    
    collider.addShape(slopeShape);
    return entity;
}

Creating Compound Shapes with Different Materials

// Create a mixed-material platform
function createMixedPlatform(): Entity {
    const entity = new Entity();
    const collider = entity.addComponent(StaticCollider);
    
    // Create main platform (normal friction)
    const platformShape = new BoxColliderShape();
    platformShape.size = new Vector3(10, 0.5, 10);
    const normalMaterial = new PhysicsMaterial();
    normalMaterial.staticFriction = 0.6;
    normalMaterial.dynamicFriction = 0.6;
    platformShape.material = normalMaterial;
    collider.addShape(platformShape);
    
    // Add ice area (low friction)
    const iceShape = new BoxColliderShape();
    iceShape.size = new Vector3(3, 0.51, 3);
    iceShape.position = new Vector3(3, 0, 0);
    const iceMaterial = new PhysicsMaterial();
    iceMaterial.staticFriction = 0.1;
    iceMaterial.dynamicFriction = 0.05;
    iceShape.material = iceMaterial;
    collider.addShape(iceShape);
    
    // Add bouncy area
    const bounceShape = new BoxColliderShape();
    bounceShape.size = new Vector3(3, 0.51, 3);
    bounceShape.position = new Vector3(-3, 0, 0);
    const bounceMaterial = new PhysicsMaterial();
    bounceMaterial.bounciness = 0.8;
    bounceMaterial.bounceCombine = PhysicsMaterialCombineMode.Maximum;
    bounceShape.material = bounceMaterial;
    collider.addShape(bounceShape);
    
    return entity;
}

Best Practices

Shape Selection
- Use multiple basic shapes for complex objects
- Avoid using too many collision shapes (affects performance)
- Choose capsule shapes for character controllers
Performance Optimization
- Use the simplest possible collision shapes
- Set reasonable local offsets to avoid excessive overlap of collision shapes
- Use triggers instead of actual physical collisions when appropriate
- Destroy unused collision shapes and physical materials in time

Was this page helpful?

On this page

Supported Shape Types
Basic Properties
Transform Properties
Physics Material
Trigger Settings
Script Usage
Creating Basic Shapes
Shape Management
Setting Physics Material
Creating Compound Shapes
Common Scenarios
Best Practices