mirror of
https://github.com/galacean/engine.git
synced 2026-07-01 23:54:36 +08:00
294 lines
13 KiB
Plaintext
294 lines
13 KiB
Plaintext
---
|
|
order: 2
|
|
title: Dynamic Collider
|
|
type: Physics
|
|
label: Physics
|
|
---
|
|
|
|
Dynamic Collider ([DynamicCollider](/apis/core/#DynamicCollider)) is used to simulate objects that can move freely and are affected by physical forces. It can respond to gravity, forces, collisions, and other physical effects, suitable for game objects that require realistic physical simulation.
|
|
|
|
## Usage
|
|
|
|
1. Select the target entity and click the Add Component button in the inspector to add the DynamicCollider component.
|
|
|
|
<Image src="https://mdn.alipayobjects.com/huamei_3zduhr/afts/img/A*Ep4xTqWpligAAAAAAAAAAAAAesJ_AQ/original" />
|
|
|
|
2. Add a collision shape to the collider. Dynamic colliders support adding multiple collision shapes. For detailed instructions on collision shapes, please refer to the [Collision Shape](/en/docs/physics/collider/colliderShape) documentation. Currently, the following types are supported:
|
|
|
|
<Image src="https://mdn.alipayobjects.com/huamei_3zduhr/afts/img/A*np90QZkKqXUAAAAAAAAAAAAAesJ_AQ/original" />
|
|
|
|
3. Adjust the position, size, and other properties of the collision shape to match the scene elements.
|
|
|
|
<Image src="https://mdn.alipayobjects.com/huamei_3zduhr/afts/img/A*QthGTLWFSh8AAAAAAAAAAAAAesJ_AQ/original" />
|
|
|
|
4. Adjust the properties of the collider as needed to modify the physical behavior of the object. The meaning and function of each property are explained below.
|
|
|
|
## Property Explanation
|
|
|
|
|
|
### Inherited from Collider
|
|
| Property | Description |
|
|
| ----------------------------------------- | ----------------- |
|
|
| [**shapes**](/apis/core/#Collider-shapes) | Collection of collision shapes |
|
|
|
|
### DynamicCollider Specific Properties
|
|
|
|
| Property | Description | Default Value |
|
|
| --------------- | --------------------------------------------------------- | ------ |
|
|
| [**mass**](/apis/core/#DynamicCollider-mass) | Mass of the collider. The larger the mass, the harder it is to change the object's motion state | 1.0 |
|
|
| [**useGravity**](/apis/core/#DynamicCollider-useGravity) | Whether to be affected by gravity | true |
|
|
| [**isKinematic**](/apis/core/#DynamicCollider-isKinematic) | Whether it is a kinematic object. Kinematic objects are not affected by physics but can affect other objects | false |
|
|
|
|
### Velocity Settings
|
|
|
|
| Property | Description | Default Value |
|
|
| ---------------------------- | ------------------------------------------- | ------- |
|
|
| [**linearVelocity**](/apis/core/#DynamicCollider-linearVelocity) | Linear velocity vector (world units/second) | (0,0,0) |
|
|
| [**angularVelocity**](/apis/core/#DynamicCollider-angularVelocity) | Angular velocity vector (degrees/second) | (0,0,0) |
|
|
| [**maxAngularVelocity**](/apis/core/#DynamicCollider-maxAngularVelocity) | Maximum angular velocity limit (degrees/second) | 18000/π |
|
|
| [**maxDepenetrationVelocity**](/apis/core/#DynamicCollider-maxDepenetrationVelocity) | Maximum separation velocity when colliders overlap, used to prevent objects from penetrating | 1e32 |
|
|
|
|
### Damping
|
|
|
|
| Property | Description | Default Value |
|
|
| ------------------ | ---------------- | ------ |
|
|
| [**linearDamping**](/apis/core/#DynamicCollider-linearDamping) | Linear motion damping coefficient | 0 |
|
|
| [**angularDamping**](/apis/core/#DynamicCollider-angularDamping) | Angular velocity damping coefficient | 0.05 |
|
|
|
|
### Mass/Inertia Tensor
|
|
|
|
| Property | Description | Default Value |
|
|
| -------------------------- | ------------------------ | ------- |
|
|
| [**centerOfMass**](/apis/core/#DynamicCollider-centerOfMass) | Position of the center of mass relative to the transform origin | (0,0,0) |
|
|
| [**automaticCenterOfMass**](/apis/core/#DynamicCollider-automaticCenterOfMass) | Whether to automatically calculate the center of mass | true |
|
|
| [**inertiaTensor**](/apis/core/#DynamicCollider-inertiaTensor) | Inertia tensor of the object relative to the center of mass | (1,1,1) |
|
|
| [**automaticInertiaTensor**](/apis/core/#DynamicCollider-automaticInertiaTensor) | Whether to automatically calculate the inertia tensor | true |
|
|
|
|
### Performance Optimization Settings
|
|
|
|
| Property | Description | Default Value |
|
|
| -------------------- | --------------------------------------- | ------ |
|
|
| [**sleepThreshold**](/apis/core/#DynamicCollider-sleepThreshold) | Sleep threshold. Objects enter sleep mode when their motion energy falls below this value | 0.005 |
|
|
| [**solverIterations**](/apis/core/#DynamicCollider-solverIterations) | Constraint solver iteration count | 4 |
|
|
|
|
<Callout type="info">
|
|
Constraint solving is the process used by the physics engine to resolve collisions and constraints between objects. Each iteration attempts to adjust the positions and velocities of objects to satisfy all physical constraints (such as collisions, joints, etc.).
|
|
- More iterations result in more accurate physical behavior but higher computational cost
|
|
- Too few iterations may cause objects to jitter or penetrate
|
|
- It is recommended to balance accuracy and performance based on actual needs:
|
|
- General objects: Use the default value of 4
|
|
- Precise physics: Increase to 6-8
|
|
- Performance priority: Reduce to 2-3
|
|
</Callout>
|
|
|
|
### Motion Constraints
|
|
|
|
- [**constraints**](/apis/core/#DynamicCollider-constraints)
|
|
Used to restrict the object's movement along specific axes. You can lock position and rotation along the X, Y, and Z axes.
|
|
```typescript
|
|
// Lock Y-axis position and all rotations
|
|
collider.constraints =
|
|
DynamicColliderConstraints.FreezePositionY |
|
|
DynamicColliderConstraints.FreezeRotationX |
|
|
DynamicColliderConstraints.FreezeRotationY |
|
|
DynamicColliderConstraints.FreezeRotationZ;
|
|
```
|
|
|
|
### Collision Detection Mode
|
|
|
|
- [**collisionDetectionMode**](/apis/core/#DynamicCollider-collisionDetectionMode)
|
|
Controls the precision of collision detection:
|
|
|
|
| Mode | Description | Applicable Scenarios | Performance Cost |
|
|
| ---- | ---- | -------- | -------- |
|
|
| **Discrete** | Basic detection mode, detects collisions at fixed time steps, may cause tunneling at high speeds | Low-speed objects | Lowest |
|
|
| **Continuous** | Continuous detection for static colliders, prevents high-speed objects from tunneling through static objects | High-speed projectiles | Moderate |
|
|
| **ContinuousDynamic** | Continuous detection for all colliders, prevents high-speed objects from tunneling through each other | Precise physical simulations | High |
|
|
| **ContinuousSpeculative** | Uses speculative algorithms for continuous detection, performance cost between Discrete and Continuous | General game scenarios | Moderate |
|
|
|
|
#### Example of Setting Collision Detection Mode
|
|
|
|
```typescript
|
|
// 1. Use discrete detection for normal objects
|
|
normalObject.collisionDetectionMode = CollisionDetectionMode.Discrete;
|
|
|
|
// 2. Use continuous detection for projectiles to prevent tunneling
|
|
projectile.collisionDetectionMode = CollisionDetectionMode.Continuous;
|
|
|
|
// 3. Use fully continuous detection for important physical interactions
|
|
importantPhysicsObject.collisionDetectionMode = CollisionDetectionMode.ContinuousDynamic;
|
|
|
|
// 4. Use speculative detection for general game objects
|
|
gameObject.collisionDetectionMode = CollisionDetectionMode.ContinuousSpeculative;
|
|
```
|
|
|
|
#### Selection Recommendations
|
|
|
|
1. **Based on Object Speed**
|
|
|
|
- Low-speed objects: Use Discrete
|
|
- Medium-speed objects: Use ContinuousSpeculative
|
|
- High-speed objects: Use Continuous or ContinuousDynamic
|
|
|
|
2. **Based on Importance**
|
|
|
|
- Normal scene objects: Use Discrete
|
|
- Critical game objects: Use ContinuousSpeculative
|
|
- Precise physical interactions: Use ContinuousDynamic
|
|
|
|
3. **Based on Performance**
|
|
- Performance priority: Use Discrete
|
|
- Balance between performance and precision: Use ContinuousSpeculative
|
|
- Precision priority: Use ContinuousDynamic
|
|
|
|
## Methods
|
|
|
|
### Inherited from Collider
|
|
| Method Name | Description |
|
|
| --------------------------------------------------- | ----------------- |
|
|
| [**addShape**](/apis/core/#Collider-addShape) | Add a collision shape |
|
|
| [**removeShape**](/apis/core/#Collider-removeShape) | Remove a specified collision shape |
|
|
| [**clearShapes**](/apis/core/#Collider-clearShapes) | Clear all collision shapes |
|
|
|
|
### DynamicCollider Specific Methods
|
|
| Method Name | Description |
|
|
| --------------- | ------------------ |
|
|
| [**applyForce**](/apis/core/#DynamicCollider-applyForce) | Apply force |
|
|
| [**applyTorque**](/apis/core/#DynamicCollider-applyTorque) | Apply torque |
|
|
| [**move**](/apis/core/#DynamicCollider-move) | Kinematic move |
|
|
| [**sleep**](/apis/core/#DynamicCollider-sleep) | Force sleep |
|
|
| [**wakeUp**](/apis/core/#DynamicCollider-wakeUp) | Wake up the object |
|
|
| [**isSleeping**](/apis/core/#DynamicCollider-isSleeping) | Check if the object is sleeping |
|
|
|
|
## Script Usage
|
|
|
|
### Basic Configuration
|
|
|
|
```typescript
|
|
// Create dynamic collider
|
|
const dynamicCollider = entity.addComponent(DynamicCollider);
|
|
|
|
// Add collision shape
|
|
const boxShape = new BoxColliderShape();
|
|
boxShape.size = new Vector3(1, 1, 1);
|
|
dynamicCollider.addShape(boxShape);
|
|
|
|
// Configure basic physical properties
|
|
dynamicCollider.mass = 1.0; // Set mass
|
|
dynamicCollider.useGravity = true; // Enable gravity
|
|
dynamicCollider.isKinematic = false; // Set to dynamic mode
|
|
```
|
|
|
|
### Motion Control
|
|
|
|
```typescript
|
|
class PhysicsController extends Script {
|
|
private _collider: DynamicCollider;
|
|
|
|
onAwake() {
|
|
// Get dynamic collider reference
|
|
this._collider = this.entity.getComponent(DynamicCollider);
|
|
|
|
// Configure motion damping
|
|
this._collider.linearDamping = 0.1; // Set linear damping
|
|
this._collider.angularDamping = 0.1; // Set angular damping
|
|
|
|
// Set motion constraints
|
|
this._collider.constraints =
|
|
DynamicColliderConstraints.FreezeRotationX | // Lock X-axis rotation
|
|
DynamicColliderConstraints.FreezeRotationZ; // Lock Z-axis rotation
|
|
}
|
|
|
|
onUpdate() {
|
|
// Get current velocity
|
|
const velocity = this._collider.linearVelocity;
|
|
|
|
// Set velocity
|
|
this._collider.linearVelocity = new Vector3(5, velocity.y, 0);
|
|
|
|
// Apply continuous force (e.g., thrust)
|
|
if (this.engine.inputManager.isKeyHeldDown(Keys.W)) {
|
|
this._collider.applyForce(new Vector3(0, 0, 10));
|
|
}
|
|
|
|
// Apply instantaneous force (e.g., jump)
|
|
if (this.engine.inputManager.isKeyDown(Keys.Space)) {
|
|
this._collider.applyForce(new Vector3(0, 500, 0));
|
|
}
|
|
|
|
// Apply torque (e.g., rotation)
|
|
if (this.engine.inputManager.isKeyHeldDown(Keys.R)) {
|
|
this._collider.applyTorque(new Vector3(0, 10, 0));
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Kinematic Control
|
|
|
|
```typescript
|
|
class KinematicController extends Script {
|
|
private _collider: DynamicCollider;
|
|
|
|
onAwake() {
|
|
this._collider = this.entity.getComponent(DynamicCollider);
|
|
this._collider.isKinematic = true; // Set to kinematic mode
|
|
}
|
|
|
|
// Implement elevator movement
|
|
onUpdate() {
|
|
const time = this.engine.time.elapsedTime;
|
|
const position = new Vector3(0, Math.sin(time) * 2, 0);
|
|
this._collider.move(position);
|
|
}
|
|
}
|
|
```
|
|
|
|
### Sleep Management
|
|
|
|
```typescript
|
|
class SleepController extends Script {
|
|
private _collider: DynamicCollider;
|
|
|
|
onAwake() {
|
|
this._collider = this.entity.getComponent(DynamicCollider);
|
|
|
|
// Configure sleep parameters
|
|
this._collider.sleepThreshold = 0.005; // Set sleep threshold
|
|
}
|
|
|
|
onUpdate() {
|
|
// Check if the object is sleeping
|
|
if (this._collider.isSleeping()) {
|
|
console.log("Object is sleeping");
|
|
}
|
|
|
|
// Manually control sleep
|
|
if (this.engine.inputManager.isKeyDown(Keys.S)) {
|
|
this._collider.sleep(); // Force sleep
|
|
}
|
|
|
|
if (this.engine.inputManager.isKeyDown(Keys.W)) {
|
|
this._collider.wakeUp(); // Wake up the object
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Mass/Inertia Tensor Settings
|
|
|
|
```typescript
|
|
// Automatic calculation
|
|
const collider = entity.addComponent(DynamicCollider);
|
|
collider.mass = 1.0;
|
|
collider.automaticCenterOfMass = true; // Automatically calculate center of mass
|
|
collider.automaticInertiaTensor = true; // Automatically calculate inertia tensor
|
|
|
|
// Manual settings
|
|
const customCollider = entity.addComponent(DynamicCollider);
|
|
customCollider.automaticCenterOfMass = false;
|
|
customCollider.automaticInertiaTensor = false;
|
|
customCollider.centerOfMass = new Vector3(0, 0.5, 0); // Manually set center of mass
|
|
customCollider.inertiaTensor = new Vector3(1, 1, 1); // Manually set inertia tensor
|
|
```
|