meta data for this page
  •  

📚 差别

这里会显示出您选择的修订版和当前版本之间的差别。

到此差别页面的链接

两侧同时换到之前的修订记录前一修订版
后一修订版		前一修订版
scripting:world:player [2025/07/26 21:57] – bibiboxsscripting:world:player [2025/08/29 15:50] (当前版本) – bibiboxs
行 12: 行 12:
 ### OnPlayerJoin( player ) ### OnPlayerJoin( player )
  
-> 当新玩家加入到主机房间时调用。+> 当新玩家**加入主机**时调用，此事件通常较少使用。
 > >
-> ==注意：此时玩家只是连接成功，并非加载完成，完整加载使用`OnPlayerComplete`。==+> 注意：此时玩家只是连接成功，并非加载完成，完整加载使用`OnPlayerComplete`。
  
  
行 20: 行 20:
 ### OnPlayerComplete( player ) ### OnPlayerComplete( player )
  
-> 当玩家完全加载完成时调用。+> 当玩家**完全加载**时调用。
 > >
-> ==此事件是获取玩家完全载入状态的正确方法。==+> 通常情况下，应该使用此事件作为玩家的**入口事件**。
  
  
行 28: 行 28:
 ### OnPlayerPart ( player, reason ) ### OnPlayerPart ( player, reason )
  
-> 当玩家离开房间时调用。+> 当玩家**离开主机**时调用。 
 +>  
 +> 注意：如果玩家是主机，且直接关闭游戏进程时，此方法可能**不会按照预期**工作。
  
 - **Reason：**离开原因（int）（0=断开连接；1=被服务器踢出；2=被服务器封禁） - **Reason：**离开原因（int）（0=断开连接；1=被服务器踢出；2=被服务器封禁）
行 38: 行 40:
 > 当玩家发送消息时调用。 > 当玩家发送消息时调用。
 > >
-> 此事件拥有返回值机制，如果返回为`false`则不使用内置的聊天输出机制（将不会输出任何消息），默认返回`true`。+> 此事件有**返回值机制**，如果返回为`false`则不使用内置的聊天输出（不会输出任何消息），默认返回`true`。
 > >
-> *如果有自定义输出聊天样式的需求，可以通过`return 0`然后使用`Message("[color#=ff0000]"+player.Name+":"+text)`等方式实现自定义。*+> 如果有**自定义聊天样式**需求，可以通过`return 0`然后使用`Message("[color#=ff0000]"+player.Name+":"+text)`等方式实现。
 > >
-> **注意：沙盘引擎默认聊天消息经过了`Native.FormatRichText()`格式化，这将使文本支持[URL\@AT\Emoji]等高亮显示，如果有自定义Chat需求并希望支持这些功能，可以在手动发送Message前使用此API格式化一次。**+> 注意：默认聊天消息经过了`Native.FormatRichText()`格式化，这将使文本支持`[URL\@AT\Emoji]`等高亮显示，如果有自定义输出需求并希望支持这些功能，可以在手动发送Message前使用API格式化一次。** 
 + 
 +[note] 
 +游戏聊天框默认支持`UBB|HTML`格式的消息，如果不希望玩家随意使用，可以通过`Misc.IsUBBText()`或其他方式检测文本，并决定哪些内容允许被发送。 
 +[/note]
  
 ```javascript ```javascript
行 56: 行 62:
  
  
-### OnPlayerNetworkCMD( cmd, arg0, arg1, arg2 )+### OnPlayerNetworkCMD( player, cmd, arg0, arg1, arg2 )
  
-> 当接收到来自玩家客户端发送的**CMD消息**时调用，**这是客户端与服务端传输自定义信息的方式之一**。+> 当接收到来自玩家客户端发送的**CMD消息**时调用，这是客户端与服务端**传输自定义信息**的方式之一。
 > >
 > **对于一些特殊情况，可以利用`json to string`进行更详细的内容传输。** > **对于一些特殊情况，可以利用`json to string`进行更详细的内容传输。**
行 64: 行 70:
 [note2] [note2]
  
-注意：`CMD\RPC`传输支持几个基础类型（`int | float | string | bool`）。+注意：`CMD\RPC`传输支持几个基础类型（`int | float | string | bool | Vector | Color`）。
  
 [/note] [/note]
行 268: 行 274:
 | ---- | -------------------- | | ---- | -------------------- |
 | 0    | 标准版（Demo\Steam） | | 0    | 标准版（Demo\Steam） |
