补充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/config.json
+++ b/docs/mcdocs/1-ModAPI/config.json
@@ -144,7 +144,8 @@
                "/mcdocs/1-ModAPI/接口/联机大厅", 
                "/mcdocs/1-ModAPI/接口/成就", 
                "/mcdocs/1-ModAPI/接口/商城", 
-                "/mcdocs/1-ModAPI/接口/渲染"
+                "/mcdocs/1-ModAPI/接口/渲染", 
+                "/mcdocs/1-ModAPI/接口/物理"
            ], 
            "title": "接口"
        }, 
@@ -160,7 +161,9 @@
                "/mcdocs/1-ModAPI/事件/UI", 
                "/mcdocs/1-ModAPI/事件/音效", 
                "/mcdocs/1-ModAPI/事件/控制", 
-                "/mcdocs/1-ModAPI/事件/联机大厅"
+                "/mcdocs/1-ModAPI/事件/联机大厅", 
+                "/mcdocs/1-ModAPI/事件/物理", 
+                "/mcdocs/1-ModAPI/事件/游戏设置"
            ], 
            "title": "事件"
        }, 
@@ -217,6 +220,11 @@
                "/mcdocs/1-ModAPI/枚举值/PlayerActionType", 
                "/mcdocs/1-ModAPI/枚举值/PlayerExhauseRatioType", 
                "/mcdocs/1-ModAPI/枚举值/PlayerUISlot", 
+                "/mcdocs/1-ModAPI/枚举值/PxActorFlag", 
+                "/mcdocs/1-ModAPI/枚举值/PxEventMask", 
+                "/mcdocs/1-ModAPI/枚举值/PxForceMode", 
+                "/mcdocs/1-ModAPI/枚举值/PxRigidBodyFlag", 
+                "/mcdocs/1-ModAPI/枚举值/PxRigidDynamicLockFlag", 
                "/mcdocs/1-ModAPI/枚举值/RayFilterType", 
                "/mcdocs/1-ModAPI/枚举值/RedstoneModeType", 
                "/mcdocs/1-ModAPI/枚举值/RenderControllerArrayType", 
