这里会显示出您选择的修订版和当前版本之间的差别。
两侧同时换到之前的修订记录前一修订版后一修订版 | 前一修订版 | ||
scripting:client:main [2023/09/10 10:02] – bibiboxs | scripting:client:main [2024/04/04 18:29] (当前版本) – bibiboxs | ||
---|---|---|---|
行 2: | 行 2: | ||
# Client/Main | # Client/Main | ||
- | ==**注意:在当前版本下,`Client`脚本更适合实现客户端独有的功能、GUI界面等。** | + | ==**注意:在当前版本下,`Client`脚本更适合实现客户端独有的功能、GUI界面等。**== |
- | **有关世界内容的玩法(如:Player、Character、Vehicle等)建议优先使用`World`脚本实现。**== | + | ==**有关世界内容的玩法(如:Player、Character、Vehicle等)建议优先使用`World`脚本实现。**== |
+ | |||
+ | > 如果有某些功能只有ClientAPI支持,可以用`SendDataToServer`相关方法与服务端进行二次通信,以实现**“通过服务端让某个玩家执行一个ClientAPI”**。 | ||
行 13: | 行 15: | ||
> 当**客户端脚本**被完整加载后调用。 | > 当**客户端脚本**被完整加载后调用。 | ||
+ | > | ||
+ | > **注意:此事件并非是客户端首个运行事件,通常会等待`Player`完整加载后才会执行,因此部分有关`OnPlayerXXX`的事件可能会更加提前。** | ||
行 24: | 行 28: | ||
### OnFrameUpdate( deltaTime ) | ### OnFrameUpdate( deltaTime ) | ||
- | > 当脚本加载完成后每帧调用。 | + | > 当脚本加载完成后**每帧**调用。 |
由于此事件属于**客户端脚本**范畴,所以可以理解为每帧渲染事件,无须担心延迟问题。 | 由于此事件属于**客户端脚本**范畴,所以可以理解为每帧渲染事件,无须担心延迟问题。 | ||
行 30: | 行 34: | ||
``` | ``` | ||
deltaTime:float // | deltaTime:float // | ||
+ | ``` | ||
+ | |||
+ | |||
+ | |||
+ | ### OnFixedUpdate( fixedDeltaTime ) | ||
+ | |||
+ | > 当脚本加载完成后**固定增量时间**调用(与[Unity原理](https:// | ||
+ | |||
+ | 此事件会以`FixedUpdate`的方式每隔固定时间调用,通常情况下可以忽略使用此事件。 | ||
+ | |||
+ | ``` | ||
+ | fixedDeltaTime:float // | ||
``` | ``` | ||
行 112: | 行 128: | ||
### Exec() | ### Exec() | ||
- | > 执行一段脚本代码。 | + | > 执行一段脚本代码(Client\World脚本不互通)。 |
> | > | ||
- | > 代码内容可能出现报错,可以考虑使用try\catch进行防范。 | + | > 代码内容可能出现报错,考虑使用try\catch进行防范。 |
```javascript | ```javascript | ||
- | function Exec( string | + | function Exec( code: string |
``` | ``` | ||
- | ### QuitGame() | + | ### OpenUrl() |
- | > 退出游戏,关闭沙盘引擎程序。 | + | > 请求访问一个网络或本地路径,执行后将由玩家决定是否打开Url。 |
+ | > | ||
+ | > 如果希望访问一个本地路径(或执行),请将url路径前增加`file:// | ||
+ | |||
+ | ```javascript | ||
+ | function OpenUrl( url: string ) | ||
+ | ``` | ||
+ | |||
+ | |||
+ | |||
+ | ### LockGameMenu() | ||
+ | |||
+ | > 激活内置主菜单界面(锁定常驻显示,并**屏蔽Esc菜单**),并绑定其中的一项(索引`0\1`,只限2项)。 | ||
+ | > | ||
+ | > 如果对于模组主菜单**没有特殊\高级自定义需求**(否则应该考虑使用FairyGUI自制菜单),可以通过此方法**极快速**的建立一个**游戏原生主菜单**(类似:静态锁定的ESC菜单样式)。 | ||
+ | > | ||
+ | > 引擎目前仅支持自定义2个按钮项目(放置在顶部`0\1`),开发者可分别为其绑定【索引、按钮标题、按钮说明、按钮事件】。 | ||
+ | > | ||
+ | > **注意:此方法通常只需要在设为主菜单的场景执行一次,并且只在当前场景生效,==切换场景后将会自动解除绑定==(自动执行`UnlockGameMenu()`)。** | ||
+ | |||
+ | ```javascript | ||
+ | function LockGameMenu( index: int, title: string, info: string, callback: Action ) | ||
+ | ``` | ||
+ | |||
+ | ```javascript | ||
+ | function OnScriptLoad() | ||
+ | { | ||
+ | LockGameMenu(0, | ||
+ | CreateHost(" | ||
+ | }); | ||
+ | LockGameMenu(1, | ||
+ | ConnectHost(" | ||
+ | }); | ||
+ | } | ||
+ | ``` | ||
+ | |||
+ | |||
+ | |||
+ | ### UnlockGameMenu() | ||
+ | |||
+ | > 解除绑定内置主菜单界面按钮项目。 | ||
+ | > | ||
+ | > 如果解除后已经不存在任何自定义绑定项目,将自动关闭菜单并重设为**默认Esc菜单模式**。 | ||
+ | > | ||
+ | > **注意:如果参数设为-1,则表示解除全部项目。** | ||
+ | |||
+ | ```javascript | ||
+ | function UnlockGameMenu( index: int = -1 ) | ||
+ | ``` | ||
+ | |||
+ | |||
+ | |||
+ | ### SetGameMenuBGEffect() | ||
+ | |||
+ | > 设置游戏菜单背景效果开关(通常为`Blur`效果),默认开启,**模组周期全局生效**。 | ||
```javascript | ```javascript | ||
- | function | + | function |
``` | ``` | ||
行 145: | 行 215: | ||
| 1 | 游戏设置 | | 1 | 游戏设置 | ||
| 2 | 多人游戏浏览器 | | 2 | 多人游戏浏览器 | ||
- | | 4 | MOD模组管理 | + | | 4 | ~~MOD模组管理~~ |
*尽管有些ID没有被表格记录,但有可能仍然是有内容的,但未被记录的ID通常不具备通用性意义,在打开时将会别引擎阻断。* | *尽管有些ID没有被表格记录,但有可能仍然是有内容的,但未被记录的ID通常不具备通用性意义,在打开时将会别引擎阻断。* | ||
行 156: | 行 226: | ||
```javascript | ```javascript | ||
- | function ExistNativeView( | + | function ExistNativeView( type: int ): bool |
``` | ``` | ||
行 166: | 行 236: | ||
```javascript | ```javascript | ||
- | DestroyNativeView(int type = -1, bool hasEffect = true) | + | function |
// | // | ||
// | // | ||
行 178: | 行 248: | ||
```javascript | ```javascript | ||
- | function LoadNativeScene( | + | function LoadNativeScene( type: int ) |
``` | ``` | ||
行 221: | 行 291: | ||
- | ### CreateHost() | + | ### SendDataToServer() |
- | > 建立一个当前模组的服务器\房间世界。 | + | > 发送一条自定义数据消息到服务端,此功能合理使用可扩展许多效果。 |
> | > | ||
- | > 任何情况下,使用此方法都将**直接断开当前服务器并建立新的服务器**,请确保相关数据提前保存。 | + | > 服务端收到数据后,将由`OnPlayerStreamData()`事件接收。 |
- | + | ||
- | ```javascript | + | |
- | function CreateHost(map: string, script: string, port: int = 0, address: string = "", | + | |
- | ``` | + | |
- | + | ||
- | ```javascript | + | |
- | // | + | |
- | CreateHost(" | + | |
- | + | ||
- | // | + | |
- | // | + | |
- | CreateHost(" | + | |
- | + | ||
- | // | + | |
- | CreateHost(" | + | |
- | + | ||
- | // | + | |
- | // | + | |
- | ``` | + | |
- | + | ||
- | + | ||
- | + | ||
- | ### ConnectHost() | + | |
- | + | ||
- | > 连接并加载到指定的多人游戏服务器,开发者应自行编写代码,确保参数信息正确。 | + | |
> | > | ||
- | > 任何情况下,使用此方法都将**直接断开当前服务器并尝试连接到新的服务器**。 | + | > **注意:这里不应该放置特别大的数据内容,否则可能造成网络阻塞。** |
```javascript | ```javascript | ||
- | function | + | function |
``` | ``` | ||
- | ```javascript | ||
- | // | ||
- | ConnectHost(" | ||
- | // | ||
- | // | ||
- | ``` | ||
+ | ### SetChatEnabled() | ||
- | + | > 设置游戏聊天框开关。 | |
- | ### Disconnect() | + | |
- | + | ||
- | > 断开当前正在连接的服务器\房间\世界,并回到入口场景(`Main`)。 | + | |
> | > | ||
- | > 任何情况下,使用此方法都将**直接断开当前服务器**。 | + | > *此功能可用作主菜单界面,此时通常不希望玩家使用“聊天”功能。* |
```javascript | ```javascript | ||
- | function | + | function |
``` | ``` | ||
- | ### Reconnect() | + | ### GetChatEnabled() |
- | > 断开当前正在连接的服务器\房间\世界,并尝试重新连接到上次的服务器(如果没有记录,则不会生效)。 | + | > 获取游戏聊天框开关。 |
- | > | + | |
- | > 任何情况下,使用此方法都将**直接断开当前服务器**。 | + | |
- | > | + | |
```javascript | ```javascript | ||
- | function | + | function |
``` | ``` | ||
- | ### SendDataToServer() | + | ### SetChatPanelPivot() |
- | > 发送一条自定义数据消息到服务端,此功能合理使用可扩展许多效果。 | + | > 设置游戏聊天框锚点位置(强制),默认值为`-1`(遵循游戏默认设置),通过此方法设定位置后,即使玩家在游戏选项设置了锚点位置,也会优先使用当前方法所设置的位置。 |
> | > | ||
- | > 服务端收到数据后,将由`OnPlayerStreamData()`事件接收。 | + | > *此功能适用于部分U丰富的模组,可能不希望聊天框占用模组UI位置(例如血条、状态条、信息面板等),可以使用此方法强制设定聊天框位置。* |
- | > | + | |
- | > **注意:这里不应该放置特别大的数据内容,否则可能造成网络阻塞。** | + | |
```javascript | ```javascript | ||
- | function | + | function |
``` | ``` | ||
- | |||
- | |||
- | |||
- | ### SetChatEnabled() | ||
- | |||
- | > 设置是否允许开启游戏聊天窗口,默认为`true`,否则将无法通过正常方式打开聊天框(但可正常收到消息)。 | ||
- | > | ||
- | > *此功能可用作主菜单界面,此时通常不希望玩家使用“聊天”功能。* | ||
- | |||
```javascript | ```javascript | ||
- | function SetChatEnabled( enable: bool ) | + | SetChatPanelPivot(-1); //Use engine config (default) |
+ | SetChatPanelPivot(0); | ||
+ | SetChatPanelPivot(1); | ||
+ | SetChatPanelPivot(2); | ||
``` | ``` | ||
- | ### | + | ### ScreenFade() |
> 执行一次全屏转场(`Alpha: | > 执行一次全屏转场(`Alpha: | ||
```javascript | ```javascript | ||
- | function ScreenFade( time: float, middleTime = 0, color: Color = Color(0, 0, 0), onMiddle = null, ignoreHit: bool = true ) | + | function ScreenFade( time: float, middleTime = 0, color: Color = Color(0, 0, 0), isTop: bool = true, onMiddle = null, ignoreHit: bool = true ) |
/* | /* | ||
time:渐变时间(渐入> | time:渐变时间(渐入> | ||
middleTime:不透明延迟时间,默认为0,否则将等待X秒后再进行透明渐变 | middleTime:不透明延迟时间,默认为0,否则将等待X秒后再进行透明渐变 | ||
color:颜色,默认为黑色 | color:颜色,默认为黑色 | ||
+ | isTop:是否顶层,默认为true | ||
onMiddle:可选委托事件,当颜色完成不透明时调用 | onMiddle:可选委托事件,当颜色完成不透明时调用 | ||
ignoreHit:转场是否屏蔽点击,默认为true | ignoreHit:转场是否屏蔽点击,默认为true | ||
行 341: | 行 368: | ||
```javascript | ```javascript | ||
- | function ScreenFadeIn( time: float, color: Color = Color(0, 0, 0), onComplete = null, ignoreHit: bool = true ) | + | function ScreenFadeIn( time: float, color: Color = Color(0, 0, 0), isTop: bool = true, onComplete = null, ignoreHit: bool = true ) |
/* | /* | ||
time:整体时间(渐入> | time:整体时间(渐入> | ||
color:颜色,默认为黑色 | color:颜色,默认为黑色 | ||
+ | isTop:是否顶层,默认为true | ||
onComplete:可选委托事件,当颜色完成不透明时调用 | onComplete:可选委托事件,当颜色完成不透明时调用 | ||
ignoreHit:转场是否屏蔽点击,默认为true | ignoreHit:转场是否屏蔽点击,默认为true | ||
行 357: | 行 385: | ||
```javascript | ```javascript | ||
- | function ScreenFadeOut( time: float, color: Color = Color(0, 0, 0), onComplete = null, ignoreHit: bool = true ) | + | function ScreenFadeOut( time: float, color: Color = Color(0, 0, 0), isTop: bool = true, onComplete = null, ignoreHit: bool = true ) |
/* | /* | ||
time:整体时间(不透明> | time:整体时间(不透明> | ||
color:颜色,默认为黑色 | color:颜色,默认为黑色 | ||
+ | isTop:是否顶层,默认为true | ||
onComplete:可选委托事件,当颜色完成透明时调用 | onComplete:可选委托事件,当颜色完成透明时调用 | ||
ignoreHit:转场是否屏蔽点击,默认为true | ignoreHit:转场是否屏蔽点击,默认为true | ||
行 368: | 行 397: | ||
- | ### SetCursor() | + | ### Transition() |
- | > 设置当前使用的光标ID,默认为`0`,具体类型样式参考[《世界资源实例汇总》](reference/ | + | > 执行一次全屏转场特效(`Alpha: |
- | > | + | |
- | > 每次加载新的世界场景后,光标样式将重置到默认值。 | + | |
```javascript | ```javascript | ||
- | function | + | function |
``` | ``` | ||
+ | - **type:**转场特效类型 | ||
+ | - **addTime:**转场中途覆盖后,等待的延迟时间(默认为`0`,即为立即渐出) | ||
+ | - **color:**转场特效颜色 | ||
+ | - **action:**当转场中途完全覆盖时执行代码 | ||
+ | - **isOut:**是否立即淡出 | ||
+ | | Type | 说明 | ||
+ | | ---- | -------------------------------------- | | ||
+ | | 0 | 平滑淡入、淡出 | ||
+ | | 1 | 左右对撞、撞开 | ||
+ | | 2 | 上下对撞、撞开 | ||
+ | | 3 | 向右推动覆盖、继续向右移出 | ||
+ | | 4 | 上下分别向左右推动覆盖(类似街机游戏) | | ||
+ | | 5 | 圆圈缩小覆盖、放大淡出 | ||
+ | | 6 | 方块旋转覆盖、类似相机镜头 | ||
+ | | 7 | 多个方块覆盖、淡出 | ||
+ | | 8 | 多个菱形覆盖、淡出 | ||
+ | | 9 | 画笔涂擦覆盖、淡出 | ||
+ | | 10 | 噪声覆盖、淡出 | ||
+ | | 11 | 液体覆盖、淡出 | ||
- | ### GetCursor() | ||
- | > 获取当前使用的光标ID,默认为`0`。 | ||
- | |||
- | ```javascript | ||
- | function GetCursor(): | ||
- | ``` | ||
行 465: | 行 505: | ||
> | > | ||
> **补充:此方法设置的按键应该为【默认按键】,后续如果玩家自定义修改按键(如B),即使代码定义的仍然是【如H】,也会自动识别为玩家修改的【B】键。** | > **补充:此方法设置的按键应该为【默认按键】,后续如果玩家自定义修改按键(如B),即使代码定义的仍然是【如H】,也会自动识别为玩家修改的【B】键。** | ||
+ | > | ||
+ | > ==(出于安全考虑,此类敏感方法无法修改引擎内置按键,且仅限本地客户端使用,由主机下载的脚本无法使用)== | ||
```javascript | ```javascript | ||
行 515: | 行 557: | ||
> 取消绑定一个**模组公开按键**,对其按键监听不再生效。 | > 取消绑定一个**模组公开按键**,对其按键监听不再生效。 | ||
+ | > | ||
+ | > (出于安全考虑,此类敏感方法无法修改引擎内置按键,且仅限本地客户端使用,由主机下载的脚本无法使用) | ||
```javascript | ```javascript | ||
行 524: | 行 568: | ||
### UnbindAllNativeKey() | ### UnbindAllNativeKey() | ||
- | > 取消绑定所有**模组公开按键**,对其按键监听不再生效。 | + | > 取消绑定所有**模组公开按键**,对其按键监听不再生效()。 |
```javascript | ```javascript | ||
行 537: | 行 581: | ||
> | > | ||
> 如果是在公开状态下,默认因为没有翻译,会显示为一串翻译代码路径,可照葫芦画瓢**修改翻译文件**以正确显示文本。 | > 如果是在公开状态下,默认因为没有翻译,会显示为一串翻译代码路径,可照葫芦画瓢**修改翻译文件**以正确显示文本。 | ||
+ | > | ||
+ | > ==(出于安全考虑,此类敏感方法无法修改引擎内置选项,且仅限本地客户端使用,由主机下载的脚本无法使用)== | ||
```javascript | ```javascript | ||
行 580: | 行 626: | ||
> 从模组空间目录`Mod/ | > 从模组空间目录`Mod/ | ||
> | > | ||
- | > 注意:由于安全原因,Client脚本无法写入文件,只有World脚本可写入。 | + | > ==(出于安全考虑,此方法对应**写入权限**仅限World端脚本使用)== |
```javascript | ```javascript | ||
function ReadFile( path: string ): string | function ReadFile( path: string ): string | ||
``` | ``` | ||
+ | |||
+ | |||
+ | |||
+ | ### GetModArchive() | ||
+ | |||
+ | > 尝试读取**指定模组**的持久化存储数据(可通过`SetModArchive()`写入修改),如不存在则返回空文本。 | ||
+ | > | ||
+ | > 注意:如果不填写参数,默认获取当前模组的数据。 | ||
+ | |||
+ | ```javascript | ||
+ | function GetModArchive( package: string = null ): string | ||
+ | ``` | ||
+ | |||
+ | |||
+ | |||
+ | ### GetSaveItem() | ||
+ | |||
+ | > 尝试读取【存档数据槽(`Slot`)】指定`Key`的项目内容,如不存在则返回`defaultValue`。 | ||
+ | |||
+ | ```javascript | ||
+ | function GetSaveItem( key: string, slot: int = 0, defaultValue: | ||
+ | ``` | ||
+ | |||
+ | ```javascript | ||
+ | SetSaveItem(" | ||
+ | DLog(" | ||
+ | ``` | ||
+ | |||
+ | |||
+ | |||
+ | ### ExistSaveItem() | ||
+ | |||
+ | > 判断【存档数据槽(`Slot`)】指定`Key`的**项目内容是否为空(`bool`)**。 | ||
+ | |||
+ | ```javascript | ||
+ | function ExistSaveItem( key: string, slot: int = 0 ): bool | ||
+ | ``` | ||
+ | |||
+ | ```javascript | ||
+ | DLog(ExistSaveItem(" | ||
+ | ``` | ||
+ | |||
+ | |||
+ | |||
+ | ### ExistSaveData() | ||
+ | |||
+ | > 判断【存档数据槽(`Slot`)】存档文件是否已被创建(`bool`)。 | ||
+ | |||
+ | ```javascript | ||
+ | function ExistSaveData( slot: int = 0 ): bool | ||
+ | ``` | ||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||
</ | </ |