🎁
🏆 导航菜单
🎪 扩展内容
🎯 沙盘引擎文档
🕹️ 文章及书籍&教程
🎖️ 外部的链接
🎁
🏆 导航菜单
🎪 扩展内容
🎯 沙盘引擎文档
🕹️ 文章及书籍&教程
🎖️ 外部的链接
这是本文档旧的修订版!
注意:在当前版本下,Client
脚本更适合实现客户端独有的功能、GUI界面等。
有关世界内容的玩法(如:Player、Character、Vehicle等)建议优先使用World
脚本实现。
如果有某些功能只有ClientAPI支持,可以用
SendDataToServer
相关方法与服务端进行二次通信,以实现“通过服务端让某个玩家执行一个ClientAPI”。
当客户端脚本被完整加载后调用。
当脚本即将被释放时调用。
当脚本加载完成后每帧调用。
由于此事件属于客户端脚本范畴,所以可以理解为每帧渲染事件,无须担心延迟问题。
deltaTime:float //增量时间
当本地客户端发送一条指令之前调用(玩家本地输入指令发送)。
此事件将决定是否投递指令到服务端,如果返回
true
(或忽略)则默认投递,否则返回false
则拦截此指令,不会发送到服务端执行。
此事件可供实现一些内置的“本地游戏指令”,例如可实现输入"quitgame"
退出游戏等功能。
注意:对于少数引擎内置的指令(如quit\q\version\disconnect...
)不会被接收和调用,这是不可拦截的。
当接收到来自服务端发送的自定义数据时调用,这是客户端与服务端传输自定义信息的方式之一。
自定义信息数据由
float(int)\string
两个参数组成。对于一些特殊情况,可以利用JSON(data参数)进行更详细的内容传输。
当脚本通过
BindKey()
绑定的按键被按下时调用。
function OnKeyDown( keyTag ) { //keyTag表示按键标签,而不是按键代码 }
当脚本通过
BindKey()
绑定的按键被抬起时调用。
function OnKeyUp( keyTag ) { //keyTag表示按键标签,而不是按键代码 }
当脚本通过
BindNativeKey()
绑定的按键被按下时调用。
function OnNativeKeyDown( keyTag ) { //keyTag表示按键标签,而不是按键代码 }
当脚本通过
BindNativeKey()
绑定的按键被抬起时调用。
function OnNativeKeyUp( keyTag ) { //keyTag表示按键标签,而不是按键代码 }
执行一段脚本代码(Client\World脚本不互通)。
代码内容可能出现报错,考虑使用try\catch进行防范。
function Exec( code: string )
请求访问一个网络或本地路径,执行后将由玩家决定是否打开Url。
如果希望访问一个本地路径(或执行),请将url路径前增加
file://
路径前缀。
function OpenUrl( url: string )
激活内置主菜单界面(锁定常驻显示,并屏蔽Esc菜单),并绑定其中的一项(索引
0\1
,只限2项)。如果对于模组主菜单没有特殊\高级自定义需求(否则应该考虑使用FairyGUI自制菜单),可以通过此方法极快速的建立一个游戏原生主菜单(类似:静态锁定的ESC菜单样式)。
引擎目前仅支持自定义2个按钮项目(放置在顶部
0\1
),开发者可分别为其绑定【索引、按钮标题、按钮说明、按钮事件】。注意:此方法通常只需要在设为主菜单的场景执行一次,并且只在当前场景生效,切换场景后将会自动解除绑定(自动执行
UnlockGameMenu()
)。
function LockGameMenu( index: int, title: string, info: string, callback: Action )
function OnScriptLoad() { LockGameMenu(0, "启动主机", "建立本地联机服务器", () => { CreateHost("mapname", "scriptname"); }); LockGameMenu(1, "[color=#ffff00]加入本地服务器[/color]", "加入本地服务器(127.0.0.1)", () => { ConnectHost("127.0.0.1"); }); }
解除绑定内置主菜单界面按钮项目。
如果解除后已经不存在任何自定义绑定项目,将自动关闭菜单并重设为默认Esc菜单模式。
注意:如果参数设为-1,则表示解除全部项目。
function UnlockGameMenu( index: int = -1 )
打开一个引擎内置UI面板(如设置、服务器列表、MOD管理器等)。
function OpenNativeView( int type, Action onDisable = null )
ID | 面板描述 |
---|---|
0 | 开发者界面(关于界面) |
1 | 游戏设置 |
2 | 多人游戏浏览器 |
4 |
尽管有些ID没有被表格记录,但有可能仍然是有内容的,但未被记录的ID通常不具备通用性意义,在打开时将会别引擎阻断。
检查某个引擎内置UI界面是否存在(被打开)。
function ExistNativeView( type: int ): bool
关闭一个引擎内置UI面板。
function DestroyNativeView(type: int = -1, hasEffect: bool = true) //如果不填写参数(-1),则默认关闭所有内置UI面板 //如果hasEffect == false则立即关闭面板
载入一个引擎内置场景(如地图编辑器等)。
function LoadNativeScene( type: int )
ID | 面板描述 |
---|---|
0 | 世界场景(相当于重载主场景) |
1 | 地图编辑器 |
为本地玩家建立一个
NativeMenu
菜单(等同于WorldScript/player.CreateNativeMenu()
的客户端版本)。更多内容请查看NativeMenu菜单。
function CreateNativeMenu( viewData: any )
为本地玩家关闭
NativeMenu
菜单。
function DestroyNativeMenu()
为本地玩家设置菜单中某项的文本。
function SetNativeMenuText( index: int, text: string ) //index: (-1 > 标题, -2 > 子标题, 0+ > 索引Item) function SetNativeMenuText( tag: string, text: string ) //同理,区别是通过tag参数来选择改变的Item
发送一条自定义数据消息到服务端,此功能合理使用可扩展许多效果。
服务端收到数据后,将由
OnPlayerStreamData()
事件接收。注意:这里不应该放置特别大的数据内容,否则可能造成网络阻塞。
function SendDataToServer( number: float(int), data: string = "" )
设置是否允许开启游戏聊天窗口,默认为
true
,否则将无法通过正常方式打开聊天框(但可正常收到消息)。此功能可用作主菜单界面,此时通常不希望玩家使用“聊天”功能。
function SetChatEnabled( enable: bool )
执行一次全屏转场(
Alpha: 0 -> 1 -> 0
)。
function ScreenFade( time: float, middleTime = 0, color: Color = Color(0, 0, 0), onMiddle = null, ignoreHit: bool = true ) /* time:渐变时间(渐入>不透明>渐出),例如设置为2,则表示0~1秒变不透明,1~2秒变透明 middleTime:不透明延迟时间,默认为0,否则将等待X秒后再进行透明渐变 color:颜色,默认为黑色 onMiddle:可选委托事件,当颜色完成不透明时调用 ignoreHit:转场是否屏蔽点击,默认为true */
执行一次全屏渐入转场(
Alpha: 0 -> 1
)。
function ScreenFadeIn( time: float, color: Color = Color(0, 0, 0), onComplete = null, ignoreHit: bool = true ) /* time:整体时间(渐入>不透明) color:颜色,默认为黑色 onComplete:可选委托事件,当颜色完成不透明时调用 ignoreHit:转场是否屏蔽点击,默认为true */
执行一次全屏渐出转场(
Alpha: 1 -> 0
)。
function ScreenFadeOut( time: float, color: Color = Color(0, 0, 0), onComplete = null, ignoreHit: bool = true ) /* time:整体时间(不透明>渐出) color:颜色,默认为黑色 onComplete:可选委托事件,当颜色完成透明时调用 ignoreHit:转场是否屏蔽点击,默认为true */
设置当前使用的光标ID,默认为
0
,具体类型样式参考《世界资源实例汇总》。每次加载新的世界场景后,光标样式将重置到默认值。
function SetCursor( cursorID: int )
获取当前使用的光标ID,默认为
0
。
function GetCursor(): int
发送一条本地客户端消息(在消息框中)。
function Message( text: string )
发送一条本地公告\大文字消息,具体类型样式参考《世界资源实例汇总》。
function Announce( text: string, type: int = 0, time: float = 6 )
发送一条本地底部字幕消息。
function Subtitle( text: string )
绑定一个脚本按键(当前场景有效),可用于监听某个键被按下\抬起。
按键参数可填写UnityEngine.KeyCode(Enum)索引或名称作为按键参数。
function BindKey( keyTag: string, key1: string, key2: string = "None", key3: string = "None" ) /* keyTag:按键标签(用于识别) key1:按键1标准名称(如'H') key2:默认'None',否则表示组合键 key3:默认'None',否则表示组合键 */
取消绑定一个脚本按键,对其按键监听不再生效。
function UnbindKey( keyTag: string )
取消绑定所有脚本按键,对其按键监听不再生效。
function UnbindAllKey()
绑定一个模组公开按键(当前场景有效,支持设置界面自定义按键),可用于监听某个键被按下\抬起。
按键参数可填写UnityEngine.KeyCode(Enum)索引或名称作为按键参数。
补充:此方法设置的按键应该为【默认按键】,后续如果玩家自定义修改按键(如B),即使代码定义的仍然是【如H】,也会自动识别为玩家修改的【B】键。
(出于安全考虑,此类敏感方法仅限本地客户端使用,由主机下载的脚本无法使用)
function BindNativeKey( keyTag: string, key1: string, key2: string = "None", key3: string = "None" ) /* keyTag:按键标签(用于识别) key1:按键1标准名称(如'H') key2:默认'None',否则表示组合键 key3:默认'None',否则表示组合键 */
注意:此功能适合绑定一个【可供玩家自定义】的游戏按键,绑定后将会在【设置界面】自动出现对应的【按键绑定选项】。
按键绑定选项只会在通过BindNativeKey()
注册过的场景打开设置菜单时出现,通常情况下,开发者应该希望设置菜单在【Main】场景时也存在绑定选项,而不只是游戏绑定过的场景,那么应该在【Main】脚本将允许玩家自定义的按键提前绑定一次。
//Main入口场景 function OnScriptLoad() { //此处绑定 不需要编写OnNativeKeyDown等逻辑,因为只是做一个注册,以供【设置菜单】会出现对应的绑定选项 BindNativeKey("EnterVehicle", "E"); //绑定一个E键按钮(默认按键) //打开设置菜单,会出现对应的绑定按钮 CreateNativeView(1); } //MyWorld游戏玩法场景 function OnScriptLoad() { //此处绑定 需要编写OnNativeKeyDown等逻辑,因为这里是真正要用到按键的场景 BindNativeKey("EnterVehicle", "E"); //绑定一个E键按钮(默认按键) //打开设置菜单,会出现对应的绑定按钮 CreateNativeView(1); } function OnNativeKeyDown( key ) { if(key == "EnterVehicle") { DLog("按下进入载具按钮!"); } }
取消绑定一个模组公开按键,对其按键监听不再生效。
function UnbindNativeKey( keyTag: string )
取消绑定所有模组公开按键,对其按键监听不再生效。
function UnbindAllNativeKey()
绑定一个模组游戏设置选项,可理解为一种有关游戏选项的键值对。
如果是在公开状态下,默认因为没有翻译,会显示为一串翻译代码路径,可照葫芦画瓢修改翻译文件以正确显示文本。
(出于安全考虑,此类敏感方法仅限本地客户端使用,由主机下载的脚本无法使用)
function SetGameOption( keyPath: string, value: any = null, isPublic: bool = false, publicParam: any = null ) /* keyPath:选项键值\路径(强制路径规则) value:选项数值(特殊情况下可空),如果公开状态,设置菜单会根据此处类型自动更换形态(如float\int则是滑动条,bool则是开关) isPublic:是否公开(展示到设置菜单,可供玩家自定义),默认为false,不公开则只有键值对作用且不会保存数据 publicParam:公开后属性(参考下方规则填写,可空) */
路径规则 | 说明 |
---|---|
Game.XXX | 通常用于放置有关游戏玩法等设定 |
Audio.XXX | 通常用于放置有关游戏音频、声音等设定 |
Display.XXX | 通常用于放置有关游戏显示、界面等设定 |
Controller.XXX | 通常用于放置有关游戏控制、自定义按键等设定(特殊) 此选项如果需要添加自定义按键,应该使用 BindNativeKey() |
XXXXX.XXX | 自定义选项组(左侧的选项菜单) 可以根据当前游戏、模组、插件来新建一个单独的菜单 |
总结:设置游戏选项必须使用XXXXX.XXX
的键值方式,并且尽可能不要重复KeyTag
,否则会替换掉旧的选项。尽量在设计初期就确认选项类型,避免后期改变类型(如bool改string,可能引起异常)。
补充:XXXXX.InternalNull
是一个特殊空隙路径,填写此路径会默认被理解为是一个空行占位符号。
SetGameOption("Game.InternalNull"); //在当前顺序建立一个空行分割
获取一个模组游戏设置选项的值,可填写默认值参数(如果没有找到储存记录的话,返回参数2)。
function GetGameOption( keyTag: string, defaultValue: any = null )
从模组空间目录
Mod/Space
读取一个文件,如果文件不存在则反馈空白文本。(出于安全考虑,此方法对应写入权限仅限World端脚本使用)
function ReadFile( path: string ): string
尝试读取指定模组的持久化存储数据(可通过
SetModArchive()
写入修改),如不存在则返回空文本。注意:如果不填写参数,默认获取当前模组的数据。
function GetModArchive( package: string = null ): string
尝试读取【存档数据槽(
Slot
)】指定Key
的项目内容,如不存在则返回defaultValue
。
function GetSaveItem( key: string, slot: int = 0, defaultValue: any = null ): any
SetSaveItem("gold", 1000); //Save file to 'SaveData/SaveData_0.json' DLog("Your coin: " + GetSaveItem("gold"));
判断【存档数据槽(
Slot
)】指定Key
的项目内容是否为空(bool
)。
function ExistSaveItem( key: string, slot: int = 0 ): bool
DLog(ExistSaveItem("gold"));
判断【存档数据槽(
Slot
)】存档文件是否已被创建(bool
)。
function ExistSaveData( slot: int = 0 ): bool