@@ -240,6 +248,7 @@
        }, 
        {
            "children": [
+                "/mcdocs/1-ModAPI/更新信息/3.7", 
                "/mcdocs/1-ModAPI/更新信息/3.6", 
                "/mcdocs/1-ModAPI/更新信息/3.5", 
                "/mcdocs/1-ModAPI/更新信息/3.4", 
--- a/docs/mcdocs/1-ModAPI/事件/事件索引表.md
+++ b/docs/mcdocs/1-ModAPI/事件/事件索引表.md
@@ -15,6 +15,8 @@ sidebarDepth: 1
 - [音效](#音效)
 - [控制](#控制)
 - [联机大厅](#联机大厅)
+- [物理](#物理)
+- [游戏设置](#游戏设置)

 ## 世界
 | 事件| <div style="width: 3em"></div> | 描述 |
@@ -337,3 +339,17 @@ sidebarDepth: 1
 | --- | --- | --- |
 | [lobbyGoodBuySucServerEvent](联机大厅.md#lobbygoodbuysucserverevent) | <span style="display:inline;color:#ff5555">服务端</span> | 玩家登录联机大厅服务器，或者联机大厅游戏内购买商品时触发。如果是玩家登录，触发时玩家客户端已经触发了UiInitFinished事件 |

+## 物理
+| 事件| <div style="width: 3em"></div> | 描述 |
+| --- | --- | --- |
+| [PhysxTouchClientEvent](物理.md#physxtouchclientevent) | <span style="display:inline;color:#7575f9">客户端</span> | 给自定义刚体添加的碰撞体，与其他碰撞体或原版实体发生碰撞/结束碰撞时触发。需要在碰撞体创建时使用PxEventMask.Client才会触发 |
+| [PhysxTouchServerEvent](物理.md#physxtouchserverevent) | <span style="display:inline;color:#ff5555">服务端</span> | 给自定义刚体添加的碰撞体，与其他碰撞体或原版实体发生碰撞/结束碰撞时触发。需要在碰撞体创建时使用PxEventMask.Server才会触发 |
+
+## 游戏设置
+| 事件| <div style="width: 3em"></div> | 描述 |
+| --- | --- | --- |
+| [OnCustomGamepadChangedEvent](游戏设置.md#oncustomgamepadchangedevent) | <span style="display:inline;color:#7575f9">客户端</span> | 当自定义手柄按键绑定发生改变时触发 |
+| [OnCustomGamepadPressInGame](游戏设置.md#oncustomgamepadpressingame) | <span style="display:inline;color:#7575f9">客户端</span> | 当玩家按下自定义手柄按键时触发 |
+| [OnCustomKeyChangedEvent](游戏设置.md#oncustomkeychangedevent) | <span style="display:inline;color:#7575f9">客户端</span> | 当自定义按键绑定发生改变时触发 |
+| [OnCustomKeyPressInGame](游戏设置.md#oncustomkeypressingame) | <span style="display:inline;color:#7575f9">客户端</span> | 当玩家按下自定义按键时触发 |
+
--- a/docs/mcdocs/1-ModAPI/事件/游戏设置.md
+++ b/docs/mcdocs/1-ModAPI/事件/游戏设置.md
@@ -0,0 +1,109 @@
+---
+sidebarDepth: 1
+---
+# 游戏设置
+
+# 索引
+
+| 事件 | <div style="width: 3em"></div> | 描述 |
+| --- | --- | --- |
+| [OnCustomGamepadChangedEvent](游戏设置.md#oncustomgamepadchangedevent) | <span style="display:inline;color:#7575f9">客户端</span> | 当自定义手柄按键绑定发生改变时触发 |
+| [OnCustomGamepadPressInGame](游戏设置.md#oncustomgamepadpressingame) | <span style="display:inline;color:#7575f9">客户端</span> | 当玩家按下自定义手柄按键时触发 |
+| [OnCustomKeyChangedEvent](游戏设置.md#oncustomkeychangedevent) | <span style="display:inline;color:#7575f9">客户端</span> | 当自定义按键绑定发生改变时触发 |
+| [OnCustomKeyPressInGame](游戏设置.md#oncustomkeypressingame) | <span style="display:inline;color:#7575f9">客户端</span> | 当玩家按下自定义按键时触发 |
+# 游戏设置
+
+## OnCustomGamepadChangedEvent
+
+<span style="display:inline;color:#7575f9">客户端</span>
+
+- 描述
+
+    当自定义手柄按键绑定发生改变时触发
+
+- 参数
+
+    | 参数名 | <div style="width: 4em">数据类型</div> | 说明 |
+    | :--- | :--- | :--- |
+    | name | str | 按键名称 |
+    | oldKey | str | 旧的键码 |
+    | newKey | str | 新的键码 |
+
+- 返回值
+
+    无
+
+
+
+## OnCustomGamepadPressInGame
+
+<span style="display:inline;color:#7575f9">客户端</span>
+
+- 描述
+
+    当玩家按下自定义手柄按键时触发
+
+- 参数
+
+    | 参数名 | <div style="width: 4em">数据类型</div> | 说明 |
+    | :--- | :--- | :--- |
+    | name | str | 按键名称 |
+    | key | str | 键码 |
+    | category | str | 按键分类 |
+    | isDown | str | 按下状态 ("1"为按下, "0"为抬起)，仅普通按键有效 |
+    | magnitude | float | 扳机力度 (0.0-1.0)，仅扳机键有效 |
+    | x | float | 摇杆X轴偏移 (-1.0-1.0)，仅摇杆键有效 |
+    | y | float | 摇杆Y轴偏移 (-1.0-1.0)，仅摇杆键有效 |
+    | screenName | str | 当前屏幕名称 |
+
+- 返回值
+
+    无
+
+
+
+## OnCustomKeyChangedEvent
+
+<span style="display:inline;color:#7575f9">客户端</span>
+
+- 描述
+
+    当自定义按键绑定发生改变时触发
+
+- 参数
+
+    | 参数名 | <div style="width: 4em">数据类型</div> | 说明 |
+    | :--- | :--- | :--- |
+    | name | str | 按键名称 |
+    | oldKey | str | 旧的键码 |
+    | newKey | str | 新的键码 |
+
+- 返回值
+
+    无
+
+
+
+## OnCustomKeyPressInGame
+
+<span style="display:inline;color:#7575f9">客户端</span>
+
+- 描述
+
+    当玩家按下自定义按键时触发
+
+- 参数
+
+    | 参数名 | <div style="width: 4em">数据类型</div> | 说明 |
+    | :--- | :--- | :--- |
+    | name | str | 按键名称 |
+    | key | str | 键码 |
+    | category | str | 按键分类 |
+    | isDown | str | 按下状态 ("1"为按下, "0"为抬起) |
+    | screenName | str | 当前屏幕名称 |
+
+- 返回值
+
+    无
+
+
--- a/docs/mcdocs/1-ModAPI/事件/物理.md
+++ b/docs/mcdocs/1-ModAPI/事件/物理.md
@@ -0,0 +1,118 @@
+---
+sidebarDepth: 1
+---
+# 物理
+
+# 索引
+
+| 事件 | <div style="width: 3em"></div> | 描述 |
+| --- | --- | --- |
+| [PhysxTouchClientEvent](物理.md#physxtouchclientevent) | <span style="display:inline;color:#7575f9">客户端</span> | 给自定义刚体添加的碰撞体，与其他碰撞体或原版实体发生碰撞/结束碰撞时触发。需要在碰撞体创建时使用PxEventMask.Client才会触发 |
+| [PhysxTouchServerEvent](物理.md#physxtouchserverevent) | <span style="display:inline;color:#ff5555">服务端</span> | 给自定义刚体添加的碰撞体，与其他碰撞体或原版实体发生碰撞/结束碰撞时触发。需要在碰撞体创建时使用PxEventMask.Server才会触发 |
+# 物理
+
+## PhysxTouchClientEvent
+
+<span style="display:inline;color:#7575f9">客户端</span>
+
+- 描述
+
+    给自定义刚体添加的碰撞体，与其他碰撞体或原版实体发生碰撞/结束碰撞时触发。需要在碰撞体创建时使用PxEventMask.Client才会触发
+
+- 参数
+
+    | 参数名 | <div style="width: 4em">数据类型</div> | 说明 |
+    | :--- | :--- | :--- |
+    | touch | list(dict) | 开始接触的碰撞体对的信息。一个碰撞体在创建时使用了PxEventMask.Found，他与其他碰撞体/原版实体开始接触时，会出现在列表中 |
+    | lost | list(dict) | 结束接触的碰撞体对的信息。一个碰撞体在创建时使用了PxEventMask.Lost，他与其他碰撞体/原版实体结束接触时，会出现在列表中 |
+
+- 返回值
+
+    无
+
+- 备注
+
+    touch列表每个元素的内容：
+
+    ```python
+    {
+        "entityId0": str,    # 一个碰撞体所属实体的entityId
+        "identifier0": str,  # 一个碰撞体所属实体的identifier
+        "shape0": str或None, # 一个碰撞体的userData
+        "entityId1": str,    # 另一个碰撞体所属实体的entityId
+        "identifier1": str,  # 另一个碰撞体所属实体的identifier
+        "shape1": str或None,  # 另一个碰撞体的userData
+        "pos": (float,float,float),  # 碰撞点的世界坐标。其中一个碰撞体在创建时使用了PxEventMask.Found_Detail才有该字段
+        "normal":(float,float,float)  # 碰撞产生的力的方向，由碰撞体1指向碰撞体0。其中一个碰撞体在创建时使用了PxEventMask.Found_Detail才有该字段
+    }
+    ```
+
+    lost列表每个元素的内容：
+
+    ```python
+    {
+        "entityId0": str,     # 一个碰撞体所属实体的entityId
+        "identifier0": str,   # 一个碰撞体所属实体的identifier
+        "shape0": str或None,  # 一个碰撞体的userData
+        "entityId1": str,     # 另一个碰撞体所属实体的entityId
+        "identifier1": str,   # 另一个碰撞体所属实体的identifier
+        "shape1": str或None   # 另一个碰撞体的userData
+    }
+    ```
+
+    列表中的碰撞对不分先后，每个碰撞对中的碰撞体0与碰撞体1也不分先后
+
+
+
+## PhysxTouchServerEvent
+
+<span style="display:inline;color:#ff5555">服务端</span>
+
+- 描述
+
+    给自定义刚体添加的碰撞体，与其他碰撞体或原版实体发生碰撞/结束碰撞时触发。需要在碰撞体创建时使用PxEventMask.Server才会触发
+
+- 参数
+
+    | 参数名 | <div style="width: 4em">数据类型</div> | 说明 |
+    | :--- | :--- | :--- |
+    | touch | list(dict) | 开始接触的碰撞体对的信息。一个碰撞体在创建时使用了PxEventMask.Found，他与其他碰撞体/原版实体开始接触时，会出现在列表中 |
+    | lost | list(dict) | 结束接触的碰撞体对的信息。一个碰撞体在创建时使用了PxEventMask.Lost，他与其他碰撞体/原版实体结束接触时，会出现在列表中 |
+
+- 返回值
+
+    无
+
+- 备注
+
+    touch列表每个元素的内容：
+
+    ```python
+    {
+        "entityId0": str,    # 一个碰撞体所属实体的entityId
+        "identifier0": str,  # 一个碰撞体所属实体的identifier
+        "shape0": str或None, # 一个碰撞体的userData
+        "entityId1": str,    # 另一个碰撞体所属实体的entityId
+        "identifier1": str,  # 另一个碰撞体所属实体的identifier
+        "shape1": str或None,  # 另一个碰撞体的userData
+        "pos": (float,float,float),  # 碰撞点的世界坐标。其中一个碰撞体在创建时使用了PxEventMask.Found_Detail才有该字段
+        "normal":(float,float,float)  # 碰撞产生的力的方向，由碰撞体1指向碰撞体0。其中一个碰撞体在创建时使用了PxEventMask.Found_Detail才有该字段
+    }
+    ```
+
+    lost列表每个元素的内容：
+
+    ```python
+    {
+        "entityId0": str,     # 一个碰撞体所属实体的entityId
+        "identifier0": str,   # 一个碰撞体所属实体的identifier
+        "shape0": str或None,  # 一个碰撞体的userData
+        "entityId1": str,     # 另一个碰撞体所属实体的entityId
+        "identifier1": str,   # 另一个碰撞体所属实体的identifier
+        "shape1": str或None   # 另一个碰撞体的userData
+    }
+    ```
+
+    列表中的碰撞对不分先后，每个碰撞对中的碰撞体0与碰撞体1也不分先后
+
+
--- 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)
+```
+
+
--- a/docs/mcdocs/1-ModAPI/更新信息/3.7.md
+++ b/docs/mcdocs/1-ModAPI/更新信息/3.7.md
@@ -0,0 +1,191 @@
+# 3.7
+
+2025.12.31：版本号（V3.7 BE1.21.50）包括Mod PC包，手机测试版启动器，和服务器引擎。
+
+示例Demo：<a href="../../../mcguide/20-玩法开发/13-模组SDK编程/60-Demo示例.html" rel="noopenner">前往此处下载</a>
+
+## 一、更新时间表
+
+1. 在2025年12月31日上线3.7第一个Beta版。
+2. 在2026年1月14日上线3.7第二个Beta版。
+3. 在2026年1月28日上线3.7稳定版。有以下注意事项:
+   - 3.7稳定包，会提供RenderDragon渲染龙、Opengl两个包体
+   - 渲染龙版本仅会在Java经典版中的基岩版（非基岩互通版和手机版）上线，基岩互通版和手机端仍然使用 OpenGL
+   - 为了确保您的模组、光影等内容后续能够兼容基岩版，您可以通过3.7稳定版渲染龙包进行测试兼容开发
+4. 在2026年2月1日，全渠道将更新3.7版本玩家包体，玩家将陆续更新到3.7版本，请开发者合理安排更新节奏。
+
+## 二、重要功能更新
+
+1. **物理系统**
+
+    > 注意：物理系列的接口为实验性内容，在后期版本中可能会存在接口变更、开发环境变更等情况。请各位开发者合理安排开发内容与正式版本，避免后续版本物理系统更新后出现模组失效的情况
+
+    - 新增创建物理刚体，开发者可以给实体创建自定义刚体，并给刚体添加力、碰撞盒，设置其位置、四元数旋转等，同时新增支持刚体碰撞盒之间碰撞检测、以及适用于刚体的射线检测
+    - 物理系统相关教程请见[物理的使用指南](../../../mcguide/20-玩法开发/13-模组SDK编程/60-Demo示例.md)
+
+2. **PC按键绑定**
+
+    - 新增自定义手柄按键(GamepadKeyMappings)的注册和获取，同时新增事件支持在按下自定义手柄按键时、自定义手柄按键绑定发生改变时触发
+    - 新增自定义按键映射(CustomKeyMapping)的注册和获取，同时新增事件支持在玩家按下自定义按键时、自定义按键绑定发生改变时触发
+
+3. **客户端实体**
+
+    - 对 CreateClientEntityByTypeStr 创建的客户端实体，接口创建的客户端实体进行了优化，对实体使用的一系列渲染、模型、材质、动画等接口，也支持对客户端实体使用
+    - 新增[GetEntitiesAroundForClientEntity](../接口/实体/属性.md#getentitiesaroundforcliententity)(客户端)
+    - 新增[GetEntitiesInSquareAreaForClientEntity](../接口/实体/属性.md#getentitiesinsquareareaforcliententity)(客户端)接口，用于获取区域内的客户端实体
+    - 新增[SetRotForClientEntity](../接口/实体/属性.md#setrotforcliententity)(客户端)，设置客户端实体头与水平方向的俯仰角度和竖直方向的旋转角度
+    - 新增[SetPosForClientEntity](../接口/实体/属性.md#setposforcliententity)(客户端)，设置客户端实体位置
+
+4. **新增其他接口**
+
+    - 新增[EntityUseItemToPos](../接口/世界/行为.md#entityuseitemtopos)(服务端)，模拟实体对某个坐标使用指定物品
+    - 新增[UseItemToEntity](../接口/世界/行为.md#useitemtoentity)(服务端)，模拟对某个实体使用物品
+    - 新增[GetRecipeByRecipeId](../接口/世界/方块管理.md#getrecipebyrecipeid)(客户端)，可以根据配方id查询配方内容
+
+5. **接口优化**
+
+    - [AddEffectToEntity](../接口/实体/状态效果.md#addeffecttoentity)(服务端)接口持续时间支持设置浮点型
+    - [UseItemAttackEntity](../接口/世界/行为.md#useitemattackentity)(服务端)接口增加damageFormula参数，可传入计算公式来修改伤害值
+    - 调整[ItemPushInCustomContainerServerEvent](../事件/方块.md#itempushincustomcontainerserverevent)(服务端)、[ItemPullOutCustomContainerServerEvent](../事件/方块.md#itempulloutcustomcontainerserverevent)(服务端)，增加容器方块所在维度的参数
+
+::: warning 特别注意
+**3.7同步微软版本后变更内容较多，以下为官方整理的重要变更，请开发者们注意适配。**
+:::
+
+- 微软在1.21.50继续修改了部分方块ID，如光源方块、虫蚀类方块等，详见[3.7版本物品id变更](../../../mcguide/20-玩法开发/13-模组SDK编程/Python脚本开发/103-3.7版本物品id变更.md)，请开发者注意适配
+- 3.7 版本同步微软后，将会移除假日创作者实验。使用实验性功能的内容可能无法正常运行。开发者可以使用网易组件+Mod API，可以复刻大部分内容
+- **极限模式说明**：以下接口不能在极限模式使用，同样原版指令也将不会生效，请开发者注意使用场景
+    - `SetPlayerGameType` 设置玩家游戏模式
+    - `SetGameRulesInfoServer` 设置游戏规则
+    - `SetGameDifficulty` 设置游戏难度
+    - `SetDefaultGameType` 设置默认游戏模式
+- **原版UI变更**：原版界面Json路径有所修改，如果开发者修改原版Json界面，则需要重新调整路径。以下文件具有变更，请开发者注意适配
+    - ui_common.json
+    - play_screen.json
+    - gameplay_common.json
+    - start_screen.json
+    - pause_screen.json
+    - settings_screen.json
+    - hud_screen.json
+    - inventory_screen.json
+    - inventory_screen_pocket.json
+    - general_section.json
+    - world_section.json
+    - controls_section.json
+    - command_block_screen.json
+
+## 三、API更新
+
+- 新增
+
+1. 新增[EntityUseItemToPos](../接口/世界/行为.md#entityuseitemtopos)(服务端)，模拟实体对某个坐标使用指定物品。
+
+1. 新增[UseItemToEntity](../接口/世界/行为.md#useitemtoentity)(服务端)，模拟对某个实体使用物品。
+
+1. 新增[CreatePxActor](../接口/物理.md#createpxactor)(服务端)，给实体创建自定义刚体
+
+1. 新增[AddBoxGeometry](../接口/物理.md#addboxgeometry)(服务端)，给自定义刚体创建盒形碰撞体
+
+1. 新增[SetRigidBodyFlag](../接口/物理.md#setrigidbodyflag)(服务端)，设置自定义刚体的行为
+
+1. 新增[SetRigidDynamicLockFlags](../接口/物理.md#setrigiddynamiclockflags)(服务端)，设置自定义刚体的约束
+
+1. 新增[SetActorFlag](../接口/物理.md#setactorflag)(服务端)，设置物理实体的行为开关
+
+1. 新增[SetKinematicTarget](../接口/物理.md#setkinematictarget)(服务端)，设置运动学刚体的目标变换
+
+1. 新增[SetGlobalPose](../接口/物理.md#setglobalpose)(服务端)，设置自定义刚体的变换（直接瞬移）
+
+1. 新增[AddForce](../接口/物理.md#addforce)(服务端)，给自定义刚体添加力
+
+1. 新增[GetQuaternion](../接口/物理.md#getquaternion)(服务端)，获取自定义刚体的四元数旋转
+
+1. 新增[Raycast](../接口/物理.md#raycast)(服务端)，射线检测
+
+1. 新增[GetRecipeByRecipeId](../接口/世界/方块管理.md#getrecipebyrecipeid)(服务端)，根据配方id查询配方内容。
+
+1. 新增[GetEntitiesAroundForClientEntity](../接口/实体/属性.md#getentitiesaroundforcliententity)(客户端)，获取区域内的客户端实体列表
+
+1. 新增[GetEntitiesInSquareAreaForClientEntity](../接口/实体/属性.md#getentitiesinsquareareaforcliententity)(客户端)，获取区域内的客户端实体列表
+
+1. 新增[GetQuaternion](../接口/物理.md#getquaternion)(客户端)，获取自定义刚体的四元数旋转
+
+1. 新增[Raycast](../接口/物理.md#raycast)(客户端)，射线检测
+
+1. 新增[GetKeyMappings](../接口/游戏设置.md#getkeymappings)(客户端)，获取指定的自定义按键映射配置
+
+1. 新增[RegisterCustomKeyMapping](../接口/游戏设置.md#registercustomkeymapping)(客户端)，注册自定义按键映射
+
+1. 新增[GetGamepadKeyMappings](../接口/游戏设置.md#getgamepadkeymappings)(客户端)，获取自定义手柄按键映射
+
+1. 新增[RegisterCustomGamepadMapping](../接口/游戏设置.md#registercustomgamepadmapping)(客户端)，注册自定义手柄按键映射
+
+1. 新增[SetPosForClientEntity](../接口/实体/属性.md#setposforcliententity)(客户端)，设置客户端实体位置。
+
+1. 新增[GetRecipeByRecipeId](../接口/世界/方块管理.md#getrecipebyrecipeid)(客户端)，根据配方id查询配方内容。
+
+1. 新增[SetRotForClientEntity](../接口/实体/属性.md#setrotforcliententity)(客户端)，设置客户端实体头与水平方向的俯仰角度和竖直方向的旋转角度。
+
+1. 新增[PhysxTouchServerEvent](../事件/物理.md#physxtouchserverevent)(服务端)，给自定义刚体添加的碰撞体，与其他碰撞体或原版生物发生碰撞/结束碰撞时触发
+
+1. 新增[OnCustomKeyPressInGame](../事件/游戏设置.md#oncustomkeypressingame)(客户端)，当玩家按下自定义按键时触发
+
+1. 新增[OnCustomKeyChangedEvent](../事件/游戏设置.md#oncustomkeychangedevent)(客户端)，当自定义按键绑定发生改变时触发
+
+1. 新增[OnCustomGamepadPressInGame](../事件/游戏设置.md#oncustomgamepadpressingame)(客户端)，当玩家按下自定义手柄按键时触发
+
+1. 新增[OnCustomGamepadChangedEvent](../事件/游戏设置.md#oncustomgamepadchangedevent)(客户端)，当自定义手柄按键绑定发生改变时触发
+
+1. 新增[PhysxTouchClientEvent](../事件/物理.md#physxtouchclientevent)(客户端)，给自定义刚体添加的碰撞体，与其他碰撞体或原版生物发生碰撞/结束碰撞时触发
+
+1. 新增[ActorDamageCause](../枚举值/ActorDamageCause.md)，新增MaceSmash类型
+
+1. 新增[BiomeType](../枚举值/BiomeType.md)，新增pale_garden(苍白花园)类型
+
+1. 新增[EntityType](../枚举值/EntityType.md)，新增Creaking(嘎枝)类型
+
+1. 新增[OpenContainerId](../枚举值/OpenContainerId.md)，新增DynamicContainer类型
+
+1. 新增[PxActorFlag](../枚举值/PxActorFlag.md)，物理实体行为枚举
+
+1. 新增[PxEventMask](../枚举值/PxEventMask.md)，碰撞事件枚举
+
+1. 新增[PxForceMode](../枚举值/PxForceMode.md)，添加力的模式
+
+1. 新增[PxRigidBodyFlag](../枚举值/PxRigidBodyFlag.md)，自定义刚体行为枚举
+
+1. 新增[PxRigidDynamicLockFlag](../枚举值/PxRigidDynamicLockFlag.md)，自定义刚体约束枚举
+
+1. 新增[RenderLayer](../枚举值/RenderLayer.md)，补充原版发光方块渲染时的材质类型
+
+- 调整
+
+1. 调整[AddEffectToEntity](../接口/实体/状态效果.md#addeffecttoentity)(服务端)，持续时间支持浮点型
+
+1. 调整[CanSee](../接口/实体/属性.md#cansee)(服务端)，增加angleX、angleY的描述
+
+1. 调整[SetGameDifficulty](../接口/世界/行为.md#setgamedifficulty)(服务端)，极限模式不可修改游戏难度
+
+1. 调整[SetDefaultGameType](../接口/世界/行为.md#setdefaultgametype)(服务端)，极限模式不可修改默认游戏模式
+
+1. 调整[SetGameRulesInfoServer](../接口/世界/游戏规则.md#setgamerulesinfoserver)(服务端)，极限模式不可修改cheat_info部分的游戏规则
+
+1. 调整[UseItemAttackEntity](../接口/世界/行为.md#useitemattackentity)(服务端)，增加damageFormula参数，可传入计算公式来修改伤害值。
+
+1. 调整[SetPlayerGameType](../接口/玩家/游戏模式.md#setplayergametype)(服务端)，极限模式不可修改玩家个人游戏模式
+
+1. 调整GetNotRenderAtAll(客户端)，新增支持CreateClientEntityByTypeStr创建的客户端实体。
+
+1. 调整SetNotRenderAtAll(客户端)，新增支持CreateClientEntityByTypeStr创建的客户端实体。
+
+1. 调整ResetActorRender(客户端)，新增支持CreateClientEntityByTypeStr创建的客户端实体。
+
+1. 调整多个客户端渲染、模型、材质、动画相关接口，新增支持CreateClientEntityByTypeStr创建的客户端实体。详见官方文档。
+
+1. 调整[ItemPushInCustomContainerServerEvent](../事件/方块.md#itempushincustomcontainerserverevent)(服务端)，增加容器方块所在维度的参数
+
+1. 调整[ItemPullOutCustomContainerServerEvent](../事件/方块.md#itempulloutcustomcontainerserverevent)(服务端)，增加容器方块所在维度的参数
+
+- 废弃（将在未来不可用）
+
+1. 废弃OpenVoiceGui，语言转文字功能已移除
--- a/docs/mcdocs/1-ModAPI/枚举值/PxActorFlag.md
+++ b/docs/mcdocs/1-ModAPI/枚举值/PxActorFlag.md
@@ -0,0 +1,18 @@
+# PxActorFlag
+
+class in mod.common.minecraftEnum
+
+- 描述
+
+    物理实体行为枚举
+
+
+
+```python
+class PxActorFlag(object):
+	eDISABLE_GRAVITY = (1 << 1)     # 禁用重力
+	eDISABLE_SIMULATION = (1 << 3)  # 禁用物理模拟
+
+``` 
+
+
--- a/docs/mcdocs/1-ModAPI/枚举值/PxEventMask.md
+++ b/docs/mcdocs/1-ModAPI/枚举值/PxEventMask.md
@@ -0,0 +1,22 @@
+# PxEventMask
+
+class in mod.common.minecraftEnum
+
+- 描述
+
+    碰撞事件枚举
+
+
+
+```python
+class PxEventMask(object):
+	Null = 0x0          # 不需要碰撞事件。若不为Null，则Found或Lost必须有一个，Server或Client必须有一个
+	Found = 0x1         # 需要接触开始事件
+	Found_Detail = 0x2  # 接触开始事件需要附带碰撞点与法线信息。性能消耗较大。
+	Lost = 0x4          # 需要接触结束事件
+	Server = 0x8        # 需要服务器事件
+	Client = 0x10       # 需要客户端事件
+
+``` 
+
+
--- a/docs/mcdocs/1-ModAPI/枚举值/PxForceMode.md
+++ b/docs/mcdocs/1-ModAPI/枚举值/PxForceMode.md
@@ -0,0 +1,20 @@
+# PxForceMode
+
+class in mod.common.minecraftEnum
+
+- 描述
+
+    添加力的模式
+
+
+
+```python
+class PxForceMode(object):
+	eFORCE = 0              # 力，单位为质量 × 距离 / 时间²
+	eIMPULSE = 1            # 冲量，单位为质量 × 距离 / 时间
+	eVELOCITY_CHANGE = 2    # 速度变化，单位为距离 / 时间，直接改变速度，与质量无关
+	eACCELERATION = 3       # 加速度，单位为距离 / 时间²，直接施加加速度，与质量无关
+
+``` 
+
+
--- a/docs/mcdocs/1-ModAPI/枚举值/PxRigidBodyFlag.md
+++ b/docs/mcdocs/1-ModAPI/枚举值/PxRigidBodyFlag.md
@@ -0,0 +1,17 @@
+# PxRigidBodyFlag
+
+class in mod.common.minecraftEnum
+
+- 描述
+
+    自定义刚体行为枚举
+
+
+
+```python
+class PxRigidBodyFlag(object):
+	eKINEMATIC = (1 << 0)   # 设置刚体的运动学模式。运动学刚体不受力的影响，使用setKinematicTarget控制移动
+
+``` 
+
+
--- a/docs/mcdocs/1-ModAPI/枚举值/PxRigidDynamicLockFlag.md
+++ b/docs/mcdocs/1-ModAPI/枚举值/PxRigidDynamicLockFlag.md
@@ -0,0 +1,22 @@
+# PxRigidDynamicLockFlag
+
+class in mod.common.minecraftEnum
+
+- 描述
+
+    自定义刚体约束枚举
+
+
+
+```python
+class PxRigidDynamicLockFlag(object):
+	eLOCK_LINEAR_X = (1 << 0)   # 锁定x轴平移
+	eLOCK_LINEAR_Y = (1 << 1)   # 锁定y轴平移
+	eLOCK_LINEAR_Z = (1 << 2)   # 锁定z轴平移
+	eLOCK_ANGULAR_X = (1 << 3)  # 锁定x轴旋转
+	eLOCK_ANGULAR_Y = (1 << 4)  # 锁定y轴旋转
+	eLOCK_ANGULAR_Z = (1 << 5)  # 锁定z轴旋转
+
+``` 
+
+
--- a/docs/mcdocs/1-ModAPI/枚举值/索引.md
+++ b/docs/mcdocs/1-ModAPI/枚举值/索引.md
@@ -56,6 +56,11 @@
 | [PlayerActionType](../枚举值/PlayerActionType.md) | 玩家动作枚举 |
 | [PlayerExhauseRatioType](../枚举值/PlayerExhauseRatioType.md) | 饥饿度消耗倍率类型 |
 | [PlayerUISlot](../枚举值/PlayerUISlot.md) | 开放容器对应的slot偏移 |
+| [PxActorFlag](../枚举值/PxActorFlag.md) | 物理实体行为枚举 |
+| [PxEventMask](../枚举值/PxEventMask.md) | 碰撞事件枚举 |
+| [PxForceMode](../枚举值/PxForceMode.md) | 添加力的模式 |
+| [PxRigidBodyFlag](../枚举值/PxRigidBodyFlag.md) | 自定义刚体行为枚举 |
+| [PxRigidDynamicLockFlag](../枚举值/PxRigidDynamicLockFlag.md) | 自定义刚体约束枚举 |
 | [RayFilterType](../枚举值/RayFilterType.md) | 射线检测类型 |
 | [RedstoneModeType](../枚举值/RedstoneModeType.md) | 命令方块红石类型 |
 | [RenderControllerArrayType](../枚举值/RenderControllerArrayType.md) | 渲染控制器字典中材质、贴图、模型的枚举值 |
--- a/docs/mcguide/20-玩法开发/13-模组SDK编程/2-Python脚本开发/103-3.7版本物品id变更.md
+++ b/docs/mcguide/20-玩法开发/13-模组SDK编程/2-Python脚本开发/103-3.7版本物品id变更.md
@@ -0,0 +1,257 @@
+# 3.7版本物品id变更
+
+## 简介
+
+微软在1.21.50继续修改了部分方块ID，取消了附加值，相关链接请参阅[基岩版扁平化](https://zh.minecraft.wiki/w/%E5%AE%98%E6%96%B9%E9%A1%B5%E9%9D%A2/%E5%9F%BA%E5%B2%A9%E7%89%88%E6%89%81%E5%B9%B3%E5%8C%96)，请开发者注意适配。
+
+## 处理方法
+
+在ModSDK的接口与事件中，我们针对上述情况做了以下处理：
+
+1. 对于返回物品信息字典的接口与事件：
+
+ newItemName及newAuxValue返回新版名称与附加值。
+
+ 原字段itemName及auxValue返回旧版名称与附加值。
+
+2. 对于接受物品信息字典的接口与事件：
+
+ 当字典存在newItemName及newAuxValue时，使用这两个字段。
+
+ 不存在时，使用旧字段itemName及auxValue。
+
+## 注意事项
+
+* 通过附加值获取获取方块状态接口没有做兼容，例如GetBlockAuxValueFromStates、GetBlockStatesFromAuxValue、GetBlockStates、SetBlockStates，如果您的组件对此有依赖，则需要对这次的改动自行做兼容处理。
+
+* **开发完成或正在开发的组件，建议统一采用newItemName及newAuxValue字段，也不要新旧字段混用。**
+
+* 某些写法可能会失效，例如
+
+  ```python
+  # 获取itemDict，然后在他基础上修改itemName或auxValue后再用来生成
+  itemdict = GetPlayerItem()
+  itemdict['itemName'] = 'xxx'
+  itemdict['auxValue'] = itemdict['auxValue']+1
+  SpawnItemToPlayerInv(itemdict)
+  ```
+
+  因为GetPlayerItem返回的itemDict含有新字段，再传入SpawnItemToPlayerInv时，会读取新字段生成物品，因此对原字段的修改无效。
+
+## 版本变更方块数据
+
+以下为3.7版本变更了id、名称等的物品列表，表格内的名称省略了minecraft命名空间。
+
+### 统计信息
+
+- 变更项数量: 89
+- 仅名称变更: 12
+- 新增项数量: 69
+- 移除项数量: 17
+
+### 变更项
+
+| 新中文名 | 旧中文名 | 旧命名 | 旧附加值 | 新命名 | 新附加值 |
+| --- | --- | --- | --- | --- | --- |
+| 蒲公英 | 蒲公英 | yellow_flower | 0 | dandelion | 0 |
+| 虫蚀石头 | 虫蚀石头 | monster_egg | 0 | infested_stone | 0 |
+| 石砖 | 石砖 | stonebrick | 0 | stone_bricks | 0 |
+| 蘑菇柄 | 蘑菇柄 | brown_mushroom_block | 15 | mushroom_stem | 0 |
+| 双红砂岩台阶 | 红砂岩双层台阶 | double_stone_block_slab2 | 0 | red_sandstone_double_slab | 0 |
+| 红砂岩台阶 | 红砂岩台阶 | stone_block_slab2 | 0 | red_sandstone_slab | 0 |
+| 末地石砖台阶 | 末地石砖台阶 | stone_block_slab3 | 0 | end_stone_brick_slab | 0 |
+| 苔石砖台阶 | 苔石砖台阶 | stone_block_slab4 | 0 | mossy_stone_brick_slab | 0 |
+| 光源方块-亮度0 | 光源方块 | light_block | 0 | light_block_0 | 0 |
+| 虫蚀圆石 | 虫蚀圆石 | monster_egg | 1 | infested_cobblestone | 0 |
+| 虫蚀石砖 | 虫蚀石砖 | monster_egg | 2 | infested_stone_bricks | 0 |
+| 虫蚀苔石砖 | 虫蚀苔石砖 | monster_egg | 3 | infested_mossy_stone_bricks | 0 |
+| 虫蚀裂纹石砖 | 虫蚀裂纹石砖 | monster_egg | 4 | infested_cracked_stone_bricks | 0 |
+| 虫蚀雕纹石砖 | 虫蚀雕纹石砖 | monster_egg | 5 | infested_chiseled_stone_bricks | 0 |
+| 苔石砖 | 苔石砖 | stonebrick | 1 | mossy_stone_bricks | 0 |
+| 裂纹石砖 | 裂纹石砖 | stonebrick | 2 | cracked_stone_bricks | 0 |
+| 雕纹石砖 | 雕纹石砖 | stonebrick | 3 | chiseled_stone_bricks | 0 |
+| 双砂岩台阶 | 砂岩双层台阶 | double_stone_block_slab | 1 | sandstone_double_slab | 0 |
+| 双圆石台阶 | 圆石双层台阶 | double_stone_block_slab | 3 | cobblestone_double_slab | 0 |
+| 双红砖台阶 | 红砖双层台阶 | double_stone_block_slab | 4 | brick_double_slab | 0 |
+| 双石砖台阶 | 石砖双层台阶 | double_stone_block_slab | 5 | stone_brick_double_slab | 0 |
+| 双石英台阶 | 石英双层台阶 | double_stone_block_slab | 6 | quartz_double_slab | 0 |
+| 双下界砖台阶 | 下界砖双层台阶 | double_stone_block_slab | 7 | nether_brick_double_slab | 0 |
+| 紫珀台阶 | 紫珀台阶 | stone_block_slab2 | 1 | purpur_slab | 0 |
+| 海晶石台阶 | 海晶石台阶 | stone_block_slab2 | 2 | prismarine_slab | 0 |
+| 暗海晶石台阶 | 暗海晶石台阶 | stone_block_slab2 | 3 | dark_prismarine_slab | 0 |
+| 海晶石砖台阶 | 海晶石砖台阶 | stone_block_slab2 | 4 | prismarine_brick_slab | 0 |
+| 苔石台阶 | 苔石台阶 | stone_block_slab2 | 5 | mossy_cobblestone_slab | 0 |
+| 平滑砂岩台阶 | 平滑砂岩台阶 | stone_block_slab2 | 6 | smooth_sandstone_slab | 0 |
+| 红色下界砖台阶 | 红色下界砖台阶 | stone_block_slab2 | 7 | red_nether_brick_slab | 0 |
+| 平滑红砂岩台阶 | 平滑红砂岩台阶 | stone_block_slab3 | 1 | smooth_red_sandstone_slab | 0 |
+| 磨制安山岩台阶 | 磨制安山岩台阶 | stone_block_slab3 | 2 | polished_andesite_slab | 0 |
+| 安山岩台阶 | 安山岩台阶 | stone_block_slab3 | 3 | andesite_slab | 0 |
+| 闪长岩台阶 | 闪长岩台阶 | stone_block_slab3 | 4 | diorite_slab | 0 |
+| 磨制闪长岩台阶 | 磨制闪长岩台阶 | stone_block_slab3 | 5 | polished_diorite_slab | 0 |
+| 花岗岩台阶 | 花岗岩台阶 | stone_block_slab3 | 6 | granite_slab | 0 |
+| 磨制花岗岩台阶 | 磨制花岗岩台阶 | stone_block_slab3 | 7 | polished_granite_slab | 0 |
+| 平滑石英台阶 | 平滑石英台阶 | stone_block_slab4 | 1 | smooth_quartz_slab | 0 |
+| 石头台阶 | 石头台阶 | stone_block_slab4 | 2 | normal_stone_slab | 0 |
+| 切制砂岩台阶 | 切制砂岩台阶 | stone_block_slab4 | 3 | cut_sandstone_slab | 0 |
+| 切制红砂岩台阶 | 切制红砂岩台阶 | stone_block_slab4 | 4 | cut_red_sandstone_slab | 0 |
+| 双石化橡木台阶 | 石化橡木双层台阶 | double_stone_block_slab | 2 | petrified_oak_double_slab | 0 |
+| 双紫珀台阶 | 双紫珀台阶 | double_stone_block_slab2 | 1 | purpur_double_slab | 0 |
+| 双海晶石台阶 | 双海晶石台阶 | double_stone_block_slab2 | 2 | prismarine_double_slab | 0 |
+| 双暗海晶石台阶 | 双暗海晶石台阶 | double_stone_block_slab2 | 3 | dark_prismarine_double_slab | 0 |
+| 双海晶石砖台阶 | 双海晶石砖台阶 | double_stone_block_slab2 | 4 | prismarine_brick_double_slab | 0 |
+| 双苔石台阶 | 双苔石台阶 | double_stone_block_slab2 | 5 | mossy_cobblestone_double_slab | 0 |
+| 双平滑砂岩台阶 | 双平滑砂岩台阶 | double_stone_block_slab2 | 6 | smooth_sandstone_double_slab | 0 |
+| 双红色下界砖台阶 | 双红色下界砖台阶 | double_stone_block_slab2 | 7 | red_nether_brick_double_slab | 0 |
+| 双平滑红砂岩台阶 | 双平滑红砂岩台阶 | double_stone_block_slab3 | 1 | smooth_red_sandstone_double_slab | 0 |
+| 双磨制安山岩台阶 | 双磨制安山岩台阶 | double_stone_block_slab3 | 2 | polished_andesite_double_slab | 0 |
+| 双安山岩台阶 | 双安山岩台阶 | double_stone_block_slab3 | 3 | andesite_double_slab | 0 |
+| 双闪长岩台阶 | 双闪长岩台阶 | double_stone_block_slab3 | 4 | diorite_double_slab | 0 |
+| 双磨制闪长岩台阶 | 双磨制闪长岩台阶 | double_stone_block_slab3 | 5 | polished_diorite_double_slab | 0 |
+| 双花岗岩台阶 | 双花岗岩台阶 | double_stone_block_slab3 | 6 | granite_double_slab | 0 |
+| 双磨制花岗岩台阶 | 双磨制花岗岩台阶 | double_stone_block_slab3 | 7 | polished_granite_double_slab | 0 |
+| 双平滑石英台阶 | 双平滑石英台阶 | double_stone_block_slab4 | 1 | smooth_quartz_double_slab | 0 |
+| 双石台阶 | 双石台阶 | double_stone_block_slab4 | 2 | normal_stone_double_slab | 0 |
+| 双切制砂岩台阶 | 双切制砂岩台阶 | double_stone_block_slab4 | 3 | cut_sandstone_double_slab | 0 |
+| 双切制红砂岩台阶 | 双切制红砂岩台阶 | double_stone_block_slab4 | 4 | cut_red_sandstone_double_slab | 0 |
+| 雕纹砂岩 | 雕纹砂岩 | sandstone | 1 | chiseled_sandstone | 0 |
+| 切制砂岩 | 切制砂岩 | sandstone | 2 | cut_sandstone | 0 |
+| 平滑砂岩 | 平滑砂岩 | sandstone | 3 | smooth_sandstone | 0 |
+| 暗海晶石 | 暗海晶石 | prismarine | 1 | dark_prismarine | 0 |
+| 海晶石砖 | 海晶石砖 | prismarine | 2 | prismarine_bricks | 0 |
+| 红沙 | 红沙 | sand | 1 | red_sand | 0 |
+| 雕纹石英块 | 雕纹石英块 | quartz_block | 1 | chiseled_quartz_block | 0 |
+| 石英柱 | 石英柱 | quartz_block | 2 | quartz_pillar | 0 |
+| 平滑石英块 | 平滑石英块 | quartz_block | 3 | smooth_quartz | 0 |
+| 雕纹红砂岩 | 雕纹红砂岩 | red_sandstone | 1 | chiseled_red_sandstone | 0 |
+| 切制红砂岩 | 切制红砂岩 | red_sandstone | 2 | cut_red_sandstone | 0 |
+| 平滑红砂岩 | 平滑红砂岩 | red_sandstone | 3 | smooth_red_sandstone | 0 |
+| 开裂的铁砧 | 开裂的铁砧 | anvil | 4 | chipped_anvil | 0 |
+| 损坏的铁砧 | 损坏的铁砧 | anvil | 8 | damaged_anvil | 0 |
+| 砂土 | 砂土 | dirt | 1 | coarse_dirt | 0 |
+| 苔石墙 | 苔石墙 | cobblestone_wall | 1 | mossy_cobblestone_wall | 0 |
+| 花岗岩墙 | 花岗岩墙 | cobblestone_wall | 2 | granite_wall | 0 |
+| 闪长岩墙 | 闪长岩墙 | cobblestone_wall | 3 | diorite_wall | 0 |
+| 安山岩墙 | 安山岩墙 | cobblestone_wall | 4 | andesite_wall | 0 |
+| 砂岩墙 | 砂岩墙 | cobblestone_wall | 5 | sandstone_wall | 0 |
+| 红砖墙 | 红砖墙 | cobblestone_wall | 6 | brick_wall | 0 |
+| 石砖墙 | 石砖墙 | cobblestone_wall | 7 | stone_brick_wall | 0 |
+| 苔石砖墙 | 苔石砖墙 | cobblestone_wall | 8 | mossy_stone_brick_wall | 0 |
+| 下界砖墙 | 下界砖墙 | cobblestone_wall | 9 | nether_brick_wall | 0 |
+| 末地石砖墙 | 末地石砖墙 | cobblestone_wall | 10 | end_stone_brick_wall | 0 |
+| 海晶石墙 | 海晶石墙 | cobblestone_wall | 11 | prismarine_wall | 0 |
+| 红砂岩墙 | 红砂岩墙 | cobblestone_wall | 12 | red_sandstone_wall | 0 |
+| 红色下界砖墙 | 红色下界砖墙 | cobblestone_wall | 13 | red_nether_brick_wall | 0 |
+| 湿海绵 | 湿海绵 | sponge | 1 | wet_sponge | 0 |
+
+### 仅名称变更（内容不变）
+
+| 新中文名 | 旧中文名 | 英文命名 | 附加值 |
+| --- | --- | --- | --- |
+| 橡木门 | 木门 | wooden_door | 0 |
+| 双绯红木台阶 | 绯红木双层台阶 | crimson_double_slab | 0 |
+| 双诡异木台阶 | 诡异木双层台阶 | warped_double_slab | 0 |
+| 双深板岩圆石台阶 | 深板岩圆石双层台阶 | cobbled_deepslate_double_slab | 0 |
+| 双磨制深板岩台阶 | 磨制深板岩双层台阶 | polished_deepslate_double_slab | 0 |
+| 双深板岩瓦台阶 | 深板岩瓦双层台阶 | deepslate_tile_double_slab | 0 |
+| 双深板岩砖台阶 | 深板岩砖双层台阶 | deepslate_brick_double_slab | 0 |
+| 悬挂式云杉木告示牌 | 云杉木悬挂告示牌 | spruce_hanging_sign | 0 |
+| 悬挂式白桦木告示牌 | 白桦木悬挂告示牌 | birch_hanging_sign | 0 |
+| 悬挂式金合欢木告示牌 | 金合欢木悬挂告示牌 | acacia_hanging_sign | 0 |
+| 悬挂式深色橡木告示牌 | 深色橡木悬挂告示牌 | dark_oak_hanging_sign | 0 |
+| 双樱花木台阶 | 樱花木双层台阶 | cherry_double_slab | 0 |
+
+### 新增项
+
+| 中文名称 | 英文命名 | 附加值 |
+| --- | --- | --- |
+| 双平滑石头台阶 | smooth_stone_double_slab | 0 |
+| 下界砖 | nether_brick | 0 |
+| 骷髅模型 | skeleton_skull | 0 |
+| 潜声感测器 | sculk_sensor | 0 |
+| 荧光物品展示框 | glow_frame | 0 |
+| 潜声 | sculk | 0 |
+| 红树木门 | mangrove_door | 0 |
+| 红树木告示牌 | mangrove_standing_sign | 0 |
+| 双红树木台阶 | mangrove_double_slab | 0 |
+| 悬挂式橡木告示牌 | oak_hanging_sign | 0 |
+| 悬挂式丛林木告示牌 | jungle_hanging_sign | 0 |
+| 悬挂式绯红木告示牌 | crimson_hanging_sign | 0 |
+| 悬挂式诡异木告示牌 | warped_hanging_sign | 0 |
+| 悬挂式红树木告示牌 | mangrove_hanging_sign | 0 |
+| 悬挂式竹告示牌 | bamboo_hanging_sign | 0 |
+| 悬挂式樱花木告示牌 | cherry_hanging_sign | 0 |
+| 光源方块-亮度1 | light_block_1 | 0 |
+| 光源方块-亮度2 | light_block_2 | 0 |
+| 光源方块-亮度3 | light_block_3 | 0 |
+| 光源方块-亮度4 | light_block_4 | 0 |
+| 光源方块-亮度5 | light_block_5 | 0 |
+| 光源方块-亮度6 | light_block_6 | 0 |
+| 光源方块-亮度7 | light_block_7 | 0 |
+| 光源方块-亮度8 | light_block_8 | 0 |
+| 光源方块-亮度9 | light_block_9 | 0 |
+| 光源方块-亮度10 | light_block_10 | 0 |
+| 光源方块-亮度11 | light_block_11 | 0 |
+| 光源方块-亮度12 | light_block_12 | 0 |
+| 光源方块-亮度13 | light_block_13 | 0 |
+| 光源方块-亮度14 | light_block_14 | 0 |
+| 光源方块-亮度15 | light_block_15 | 0 |
+| 紫珀柱 | purpur_pillar | 0 |
+| 凋灵骷髅模型 | wither_skeleton_skull | 0 |
+| 僵尸模型 | zombie_head | 0 |
+| 模型 | player_head | 0 |
+| 苦力怕模型 | creeper_head | 0 |
+| 龙的模型 | dragon_head | 0 |
+| 猪灵模型 | piglin_head | 0 |
+| 苍白橡木按钮 | pale_oak_button | 0 |
+| 苍白橡木门 | pale_oak_door | 0 |
+| 苍白橡木栅栏 | pale_oak_fence | 0 |
+| 苍白橡木栅栏大门 | pale_oak_fence_gate | 0 |
+| 苍白橡木悬挂告示牌 | pale_oak_hanging_sign | 0 |
+| 去皮苍白橡树原木 | stripped_pale_oak_log | 0 |
+| 苍白橡树原木 | pale_oak_log | 0 |
+| 苍白橡木木板 | pale_oak_planks | 0 |
+| 苍白橡木压力板 | pale_oak_pressure_plate | 0 |
+| 苍白橡木台阶 | pale_oak_slab | 0 |
+| 苍白橡木双台阶 | pale_oak_double_slab | 0 |
+| 苍白橡木楼梯 | pale_oak_stairs | 0 |
+| 苍白橡木活板门 | pale_oak_trapdoor | 0 |
+| 去皮苍白橡木 | stripped_pale_oak_wood | 0 |
+| 苍白橡木 | pale_oak_wood | 0 |
+| 苍白橡木树苗 | pale_oak_sapling | 0 |
+| 苍白橡木树叶 | pale_oak_leaves | 0 |
+| 苍白苔藓块 | pale_moss_block | 0 |
+| 苍白苔藓地毯 | pale_moss_carpet | 0 |
+| 苍白垂须 | pale_hanging_moss | 0 |
+| 嘎枝之心 | creaking_heart | 0 |
+| 树脂砖块 | resin_bricks | 0 |
+| 树脂砖台阶 | resin_brick_slab | 0 |
+| 双树脂砖台阶 | resin_brick_double_slab | 0 |
+| 树脂砖楼梯 | resin_brick_stairs | 0 |
+| 树脂砖墙 | resin_brick_wall | 0 |
+| 张开的眼眸花 | open_eyeblossom | 0 |
+| 闭合的眼眸花 | closed_eyeblossom | 0 |
+| 雕纹树脂砖块 | chiseled_resin_bricks | 0 |
+| 树脂块 | resin_block | 0 |
+| 树脂团 | resin_clump | 0 |
+
+### 移除项
+
+| 中文名称 | 英文命名 | 附加值 |
+| --- | --- | --- |
+| 石头双层台阶 | double_stone_block_slab | 0 |
+| 蘑菇 | brown_mushroom_block | 0 |
+| 下界砖块 | nether_brick | 0 |
+| 生物头颅 | skull | 0 |
+| 紫珀柱子 | purpur_block | 2 |
+| 幽匿感测体 | sculk_sensor | 0 |
+| 幽匿块 | sculk | 0 |
+| 红树林门 | mangrove_door | 0 |
+| 红树林告示牌 | mangrove_standing_sign | 0 |
+| 双红树林台阶 | mangrove_double_slab | 0 |
+| 橡树悬挂告示牌 | oak_hanging_sign | 0 |
+| 丛林悬挂告示牌 | jungle_hanging_sign | 0 |
+| 绯红悬挂告示牌 | crimson_hanging_sign | 0 |
+| 翘曲悬挂告示牌 | warped_hanging_sign | 0 |
+| 红树林悬挂告示牌 | mangrove_hanging_sign | 0 |
+| 竹制悬挂告示牌 | bamboo_hanging_sign | 0 |
+| 樱花悬挂告示牌 | cherry_hanging_sign | 0 |
--- a/docs/mcguide/20-玩法开发/20-物理玩法开发/1-物理的使用指南.md
+++ b/docs/mcguide/20-玩法开发/20-物理玩法开发/1-物理的使用指南.md
@@ -0,0 +1,258 @@
+# 物理的使用指南
+
+## 使用准则与免责声明
+
+### 使用准则
+
+- 仅限第三方用户生成内容（UGC）使用
+- 只有创作者创建的自定义实体才能与物理刚体绑定，原版实体无法与PhysX创建的刚体绑定
+- 物理身件可以与其他游戏物件（包括原生游戏物件）产生互动，但是原生游戏物件与其他原生游戏物件之间的互动方式及物理碰撞不会被改变
+- 当两个碰撞同时发生时，核心游戏的物理引擎具有最高优先级
+
+只有满足上述条件，您的模组才能符合要求进行上架
+
+### 免责声明
+
+物理相关api与特性，可能会在将来调整并且不向前兼容。请随时做好调整的准备
+
+但是，每次调整都会做出充分的预告和调整内容公告，方便你对您的模组进行最新内容的兼容。
+
+## 准备工作
+
+由于我们的物理引擎是用的 NVIDIA PhysX，您可以先前往NVIDIA官网下载PhysX Visual Debugger，方便后续调试。
+
+[https://developer.nvidia.com/physx-visual-debugger](https://developer.nvidia.com/physx-visual-debugger)
+
+![img.png](./picture/physx/img_2.png)
+
+## 全局配置
+
+在使用物理引擎之前，您需要在模组的 behavior_packs 行为包中新增 physx_setting.json 全局配置文件
+
+![img.png](./picture/physx/img.png)
+
+文件里面需要设置成
+
+```json
+{
+    "enable": true
+}
+```
+
+保存后，您的模组可以正常使用 PhysX 物理引擎了。
+
+## 开始创作
+
+现在我会通过demo，来向你介绍physx能做的内容
+
+### 创建自定义刚体
+
+使用物理内容的之前，您首先需要创建一个新的物理刚体，物理刚体**必须**绑定在`自定义实体`上，且创建刚体的方法只能在 `AddEntityServerEvent` 事件中使用
+
+```python
+# 创建一个自定义刚体
+comp = serverApi.GetEngineCompFactory().CreatePhysx(entityId)
+comp.CreatePxActor()
+```
+
+现在你已经为这个 entityId 的实体添加了一个物理刚体
+
+> 注意： 刚体创建数量不得大于 8192， 虽然Physx限制是31767，但是我们需要预留一些刚体阈值给到其他实体和客户端内容
+
+> 注意：必须要在 AddEntityServerEvent 事件中创建刚体，否则会报错
+
+> 注意：实体必须绑定在 自定义实体上，不得绑定在原版实体上
+
+### 添加包围盒
+
+目前这个刚体暂时没有任何功能和属性，为了让它能够正常工作，我们需要给刚体添加一些属性
+
+首先需要添加包围盒，包围盒是刚体的基本属性，你只有添加了包围盒，才能让刚体与世界实体进行交互
+
+添加包围盒的方法是 AddBoxGeometry ，参数方法如下
+
+```python
+# localTransform	tuple(float,float,float)	盒子中心相对实体原点的偏移
+# halfX	float	表示盒子长度的一半
+# halfY	float	表示盒子高度的一半
+# halfZ	float	表示盒子宽度的一半
+# staticFriction	float	静摩擦系数
+# dynamicFriction	float	动摩擦系数，默认为e 注意：此摩擦力设置为0，并不代表刚体与原生游戏交互也是 0 摩擦力
+# restitution	float	弹性恢复系数，默认为0
+# eventMask	int	PxEventMask枚举，用于监听碰撞事件，默认为PxRigidBodyFlag.Null，即不需要碰撞事件
+# userData	None或str	可记录自定义数据，长度不超过20，默认为None
+comp.AddBoxGeometry((0, 0.9, 0), 0.3, 0.9, 0.3, 0.05, 0.05, 0, PxEventMask.Server | PxEventMask.Found, None)
+```
+
+PxEventMask 枚举目前有六个
+
+- PxEventMask.Server   服务端事件
+- PxEventMask.Client   客户端事件
+- PxEventMask.Lost   结束碰撞事件
+- PxEventMask.Found   开始碰撞事件
+- PxEventMask.Found_Detail    碰撞事件的详细信息
+- PxEventMask.Null   该刚体不附加任何事件
+
+此时你已经成功为你的刚体创建好了包围盒
+
+当你启动游戏时，如果你此时提前打开了 PhysX Visual Debugger，那么刚体的包围盒就会显示出来了
+
+![img.png](./picture/physx/img_3.png)
+
+红色代表世界的原生方块、绿色和黄色代表刚体的包围盒
+
+![img.png](./picture/physx/img_4.png)
+
+### 添加约束和运动
+
+如果你想给刚体添加一些约束，比如刚体的运动锁定某个轴体，您需要添加动态约束
+
+```python
+# 下面的方法是规定此刚体只会沿着 X Y Z 轴运动
+comp.SetRigidDynamicLockFlags(PxRigidDynamicLockFlag.eLOCK_ANGULAR_X | PxRigidDynamicLockFlag.eLOCK_ANGULAR_Y | PxRigidDynamicLockFlag.eLOCK_ANGULAR_Z)
+```
+
+PxRigidDynamicLockFlag 枚举目前有六个
+
+- PxRigidDynamicLockFlag.eLOCK_ANGULAR_X  锁定沿着 X 轴运动
+- PxRigidDynamicLockFlag.eLOCK_ANGULAR_Y   锁定沿着 Y 轴运动
+- PxRigidDynamicLockFlag.eLOCK_ANGULAR_Z   锁定沿着 Z 轴运动
+- PxRigidDynamicLockFlag.eLOCK_LINEAR_X   锁定沿着 X 轴旋转
+- PxRigidDynamicLockFlag.eLOCK_LINEAR_Y   锁定沿着 Y 轴旋转
+- PxRigidDynamicLockFlag.eLOCK_LINEAR_Z   锁定沿着 Z 轴旋转
+
+如果你希望您的刚体具有运动的属性，你需要将刚体设置为运动学刚体
+
+那什么叫做有运动的属性？
+比如你想要手动控制刚体的运动，那么你需要将刚体设置为运动学刚体
+包括做成刚体风车、刚体传送带等行为
+
+```python
+# 目前PxRigdiBodyFlag 仅支持PxRigidBodyFlag.eKINEMATIC
+comp.SetRigidBodyFlag(PxRigidBodyFlag.eKINEMATIC, True)
+```
+
+### AI控制
+
+利用实体创建刚体，您需要对AI进行调整
+否则在客户端会出现悬空的情况
+
+```python
+comp = serverApi.GetEngineCompFactory().CreateControlAi(entityId)
+comp.SetBlockControlAi(False)
+```
+
+### 做一个简单的风车
+
+对此我们可以通过上述内容做一个简单的风车，我们计划是配合方块调色板 + 物理引擎来做一个简单的风车
+
+机械动力的风车是一个比较不错的参考对象
+
+我们仿照机械动力的风车，来做一个中国版物理引擎的风车
+
+首先根据上面介绍的内容，我们依次创建刚体，设置包围盒
+
+但是原版Java版机械动力的风车，可以自由组合方块，所以我们需要一个刚体对应一个方块。目前规划是创建一个长度5格的刚体
+
+可以做一个for循环
+
+```python
+for i in range(2):
+    for j in range(-2,3):
+        comp.AddBoxGeometry((j, 0.5 + i, 0), 0.5, 0.5, 0.5, 0.05, 0.05, 0, 
+                             PxEventMask.Server | PxEventMask.Client | PxEventMask.Found | PxEventMask.Found_Detail | PxEventMask.Lost, 
+                             '%s,%s,0' % (j, i))
+```
+
+此时就会创建一个总长度 5 格的刚体包围盒，并且每个刚体对应一个方块
+
+因为这个刚体会有旋转的效果，所以我们需要给刚体添加一个运动属性
+
+```python
+# 目前PxRigdiBodyFlag 仅支持PxRigidBodyFlag.eKINEMATIC
+comp.SetRigidBodyFlag(PxRigidBodyFlag.eKINEMATIC, True)
+```
+
+因为刚体旋转是通过传入一个四元数并对四元数调整来达到目标的
+
+所以我们需要创建一个四元数组
+
+```python
+# 这里建议用一个成员变量来做存储，方便删除实体后对数据进行调整和删除
+self.mSkeletons[entityId] = Quaternion(0, 0, 0, 1)
+```
+
+因为旋转是一个连续的过程，所以我们需要重写Update方法，以达到每tick刷新我们的旋转数据
+
+```python
+# 这里我们对 self.mSkeletons 进行遍历，获取刚刚存储好的四元数，修改的同时传入刚体运动方法
+for entityId, v in self.mSkeletons.iteritems():
+    # 旋转
+    q = v * Quaternion.AngleAxis(1, Vector3.Up())
+    # 修改变量值
+    self.mSkeletons[entityId] = q
+    # 设置为运动学目标
+    comp = serverApi.GetEngineCompFactory().CreatePhysx(entityId)
+    # 运动
+    comp.SetKinematicTarget(None, q.ToTuple())
+```
+
+此时刚体就会每tick旋转角度
+
+但是目前做的内容仅仅只是对刚体进行了旋转，客户端没有表现，我们还需要用方块调色板对客户端进行调试
+
+首先创建一个调色板
+
+```python
+dataDict = {'extra': {}, 'void': False, 'actor': {}, 'volume': (1, 5, 2), 'common': {('minecraft:grass_block', 0): [4, 9], ('minecraft:glass', 0): [1, 6], ('minecraft:quartz_block', 0): [3, 8], ('minecraft:white_wool', 0): [0, 5], ('minecraft:oak_planks', 0): [2, 7]}, 'eliminateAir': True}
+comp = compFactory.CreateBlock(levelId)
+palette = comp.GetBlankBlockPalette()
+palette.DeserializeBlockPalette(dataDict)
+blockGeometryComp = compFactory.CreateBlockGeometry(levelId)
+geometryName = blockGeometryComp.CombineBlockPaletteToGeometry(palette,"my_block_geometry")
+```
+
+然后需要将调色板绑定在实体上，但是绑定刚体是欧拉角，也就是说我们还需要将四元数转成欧拉角
+
+好在，ModSDK提供了这个简单的方法，物理引擎也有获取客户端刚体的四元数数据
+
+```python
+actorRenderComp = compFactory.CreateActorRender(entityId)
+comp = compFactory.CreatePhysx(entityId)
+q = Quaternion(comp.GetQuaternion())
+# AddActorBlockGeometry 在 3.7 新增了一个参数， 会控制先旋转后偏移，还是先偏移后旋转。默认是False
+# 为了做风车，我们设置为 True，也就是先旋转再偏移
+actorRenderComp.AddActorBlockGeometry(geometryName, (-2, 0, 0), q.EulerAngles().ToTuple(), True)
+self.mSkeletons.add(entityId)
+```
+
+此时刚体的方块调色板就已经绑定在实体上了，但是这个我们查看 PhysX Visual Debugger 时，发现刚体变动了，但是调色板方块没有变化
+
+所以我们也要对客户端表现进行调整
+
+同样需要重写 Update 方法，每tick修改方块调色板的旋转角度
+
+```python
+def Update(self):
+    for entityId in self.mSkeletons:
+        comp = compFactory.CreatePhysx(entityId)
+        q = comp.GetQuaternion()
+        if q:
+            q = Quaternion(q)
+            actorRenderComp = compFactory.CreateActorRender(entityId)
+            actorRenderComp.SetActorBlockGeometryRotation("my_block_geometry", q.EulerAngles().ToTuple())
+```
+
+当全部完成后，就可以做到风车围绕着一个自定义实体进行旋转，然后推动实体进行移动了
+
+并且你也可以站在这个刚体上，但是站在刚体上，刚体并不会带着玩家一起移动，开发者们可以自行思考解决办法来处理这个问题！
+
+![img_5.png](./picture/physx/img_5.png)
+
+### 思考
+
+虽然我们现在是在用 Update 的方式去动态的调整刚体旋转和外观旋转
+
+但是进入游戏后会发现，用此方法来旋转会有一点的顿挫感，虽然影响不是很大，但如果你需要追求细致，可能还不算太完美
+
+或许还可以通过 `GameRenderTickEvent` 来调整，但是这个方法笔者并没有使用过，所以需要开发者们自行思考研究