📚 World/Player

玩家对象是一个抽象的概念，它并不是一个可以看见的世界实例。

任何加入到当前服务器的玩家（包括本地玩家）均被认定为Player。

📒 Event

📘 OnPlayerJoin( player )

当新玩家加入主机时调用，此事件通常较少使用。

注意：此时玩家只是连接成功，并非加载完成，完整加载使用OnPlayerComplete。

📘 OnPlayerComplete( player )

当玩家完全加载时调用。

通常情况下，应该使用此事件作为玩家的入口事件。

📘 OnPlayerPart ( player, reason )

当玩家离开主机时调用。

注意：如果玩家是主机，且直接关闭游戏进程时，此方法可能不会按照预期工作。

Reason：离开原因（int）（0=断开连接；1=被服务器踢出；2=被服务器封禁）

📘 OnPlayerChat( player, text )

当玩家发送消息时调用。

此事件有返回值机制，如果返回为false则不使用内置的聊天输出（不会输出任何消息），默认返回true。

如果有自定义聊天样式需求，可以通过return 0然后使用Message("[color#=ff0000]"+player.Name+":"+text)等方式实现。

注意：默认聊天消息经过了Native.FormatRichText()格式化，这将使文本支持[URL\@AT\Emoji]等高亮显示，如果有自定义输出需求并希望支持这些功能，可以在手动发送Message前使用API格式化一次。**

游戏聊天框默认支持UBB|HTML格式的消息，如果不希望玩家随意使用，可以通过Misc.IsUBBText()或其他方式检测文本，并决定哪些内容允许被发送。

function OnPlayerChat( player, text )
{
    //以下2行内容实现了自定义聊天消息的扩展
    //举一反三，也可以扩展出私聊、团队信息、前缀、关键词替换等
    Message("[DIY CHAT] " + player.Name + ": " + text);
    return 0; //return 0 == ignore engine default chat message
}

📘 OnPlayerNetworkCMD( player, cmd, arg0, arg1, arg2 )

当接收到来自玩家客户端发送的CMD消息时调用，这是客户端与服务端传输自定义信息的方式之一。

对于一些特殊情况，可以利用json to string进行更详细的内容传输。

📘 OnPlayerStreamData( player, number, data )

当接收到来自玩家客户端发送的自定义数据时调用，这是客户端与服务端传输自定义信息的方式之一。

自定义信息数据由float(int)\string两个参数组成。

对于一些特殊情况，可以利用JSON（data参数）进行更详细的内容传输。

function OnPlayerStreamData( player: Player, number: float, data: string )

📘 OnPlayerCommand( player, cmd, arg )

当玩家输入指令时调用（以'/'作为前缀发送消息）。

📘 OnPlayerTypingChange( player, state )

当玩家聊天框输入状态发生改变时调用。

function OnPlayerTypingChange( player: Player, state: bool )

📘 OnPlayerVoiceStateChange( player, state )

当玩家语音聊天状态发生改变时调用（正在语音聊天）。

function OnPlayerVoiceStateChange( player: Player, state: bool )

📘 OnPlayerFocusEntityChange( player, entity )

当玩家焦点对象发生改变时调用。

function OnPlayerFocusEntityChange( player: Player, entity: Entity )

📘 OnPlayerEntityLogin( player, entity )

当玩家绑定到一个控制实体（Character）时调用。

📘 OnPlayerEntityLogout( player, entity )

当玩家取消绑定控制实体（Character）时调用。

📘 OnPlayerKeyDown( player, keyTag )

当玩家按下服务器监听按键时调用，只有服务器监听的按键（RegisterKeyListener）才会触发。

📘 OnPlayerKeyUp( player, keyTag )

当玩家抬起服务器监听按键时调用，只有服务器监听的按键（RegisterKeyListener）才会触发。

📘 OnPlayerWorldChange( player, world )

当玩家世界ID发生改变时调用。

📘 OnPlayerColorChange( player, color )

当玩家颜色发生改变时调用。

📘 OnPlayerNameChange( player, name )

当玩家名称发生改变时调用。

📘 OnPlayerBackpackPropOperation( player, slot, isMain, isShift )

当玩家背包请求操作物品时调用。

此方法可配合player.GetBackpackTempProp()使用。

isMain：是否为左键（主要）点击（否则为右键）
isShift：是否按住Shift键
return：默认返回true，决定是否允许后续操作

