📚 World/Player

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

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

📒 Event

📘 OnPlayerJoin( player )

当新玩家加入到主机房间时调用。

📘 OnPlayerPart ( player, reason )

当玩家离开房间时调用。

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

📘 OnPlayerChat( player, text )

当玩家发送消息时调用。

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

如果有自定义输出聊天样式的需求，可以通过return 0然后使用Message("颜色代码+[玩家名]：内容XXX")等方式实现自定义。

注意：沙盘引擎默认聊天消息经过了Native.FormatRichText()格式化，这将使文本支持[URL\@AT\Emoji]等高亮显示，如果有自定义Chat需求并希望支持这些功能，可以使用此API格式化一次。

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

📘 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 )

📘 OnPlayerEntityLogin( player, entity )

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

📘 OnPlayerEntityLogout( player, entity )

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

📘 OnPlayerKeyDown( player, keyTag )

当玩家按下服务器绑定按键时调用，只有服务器绑定的按键才会触发。

📘 OnPlayerKeyUp( player, keyTag )

当玩家抬起服务器绑定按键时调用，只有服务器绑定的按键才会触发。

📘 OnPlayerNativeKeyDown( player, keyTag )

当玩家按下服务器监听的原生公开按键时调用，只有服务器监听的原生按键才会触发。

📘 OnPlayerNativeKeyUp( player, keyTag )

当玩家抬起服务器监听的原生公开按键时调用，只有服务器监听的原生按键才会触发。

📒 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.UserData

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

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

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

player.UserData: string

📘 player.GameEdition

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

player.GameEdition: int

📘 player.Authority

获取玩家用户类型。

player.Authority: int

📘 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.World = 0; //int

📘 player.UniqueWorld

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

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.Entity: Character

📘 player.Character

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

player.Character: Character

📘 player.IsBindEntity

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

player.IsBindEntity = true;

📘 player.Pos

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

player.Pos: Vector

📘 player.FocusPos

获取玩家控制焦点坐标，如果玩家正在控制一个角色，则两者坐标相同（同步于此属性）。

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

主要表现于：【鸟瞰】基于陆地坐标；【第三人称】屏幕准星焦点

player.FocusPos: Vector

📘 player.Angle

获取玩家屏幕方向角度。

player.Angle: float

📘 player.EngineLanguage

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

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

player.EngineLanguage: string

📘 player.ModLanguage

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

player.ModLanguage: string

📘 player.IsTyping

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

player.IsTyping: bool

📘 player.VoiceState

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

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

player.VoiceState: bool

📘 player.CameraMode

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

player.CameraMode: int

📘 player.CameraFreeMode

设置玩家的相机自由模式开关（Client.Camera.FreeMode）。

player.CameraFreeMode = false; //bool

📘 player.CameraSlowMode

设置玩家的相机慢速延迟模式开关（Client.Camera.SlowMode）。

player.CameraSlowMode = false; //bool

📘 player.AudioReverbInternal

设置玩家的音频混响模式（建筑内部），枚举索引参考《AudioReverbPreset》。

player.AudioReverbInternal = 3; //Room

📘 player.AudioReverbExternal

设置玩家的音频混响模式（默认，建筑外部），枚举索引参考《AudioReverbPreset》。

player.AudioReverbExternal = 16; //Forest

📒 Static Function

📘 Player.Find()

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

function Player.Find( id: int ): Player

📘 Player.Search()

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

function Player.Search( any: string ): Player

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

📘 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.CreateNativeMenu()

为玩家建立一个NativeMenu菜单（NativeMenu菜单），用法与客户端NativeMenu相同。

let view = {
    Cover: 5,
    Tag: "Test",
    Title: "XXX",
    Info: "ABC",
    Width: 500,
    Align: 1,
    Layout: 1,
    Items: [
        {
            Text: "点击：输出玩家Name",
            OnClick: () => {
                DLog("PlayerName: " + player.Name);
            }
        },{
            Input: "xxx",
            Restrict: "*",
            OnFocus: (text) => {
                DLog("输入框文本: " + text);
            }
        },{
            Text: "点击：刷一辆载具+关闭菜单",
            OnClick: () => {
                Vehicle.Create(10, player.Entity.Pos, player.Entity.Angle);
                player.DestroyNativeMenu();
            }
        }
    ]
};
 
player.CreateNativeMenu(view);

📘 player.DestroyNativeMenu()

为玩家关闭NativeMenu菜单，用法与客户端NativeMenu相同。

📘 player.SetNativeMenuText()

为玩家关闭NativeMenu菜单，用法与客户端NativeMenu相同。

📘 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.StoryDialog()

为玩家发送一条故事对话框消息，并加入到队列中，等待上次对话框结束后陆续执行。

解释：此方法执行后可能不会立即显示，默认会加入到队列中，按加入顺序依次执行历史对话框。

function player.StoryDialog( title: string, text: string, avatar: int = -1, sound: int = -1, buttons: any = null, onComplete: Action = null )