-| 1    | 白金版（Steam+DLC）      |+| 1    | 白金版（Steam+DLC）  |
  
  
行 284: 行 290:
 | ---- | ------------------------------------- | | ---- | ------------------------------------- |
 | 0    | 本地用户，非Steam用户（可能非安全的） | | 0    | 本地用户，非Steam用户（可能非安全的） |
-| 1    | Steam用户（标准版\白金版）        |+| 1    | Steam用户（标准版\白金版）            |
  
  
行 328: 行 334:
 > >
 > **注意：如果世界被修改时玩家绑定的`Character`已存在，那么将同步`Character`修改为新的World，并且不会解除绑定控制。如果不希望这样，可以提前`player.SetEntity(null)`解除绑定，再修改World。** > **注意：如果世界被修改时玩家绑定的`Character`已存在，那么将同步`Character`修改为新的World，并且不会解除绑定控制。如果不希望这样，可以提前`player.SetEntity(null)`解除绑定，再修改World。**
-> +>
 > **==注意：`player.UniqueWorld`的机制是`10000 + player.ID`，因此应该避免手动将世界设置为`10000`及以上的数值。==** > **==注意：`player.UniqueWorld`的机制是`10000 + player.ID`，因此应该避免手动将世界设置为`10000`及以上的数值。==**
  
行 340: 行 346:
  
 > 获取玩家**私人同步世界ID**，此项与`player.World`功能相似，不同的是，如果将某个对象设置为`player.UniqueWorld`，则指定对象只有此玩家可见，哪怕此玩家仍然在默认世界（0）。 > 获取玩家**私人同步世界ID**，此项与`player.World`功能相似，不同的是，如果将某个对象设置为`player.UniqueWorld`，则指定对象只有此玩家可见，哪怕此玩家仍然在默认世界（0）。
-> +>
 > **==注意：`player.UniqueWorld`的机制是`10000 + player.ID`，因此应该避免手动将世界设置为`10000`及以上的数值。==** > **==注意：`player.UniqueWorld`的机制是`10000 + player.ID`，因此应该避免手动将世界设置为`10000`及以上的数值。==**
  
行 374: 行 380:
  
 > 获取玩家绑定的实体对象（角色）。 > 获取玩家绑定的实体对象（角色）。
 +> 
 +> 此方法也可以设置赋值对象（等同于`player.SetEntity(value, true)`，默认执行`isBind`）。
  
 ```javascript ```javascript
行 393: 行 401:
 ### player.IsAdmin ### player.IsAdmin
  
-> 设置玩家**是否为管理员**，管理员可通过[TAB]菜单进行基础的玩家管理。 +> 设置玩家**是否为管理员**，管理员可通过`TAB`菜单进行基础的玩家管理。 
-> +>
 > 通常情况下，此属性是一个验证管理员权限的**预制抽象属性**，开发者可考虑自行编写更高级的管理员系统。 > 通常情况下，此属性是一个验证管理员权限的**预制抽象属性**，开发者可考虑自行编写更高级的管理员系统。
 +> 
 +> 如果服务器由**本地主机**建立，主机玩家会自动激活此属性。
  
 ```javascript ```javascript
行 450: 行 460:
  
 > 获取玩家**视角焦点实体检测距离**，此数值直接影响`FocusEntity`的检测结果，默认距离为`3.0`（`0.0~512.0`）。 > 获取玩家**视角焦点实体检测距离**，此数值直接影响`FocusEntity`的检测结果，默认距离为`3.0`（`0.0~512.0`）。
-> +>
 > **注意：对于远距离视角、鸟瞰视角等情况，应该在合理范围内调高此数值，否则可能距离过短导致无法正确检测。** > **注意：对于远距离视角、鸟瞰视角等情况，应该在合理范围内调高此数值，否则可能距离过短导致无法正确检测。**
  
行 577: 行 587:
 ```javascript ```javascript
 player.CameraMode: int player.CameraMode: int
-``` 
- 
- 
- 
-### player.CameraFreeMode 
- 
-> 设置玩家的相机自由模式开关（`Client.Camera.FreeMode`）。 
- 
-[note2] 
-注意：此模式不会修改鼠标可见状态，因此通常应该手动关闭鼠标可见（Client），已达到随鼠标自由旋转。 
-[/note] 
- 
-```javascript 
-player.CameraFreeMode = false; //bool 
-``` 
- 
- 
- 
-### player.CameraSlowMode 
- 
-> 设置玩家的相机慢速延迟模式开关（`Client.Camera.SlowMode`）。 
- 
-```javascript 
-player.CameraSlowMode = false; //bool 
-``` 
- 
- 
- 
-### player.AudioReverbInternal 
- 
-> 设置玩家的音频混响模式（建筑内部），枚举索引参考[《AudioReverbPreset》](https://docs.unity.cn/cn/current/ScriptReference/AudioReverbPreset.html "《AudioReverbPreset》")。 
-> 
- 
-```javascript 
-player.AudioReverbInternal = 3; //Room 
-``` 
- 
- 
- 
-### player.AudioReverbExternal 
- 
-> 设置玩家的音频混响模式（默认，建筑外部），枚举索引参考[《AudioReverbPreset》](https://docs.unity.cn/cn/current/ScriptReference/AudioReverbPreset.html "《AudioReverbPreset》")。 
-> 
- 
-```javascript 
-player.AudioReverbExternal = 16; //Forest 
 ``` ```
  