📘 OnPlayerBackpackPropDiscard( player, prop, isDelete )

当玩家背包请求扔掉物品时调用。

isDelete：是否为请求删除物品（否则视为丢弃）
return：默认返回true，决定是否允许后续操作

📒 Property

📘 player.ID

获取玩家序列ID，每个玩家ID是唯一的。

当之前的玩家离开游戏后，空闲的靠前ID将会被后续新玩家重新使用（对于特殊情况，UUID是更合适的筛选选择）。

player.ID: int

📘 player.UUID

获取玩家唯一标识值。

特别注意：此值并非是绝对安全的，玩家（尤其是Demo版玩家）更换设备、账号、手动修改等行为后会发生改变，通常只有Steam用户的UUID是相对唯一且安全的。

player.UUID: string

📘 player.Name

获取玩家用户名称，长度限制最多16。

此属性服务器脚本是可修改的，但不会真正影响到玩家配置名称，只在本次服务器内生效。

player.Name: string

📘 player.Address

获取玩家网络\联机标识地址。

在Socket情况下，这可能返回一个IPV4、IPV6网络地址，否则可能返回联机标识地址（如SteamP2P）。

player.Address: string

📘 player.Data

内置的自定义类型属性（建议使用基础类型），可供开发者自行使用，需要自行做好类型Type和生命周期处理。

player.Data = null; //any

📘 player.UserData

获取玩家自定义用户信息。

此信息仅支持字符串（可用Json扩展），当玩家使用CreateHost\ConnectHost方法时可传递对应参数。

总结：可在建立\加入服务器时提前告知服务器一些信息，例如部分游戏可能支持在主菜单选择衣服，加入服务器时只需要将衣服参数告知服务器即可，相当于一个前置信息传递。

player.UserData: string

📘 player.GameEdition

获取玩家用户游戏版本类型（非版本号）。

player.GameEdition: int

索引	版本
0	标准版（Demo\Steam）
1	白金版（Steam+DLC）

📘 player.Authority

获取玩家用户类型。

player.Authority: int

索引	账户类型
0	本地用户，非Steam用户（可能非安全的）
1	Steam用户（标准版\白金版）

📘 player.Ping

获取玩家用户网络延迟。

player.Ping: int

📘 player.FPS

获取玩家用户FPS帧数。

player.FPS: int

📘 player.Stats

设置玩家自定义信息\状态（短文本，将显示在[TAB]菜单的用户名附近）。

player.Stats = ""; //string

📘 player.World

设置玩家同步世界ID（不同世界将不可视\不可交互）。

当此属性被修改后，任何实例.World != 自身.World的对象都将不可见、不可操作，就像不存在一样。

注意：如果世界被修改时玩家绑定的Character已存在，那么将同步Character修改为新的World，并且不会解除绑定控制。如果不希望这样，可以提前player.SetEntity(null)解除绑定，再修改World。

注意：player.UniqueWorld的机制是10000 + player.ID，因此应该避免手动将世界设置为10000及以上的数值。

player.World = 0; //int

📘 player.UniqueWorld

获取玩家私人同步世界ID，此项与player.World功能相似，不同的是，如果将某个对象设置为player.UniqueWorld，则指定对象只有此玩家可见，哪怕此玩家仍然在默认世界（0）。

注意：player.UniqueWorld的机制是10000 + player.ID，因此应该避免手动将世界设置为10000及以上的数值。

player.UniqueWorld: int //10000 + player.ID

📘 player.Color

设置玩家的标识颜色，此颜色用于改变玩家的名称颜色、队伍颜色（概念）等，默认值为Color(255, 255, 255)。

player.Color = Color(255, 255, 255);

📘 player.Group

设置玩家的组ID，此值没有实际的功能意义，且不同于Entity.Group属性，目前只作保留属性用途。

扩展：在特殊情况下，可以通过此属性为玩家们分配不同的组ID，以此认为他们是不同的阵营，执行不同的代码。

player.Group = 0; //int

📘 player.Entity

获取玩家绑定的实体对象（角色）。

此方法也可以设置赋值对象（等同于player.SetEntity(value, true)，默认执行isBind）。

player.Entity: Character

📘 player.Character

获取玩家绑定的实体对象（角色），作用与player.Entity完全相同。

player.Character: Character

📘 player.IsAdmin