• title：标题、故事对话人昵称
• text：主要文本内容（可用html语法，以及\n换行）
• avatar：故事对话人形象图片ID（基于Texture文件机制），默认为-1
• sound：故事对话时音频ID（例如配音等，基于Sound文件机制），默认为-1，仅在当前对话框生命周期有效，对话结束（或切换对话框）后将自动停止播放
• buttons：附加按钮（最多支持3个），以数组的形式传递数据（见下方示例）
• onComplete：对话结束时触发事件

player.StoryDialog("测试角色", "风平浪静……", -1, -1, [
    {
        Button: "Button A", 
        Action: () => {
            DLog("Click A");
        }
    },{
        Button: "Button B", 
        Action: () => {
            DLog("Click B");
        }
    }
], () => {
    DLog("OnComplete Invoke!");
}); //1
player.StoryDialog("测试角色2", "风平浪静1……", -1, 1124); //2
player.StoryDialog("测试角色2", "风平浪静2……", -1, 1124); //3

📘 player.NextStoryDialog()

为玩家切换下一个故事对话框（如有队列），相当于自动为玩家执行了跳过方法，并且会忽略Buttons焦点（无论是否设置Buttons，都会切换到下一个队列）。

function player.NextStoryDialog()

📘 player.ClearStoryDialog()

为玩家清空故事对话框队列，并结束全部故事对话框（会触发队列最后一个OnComplete）。

function player.ClearStoryDialog()

📘 player.SendData()

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

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

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

function player.SendData( number: float, data: 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.FocusCamera()

立即将玩家相机定位到追踪目标位置，适用于希望立即到相机目标位置（不需要平移效果）时调用。

function player.FocusCamera()

📘 player.BindKeyPresser()

为玩家绑定按键快捷对象的UI布局方式（2D屏幕、3D坐标、实体对象跟随），具体取决于参数类型。

注意：每次建立的按键快捷对象全部移出后，再次建立时，UI布局方式将自动切换至Null（2D屏幕偏右）。

function player.BindKeyPresser( target: any )
/*
	target可选类型：null\Vector\Entity（Vector\Entity类型将作为3D坐标展示，Entity会有自动跟随）
*/

📘 player.AddKeyPresser()

为玩家建立一个按键快捷对象，默认将加入到玩家屏幕偏右位置，如果你希望目标UI作为3D空间、跟随实体效果，使用BindKeyPresser提前绑定即可。

这将在目标玩家的屏幕中显示[按键] XXXX的效果（例如[F]进入此载具，并为其绑定进入载具的事件）。

同时，此功能支持同时绑定至多6个按键对象（同列表下，并非不同位置），只需要为其填写不同的index即可。

Index目前只是标签占位，排序仍然根据代码添加顺序。

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来检查某个按键对象是否存在

//同时绑定多个按键对象的示例
player.AddKeyPresser(0, "F", "进入当前载具", () => { 进入代码... });
player.AddKeyPresser(3, "H", "修复当前载具", () => { 修复代码... });
 
//此时将会在玩家屏幕中，显示竖向的两行（最多支持6行）
【F】进入当前载具
【H】修复当前载具

📘 player.RemoveKeyPresser()

为玩家移除一个按键快捷对象。

注意：每次建立的按键快捷对象全部移出后，再次建立时，UI布局方式将自动切换至Null（2D屏幕右下）。

function player.RemoveKeyPresser( index: int )

📘 player.ExistKeyPresser()

获取玩家指定索引的按键快捷对象是否存在。

function player.ExistKeyPresser( index: int ): bool

📘 player.ClearKeyPressers()

移除玩家所有按键快捷对象。

注意：每次建立的按键快捷对象全部移出后，再次建立时，UI布局方式将自动切换至Null（2D屏幕右下）。

function player.ClearKeyPressers()

📘 player.AddGuider()

为玩家建立一个指引目标（屏幕边缘箭头）。

function player.AddGuider( index: int, target: any, autoDestroy: bool = false )
/*
	index：指引索引（如索引已存在指引，将会替换修改，一个index只能存在并表示一个指引实例），相当于一个标签作用
	target：目标对象（可以是Vector|Entity等类型，分别表示静态坐标与动态跟随目标）
	autoDestroy：到达指引目标附近是否自动移除指引，默认为false
*/
 
//通常情况下，如果同时只使用1个指引功能，只需要一直将index填写0即可

📘 player.RemoveGuider()

为玩家移除一个指引目标（屏幕边缘箭头）。

function player.RemoveGuider( index: int )

📘 player.ExistGuider()

获取玩家指定索引的指引实例是否存在。

function player.ExistGuider( index: int ): bool

📘 player.SetCinematicBorder()

设置玩家屏幕电影边框开关，与客户端API作用相同。

function player.SetCinematicBorder( active: bool, time: float = 1.0 ): bool

📘 player.GetCinematicBorder()

获取玩家屏幕电影边框开关。

function player.GetCinematicBorder(): bool

📘 player.SetVoiceMode()

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

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

function player.SetVoiceMode( mode: int = 0 )

📘 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，玩家才有资格进行说话，否则玩家将无法在语音聊天中说话。

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

function player.SetVoiceWorldMode( active: bool )

📘 player.GetVoiceAuthority()

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

function player.GetVoiceAuthority(): bool

📘 player.SetVoiceIgnore()

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

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

📘 player.GetVoiceIgnore()

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

function player.GetVoiceIgnore( player: Player ): bool