docs(zh): update physics docs (#178)

Author: ID-Emmett

docs/.vitepress/config.ts

@@ -348,7 +348,10 @@ function sidebarGuide(): SidebarItem {
             collapsible: true,
             items: [
                 { text: '物理总览', link: '/guide/physics/Readme.md' },
-                { text: '内置组件', link: '/guide/physics/rigidbody.md' },
+                { text: '碰撞体', link: '/guide/physics/collisionShape.md' },
+                { text: '刚体', link: '/guide/physics/rigidbody.md' },
+                { text: '软体', link: '/guide/physics/softbody.md' },
+                { text: '约束', link: '/guide/physics/constraint.md' },
             ]
         },
         {

docs/.vitepress/theme/custom.css

@@ -81,6 +81,9 @@
     display: table;
     table-layout: auto;
 }
+.details > table {
+    display: block;
+}
 thead,
 tbody {
     width: 100%;

docs/guide/physics/Readme.md

@@ -32,18 +32,30 @@ import { Physics } from "@orillusion/physics"
 </script>
 ```
 
-## 物理环境的运行
-
+## 基本用法
 目前 [Physics](/physics/classes/Physics) 支持的参数及方法如下表所示：
 
 | API | 描述 |
 | --- | --- |
 | init(): void | 初始化物理引擎 |
+| initDebugDrawer(): void | 初始化物理调试器 |
 | update(): void | 更新物理系统，需要在 loop 主体中调用 |
 | gravity: Vector3 | 重力参数 |
 | isStop: boolean | 控制物理世界是否暂停运行 |
-| world: Ammo.btDiscreteDynamicsWorld | ammo.js 原生物理世界 |
+| debugDrawer: PhysicsDebugDrawer | 可视化调试工具 |
+| physicsDragger: PhysicsDragger | 拖拽交互工具 |
+| world: Ammo.btDiscreteDynamicsWorld | Ammo.js 原生物理世界 |
+
+ `init()` 初始化配置参数：
+
+| 参数 | 类型 | 描述 |
+| --- | --- | --- |
+| useSoftBody | `boolean` | 是否启用软体模拟 |
+| useDrag | `boolean` | 是否启用拖拽交互功能 |
+| physicBound | `Vector3` | 物理世界边界 |
+| destroyObjectBeyondBounds | `boolean` | 超出边界时销毁3D对象 |
 
+### 启动物理系统
 我们可以初始化 `init()` 来开启物理系统，并通过在渲染主循环中调用 `update()` 实现物理世界的运行：
 ```ts
 import { Engine3D } from '@orillusion/core'
@@ -54,21 +66,61 @@ await Engine3D.init({
   renderLoop: () => Physics.update()
 });
 ```
+::: tip
 通过以上方法开启并运行物理系统后，引擎会在每一帧渲染时，根据设定的参数计算并更新物体模型对物理世界的实际响应。
+:::
 
-在一些项目中通常会有暂停物理世界模拟的需求，因此我们提供了一个参数可以暂停&恢复物理世界的运行：
+### 暂停与恢复
 ```ts
 Physics.isStop = !Physics.isStop;
 ```
 
-## 重力环境模拟
-引擎默认的重力参数为 `Vector3(0, -9.8, 0)`，模拟的是地球的重力。如果需要自定义重力参数的话，只需更改 `Physics.gravity` 属性即可。
 
-例如，如果需要模拟太空中的无重力环境，可以更改 `gravity` 参数为：
+### 重力环境模拟
+默认重力为 `Vector3(0, -9.8, 0)`（地球重力）。自定义重力只需修改 `Physics.gravity`：
+```ts
+Physics.gravity = new Vector3(0, 0, 0); // 无重力环境
+```
+
+## 辅助功能
+- **物理可视化**：为了可视化物理对象，我们可以在引擎启动后初始化物理可视化调试器，需要为其传入 `Graphic3D` 对象：
 ```ts
-Physics.gravity = new Vector3(0,0,0);
+const graphic3D = new Graphic3D();
+scene.addChild(graphic3D);
+Physics.initDebugDrawer(graphic3D, { enable: true });
 ```
 
+::: details 使用 dat 控制调试器
+```ts
+import dat from "dat.gui";
+
+let gui = new dat.GUI();
+let f = gui.addFolder("PhysicsDebugDrawer");
+f.add(Physics.debugDrawer, 'enable').listen(); // 开启或关闭调试功能
+f.add(Physics.debugDrawer, 'debugMode', Physics.debugDrawer.debugModeList); // 调试模式
+f.add(Physics.debugDrawer, 'updateFreq', 1, 360, 1); // 线条渲染的频率（每帧）
+f.add(Physics.debugDrawer, 'maxLineCount', 100, 33000, 100); // 设置渲染的最大线条数量
+```
+:::
+
+- **物理对象交互**：如果需要使用鼠标与刚体进行拖拽控制，可以在 `init()` 中将此功能开启：
+
+```ts
+await Physics.init({ useDrag: true });
+```
+::: tip
+可以通过 `Physics.physicsDragger` 进行相关设置，详见 [PhysicsDragger](/physics/classes/PhysicsDragger)
+:::
+
+## 物理工具
+物理系统提供了一些工具，帮助开发者更灵活地进行定制开发。
+- [CollisionShapeUtil](/physics/classes/CollisionShapeUtil)：提供多种方法来创建不同类型的碰撞形状。
+- [ContactProcessedUtil](/physics/classes/ContactProcessedUtil)：用于注册和管理物理对象之间碰撞事件的工具类。
+- [RigidBodyMapping](/physics/classes/RigidBodyMapping)：管理 `Ammo` 刚体与三维模型对象映射关系的工具类，需手动指定映射。
+- [RigidBodyUtil](/physics/classes/RigidBodyUtil)：提供多种与 `Ammo` 刚体相关的实用方法，简化刚体的创建和各项操作。
+- [TempPhyMath](/physics/classes/TempPhyMath)：临时物理数学工具类，提供 `Ammo` 数学对象（如向量和四元数）的实例，并支持与引擎数据类型相互转换。
+
+
 ## 原生扩展
 当前引擎只封装了几个常用的组件，如果需要实现复杂的物理模拟，用户可以直接引用 `Ammo` 来使用原生的物理世界对象，通过 `Ammo.js` 自身提供的原生 `API` 实现更多自定化需求：
 ```ts
@@ -89,45 +141,43 @@ let transform = new Ammo.btTransform();
 更多用法详见 [Ammo API](/physics/modules/Ammo)
 
 ## 简单示例
-这里我们通过模拟一个正方体掉落在地上的过程，看一下物理系统具体可以提供哪下效果。
+这里我们通过模拟一个正方体掉落在地上的过程，看一下物理系统具体可以提供哪些效果。
 
 <Demo src="/demos/physics/demo1.ts"></Demo>
 
 <<< @/public/demos/physics/demo1.ts
 
 依照前面章节所介绍的流程，我们首先将场景、相机、环境贴图、光照等基础组件初始化并设定好参数。
-接下来，我们创建一个立方体，并为其添加刚体与碰撞体组件，使之拥有质量并能正确响应重力与碰撞。
-```ts
+接下来，我们创建一个立方体，并为其添加刚体组件并指定碰撞形状，使之拥有质量并能正确响应重力与碰撞。
+
+```ts {7-9}
 const obj = new Object3D();
 let mr = obj.addComponent(MeshRenderer);
 mr.geometry = new BoxGeometry(5, 5, 5);
 mr.material = new LitMaterial();
-// 响应重力
+
+// 响应重力并设置碰撞形状
 let rigidbody = obj.addComponent(Rigidbody);
 rigidbody.mass = 10;
-// 设置碰撞盒子
-let collider = obj.addComponent(ColliderComponent);
-collider.shape = new BoxColliderShape();
-collider.shape.size = new Vector3(5, 5, 5);
+rigidbody.shape = Rigidbody.collisionShape.createShapeFromObject(obj);
 
 scene3D.addChild(obj);
 ```
 
-之后，我们在正方体下方创建一个平面，作为地面，同样为其添加刚体与碰撞体组件。由于地面是静止的，所以我们设置其质量为 `0`。
-```ts
+之后，我们在正方体下方创建一个平面，作为地面，同样为其添加刚体组件并指定碰撞形状。由于地面是静止的，所以我们设置其质量为 `0`。
+
+```ts {7-9}
 const obj = new Object3D();
 let mr = obj.addComponent(MeshRenderer);
 mr.geometry = new PlaneGeometry(size.x, size.y);
 mr.material = new LitMaterial();
-// 静态钢体，不响应重力
+
+// 静态刚体，不响应重力
 let rigidbody = obj.addComponent(Rigidbody);
 rigidbody.mass = 0;
-// 设置碰撞盒子
-let collider = obj.addComponent(ColliderComponent);
-collider.shape = new BoxColliderShape();
-collider.shape.size = new Vector3(size.x, 0.1, size.y);
+rigidbody.shape = Rigidbody.collisionShape.createShapeFromObject(obj);
 
 scene.addChild(obj);
 ```
 
-物理系统启动后，引擎立即根据物体质量响应其重力感应，当立方体和地面的碰撞体形状产生交集时，我们可以看到真实的物体落地碰撞效果。更多[物理示例](/example/physics/Dominoes)。
+物理系统启动后，引擎立即根据物体质量响应其重力感应，当立方体和地面的碰撞体形状产生交集时，我们可以看到真实的物体落地碰撞效果，更多[物理示例](/example/physics/Dominoes)。

docs/guide/physics/collider.md

@@ -0,0 +1,107 @@
+# 碰撞体
+碰撞体形状 `Collision Shape` 定义了刚体响应碰撞的实际物理形状，物理系统可以通过 `Shape` 判定两个物体是否相交，从而产生碰撞效果。
+
+:::tip
+从 `@orillusion/physics@0.3` 开始，我们推荐直接使用 `Ammo` 原生 `Shape` 管理碰撞体
+:::
+
+## 碰撞体工具
+为了简化碰撞体的创建过程，[CollisionShapeUtil](/physics/classes/CollisionShapeUtil) 工具类提供了便捷的物理形状构建方法，涵盖了多种常见的碰撞体形状。该工具类将复杂的物理形状生成过程封装为一系列易于调用的方法，使开发者能够快速高效地为模型对象生成适配的碰撞体。
+
+### 内置形状
+
+目前 [CollisionShapeUtil](/physics/classes/CollisionShapeUtil) 提供的物理形状创建方法如下表所示：
+
+| 函数名称 | 返回类型 | 描述 |
+| --- | --- | --- |
+| createStaticPlaneShape | `Ammo.btStaticPlaneShape` | 创建一个静态平面碰撞形状，适用于无限大且静止的平面，如地面或墙壁 |
+| createBoxShape | `Ammo.btBoxShape` | 盒型碰撞形状 |
+| createSphereShape | `Ammo.btSphereShape` | 球型碰撞形状 |
+| createCapsuleShape | `Ammo.btCapsuleShape` | 胶囊型碰撞形状 |
+| createCylinderShape | `Ammo.btCylinderShape` | 圆柱型碰撞形状 |
+| createConeShape | `Ammo.btConeShape` | 圆锥形碰撞形状 |
+| createCompoundShape | `Ammo.btCompoundShape` | 复合形状，将多个子形状组合成一个复杂的碰撞体 |
+| createHeightfieldTerrainShape | `Ammo.btHeightfieldTerrainShape` | 高度场形状，适用于地形的碰撞检测 |
+| createConvexHullShape | `Ammo.btConvexHullShape` | 凸包形状，适用于动态物体的快速碰撞检测 |
+| createConvexTriangleMeshShape | `Ammo.btConvexTriangleMeshShape` | 凸包网格形状，适用于需要复杂几何表示的动态物体 |
+| createBvhTriangleMeshShape | `Ammo.btBvhTriangleMeshShape` | 边界体积层次 `BVH` 网格形状，适用于需要复杂几何表示的静态物体 |
+| createGImpactMeshShape | `Ammo.btGImpactMeshShape` | `GImpact` 网格形状，适用于复杂的三角网格碰撞检测，特别是动态物体 |
+| createShapeFromObject | `Ammo.btCollisionShape` | 创建一个匹配 `Object3D` 几何体类型的碰撞形状 |
+
+### 复杂结构支持
+`CollisionShapeUtil` 提供了两个支持处理嵌套对象的 `API`。这些 `API` 可以自动生成适合的碰撞形状或提取几何数据，适用于由引擎创建的复杂结构，无需手动为每个子对象单独配置。
+
+| 函数名称 | 返回类型 | 描述 |
+| --- | --- | --- |
+| createCompoundShapeFromObject | `Ammo.btCompoundShape` | 根据传入的 `Object3D` 及其子对象的几何体类型，自动创建一个复合碰撞体 |
+| getAllMeshVerticesAndIndices | `{ vertices:Float32Array; indices: Uint16Array; }` | 返回 `Object3D` 及其子对象的所有顶点和索引数据，经过世界变换矩阵转换后，可用于创建高精度的网格碰撞体 |
+
+## 基本使用
+
+创建碰撞体的过程已被简化，在大多数情况下，只需传入 `Object3D`，即可生成碰撞体。以下是使用 `CollisionShapeUtil` 创建基础碰撞形状的示例代码：
+
+```ts
+import { Object3D, MeshRenderer, CylinderGeometry, LitMaterial } from '@orillusion/core';
+import { CollisionShapeUtil } from '@orillusion/physics';
+
+// 创建一个圆锥体
+const coneObject = new Object3D();
+let mr = coneObject.addComponent(MeshRenderer);
+mr.geometry = new CylinderGeometry(0.01, 1, 5);
+mr.material = new LitMaterial();
+
+// 对于简单类型的几何体，如盒型、球型、圆锥、圆柱可以使用通用的方法创建碰撞体
+let coneShape1 = CollisionShapeUtil.createShapeFromObject(coneObject);
+// 或者通过计算局部包围盒创建圆锥形状
+let coneShape2 = CollisionShapeUtil.createConeShape(coneObject);
+// 或者指定形状尺寸
+let coneShape3 = CollisionShapeUtil.createConeShape(null, 1, 5);
+```
+
+同时，针对复杂类型的碰撞形状，构建流程也得到了简化。为了满足自定义需求，开发者可以传入 `vertices` 和 `indices` 以生成自定义的碰撞形状：
+
+```ts
+const object = await Engine3D.res.loadGltf('model.glb');
+
+// 创建一个BVH网格形状，使用模型自身的顶点和索引
+let bvhMeshShape = CollisionShapeUtil.createBvhTriangleMeshShape(object);
+
+// 或手动传入的顶点和索引
+const vertices = [...]
+const indices = [...]
+const vertices = new Float32Array(vertices);
+const indices = new Uint16Array(data.indices);
+let bvhMeshShape = CollisionShapeUtil.createBvhTriangleMeshShape(object, vertices, indices);
+```
+
+此外，基于 `TerrainGeometry` 或 `PlaneGeometry`，可以创建适用于模拟地形的高度场碰撞形状：
+
+```ts
+import { TerrainGeometry } from '@orillusion/geometry';
+
+// Load textures and create terrain geometry
+let heightTexture = await Engine3D.res.loadTexture('height.png');
+let terrainGeometry = new TerrainGeometry(100, 100, 60, 60);
+terrainGeometry.setHeight(heightTexture as BitmapTexture2D, 50);
+
+const terrain = new Object3D();
+let mr = terrain.addComponent(MeshRenderer);
+mr.geometry = terrainGeometry;
+mr.material = new LitMaterial();
+
+// 创建地形碰撞体
+let terrainShape = CollisionShapeUtil.createHeightfieldTerrainShape(terrain);
+```
+
+通过上述操作，我们可以创建多种碰撞体以适应不同的物理需求。然而，为了实现全面的物理模拟，单独的碰撞体是不够的。要获得真实的物理效果，还需要与 [刚体](/guide/physics/Rigidbody.html) 结合使用，从而实现完整的物理交互和模拟。
+
+
+## 示例
+
+不同的碰撞体形状适用于各类物理场景。以下示例展示了如何使用 `CollisionShapeUtil` 为多种几何形状生成对应的碰撞体，并结合 [刚体](/guide/physics/Rigidbody.html) 在物理系统中应用这些形状。
+
+<Demo src="/demos/physics/shapes.ts"></Demo>
+
+<<< @/public/demos/physics/shapes.ts
+
+更多[物理示例](/example/physics/Dominoes)