设置玩家是否为管理员，管理员可通过TAB菜单进行基础的玩家管理。

通常情况下，此属性是一个验证管理员权限的预制抽象属性，开发者可考虑自行编写更高级的管理员系统。

如果服务器由本地主机建立，主机玩家会自动激活此属性。

player.IsAdmin = false;

📘 player.IsBindEntity

如果设定为true则玩家断开时同时销毁角色（通过player.SetEntity()绑定的角色实例），否则将会保留角色，默认为true。

player.IsBindEntity = true;

📘 player.Pos

获取玩家世界坐标位置（通常是玩家屏幕中心位置），如果玩家正在控制角色，则返回角色坐标位置。

player.Pos: Vector

📘 player.FocusPos

获取玩家视角焦点坐标（屏幕中心、准星&鼠标位置）。

在玩家不同视角模式（Client.Camera.Mode）下（鸟瞰、第一人称、第三人称），坐标获取方式会发生变化。

主要表现于：[鸟瞰]鼠标坐标、[第三人称]屏幕准星坐标

player.FocusPos: Vector

📘 player.FocusEntity

获取玩家视角焦点实体，如果不存在则返回null。

player.FocusEntity: Entity

📘 player.FocusEntityDistance

获取玩家视角焦点实体检测距离，此数值直接影响FocusEntity的检测结果，默认距离为3.0（0.0~512.0）。

注意：对于远距离视角、鸟瞰视角等情况，应该在合理范围内调高此数值，否则可能距离过短导致无法正确检测。

player.FocusEntityDistance: float

📘 player.FocusVAngle

设置&获取玩家控制视角上下角度（Camera.VAngle）。

player.FocusVAngle: float

📘 player.FocusHAngle

设置&获取玩家控制视角横向角度（Camera.HAngle）。

player.FocusHAngle: float

📘 player.FocusEulerAngle

设置&获取玩家控制焦点（游戏视角+屏幕方向）XY角度（Vector2(x, y)）。

在玩家不同视角模式（Client.Camera.Mode）下，坐标处理方式会发生变化。

注意：多数情况下，应该使用Client\Camera实现视角相关逻辑。

player.FocusAngle: Vector2

📘 player.FocusAngleForward

获取玩家控制焦点前方向量。

在玩家不同视角模式（Client.Camera.Mode）下，坐标处理方式会发生变化。

player.FocusAngleForward: Vector2

📘 player.EngineLanguage

获取玩家正在使用的引擎语言（如果中途改动语言，不会更新）。

根据《沙盘引擎》语言机制，通常应该采用此方法作为玩家语言的判定。

player.EngineLanguage: string

📘 player.ModLanguage

获取玩家正在使用的模组语言（如果中途改动语言，不会更新）。

player.ModLanguage: string

📘 player.IsTyping

获取玩家聊天框输入状态（是否正在输入）。

player.IsTyping: bool

📘 player.IsComplete

获取玩家是否完全加载完毕。

player.IsComplete: bool

📘 player.IsObserver

获取玩家是否当前为相机观察模式（Client.Camera.IsObserver）。

player.IsObserver: bool

📘 player.VoiceState

获取玩家语音聊天状态（是否正在语音聊天）。

注意：玩家必须player.SetVoiceAuthority(true)给予语音权限（默认），且由玩家主动触发按键才会进行聊天。

player.VoiceState: bool

📘 player.CameraMode

获取（只读）玩家相机模式（参考Client.Camera.Mode）。

player.CameraMode: int

📒 Static Function

📘 Player.Find()

寻找一个玩家实例（通过ID），不存在则返回null。

function Player.Find( id: int ): Player

📘 Player.Search()

寻找一个玩家实例（通过模糊查找，通常根据玩家名称\ID，不区分大小写），不存在则返回null。

function Player.Search( any: string ): Player

//Players: "Alnny", "Tommy", "Tom"
Player.Search("Tom"); //Tom（完整匹配）
Player.Search("Tomm"); //Tommy（相似匹配）
Player.Search("To"); //Tommy（以最先搜索到的为主）
Player.Search("0"); //By ID

📘 Player.FindByUUID()

寻找一个玩家实例（通过UUID），不存在则返回null。

function Player.FindByUUID( uuid: string ): Player

📘 Player.GetCount()

获取当前所有存在玩家数量。

function Player.GetCount(): int

📘 Player.Get()

