这里会显示出您选择的修订版和当前版本之间的差别。
两侧同时换到之前的修订记录前一修订版后一修订版 | 前一修订版 | ||
scripting:native:main [2023/09/08 15:58] – bibiboxs | scripting:native:main [2024/03/31 16:57] (当前版本) – bibiboxs | ||
---|---|---|---|
行 6: | 行 6: | ||
==此文档内所代码均可在**Client**和**World**脚本及其子脚本直接进行使用。== | ==此文档内所代码均可在**Client**和**World**脚本及其子脚本直接进行使用。== | ||
- | > 标注原生(Native)类型的数据、函数、常量等,它们都基于原生类。 | + | > 标注原生(Native)类型的常量、类型、事件、函数方法等,它们都基于原生`Native`类。 |
> | > | ||
- | > 在脚本开发时可省略前缀`Native.XXXX`,而直接使用`XXXX()`即可。 | + | > 在脚本开发时可省略前缀`Native.XXXX`,而直接使用`XXXX`即可。 |
- | ## NativeType | + | ## Const |
+ | |||
+ | ### VECTOR_NULL | ||
+ | |||
+ | > 三维坐标默认“空”坐标。 | ||
+ | > | ||
+ | > 由于`Vector`是一个**值类型**,所以表示为空时不应该直接设为`null`,在通常情况下应该使用**常量代替**。 | ||
+ | |||
+ | ```javascript | ||
+ | const VECTOR_NULL = Vector3(-128000, | ||
+ | ``` | ||
+ | |||
+ | |||
+ | |||
+ | ## Type | ||
### Vector() | ### Vector() | ||
行 20: | 行 34: | ||
```javascript | ```javascript | ||
let pos = Vector(0, 0, 10); //X, Y, Z | let pos = Vector(0, 0, 10); //X, Y, Z | ||
+ | |||
+ | //Extend | ||
+ | pos.magnitude; | ||
+ | pos.normalized; | ||
``` | ``` | ||
+ | |||
+ | - `x`:X轴数值(左右) | ||
+ | - `y`:Y轴数值(上下) | ||
+ | - `z`:Z轴数值(前后) | ||
行 32: | 行 54: | ||
let newColor2 = Color(255, 255, 255); //R, G, B, A=255 | let newColor2 = Color(255, 255, 255); //R, G, B, A=255 | ||
``` | ``` | ||
+ | |||
+ | - `r`:颜色数值 | ||
+ | - `g`:颜色数值 | ||
+ | - `b`:颜色数值 | ||
+ | - `a`:透明度数值 | ||
+ | |||
+ | |||
+ | |||
+ | ### RayTraceResult() | ||
+ | |||
+ | > (只读)射线检测函数的返回值,属性可获取射线检测结果(是否碰撞、最终坐标、检测实体等)。 | ||
+ | |||
+ | - `IsHit`:是否碰撞射线 | ||
+ | - `Point`:射线检测坐标(如没有产生碰撞,则坐标即是默认终点) | ||
+ | - `Entity`:射线碰撞实体(如果对象不是标准的`Entity`实体,或对象为**静态模型(本地静态模型)**,则返回为`null`) | ||
+ | |||
+ | |||
+ | |||
+ | ### VectorPoint() | ||
+ | |||
+ | > 坐标点结构类型,表示一组由**坐标、旋转、缩放**三个Vector类型组成的对象,并且包含一个**Tag标签**以供可选筛选。 | ||
+ | > | ||
+ | > 此类型只有坐标记录的功能,通常用于地图编辑器(ID5物体)与脚本的可见预设坐标交互。 | ||
+ | > | ||
+ | > 使用此结构时**不应该使用**`new VectorPoint| VectorPoint()`这类方法,而是应该使用`AddVectorPoint()`等方法增加到后台。 | ||
+ | > | ||
+ | > **注意:结构内的三种Vector类型虽然命名不同,但均是以`Vector`作为属性类型,因此在某些情况下可以忽略命名问题。** | ||
+ | |||
+ | - `Tag`:筛选标签(可空`"" | ||
+ | - `Pos`:坐标(Vector,不可空,至少要有一个) | ||
+ | - `Angle`:旋转角度(Vector,可空) | ||
+ | - `Scale`:缩放(Vector,可空) | ||
行 65: | 行 119: | ||
## Function | ## Function | ||
+ | |||
+ | ### UnloadMod() | ||
+ | |||
+ | > 卸载当前引擎,回到沙盘引擎初始界面。 | ||
+ | > | ||
+ | > **注意:通常情况下,可以考虑优先将【退出游戏】操作替换为此方法,而不是直接`QuitGame()`关闭游戏。** | ||
+ | |||
+ | ```javascript | ||
+ | function UnloadMod() | ||
+ | ``` | ||
+ | |||
+ | |||
+ | |||
+ | ### QuitGame() | ||
+ | |||
+ | > 退出游戏,关闭沙盘引擎程序。 | ||
+ | |||
+ | ```javascript | ||
+ | function QuitGame() | ||
+ | ``` | ||
+ | |||
+ | |||
### DLog() | ### DLog() | ||
行 106: | 行 182: | ||
```javascript | ```javascript | ||
function LoadScript( path: string ) | function LoadScript( path: string ) | ||
- | /* | ||
- | path:脚本目录下的 同级或子级 脚本文件路径(例如:" | ||
- | */ | ||
``` | ``` | ||
+ | |||
+ | - `path`:脚本目录下的 同级或子级 脚本文件路径(例如:" | ||
```javascript | ```javascript | ||
行 132: | 行 207: | ||
DLog(" | DLog(" | ||
} | } | ||
+ | ``` | ||
+ | |||
+ | |||
+ | |||
+ | ### CreateHost() | ||
+ | |||
+ | > 建立一个当前模组的服务器\房间世界。 | ||
+ | > | ||
+ | > 任何情况下,使用此方法都将**直接断开当前服务器并建立新的服务器**,请确保相关数据提前保存。 | ||
+ | > | ||
+ | > **补充:如果不填写任何参数,则表示加载到初始入口世界(`Main`世界)。** | ||
+ | > | ||
+ | > **==注意:我们建议不指定固定的端口号,而是使用`Mod.json -> NetworkPort`机制设定模组端口,并设置当前方法参数`Port=0`(自动识别模组`NetworkPort`)。==** | ||
+ | |||
+ | ```javascript | ||
+ | function CreateHost( map: string, script: string, port: int = 0, address: string = "", | ||
+ | ``` | ||
+ | |||
+ | > 载入并创建一个地图为“test2”且脚本为“Main2”的服务器。 | ||
+ | |||
+ | ```javascript | ||
+ | CreateHost(" | ||
+ | ``` | ||
+ | |||
+ | > 载入并创建一个地图为“test2”且脚本为“Main2”,端口指定为8195的服务器(0为默认端口,并非随机端口)。 | ||
+ | > | ||
+ | > 默认端口配置文件:Mod.json `[" | ||
+ | |||
+ | ```javascript | ||
+ | CreateHost(" | ||
+ | ``` | ||
+ | |||
+ | > 载入并创建一个地图为“test2”且脚本为“Main2”,端口随意,但使用SteamP2P网络的房间(地址参数填写`steam`)。 | ||
+ | |||
+ | ```javascript | ||
+ | CreateHost(" | ||
+ | ``` | ||
+ | |||
+ | > `UserData`参数可传递给服务器一个前置字符串参数(长度限制0~256,可用Json扩展),可提前告知服务器一些【玩家自身】自定义信息。 | ||
+ | > | ||
+ | > **(World脚本可用player.UserData读取内容)** | ||
+ | |||
+ | ```javascript | ||
+ | CreateHost(" | ||
+ | ``` | ||
+ | |||
+ | > `additional`参数可指定是否使用地图附加内容(例如:地图内创建的载具),默认为`true`,如果只希望加载纯净的地图则设置为`false`。 | ||
+ | |||
+ | ```javascript | ||
+ | CreateHost(" | ||
+ | ``` | ||
+ | |||
+ | |||
+ | |||
+ | ### ConnectHost() | ||
+ | |||
+ | > 连接并加载到指定的多人游戏服务器,开发者应自行编写代码,确保参数信息正确。 | ||
+ | > | ||
+ | > 任何情况下,使用此方法都将**直接断开当前服务器并尝试连接到新的服务器**。 | ||
+ | |||
+ | ```javascript | ||
+ | function ConnectHost(address: | ||
+ | ``` | ||
+ | |||
+ | > 尝试连接并加载到指定IP地址的服务器 | ||
+ | > | ||
+ | > 方法与CreateHost部分相同,`0`表示默认端口,服务器密码可空 | ||
+ | > | ||
+ | > `UserData`参数可传递给服务器一个前置字符串参数(长度限制0~256,可用Json扩展),可提前告知服务器一些【玩家自身】自定义信息 | ||
+ | > | ||
+ | > **(World脚本可用player.UserData读取内容)** | ||
+ | |||
+ | ```javascript | ||
+ | ConnectHost(" | ||
+ | ``` | ||
+ | |||
+ | |||
+ | |||
+ | ### Disconnect() | ||
+ | |||
+ | > 断开当前正在连接的服务器\房间\世界,并回到入口场景(`Main`)。 | ||
+ | > | ||
+ | > 任何情况下,使用此方法都将**直接断开当前服务器**。 | ||
+ | |||
+ | ```javascript | ||
+ | function Disconnect() | ||
``` | ``` | ||
行 138: | 行 299: | ||
### Reconnect() | ### Reconnect() | ||
- | > 重新建立连接当前服务器(重新建立\重连)。 | + | > 断开当前正在连接的服务器\房间\世界,并尝试重新连接到上次的服务器(如果没有记录,则不会生效)。 |
+ | > | ||
+ | > 任何情况下,使用此方法都将**直接断开当前服务器**。 | ||
+ | > | ||
```javascript | ```javascript | ||
行 146: | 行 310: | ||
- | ### CheckServerMode() | + | ### IsServerMode() |
- | > 获取当前是否为**服务端模式**(仅作为服务器启动)。 | + | > 获取当前是否为**服务端模式**(仅作为专用服务器启动,通常由`bat`格式扩展)。 |
> | > | ||
```javascript | ```javascript | ||
- | function | + | function |
+ | ``` | ||
+ | |||
+ | |||
+ | |||
+ | ### IsNewPlayer() | ||
+ | |||
+ | > 判断当前是否为**玩家初次进入此模组**。 | ||
+ | |||
+ | ```javascript | ||
+ | function IsNewPlayer(): bool | ||
``` | ``` | ||
行 282: | 行 456: | ||
``` | ``` | ||
+ | |||
+ | |||
+ | ### GetMapCount() | ||
+ | |||
+ | > 获取当前用户本地地图数量,可使用`filter`进行条件过滤。 | ||
+ | |||
+ | ```javascript | ||
+ | function GetMapCount( filter: int = 0 ): int | ||
+ | ``` | ||
+ | |||
+ | | 过滤Filter | 说明 | ||
+ | | ---------- | ---------------------------- | | ||
+ | | 0 | 默认全部(模组> | ||
+ | | 1 | 只获取模组内置地图 | ||
+ | | 2 | 只获取`Map`地图目录 | ||
+ | | 3 | 只获取`Map\Download`地图目录 | | ||
+ | |||
+ | |||
+ | |||
+ | ### GetMapByIndex() | ||
+ | |||
+ | > 获取当前用户**指定索引**本地地图**文件名称**,通常搭配`GetMapCount()`遍历使用,可使用`filter`进行条件过滤。 | ||
+ | |||
+ | ```javascript | ||
+ | function GetMapByIndex( index: int, filter: int = 0 ): string | ||
+ | ``` | ||
+ | |||
+ | ```javascript | ||
+ | let mapCount = GetMapCount(); | ||
+ | for(let i=0; | ||
+ | { | ||
+ | DLog(i + ">" | ||
+ | } | ||
+ | ``` | ||
+ | |||
+ | |||
+ | ### GenerateUUID() | ||
+ | |||
+ | > 生成一段唯一的UUID字符串(GUID)。 | ||
+ | > | ||
+ | > 在绝大部分情况下,由此方法生成的UUID应该是全球唯一的。 | ||
+ | |||
+ | ```javascript | ||
+ | function GenerateUUID(): | ||
+ | ``` | ||
行 291: | 行 510: | ||
function DistancePoint( pos: Vector, pos2: Vector ): float | function DistancePoint( pos: Vector, pos2: Vector ): float | ||
``` | ``` | ||
+ | |||
+ | |||
+ | |||
+ | ### OverlapEntity() | ||
+ | |||
+ | > 在指定位置**检测并记录范围检测世界实体**(某坐标指定范围内所有对象),可用于检测指定位置的范围内实体对象(基于`Entity`的核心对象)。 | ||
+ | > | ||
+ | > 如果只希望获取`Entity`基础类型中其中的一个或多个子类,可使用`filter`参数进行筛选(位操作)。 | ||
+ | > | ||
+ | > **注意:此方法只用于单次记录,==并返回检测到的数量==,应搭配使用`OverlapEntityByIndex()`获取具体索引的对象实例。** | ||
+ | > | ||
+ | > ==(此方法在World\Client脚本有隔离机制,无须担心结果重叠覆盖问题)== | ||
+ | |||
+ | ```javascript | ||
+ | function OverlapEntity( pos: Vector, radius: float, filter: int = 0 ): int | ||
+ | ``` | ||
+ | |||
+ | | 过滤(Filter) | 说明 | ||
+ | | -------------- | ---------- | | ||
+ | | 0 | 默认全部 | ||
+ | | 1 | Model | | ||
+ | | 2 | Character | ||
+ | | 4 | Vehicle | ||
+ | | 8 | Pickup | ||
+ | | 16 | Checkpoint | | ||
+ | |||
+ | ```javascript | ||
+ | //Only check ' | ||
+ | OverlapEntity(Vector(0, | ||
+ | //or | ||
+ | OverlapEntity(Vector(0, | ||
+ | ``` | ||
+ | |||
+ | |||
+ | |||
+ | ### OverlapEntityByIndex() | ||
+ | |||
+ | > 获取由`OverlapEntity()`记录后的**指定索引实例**,如不存在或已销毁则返回`null`。 | ||
+ | > | ||
+ | > **注意:此方法使用前必须执行一次`OverlapEntity()`,以此获取最新的范围内检测信息。** | ||
+ | > | ||
+ | > ==(此方法在World\Client脚本有隔离机制,无须担心结果重叠覆盖问题)== | ||
+ | |||
+ | ```javascript | ||
+ | function OverlapEntityByIndex( index: int ): Entity | ||
+ | ``` | ||
+ | |||
+ | ```javascript | ||
+ | let count = OverlapEntity(Vector(0, | ||
+ | if(count > 0) | ||
+ | { | ||
+ | DLog(i + " | ||
+ | } | ||
+ | ``` | ||
+ | |||
+ | |||
+ | |||
+ | ### InPoly() | ||
+ | |||
+ | > 获取某个点是否在多边形点范围内(X\Z是否在某片2D形状范围内)。 | ||
+ | > | ||
+ | > **注意:此方法判断坐标系只需要X\Z轴,Y轴数值可以忽略(最低要求输入3个多边形点,最多支持8个多边形点验证)。** | ||
+ | |||
+ | ```javascript | ||
+ | function InPoly( pos: Vector, p1: Vector, p2: Vector, p3: Vector, p4: Vector = null, p5: Vector = null, p6: Vector = null, p7: Vector = null, p8: Vector = null ): bool | ||
+ | ``` | ||
+ | ```javascript | ||
+ | DLog(InPoly(Vector(0, | ||
+ | ``` | ||
+ | |||
+ | |||
+ | |||
+ | ### GetLanguage() | ||
+ | |||
+ | > 获取**当前[引擎语言](developer/ | ||
+ | > | ||
+ | > **例如:沙盘引擎本体支持A语言,但当前模组可能仅支持B语言,此时返回的是A语言的标准英文名称。** | ||
+ | > | ||
+ | > ==通常情况下,开发者应该主动参考此方法获得的语言名称。此方法也会在游戏启动时自动识别`GetSystemLanguage()`系统语言兼容。== | ||
+ | |||
+ | ```javascript | ||
+ | function GetLanguage(): | ||
+ | ``` | ||
+ | |||
+ | |||
+ | |||
+ | ### GetModLanguage() | ||
+ | |||
+ | > 获取**当前[模组语言](developer/ | ||
+ | > | ||
+ | > **例如:沙盘引擎默认暂不支持A语言,但当前模组支持B语言,此时返回的是B语言的标准英文名称。** | ||
+ | |||
+ | ```javascript | ||
+ | function GetLanguage(): | ||
+ | ``` | ||
+ | |||
+ | |||
+ | |||
+ | ### GetSystemLanguage() | ||
+ | |||
+ | > 获取**当前[系统识别语言](developer/ | ||
+ | > | ||
+ | |||
+ | ```javascript | ||
+ | function GetLanguage(): | ||
+ | ``` | ||
+ | |||
+ | |||
+ | |||
+ | ### GetLanguageText() | ||
+ | |||
+ | > 获取[游戏语言文件](developer/ | ||
+ | |||
+ | ```javascript | ||
+ | function GetLanguageText( key: string, params: any... ): string | ||
+ | function GetLanguageText( key: string, index: int = 0, params: any... ): string | ||
+ | ``` | ||
+ | |||
+ | - `key`:游戏语言文件内的完整路径 | ||
+ | - `index`:可省略参数,表示语言结构数组索引,默认或省略为`0` | ||
+ | - `params`:如果目标语言文本拥有`{0}{1}{2}`占位替换符号,可以根据索引填写后续参数 | ||
+ | |||
+ | > 此方法的使用扩展性比较强,几乎可覆盖大多数多语言文本需求。 | ||
+ | > | ||
+ | > 同时为了方便开发者减少代码量,这里提供了一个简单的映射方法`_Language()`,与此函数作用完全相同。 | ||
+ | |||
+ | ```javascript | ||
+ | GetLanguageText(" | ||
+ | _Language(" | ||
+ | |||
+ | _Language(" | ||
+ | _Language(" | ||
+ | ``` | ||
+ | |||
+ | |||
+ | |||
+ | ### GetVectorPointCount() | ||
+ | |||
+ | > 获取当前世界所有满足`Tag`标签筛选的`VectorPoint`坐标点**数量**。 | ||
+ | |||
+ | ```javascript | ||
+ | function GetVectorPointCount( tag: string = "" | ||
+ | ``` | ||
+ | |||
+ | |||
+ | |||
+ | ### GetVectorPoint() | ||
+ | |||
+ | > 获取当前世界所有满足`Tag`标签筛选的`VectorPoint`坐标点**对象**,通常搭配`GetVectorPointCount()`遍历使用。 | ||
+ | > | ||
+ | > **具体`VectorPoint`数值对象参考本文上方`Type`部分。** | ||
+ | > | ||
+ | > **==注意:通过此方法获取的对象可进行set修改其内部属性,仅限本地使用,不会同步到其他客户端。==** | ||
+ | |||
+ | ```javascript | ||
+ | function GetVectorPoint( tag: string, index: int = 0 ): VectorPoint | ||
+ | ``` | ||
+ | |||
+ | ```javascript | ||
+ | //Test Code | ||
+ | let tag = " | ||
+ | let count = GetVectorPointCount(tag); | ||
+ | for(let i=0; | ||
+ | { | ||
+ | DLog(GetVectorPoint(tag, | ||
+ | } | ||
+ | ``` | ||
+ | |||
+ | |||
+ | |||
+ | ### AddVectorPoint() | ||
+ | |||
+ | > 增加一条指定`Tag`标签的`VectorPoint`坐标点**对象**,如果不需要`Tag`标签也可以留空(这会导致无法通过`RemoveVectorPoint()`针对删除)。 | ||
+ | |||
+ | ```javascript | ||
+ | function AddVectorPoint( tag: string, pos: Vector, angle: Vector = null, scale: Vector = null ): VectorPoint | ||
+ | ``` | ||
+ | |||
+ | ```javascript | ||
+ | //Test Code | ||
+ | AddVectorPoint("", | ||
+ | AddVectorPoint(" | ||
+ | ``` | ||
+ | |||
+ | |||
+ | |||
+ | ### RemoveVectorPoint() | ||
+ | |||
+ | > 移除**所有**符合指定`Tag`标签条件的`VectorPoint`坐标点**对象**(也可以留空`Tag`标签,会删除所有没有`Tag`标签的坐标点对象)。 | ||
+ | |||
+ | ```javascript | ||
+ | function RemoveVectorPoint( tag: string = "" | ||
+ | ``` | ||
+ | |||
+ | ```javascript | ||
+ | //Test Code | ||
+ | RemoveVectorPoint(); | ||
+ | RemoveVectorPoint(" | ||
+ | ``` | ||
+ | |||
+ | |||
+ | ### FormatRichText() | ||
+ | > 格式化指定文本为引擎富文本(并非传统意义的`Richtext`),这将使一段文本执行以下操作:**链接地址标蓝、@玩家名(高亮)、# | ||
+ | |||
+ | ```javascript | ||
+ | function FormatRichText( text: string, onlyEmoji: bool = false ) | ||
+ | ``` | ||
+ | |||
+ | - **onlyEmoji:**如果设置为`true`,则`# | ||
+ | |||
+ | ```javascript | ||
+ | FormatRichText("# | ||
+ | FormatRichText("# | ||
+ | ``` | ||
+ | |||
+ | |||
+ | |||
+ | |||
</ | </ |