Overview of 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 through WebAssembly; on the other hand, it also provides a lightweight physics engine. Both are consistent in API 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.

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
• physics-physx

Developers can set the physics backend in the Project Settings panel opened from the Main Menu interface.

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

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

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, allowing developers to flexibly choose based on project requirements. For detailed design specifications of the physics system, please refer to the Design Document.

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

1. Lite(physics-lite)

   • Lightweight physics engine implementation
   • Only supports basic collision detection
   • Suitable for simple interaction scenarios

2. PhysX(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

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.

Script Usage

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

Using Lite Physics Engine

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

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
  • DynamicCollider - Freely moving physical objects
  • StaticCollider - Fixed physical objects in the scene
  • CharacterController - Collider dedicated to character control
  • ColliderShape - Shape definition for colliders

Joint System

• Joint System Overview
  • FixedJoint - Completely restricts relative motion between objects
  • SpringJoint - Spring-like distance constraints
  • HingeJoint - Axial rotation constraints

PhysicsScene

• PhysicsScene - Physics system manager in the scene

Physics Debugging

• Physics Debug - Physics system debugging tools