获取当前存在的指定索引玩家，通常搭配GetCount()遍历使用。

function Player.Get( index: int ): Player

📘 Player.BanUUID()

封禁指定完整UUID的玩家（仅在当前服务器运行时生效，重启服务器后将清空封禁列表）。

function Player.BanUUID( uuid: string )

📘 Player.UnbanUUID()

取消封禁指定完整UUID的玩家（仅在当前服务器运行时生效，重启服务器后将清空封禁列表）。

function Player.UnbanUUID( uuid: string )

📘 Player.UnbanName()

取消封禁指定完整名称（被封禁时）的玩家（仅在当前服务器运行时生效，重启服务器后将清空封禁列表）。

此方法只能取消由player.Ban()执行封禁的玩家，具体逻辑仍然基于UUID。

function Player.UnbanName( name: string )

📘 Player.UnbanAll()

取消所有玩家封禁（仅在当前服务器运行时生效，重启服务器后将清空封禁列表）。

function Player.UnbanAll()

📒 Function

📘 player.SetEntity()

为玩家设置一个实体（Character），在多数玩法框架的实现过程中，一个角色（Character）是基本的入口点。

function player.SetEntity( entity: Character, isBind: bool = true )
/*
	entity：要绑定的角色对象（如果为null则解除绑定）
	isBind：是否绑定实体（等同于player.IsBindEntity = isBind），如果设定为true则玩家断开时同时销毁角色，否则将会保留角色
*/

function OnPlayerJoin( player )
{
	let chara = Character.Create(0, Vector(0, 0, 0), 0, 0);
	player.SetEntity(chara);
}

📘 player.Kick()

从服务器踢出玩家。

function player.Kick( reason: string = "Kicked" )

📘 player.Ban()

从服务器封禁玩家（仅在服务器运行时生效，重启服务器将清空封禁列表）。

如果希望实现持久化的封禁列表，请考虑自行实现维护一个txt|json文件表，在每次服务器建立后读取文件+遍历执行Player.BanUUID()。

function player.Ban( reason: string = "Banned" )

📘 player.Message()

为玩家发送一条单独公屏消息（在消息框中）。

function player.Message( text: string )

📘 player.Announce()

为玩家发送一条单独公告\大文字消息。

function player.Announce( text: string, type: int = 0, time: float = 6 )

📘 player.Subtitle()

为玩家发送一条单独底部字幕消息。

function player.Subtitle( text: string )

📘 player.NetworkRPC()

为玩家发送一条RPC指令。

目标玩家客户端脚本通过OnServerNetworkRPC()接收数据。

注意：CMD\RPC方法仅支持基础类型，并且会自动类型转换。

function NetworkRPC( rpc: string, arg0: any, arg1: any, arg2: any )

📘 player.SendData()

为玩家发送一条服务端>客户端的自定义Stream数据信息。

目标玩家客户端脚本通过OnServerStreamData()接收数据。

注意：这里不应该放置特别大的数据内容（4096），否则可能造成网络阻塞。

function player.SendData( number: float, data: string = "" )

📘 player.ClientExec()

为玩家发送一条客户端脚本代码，目标玩家客户端将执行对应的脚本代码。

注意：这里不应该放置特别大的数据内容（2048），否则可能造成网络阻塞。

function player.ClientExec( code: string )

📘 player.PlaySound()

为玩家播放一段声音，用法及详细说明与客户端Audio相同。

function player.PlaySound( audioID: int, loop: bool = false, volume: float = 1f, tag: string = null ): string

📘 player.Play3DSound()

为玩家播放一段3D空间声音，用法及详细说明与客户端Audio相同。

function player.Play3DSound( audioID: int, pos: Vector, radius: float, loop: bool = false, volume: float = 1f, tag: string = null ): string

📘 player.StopSound()

为玩家停止播放并销毁一段声音实例，用法及详细说明与客户端Audio相同。

function player.StopSound( uuid: string, fadeTime: float = 0 )

📘 player.PlayMusic()

为玩家播放音乐（音乐轨道），用法及详细说明与客户端Audio相同。

function player.PlayMusic( audioID: int, loop: bool = false, volume: fadeTime = 3 )

📘 player.Play3DMusic()

为玩家播放3D空间音乐（音乐轨道），用法及详细说明与客户端Audio相同。

function player.Play3DMusic( audioID: int, pos: Vector, radius: float, loop: bool = false, fadeTime: float = 3f )