行 750: 行 714:
  player.SetEntity(chara);  player.SetEntity(chara);
 } }
-``` 
- 
- 
- 
-### player.SetObserver() 
- 
-[note2] 
-此方法已过时，已在新版本移除。 
-[/note] 
- 
-> 设置玩家视角观察对象（`Client.Camera.Target`）。 
->  
-> 设置为`null`可恢复观察控制`character.Entity`。 
- 
-```javascript 
-function player.SetObserver( character: Character ) 
-``` 
- 
- 
- 
-### player.GetObserver() 
- 
-[note2] 
-此方法已过时，已在新版本移除。 
-[/note] 
- 
-> 获取玩家视角观察对象（`Client.Camera.Target`），如未观察其他角色则返回`character.Entity`，否则返回`null`。 
- 
-```javascript 
-function player.GetObserver(): Character 
 ``` ```
  
行 796: 行 730:
 ### player.Ban() ### player.Ban()
  
-> 从服务器封禁玩家（仅在当前服务器运行时生效，重启服务器后将清空封禁列表）。+> 从服务器封禁玩家（仅在服务器运行时生效，重启服务器将清空封禁列表）。
 > >
 > 如果希望实现持久化的封禁列表，请考虑自行实现维护一个`txt|json`文件表，在每次服务器建立后读取文件+遍历执行`Player.BanUUID()`。 > 如果希望实现持久化的封禁列表，请考虑自行实现维护一个`txt|json`文件表，在每次服务器建立后读取文件+遍历执行`Player.BanUUID()`。
行 878: 行 812:
 ### player.PlaySound() ### player.PlaySound()
  
-> 为玩家播放一段声音，用法及详细说明与[客户端Audio](scripting/client/audio)相同。+> 为玩家播放一段**声音**，用法及详细说明与[客户端Audio](scripting/client/audio)相同。
  
 ```javascript ```javascript
行 888: 行 822:
 ### player.Play3DSound() ### player.Play3DSound()
  
-> 为玩家播放一段3D空间声音，用法及详细说明与[客户端Audio](scripting/client/audio)相同。+> 为玩家播放一段**3D空间声音**，用法及详细说明与[客户端Audio](scripting/client/audio)相同。
  
 ```javascript ```javascript
行 898: 行 832:
 ### player.StopSound() ### player.StopSound()
  
-> 为玩家停止播放并销毁一段声音实例，用法及详细说明与[客户端Audio](scripting/client/audio)相同。+> 为玩家停止播放并销毁一段**声音实例**，用法及详细说明与[客户端Audio](scripting/client/audio)相同。
  
 ```javascript ```javascript
行 908: 行 842:
 ### player.PlayMusic() ### player.PlayMusic()
  
-> 为玩家播放音乐（音乐轨道），用法及详细说明与[客户端Audio](scripting/client/audio)相同。+> 为玩家播放**音乐**（音乐轨道），用法及详细说明与[客户端Audio](scripting/client/audio)相同。
  
 ```javascript ```javascript
行 918: 行 852:
 ### player.Play3DMusic() ### player.Play3DMusic()
  
-> 为玩家播放3D空间音乐（音乐轨道），用法及详细说明与[客户端Audio](scripting/client/audio)相同。+> 为玩家播放**3D空间音乐**（音乐轨道），用法及详细说明与[客户端Audio](scripting/client/audio)相同。
  
 ```javascript ```javascript
行 928: 行 862:
 ### player.PauseMusic() ### player.PauseMusic()
  
-> 为玩家暂停播放音乐（音乐轨道），用法及详细说明与[客户端Audio](scripting/client/audio)相同。+> 为玩家暂停播放**音乐**（音乐轨道），用法及详细说明与[客户端Audio](scripting/client/audio)相同。
  
 ```javascript ```javascript
行 938: 行 872:
 ### player.ResumeMusic() ### player.ResumeMusic()
  
