补充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
@@ -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也不分先后
+
+