补充3.7版本文档：物理系统API/事件/枚举值、游戏设置事件、物品ID变更、物理使用指南

2026-03-02 00:17:03 +08:00
parent 073d730337
commit 1d963e8307
16 changed files with 30681 additions and 28994 deletions
--- a/docs/mcdocs/1-ModAPI/接口/物理.md
+++ b/docs/mcdocs/1-ModAPI/接口/物理.md
@@ -0,0 +1,469 @@
+---
+sidebarDepth: 1
+---
+# 物理
+
+# 索引
+
+---
+
+| 接口 | <div style="width: 3em"></div> | 描述 |
+| --- | --- | --- |
+| [AddBoxGeometry](物理.md#addboxgeometry) | <span style="display:inline;color:#ff5555">服务端</span> | 给自定义刚体创建盒形碰撞体 |
+| [AddForce](物理.md#addforce) | <span style="display:inline;color:#ff5555">服务端</span> | 对自定义刚体的质心添加力，对运动学刚体无效 |
+| [CreatePxActor](物理.md#createpxactor) | <span style="display:inline;color:#ff5555">服务端</span> | 给实体创建自定义刚体 |
+| [GetQuaternion](物理.md#getquaternion) | <span style="display:inline;color:#ff5555">服务端</span> <span style="display:inline;color:#7575f9">客户端</span> | 获取自定义刚体的四元数旋转 |
+| [Raycast](物理.md#raycast) | <span style="display:inline;color:#ff5555">服务端</span> <span style="display:inline;color:#7575f9">客户端</span> | 射线检测，获取与射线相交的碰撞体。目前仅支持获取自定义刚体 |
+| [SetActorFlag](物理.md#setactorflag) | <span style="display:inline;color:#ff5555">服务端</span> | 设置物理实体的行为开关 |
+| [SetGlobalPose](物理.md#setglobalpose) | <span style="display:inline;color:#ff5555">服务端</span> | 设置自定义刚体的变换（直接瞬移） |
+| [SetKinematicTarget](物理.md#setkinematictarget) | <span style="display:inline;color:#ff5555">服务端</span> | 设置运动学刚体的目标变换，仅对开启了PxRigidBodyFlag.eKINEMATIC的自定义刚体生效 |
+| [SetRigidBodyFlag](物理.md#setrigidbodyflag) | <span style="display:inline;color:#ff5555">服务端</span> | 设置自定义刚体的行为开关 |
+| [SetRigidDynamicLockFlags](物理.md#setrigiddynamiclockflags) | <span style="display:inline;color:#ff5555">服务端</span> | 设置自定义刚体的约束 |
+
+## AddBoxGeometry
+
+<span style="display:inline;color:#ff5555">服务端</span>
+
+method in mod.server.component.physxCompServer.PhysxComponentServer
+
+- 描述
+
+    给自定义刚体创建盒形碰撞体
+
+- 参数
+
+    | 参数名 | <div style="width: 4em">数据类型</div> | 说明 |
+    | :--- | :--- | :--- |
+    | localTransform | tuple(float,float,float) | 盒子中心相对实体原点的偏移 |
+    | halfX | float | 表示盒子长度的一半 |
+    | halfY | float | 表示盒子高度的一半 |
+    | halfZ | float | 表示盒子宽度的一半 |
+    | staticFriction | float | 静摩擦系数 |
+    | dynamicFriction | float | 动摩擦系数 |
+    | restitution | float | 弹性恢复系数，范围：[0, 1] |
+    | eventMask | int | [PxEventMask](../枚举值/PxEventMask.md)枚举，用于监听碰撞事件，默认为PxEventMask.Null，即不需要碰撞事件 |
+    | userData | None或str | 可记录自定义数据，长度不超过20，默认为None |
+
+- 返回值
+
+    | <div style="width: 4em">数据类型</div> | 说明 |
+    | :--- | :--- |
+    | bool | 是否成功 |
+
+- 备注
+
+    - 目前只能在AddEntityServerEvent事件中使用，不存档
+    - 世界中同时存在的碰撞体上限为8192个
+
+- 示例
+
+```python
+import mod.server.extraServerApi as serverApi
+comp = serverApi.GetEngineCompFactory().CreatePhysx(entityId)
+comp.AddBoxGeometry((0, 0.9, 0), 0.3, 0.9, 0.3, 0.05, 0.05, 0)
+```
+
+
+
+## AddForce
+
+<span style="display:inline;color:#ff5555">服务端</span>
+
+method in mod.server.component.physxCompServer.PhysxComponentServer
+
+- 描述
+
+    对自定义刚体的质心添加力，对运动学刚体无效
+
+- 参数
+
+    | 参数名 | <div style="width: 4em">数据类型</div> | 说明 |
+    | :--- | :--- | :--- |
+    | dir | tuple(float,float,float) | 在全局坐标系中定义的力/冲量 |
+    | mode | int | [PxForceMode](../枚举值/PxForceMode.md)枚举，施加力/冲量时使用的模式 |
+
+- 返回值
+
+    | <div style="width: 4em">数据类型</div> | 说明 |
+    | :--- | :--- |
+    | bool | 是否成功 |
+
+- 示例
+
+```python
+import mod.server.extraServerApi as serverApi
+from common.minecraftEnum import PxForceMode
+comp = serverApi.GetEngineCompFactory().CreatePhysx(entityId)
+# 添加一个向上的速度
+comp.AddForce((0,1,0), PxForceMode.eVELOCITY_CHANGE)
+```
+
+
+
+## CreatePxActor
+
+<span style="display:inline;color:#ff5555">服务端</span>
+
+method in mod.server.component.physxCompServer.PhysxComponentServer
+
+- 描述
+
+    给实体创建自定义刚体
+
+- 参数
+
+    无
+
+- 返回值
+
+    | <div style="width: 4em">数据类型</div> | 说明 |
+    | :--- | :--- |
+    | bool | 是否成功 |
+
+- 备注
+
+    - 只能在AddEntityServerEvent事件中使用，不存档
+    - 只能对自定义生物使用，不支持玩家与原版实体。自定义生物需移除minecraft:physics等原生物理组件，并且使用SetBlockControlAi关闭ai
+
+- 示例
+
+```python
+import mod.server.extraServerApi as serverApi
+comp = serverApi.GetEngineCompFactory().CreatePhysx(entityId)
+comp.CreatePxActor()
+```
+
+
+
+## GetQuaternion
+
+<span style="display:inline;color:#ff5555">服务端</span> <span style="display:inline;color:#7575f9">客户端</span>
+
+### 服务端接口
+
+method in mod.server.component.physxCompServer.PhysxComponentServer
+
+- 描述
+
+    获取自定义刚体的四元数旋转
+
+- 参数
+
+    无
+
+- 返回值
+
+    | <div style="width: 4em">数据类型</div> | 说明 |
+    | :--- | :--- |
+    | tuple(float,float,float,float) | 四元数 |
+
+- 备注
+
+    非自定义刚体返回(0,0,0,1)
+
+- 示例
+
+```python
+import mod.server.extraServerApi as serverApi
+comp = serverApi.GetEngineCompFactory().CreatePhysx(entityId)
+print comp.GetQuaternion()
+```
+
+### 客户端接口
+
+method in mod.client.component.physxCompClient.PhysxComponentClient
+
+- 描述
+
+    获取自定义刚体的四元数旋转
+
+- 参数
+
+    无
+
+- 返回值
+
+    | <div style="width: 4em">数据类型</div> | 说明 |
+    | :--- | :--- |
+    | tuple(float,float,float,float) | 四元数 |
+
+- 备注
+
+    非自定义刚体返回(0,0,0,1)
+
+- 示例
+
+```python
+import mod.client.extraClientApi as clientApi
+comp = clientApi.GetEngineCompFactory().CreatePhysx(entityId)
+print comp.GetQuaternion()
+```
+
+
+
+## Raycast
+
+<span style="display:inline;color:#ff5555">服务端</span> <span style="display:inline;color:#7575f9">客户端</span>
+
+### 服务端接口
+
+method in mod.server.component.physxCompServer.PhysxComponentServer
+
+- 描述
+
+    射线检测，获取与射线相交的碰撞体。目前仅支持获取自定义刚体
+
+- 参数
+
+    | 参数名 | <div style="width: 4em">数据类型</div> | 说明 |
+    | :--- | :--- | :--- |
+    | dimensionId | int | 维度id |
+    | origin | tuple(float,float,float) | 射线的起点 |
+    | dir | tuple(float,float,float) | 射线的方向 |
+    | maxDist | float | 射线的最大长度，最大128 |
+    | maxHits | int | 获取射线相交的前N个碰撞体，最大为16，默认为1 |
+
+- 返回值
+
+    | <div style="width: 4em">数据类型</div> | 说明 |
+    | :--- | :--- |
+    | list(dict) | 返回相交的碰撞体的信息。每个元素的内容见备注 |
+
+- 备注
+
+    返回列表的每个元素为一个dict，内容如下：
+
+    ```python
+    {
+        "entityId": str,                # 碰撞体所属的实体id
+        "userData": str或None,          # 碰撞体的userData
+        "pos": (float,float,float),     # 相交的位置
+        "normal": (float,float,float),  # 碰撞体在相交位置的法线
+        "dist": float,                  # 射线起点与相交点的距离
+    }
+    ```
+
+- 示例
+
+```python
+import mod.server.extraServerApi as serverApi
+comp = serverApi.GetEngineCompFactory().CreatePhysx(levelId)
+print comp.Raycast(0, (0,80,0), (0,1,0), 5)
+```
+
+### 客户端接口
+
+method in mod.client.component.physxCompClient.PhysxComponentClient
+
+- 描述
+
+    射线检测，获取与射线相交的碰撞体。目前仅支持获取自定义刚体
+
+- 参数
+
+    | 参数名 | <div style="width: 4em">数据类型</div> | 说明 |
+    | :--- | :--- | :--- |
+    | origin | tuple(float,float,float) | 射线的起点 |
+    | dir | tuple(float,float,float) | 射线的方向 |
+    | maxDist | float | 射线的最大长度，最大128 |
+    | maxHits | int | 获取射线相交的前N个碰撞体，最大为16，默认为1 |
+
+- 返回值
+
+    | <div style="width: 4em">数据类型</div> | 说明 |
+    | :--- | :--- |
+    | list(dict) | 按顺序返回相交的碰撞体的信息。每个元素的内容见备注 |
+
+- 备注
+
+    返回列表的每个元素为一个dict，内容如下：
+
+    ```python
+    {
+        "entityId": str,                # 碰撞体所属的实体id
+        "userData": str或None,          # 碰撞体的userData
+        "pos": (float,float,float),     # 相交的位置
+        "normal": (float,float,float),  # 碰撞体在相交位置的法线
+        "dist": float,                  # 射线起点与相交点的距离
+    }
+    ```
+
+- 示例
+
+```python
+import mod.client.extraClientApi as clientApi
+comp = clientApi.GetEngineCompFactory().CreatePhysx(levelId)
+print comp.Raycast((0,80,0), (0,1,0), 5)
+```
+
+
+
+## SetActorFlag
+
+<span style="display:inline;color:#ff5555">服务端</span>
+
+method in mod.server.component.physxCompServer.PhysxComponentServer
+
+- 描述
+
+    设置物理实体的行为开关
+
+- 参数
+
+    | 参数名 | <div style="width: 4em">数据类型</div> | 说明 |
+    | :--- | :--- | :--- |
+    | flag | int | [PxActorFlag](../枚举值/PxActorFlag.md)枚举 |
+
+- 返回值
+
+    | <div style="width: 4em">数据类型</div> | 说明 |
+    | :--- | :--- |
+    | bool | 是否成功 |
+
+- 示例
+
+```python
+import mod.server.extraServerApi as serverApi
+from common.minecraftEnum import PxActorFlag
+comp = serverApi.GetEngineCompFactory().CreatePhysx(entityId)
+# 不受重力
+comp.SetActorFlag(PxActorFlag.eDISABLE_GRAVITY, True)
+```
+
+
+
+## SetGlobalPose
+
+<span style="display:inline;color:#ff5555">服务端</span>
+
+method in mod.server.component.physxCompServer.PhysxComponentServer
+
+- 描述
+
+    设置自定义刚体的变换（直接瞬移）
+
+- 参数
+
+    | 参数名 | <div style="width: 4em">数据类型</div> | 说明 |
+    | :--- | :--- | :--- |
+    | pos | tuple(float,float,float)或None | 目标位置，None表示位置不变 |
+    | rot | tuple(float,float,float,float)或None | 目标旋转，用四元数表示，None表示旋转不变 |
+
+- 返回值
+
+    | <div style="width: 4em">数据类型</div> | 说明 |
+    | :--- | :--- |
+    | bool | 是否成功 |
+
+- 示例
+
+```python
+import mod.server.extraServerApi as serverApi
+comp = serverApi.GetEngineCompFactory().CreatePhysx(entityId)
+# 瞬移到0,80,0，旋转不变
+comp.SetGlobalPose((0,80,0), None)
+```
+
+
+
+## SetKinematicTarget
+
+<span style="display:inline;color:#ff5555">服务端</span>
+
+method in mod.server.component.physxCompServer.PhysxComponentServer
+
+- 描述
+
+    设置运动学刚体的目标变换，仅对开启了PxRigidBodyFlag.eKINEMATIC的自定义刚体生效
+
+- 参数
+
+    | 参数名 | <div style="width: 4em">数据类型</div> | 说明 |
+    | :--- | :--- | :--- |
+    | pos | tuple(float,float,float)或None | 目标位置，None表示位置不变 |
+    | rot | tuple(float,float,float,float)或None | 目标旋转，用四元数表示，None表示旋转不变 |
+
+- 返回值
+
+    | <div style="width: 4em">数据类型</div> | 说明 |
+    | :--- | :--- |
+    | bool | 是否成功 |
+
+- 示例
+
+```python
+import mod.server.extraServerApi as serverApi
+comp = serverApi.GetEngineCompFactory().CreatePhysx(entityId)
+# 位置移动到0,80,0，旋转不变
+comp.SetKinematicTarget((0,80,0), None)
+```
+
+
+
+## SetRigidBodyFlag
+
+<span style="display:inline;color:#ff5555">服务端</span>
+
+method in mod.server.component.physxCompServer.PhysxComponentServer
+
+- 描述
+
+    设置自定义刚体的行为开关
+
+- 参数
+
+    | 参数名 | <div style="width: 4em">数据类型</div> | 说明 |
+    | :--- | :--- | :--- |
+    | flag | int | [PxRigidBodyFlag](../枚举值/PxRigidBodyFlag.md)枚举 |
+    | val | bool | 开关 |
+
+- 返回值
+
+    | <div style="width: 4em">数据类型</div> | 说明 |
+    | :--- | :--- |
+    | bool | 是否成功 |
+
+- 示例
+
+```python
+import mod.server.extraServerApi as serverApi
+from common.minecraftEnum import PxRigidBodyFlag
+comp = serverApi.GetEngineCompFactory().CreatePhysx(entityId)
+comp.SetRigidBodyFlag(PxRigidBodyFlag.eKINEMATIC, True) # 设置为运动学刚体
+```
+
+
+
+## SetRigidDynamicLockFlags
+
+<span style="display:inline;color:#ff5555">服务端</span>
+
+method in mod.server.component.physxCompServer.PhysxComponentServer
+
+- 描述
+
+    设置自定义刚体的约束
+
+- 参数
+
+    | 参数名 | <div style="width: 4em">数据类型</div> | 说明 |
+    | :--- | :--- | :--- |
+    | flag | int | [PxRigidDynamicLockFlag](../枚举值/PxRigidDynamicLockFlag.md)枚举 |
+
+- 返回值
+
+    | <div style="width: 4em">数据类型</div> | 说明 |
+    | :--- | :--- |
+    | bool | 是否成功 |
+
+- 示例
+
+```python
+import mod.server.extraServerApi as serverApi
+from common.minecraftEnum import PxRigidDynamicLockFlag
+comp = serverApi.GetEngineCompFactory().CreatePhysx(entityId)
+# 锁定xyz轴旋转
+comp.SetRigidDynamicLockFlags(PxRigidDynamicLockFlag.eLOCK_ANGULAR_X | PxRigidDynamicLockFlag.eLOCK_ANGULAR_Y | PxRigidDynamicLockFlag.eLOCK_ANGULAR_Z)
+```
+
+