-> 为玩家继续播放音乐（音乐轨道），用法及详细说明与[客户端Audio](scripting/client/audio)相同。+> 为玩家继续播放**音乐**（音乐轨道），用法及详细说明与[客户端Audio](scripting/client/audio)相同。
  
 ```javascript ```javascript
行 948: 行 882:
 ### player.StopMusic() ### player.StopMusic()
  
-> 为玩家停止播放并销毁音乐实例（音乐轨道），用法及详细说明与[客户端Audio](scripting/client/audio)相同。+> 为玩家停止播放并销毁**音乐实例**（音乐轨道），用法及详细说明与[客户端Audio](scripting/client/audio)相同。
  
 ```javascript ```javascript
行 958: 行 892:
 ### player.PlayNatural() ### player.PlayNatural()
  
-> 为玩家播放背景音（背景音轨道），用法及详细说明与[客户端Audio](scripting/client/audio)相同。+> 为玩家播放**背景环境音**（背景音轨道），用法及详细说明与[客户端Audio](scripting/client/audio)相同。
  
 ```javascript ```javascript
行 968: 行 902:
 ### player.StopNatural() ### player.StopNatural()
  
-> 为玩家停止播放并销毁指定背景音实例（背景音轨道），用法及详细说明与[客户端Audio](scripting/client/audio)相同。+> 为玩家停止播放并销毁指定**背景环境音实例**（背景音轨道），用法及详细说明与[客户端Audio](scripting/client/audio)相同。
  
 ```javascript ```javascript
行 978: 行 912:
 ### player.StopAllNatural() ### player.StopAllNatural()
  
-> 为玩家停止播放并销毁全部背景音实例（背景音轨道），用法及详细说明与[客户端Audio](scripting/client/audio)相同。+> 为玩家停止播放并销毁全部**背景环境音实例**（背景音轨道），用法及详细说明与[客户端Audio](scripting/client/audio)相同。
  
 ```javascript ```javascript
行 986: 行 920:
  
  
-### player.FocusCamera()+### player.RunTaskAction()
  
-> 立即将**玩家相机定位到追踪目标位置**，适用于希望立即到相机目标位置（不需要平移效果）时调用。+> 为玩家执行一次**倒计时任务**（UI进度条+倒计时），每个玩家**同一时间**只能执行一个任务
  
 ```javascript ```javascript
-function player.FocusCamera()+function player.RunTaskAction( tag: string, time: float, title: string, onComplete: Action, theme: int = 0 )
 ``` ```
  
- +- `tag`识别标签，仅供参考记录 
- +- `time`倒计时时间（秒） 
-### player.RunTask() +- `title`文本标题（支持宏文本） 
- +- `theme`范围0~4，表示不同的颜色
-> 为玩家执行一次**倒计时任务**（例如拆除炸弹+UI进度条），每个玩家同一时间只能执行一个任务 +
- +
-```javascript +
-function player.RunTask( time: float, title: string, onComplete: Action, theme: int = 0 ) +
-``` +
- +
-- **`theme`：**范围0~4，表示不同的颜色+
  
 ```javascript ```javascript
-player.RunTask(5, "正在安装C4...", () => { +player.RunTaskAction("install", 5, "Installation in progress...", () => { 
-    //C4 Setup+    //OnComplete
 }); });
 ``` ```
行 1014: 行 941:
  
  
-### player.StopTask()+### player.StopTaskAction()
  
 > 停止玩家**倒计时任务**。 > 停止玩家**倒计时任务**。
  
 ```javascript ```javascript
-function player.StopTask()+function player.StopTaskAction()
 ``` ```
  
  
  
-### player.BindKeyPresser()+### player.UpdateTaskActionData()
  
-> 为玩家绑定**按键快捷对象**的UI布局方式（2D屏幕、3D坐标、实体对象跟随），具体取决于参数类型。 +> 更新玩家**倒计时任务**信息。
-> +
-> ==注意：每次建立的**按键快捷对象**全部移出后，再次建立时，UI布局方式将自动切换至`Null（2D屏幕偏右）`。==+
  
 ```javascript ```javascript
-function player.BindKeyPresser( target: any ) +function player.UpdateTaskActionData( title: string, theme: int = -1 )
-/* +
- target可选类型：null\Vector\Entity（Vector\Entity类型将作为3D坐标展示，Entity会有自动跟随） +
-*/+
 ``` ```
  
