mirror of
https://github.com/galacean/engine.git
synced 2026-05-22 17:00:49 +08:00
288 lines
10 KiB
Plaintext
288 lines
10 KiB
Plaintext
---
|
|
order: 4
|
|
title: Collision Shapes
|
|
type: Physics
|
|
label: Physics
|
|
---
|
|
|
|
Collision shapes ([ColliderShape](/apis/core/#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
|
|
|
|
<Image src="https://mdn.alipayobjects.com/huamei_3zduhr/afts/img/A*jsEBTIs9C_MAAAAAAAAAAAAAesJ_AQ/original" />
|
|
|
|
| Shape Type | Features | Backend Support |
|
|
| -------- | ---- | -------- |
|
|
| [**BoxColliderShape**](/apis/core/#BoxColliderShape) | Most fundamental collision shape<br/>Ideal for box-like objects<br/>Size adjustable along all three axes using size property | All physics backends |
|
|
| [**SphereColliderShape**](/apis/core/#SphereColliderShape) | Perfect for spherical collision detection<br/>Single radius parameter for simple configuration | All physics backends |
|
|
| [**PlaneColliderShape**](/apis/core/#PlaneColliderShape) | Infinite plane collision surface<br/>Ideal for ground planes | PhysX physics backend only |
|
|
| [**CapsuleColliderShape**](/apis/core/#CapsuleColliderShape) | Combination of cylinder and hemispheres<br/>Perfect for character controllers<br/>Configurable radius and height | PhysX physics backend only |
|
|
|
|
## Basic Properties
|
|
|
|
### Transform Properties
|
|
- [**position**](/apis/core/#ColliderShape-position)
|
|
Local position offset relative to the collider entity.
|
|
|
|
- [**rotation**](/apis/core/#ColliderShape-rotation)
|
|
Local rotation relative to the collider entity.
|
|
|
|
### Physics Material
|
|
- [**material**](/apis/core/#ColliderShape-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**](/apis/core/#PhysicsMaterial-staticFriction) | Friction when the object is stationary. Higher values increase starting resistance | 0.6 |
|
|
| [**dynamicFriction**](/apis/core/#PhysicsMaterial-dynamicFriction) | Friction when the object is moving. Higher values increase movement resistance | 0.6 |
|
|
| [**bounciness**](/apis/core/#PhysicsMaterial-bounciness) | Controls collision restitution. Range: 0-1 (0 = no bounce, 1 = perfect bounce) | 0 |
|
|
| [**bounceCombine**](/apis/core/#PhysicsMaterial-bounceCombine) | How bounce combines between objects: <ul><li>Average: Mean of both values (default)</li><li>Minimum: Lower of both values</li><li>Maximum: Higher of both values</li><li>Multiply: Product of both values</li></ul> | Average |
|
|
| [**frictionCombine**](/apis/core/#PhysicsMaterial-frictionCombine) | How friction combines between objects: <ul><li>Average: Mean of both values (default)</li><li>Minimum: Lower of both values</li><li>Maximum: Higher of both values</li><li>Multiply: Product of both values</li></ul> | Average |
|
|
|
|
### Trigger Settings
|
|
- [**isTrigger**](/apis/core/#ColliderShape-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](/en/docs/physics/collider/event) documentation.
|
|
|
|
## Script Usage
|
|
|
|
### Creating Basic Shapes
|
|
|
|
```typescript
|
|
// 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
|
|
|
|
```typescript
|
|
// 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
|
|
|
|
```typescript
|
|
// 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
|
|
|
|
```typescript
|
|
// 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
|
|
|
|
1. **Creating Ground**
|
|
```typescript
|
|
// 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;
|
|
}
|
|
```
|
|
|
|
2. **Creating Walls**
|
|
```typescript
|
|
// 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;
|
|
}
|
|
```
|
|
|
|
3. **Creating Slopes**
|
|
```typescript
|
|
// 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;
|
|
}
|
|
```
|
|
|
|
4. **Creating Compound Shapes with Different Materials**
|
|
```typescript
|
|
// 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
|
|
|
|
1. **Shape Selection**
|
|
- Use multiple basic shapes for complex objects
|
|
- Avoid using too many collision shapes (affects performance)
|
|
- Choose capsule shapes for character controllers
|
|
|
|
2. **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
|