Doc: opt physics doc (#2551)

* feat: opt physics doc

Author: luzhuang

docs/en/physics/_meta.json

@@ -0,0 +1,22 @@
+{
+  "overall": {
+    "title": "Physics Overview",
+    "order": 0
+  },
+  "collider": {
+    "title": "Collider",
+    "order": 1
+  },
+  "joint": {
+    "title": "Joint",
+    "order": 2
+  },
+  "manager": {
+    "title": "Physics Scene",
+    "order": 3
+  },
+  "debug": {
+    "title": "Physics Debug",
+    "order": 4
+  }
+}

docs/en/physics/collider.mdx

@@ -0,0 +1,174 @@
+---
+order: 3
+title: Character Controller
+type: Physics
+label: Physics
+---
+
+Character Controller ([CharacterController](/apis/core/#CharacterController)) is a special type of collider component specifically designed for handling character movement. It provides specialized movement algorithms and collision detection, capable of handling steps, slopes, and other complex terrains, making it particularly suitable for first-person or third-person game character control.
+
+## Usage
+
+1. Select the target entity and click the Add Component button in the inspector to add the CharacterController component.
+
+<Image src="https://mdn.alipayobjects.com/huamei_3zduhr/afts/img/A*nEMXRKiqpy8AAAAAAAAAAAAAesJ_AQ/original" />
+
+2. Set the collision shape of the controller to match the character's appearance as closely as possible. For detailed instructions on collision shapes, please refer to the [Collision Shape](/docs/physics/collider/colliderShape) documentation.
+
+<Callout type="positive">
+Unlike other colliders, the character controller can only add one collision shape. It is generally recommended to use a capsule shape (CapsuleColliderShape) as the character's collision shape.
+</Callout>
+
+<Image src="https://mdn.alipayobjects.com/huamei_3zduhr/afts/img/A*4QvUTI4D89EAAAAAAAAAAAAAesJ_AQ/original" />
+
+<Image src="https://mdn.alipayobjects.com/huamei_3zduhr/afts/img/A*aRGqSIMqDmsAAAAAAAAAAAAAesJ_AQ/original" />
+
+3. 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 |
+
+### CharacterController Specific Properties
+| Property | Description | Default Value |
+| ---- | ---- | ------ |
+| [**stepOffset**](/apis/core/#CharacterController-stepOffset) | The maximum step height the character can automatically step over. <ul><li>Must be greater than or equal to 0</li><li>Actual step height = stepOffset + contact offset of the collision shape</li></ul> | 0.5 |
+| [**slopeLimit**](/apis/core/#CharacterController-slopeLimit) | The maximum slope angle (degrees) the character can walk on. <ul><li>Slopes steeper than this angle will be treated as walls</li><li>Affects the character's ability to climb slopes</li></ul> | 45° |
+| [**nonWalkableMode**](/apis/core/#CharacterController-nonWalkableMode) | Defines how to handle non-walkable surfaces. <ul><li>PreventClimbing: Prevents the character from climbing non-walkable slopes but does not force other movements (default)</li><li>PreventClimbingAndForceSliding: Prevents the character from climbing non-walkable slopes and forces the character to slide down the slope</li></ul> | PreventClimbing |
+| [**upDirection**](/apis/core/#CharacterController-upDirection) | Defines the upward direction of the character. The default is (0, 1, 0), which is the Y-axis in world space. Affects the direction determination for movement and collision detection | (0, 1, 0) |
+
+## 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 |
+
+### CharacterController Specific Methods
+| Method Name | Description |
+| ---- | ---- |
+| [**move**](/apis/core/#CharacterController-move) | Moves the character controller. Returns a collision flag value indicating the collision state. <ul><li>displacement: Movement vector</li><li>minDist: Minimum movement distance</li><li>elapsedTime: Elapsed time</li></ul> |
+
+### Collision Flags
+
+The `move()` function returns a collision flag value that indicates the collision state of the character controller with the environment. These flags can be checked using bitwise AND operations (&):
+
+| Flag Name | Value | Description |
+|---------|----|----|
+| None | 0 | No collision occurred |
+| Sides | 1 | Collided with sides |
+| Up | 2 | Collided with the top (e.g., ceiling) |
+| Down | 4 | Collided with the bottom (e.g., ground) |
+
+## Script Usage
+
+### Basic Configuration
+```typescript
+// Create character controller
+const controller = entity.addComponent(CharacterController);
+
+// Add capsule shape
+const capsule = new CapsuleColliderShape();
+capsule.radius = 0.5;
+capsule.height = 2;
+controller.addShape(capsule);
+
+// Configure controller properties
+controller.stepOffset = 0.5;      // Set step height
+controller.slopeLimit = 45;       // Set maximum walkable slope angle
+controller.upDirection = new Vector3(0, 1, 0); // Set upward direction
+```
+
+### Using the Move Function
+```typescript
+class CharacterMovement extends Script {
+  private _velocity = new Vector3();
+  
+  onUpdate() {
+    const controller = this.entity.getComponent(CharacterController);
+    const deltaTime = engine.deltaTime;
+
+    // Create displacement vector
+    const displacement = new Vector3();
+    Vector3.scale(this._velocity, deltaTime, displacement);
+
+    // Execute movement and get collision flags
+    // minDist: Minimum movement distance, usually set to 0
+    // deltaTime: Elapsed time for physics calculations
+    const collisionFlags = controller.move(displacement, 0, deltaTime);
+    
+    // Handle collision response
+    if (collisionFlags & ControllerCollisionFlag.Down) {
+      // Character is on the ground
+    }
+  }
+}
+```
+
+### Collision Flags
+
+The `move()` function returns a collision flag value indicating the character controller's collision state with the environment. These flags can be checked using bitwise AND (&) operations:
+
+| Flag Name | Value | Description |
+|---------|----|----|
+| None | 0 | No collision occurred |
+| Sides | 1 | Collision with sides |
+| Up | 2 | Collision with ceiling |
+| Down | 4 | Collision with ground |
+
+Usage example:
+```typescript
+const flags = controller.move(displacement, 0, deltaTime);
+
+// Check if touching ground
+if (flags & ControllerCollisionFlag.Down) {
+    // Character is on ground
+    this._isGrounded = true;
+}
+
+// Check if hitting ceiling
+if (flags & ControllerCollisionFlag.Up) {
+    // Character hit ceiling
+    this._velocity.y = 0;
+}
+
+// Check if hitting walls
+if (flags & ControllerCollisionFlag.Sides) {
+    // Character hit wall
+    this._handleWallCollision();
+}
+
+// Check multiple flags
+if ((flags & ControllerCollisionFlag.Down) && 
+    (flags & ControllerCollisionFlag.Sides)) {
+    // Character is touching both ground and wall
+}
+```
+
+### Walking on Slopes/Steps
+
+1. **Walking on Slopes**
+```typescript
+// Control the walkable slope angle by setting slopeLimit
+controller.slopeLimit = 60; // Allow steeper slopes
+
+// Set the handling method for non-walkable slopes
+controller.nonWalkableMode = ControllerNonWalkableMode.PreventClimbingAndForceSliding; // Slide down steep slopes
+```
+
+2. **Adjusting Step Height**
+```typescript
+// Adjust stepOffset to control the maximum step height
+controller.stepOffset = 0.3; // Lower steps
+controller.stepOffset = 0.5; // Higher steps
+```
+
+For a complete example, refer to:
+<Playground href="/embed/physx-controller" />