engine/docs/en/physics/overall.mdx

---
order: 1
title: Overview of Physics
type: Physics
label: Physics
---

The physics engine is a very important part of the game engine. The industry generally adopts PhysX to introduce related functions. However, for lightweight scenarios, PhysX makes the final application size very large, exceeding the limits of these projects. Galacean is designed based on multiple backends. On one hand, it compiles [PhysX.js](https://github.com/galacean/physX.js) through WebAssembly; on the other hand, it also provides a lightweight physics engine. Both are consistent in [API](https://github.com/galacean/engine/tree/main/packages/design/src/physics) design. Users only need to choose a specific physics backend when initializing the engine. It can meet the needs of various scenarios such as lightweight applications and heavyweight games. For the overall design of the physics components, you can refer to the [Wiki](https://github.com/galacean/engine/wiki/Physical-system-design).

For scenarios that need to use various physics components and `InputManager` that require Raycast picking, the physics engine needs to be initialized before use. Currently, the Galacean engine provides two built-in physics engine backend implementations:

 - [physics-lite](https://github.com/galacean/engine/tree/main/packages/physics-lite)
 - [physics-physx](https://github.com/galacean/engine/tree/main/packages/physics-physx)

Developers can set the physics backend in the **Project Settings** panel opened from the [Main Menu](/en/docs/interface/sidebar) interface.

<Image src="https://mdn.alipayobjects.com/huamei_3zduhr/afts/img/A*LO_FRIsaIzIAAAAAAAAAAAAADsJ_AQ/original" />
<Image src="https://mdn.alipayobjects.com/huamei_3zduhr/afts/img/A*ZvWdQqEfIKoAAAAAAAAAAAAADsJ_AQ/original" />

If initializing the engine through a script, you only need to pass the physics backend object into the `Engine`:

```typescript
import {LitePhysics} from "@galacean/engine-physics-lite";

const engine = await WebGLEngine.create({
  canvas: htmlCanvas,
  physics: new LitePhysics(),
});
```

## Loading and Initializing the PhysX Version of the Physics Engine

```typescript
import { PhysXPhysics } from "@galacean/engine-physics-physx";

const engine = await WebGLEngine.create({
  canvas: htmlCanvas,
  physics: new PhysXPhysics(),
});
```

## Choosing a Physics Backend
Choosing a physics backend needs to consider three factors: functionality, performance, and package size:
1. Functionality: For complete physics engine functionality and high-performance physics simulation, it is recommended to choose the PhysX backend. The Lite backend only supports collision detection.
2. Performance: PhysX will automatically downgrade to pure JavaScript code on platforms that do not support WebAssembly, so performance will also decrease. However, due to the built-in data structures for scene search, the performance is still better than the Lite backend.
3. Package Size: Choosing the PhysX backend will additionally introduce nearly 2.5mb of wasm files (the size of the pure JavaScript version is similar), increasing the package size while reducing the application's initialization speed.

---
order: 0
title: Physics Overview
type: Physics
label: Physics
---

The physics engine is a crucial component of game engines, primarily responsible for the following functions:
- Physical collision detection
- Rigid body dynamics simulation  
- Joint constraint system
- Physics event response

To meet the needs of different application scenarios, Galacean adopts a multi-backend design:

- **Lite**: Optimized for simple interaction scenarios, lightweight
- **PhysX**: Provides complete physics features based on PhysX physics engine

Both backends implement a unified [Physics System API](https://github.com/galacean/engine/tree/main/packages/design/src/physics), allowing developers to flexibly choose based on project requirements. For detailed design specifications of the physics system, please refer to the [Design Document](https://github.com/galacean/engine/wiki/Physical-system-design).

<Callout type="info">
For scenarios requiring physics components or Raycast picking like `InputManager`, the physics engine needs to be initialized before use.
</Callout>

Currently, Galacean Engine provides two built-in physics engine backend implementations:

1. [Lite](/apis/physics-lite)([physics-lite](https://github.com/galacean/engine/tree/main/packages/physics-lite))
   - Lightweight physics engine implementation
   - Only supports basic collision detection
   - Suitable for simple interaction scenarios

2. [PhysX](/apis/physics-physx)([physics-physx](https://github.com/galacean/engine/tree/main/packages/physics-physx))
   - Based on PhysX physics engine, compiled through WebAssembly
   - Supports advanced physics features and accurate simulation
   - Suitable for complex physical interaction scenarios

## Choosing a Physics Backend

When choosing a physics backend, three factors need to be considered: functionality, performance, and package size:

### 1. Feature Support

| Feature | physics-lite | physics-physx |
|---------|-------------|---------------|
| Collision Detection | ✓ | ✓ |
| Physics Effects and Feedback | × | ✓ |
| Continuous Collision Detection | × | ✓ |
| Joint System | × | ✓ |

### 2. Performance
- **PhysX**: 
  - Best performance on WebAssembly platform
  - Automatically falls back to JavaScript implementation
  - Built-in scene acceleration structure
  
- **Lite**: 
  - Lightweight implementation, low performance overhead
  - Suitable for simple scenarios

### 3. Package Size
- **PhysX**: About 2.5MB (wasm/js)
- **Lite**: Lightweight, almost no additional overhead

## Usage

### Configuration in Editor

Developers can set the physics backend in the **Project Settings** panel accessed through the [Main Menu](/en/docs/interface/menu).

<Image src="https://mdn.alipayobjects.com/huamei_3zduhr/afts/img/A*LO_FRIsaIzIAAAAAAAAAAAAADsJ_AQ/original" />
<Image src="https://mdn.alipayobjects.com/huamei_3zduhr/afts/img/A*ZvWdQqEfIKoAAAAAAAAAAAAADsJ_AQ/original" />

### Script Usage

When initializing the engine through scripts, simply pass the physics backend object to the `Engine`:

#### Using Lite Physics Engine
```typescript
import { WebGLEngine } from "@galacean/engine-rhi-webgl";
import { LitePhysics } from "@galacean/engine-physics-lite";

const engine = await WebGLEngine.create({ canvas: "canvas" });
engine.physicsManager.initialize(LitePhysics);
```

#### Using PhysX Physics Engine
```typescript
import { WebGLEngine } from "@galacean/engine-rhi-webgl";
import { PhysXPhysics } from "@galacean/engine-physics-physx";

const engine = await WebGLEngine.create({ canvas: "canvas" });
await engine.physicsManager.initialize(PhysXPhysics);
```

## More Information

For detailed usage of the physics system, please refer to the following documentation:

### Colliders
- [Collider Overview](/en/docs/physics/collider/overview)
  - [DynamicCollider](/en/docs/physics/collider/dynamicCollider) - Freely moving physical objects
  - [StaticCollider](/en/docs/physics/collider/staticCollider) - Fixed physical objects in the scene
  - [CharacterController](/en/docs/physics/collider/characterController) - Collider dedicated to character control
  - [ColliderShape](/en/docs/physics/collider/colliderShape) - Shape definition for colliders

### Joint System
- [Joint System Overview](/en/docs/physics/joint/overview)
  - [FixedJoint](/en/docs/physics/joint/fixedJoint) - Completely restricts relative motion between objects
  - [SpringJoint](/en/docs/physics/joint/springJoint) - Spring-like distance constraints
  - [HingeJoint](/en/docs/physics/joint/hingeJoint) - Axial rotation constraints

### PhysicsScene
- [PhysicsScene](/en/docs/physics/manager) - Physics system manager in the scene


### Physics Debugging
- [Physics Debug](/en/docs/physics/debug) - Physics system debugging tools