📘 player.PauseMusic()

为玩家暂停播放音乐（音乐轨道），用法及详细说明与客户端Audio相同。

function player.PauseMusic( fadeTime: float = 3 )

📘 player.ResumeMusic()

为玩家继续播放音乐（音乐轨道），用法及详细说明与客户端Audio相同。

function player.ResumeMusic( fadeTime: float = 3 )

📘 player.StopMusic()

为玩家停止播放并销毁音乐实例（音乐轨道），用法及详细说明与客户端Audio相同。

function player.StopMusic( fadeTime: float = 3 )

📘 player.PlayNatural()

为玩家播放背景环境音（背景音轨道），用法及详细说明与客户端Audio相同。

function player.PlayNatural( audioID: int, channel: int, loop: bool = true, volume: fadeTime = 3 )

📘 player.StopNatural()

为玩家停止播放并销毁指定背景环境音实例（背景音轨道），用法及详细说明与客户端Audio相同。

function player.StopNatural( channel: int, fadeTime: float = 3 )

📘 player.StopAllNatural()

为玩家停止播放并销毁全部背景环境音实例（背景音轨道），用法及详细说明与客户端Audio相同。

function player.StopAllNatural( fadeTime: float = 3 )

📘 player.RunTaskAction()

为玩家执行一次倒计时任务（UI进度条+倒计时），每个玩家同一时间只能执行一个任务

function player.RunTaskAction( tag: string, time: float, title: string, onComplete: Action, theme: int = 0 )

tag识别标签，仅供参考记录
time倒计时时间（秒）
title文本标题（支持宏文本）
theme范围0~4，表示不同的颜色

player.RunTaskAction("install", 5, "Installation in progress...", () => {
    //OnComplete
});

📘 player.StopTaskAction()

停止玩家倒计时任务。

function player.StopTaskAction()

📘 player.UpdateTaskActionData()

更新玩家倒计时任务信息。

function player.UpdateTaskActionData( title: string, theme: int = -1 )

title文本标题（支持宏文本）
theme颜色主题，默认-1不进行修改

📘 player.GetTaskActionTag()

获取玩家倒计时任务标签。

function player.GetTaskActionTag(): string

📘 player.ExistTaskAction()

获取玩家倒计时任务是否存在并进行中。

function player.ExistTaskAction(): bool

📘 player.SetVoiceMode()

设置玩家语音聊天模式，默认关闭。

如果希望激活语音聊天功能，请为玩家设定一个非关闭的语音模式。

function player.SetVoiceMode( mode: int = 0 )

索引	语音聊天模式	说明
0	关闭	不会发送与接收任何语音聊天
1	全局模式	发送与接收所有聊天，除特定情况及权限、禁言等
2	（频道）组模式	发送与接收相同频道组（`VoiceGroup`）的聊天，除特定情况及权限、禁言等

📘 player.GetVoiceMode()

获取玩家语音聊天模式。

function player.GetVoiceMode(): int

📘 player.SetVoiceWorldMode()

设置玩家语音聊天世界模式开关（3D空间音频，跟随玩家的实体对象）。

此选项可能在部分玩法中提高玩家沉浸感，就像其他玩家真的在不远处说话一样。

（可通过GameRule > voice_worlddistance 控制3D空间声音的传播距离）

function player.SetVoiceWorldMode( active: bool )

📘 player.GetVoiceWorldMode()

获取玩家语音聊天世界模式开关。

function player.GetVoiceWorldMode(): bool

📘 player.SetVoiceAuthority()

设置玩家语音聊天权限开关（静音\禁言），默认开启（true）。

注意：此选项必须设置为true，玩家才有资格进行说话，否则玩家将无法在语音聊天中说话（禁言Muted）。

（此选项并非是玩家麦克风控制开关，安全考虑，只有玩家自行按住【说话按键】时才会录入音频）

function player.SetVoiceAuthority( active: bool )

📘 player.GetVoiceAuthority()

获取玩家语音聊天权限开关。

function player.GetVoiceAuthority(): bool

📘 player.SetVoiceIgnore()

设置玩家屏蔽指定玩家语音开关，可用于屏蔽其他玩家的语音输出，但不会屏蔽自身对其他玩家的声音。

function player.SetVoiceIgnore( player: Player, active: bool )

📘 player.GetVoiceIgnore()