- +- `title`文本标题（支持宏文本） 
- +- `theme`颜色主题，默认`-1`不进行修改
-### player.AddKeyPresser() +
- +
-> 为玩家建立一个**按键快捷对象**，默认将加入到玩家**屏幕偏右**位置，如果你希望目标UI作为3D空间、跟随实体效果，使用`BindKeyPresser`提前绑定即可。 +
-> +
-> 这将在目标玩家的屏幕中显示`[按键] XXXX`的效果（例如`[F]进入此载具`，并为其绑定进入载具的事件）。 +
-> +
-> 同时，此功能支持同时**绑定至多6个按键对象**（同列表下，并非不同位置），只需要为其填写不同的index即可。 +
-> +
-> **Index目前只是标签占位，排序仍然根据代码添加顺序。** +
- +
-```javascript +
-function player.AddKeyPresser( index: int, keyCode: string, text: string, onPress: Action = null ) +
-/* +
- index：指引索引（如索引已存在指引，将会替换修改，一个index只能存在并表示一个指引实例），相当于一个标签作用 +
- keyCode：绑定按键，最好不要和其他按键冲突，除非知道在做什么 +
- text：按键后面的文本内容 +
- onPress：当玩家按下后执行的事件 +
-*/ +
- +
-//通常情况下，如果同时只使用1个指引功能，只需要一直将index填写0即可 +
-//在可能处理多个按键对象的情况下，可以将index作为区分标签作用，比如上车index是100，下车可能是101，这样可以随时用ExistKeyPresser来检查某个按键对象是否存在 +
-``` +
- +
-```javascript +
-//同时绑定多个按键对象的示例 +
-player.AddKeyPresser(0, "F", "进入当前载具", () => { 进入代码... }); +
-player.AddKeyPresser(3, "H", "修复当前载具", () => { 修复代码... }); +
- +
-//此时将会在玩家屏幕中，显示竖向的两行（最多支持6行） +
-【F】进入当前载具 +
-【H】修复当前载具 +
-``` +
- +
- +
- +
-### player.RemoveKeyPresser() +
- +
-> 为玩家移除一个**按键快捷对象**。 +
-> +
-> ==注意：每次建立的**按键快捷对象**全部移出后，再次建立时，UI布局方式将自动切换至`Null（2D屏幕右下）`。== +
- +
-```javascript +
-function player.RemoveKeyPresser( index: int ) +
-``` +
- +
- +
- +
-### player.ExistKeyPresser() +
- +
-> 获取玩家**指定索引**的**按键快捷对象**是否存在。 +
- +
-```javascript +
-function player.ExistKeyPresser( index: int ): bool +
-``` +
- +
- +
- +
-### player.ClearKeyPressers() +
- +
-> 移除玩家所有**按键快捷对象**。 +
-> +
-> ==注意：每次建立的**按键快捷对象**全部移出后，再次建立时，UI布局方式将自动切换至`Null（2D屏幕右下）`。== +
- +
-```javascript +
-function player.ClearKeyPressers() +
-``` +
- +
- +
- +
-### player.AddGuider() +
- +
-> 为玩家建立一个指引目标（屏幕边缘箭头），允许附加指引文字。 +
- +
-```javascript +
-function player.AddGuider( index: int, target: any, text: string = "", autoDestroy: bool = false ) +
-/* +
- index：指引索引（如索引已存在指引，将会替换修改，一个index只能存在并表示一个指引实例），相当于一个标签作用 +
- target：目标对象（可以是Vector|Entity等类型，分别表示静态坐标与动态跟随目标） +
- text：指引文字 +
- autoDestroy：到达指引目标附近是否自动移除指引，默认为false +
-*/ +
- +
-//通常情况下，如果同时只使用1个指引功能，只需要一直将index填写0即可 +
-```+
  
  
  
-### player.RemoveGuider()+### player.GetTaskActionTag()
  
-> 为玩家移除一个指引目标（屏幕边缘箭头）。+> 获取玩家**倒计时任务**标签。
  
 ```javascript ```javascript
-function player.RemoveGuider( index: int )+function player.GetTaskActionTag(): string
 ``` ```
  
  
  
-### player.ExistGuider()+### player.ExistTaskAction()
  
-> 获取玩家**指定索引**的指引实例是否存在。+> 获取玩家**倒计时任务**是否**存在**并进行中。
  
 ```javascript ```javascript
-function player.ExistGuider( index: int ): bool+function player.ExistTaskAction(): bool
 ``` ```
  
行 1312: 行 1150:
  
 - `return`：是否正常返回（如果没有临时物品，也会返回`true`） - `return`：是否正常返回（如果没有临时物品，也会返回`true`）
 +
 +
 +
 +
 +
 +
 +
 +
 +