沙盘引擎 (SEngine)

创意诞生沙盘世界，不止如此想象！

用户工具

站点工具

您在这里: 《沙盘引擎》主页 » 脚本开发及API » native » Native/Main
您的足迹: • Client/Main • Client/Vehicle • CharacterAI
scripting:native:main

📚 差别

这里会显示出您选择的修订版和当前版本之间的差别。

到此差别页面的链接

两侧同时换到之前的修订记录前一修订版
后一修订版		前一修订版
scripting:native:main [2023/09/05 13:52] – bibiboxsscripting:native:main [2024/03/31 16:57] (当前版本) – bibiboxs
行 2: 行 2:
 # Native/Main # Native/Main
  
-原生脚本是一个内置的脚本功能类，此分类下还有更多通用的扩展工具类。+原生脚本是一个内置的通用脚本功能类，此分类下还有更多通用的扩展工具类。
  
 ==此文档内所代码均可在**Client**和**World**脚本及其子脚本直接进行使用。== ==此文档内所代码均可在**Client**和**World**脚本及其子脚本直接进行使用。==
  
-> 标注原生（Native）类型的数据、函数、常量等，它们都基于原生类。+> 标注原生（Native）类型的常量、类型、事件、函数方法等，它们都基于原生`Native`类。
 > >
-> 在脚本开发时可省略前缀`Native.XXXX`，而直接使用`XXXX()`即可。+> 在脚本开发时可省略前缀`Native.XXXX`，而直接使用`XXXX`即可。 
 + 
 + 
 + 
 +## Const 
 + 
 +### VECTOR_NULL 
 + 
 +> 三维坐标默认“空”坐标。 
 +> 
 +> 由于`Vector`是一个**值类型**，所以表示为空时不应该直接设为`null`，在通常情况下应该使用**常量代替**。 
 + 
 +```javascript 
 +const VECTOR_NULL = Vector3(-128000, -128000, -128000); 
 +``` 
 + 
 + 
 + 
 +## Type 
 + 
 +### Vector() 
 + 
 +> 三维坐标结构类型，沙盘引擎世界坐标的通用形式，其中Y轴表示高度。 
 + 
 +```javascript 
 +let pos = Vector(0, 0, 10); //X, Y, Z 
 + 
 +//Extend 
 +pos.magnitude; //magnitude（向量长度） 
 +pos.normalized; //normalized（归一化） 
 +``` 
 + 
 +- `x`：X轴数值（左右） 
 +- `y`：Y轴数值（上下） 
 +- `z`：Z轴数值（前后） 
 + 
 + 
 + 
 +### Color() 
 + 
 +> 颜色结构类型，表示一种RGBA组成的颜色，默认情况下`A=255`（可省略）。 
 + 
 +```javascript 
 +let newColor = Color(255, 255, 255, 255); //R, G, B, A 
 +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，可空） 
 + 
 + 
 + 
 +## Event 
 + 
 +### OnGameOptionUpdate( optionKey ) 
 + 
 +> 当游戏配置（通过`SetGameOption`被绑定过的）发生主动更新时触发（或有数值被改变）。 
 +> 
 +> 每次客户端脚本加载完成时，都会自动触发一次（`optionKey==null`）。 
 + 
 +```javascript 
 +function OnGameOptionUpdate( optionKey: string ) 
 +``` 
 + 
 +```javascript 
 +function OnGameOptionUpdate( optionKey ) 
 +{ 
 +    if(optionKey == null) 
 +    { 
 +        //如果参数==null，表示不是由某个选项更新触发，而是引擎主动刷新 
 +        DLog("Force Update."); 
 +        return; 
 +    } 
 +     
 +    //如果不为空，则OptionKey返回具体哪个选项发生更新 
 +    DLog("OnGameOptionUpdate: " + optionKey); 
 +} 
 +```
  
  
  
 ## Function ## Function
 +
 +### UnloadMod()
 +
 +> 卸载当前引擎，回到沙盘引擎初始界面。
 +>
 +> **注意：通常情况下，可以考虑优先将【退出游戏】操作替换为此方法，而不是直接`QuitGame()`关闭游戏。**
 +
 +```javascript
 +function UnloadMod()
 +```
 +
 +
 +
 +### QuitGame()
 +
 +> 退出游戏，关闭沙盘引擎程序。
 +
 +```javascript
 +function QuitGame()
 +```
 +
 +
  
 ### DLog() ### DLog()
行 54: 行 182:
 ```javascript ```javascript
 function LoadScript( path: string ) function LoadScript( path: string )
-/* 
- path：脚本目录下的 同级或子级 脚本文件路径（例如："Test/MyCode.js"） 
-*/ 
 ``` ```
 +
 +- `path`：脚本目录下的 同级或子级 脚本文件路径（例如："Test/MyCode.js"）
  
 ```javascript ```javascript
行 80: 行 207:
     DLog("TestMode");     DLog("TestMode");
 } }
 +```
 +
 +
 +
 +### CreateHost()
 +
 +> 建立一个当前模组的服务器\房间世界。
 +>
 +> 任何情况下，使用此方法都将**直接断开当前服务器并建立新的服务器**，请确保相关数据提前保存。
 +>
 +> **补充：如果不填写任何参数，则表示加载到初始入口世界（`Main`世界）。**
 +>
 +> **==注意：我们建议不指定固定的端口号，而是使用`Mod.json -> NetworkPort`机制设定模组端口，并设置当前方法参数`Port=0`（自动识别模组`NetworkPort`）。==**
 +
 +```javascript
 +function CreateHost( map: string, script: string, port: int = 0, address: string = "", userData: string = "", additional: bool = true ): bool //是否建立成功
 +```
 +
 +> 载入并创建一个地图为“test2”且脚本为“Main2”的服务器。
 +
 +```javascript
 +CreateHost("test2", "Main2");
 +```
 +
 +> 载入并创建一个地图为“test2”且脚本为“Main2”，端口指定为8195的服务器（0为默认端口，并非随机端口）。
 +>
 +> 默认端口配置文件：Mod.json `["NetworkPort": 8192]`。
 +
 +```javascript
 +CreateHost("test2", "Main2", 8195);
 +```
 +
 +> 载入并创建一个地图为“test2”且脚本为“Main2”，端口随意，但使用SteamP2P网络的房间（地址参数填写`steam`）。
 +
 +```javascript
 +CreateHost("test2", "Main2", 0, "steam");
 +```
 +
 +> `UserData`参数可传递给服务器一个前置字符串参数（长度限制0~256，可用Json扩展），可提前告知服务器一些【玩家自身】自定义信息。
 +>
 +> **（World脚本可用player.UserData读取内容）**
 +
 +```javascript
 +CreateHost("test2", "Main2", 0, "", "TestStringOrJson...");
 +```
 +
 +> `additional`参数可指定是否使用地图附加内容（例如：地图内创建的载具），默认为`true`，如果只希望加载纯净的地图则设置为`false`。
 +
 +```javascript
 +CreateHost("test2", "Main2", 0, "", "", false);
 +```
 +
 +
 +
 +### ConnectHost()
 +
 +> 连接并加载到指定的多人游戏服务器，开发者应自行编写代码，确保参数信息正确。
 +>
 +> 任何情况下，使用此方法都将**直接断开当前服务器并尝试连接到新的服务器**。
 +
 +```javascript
 +function ConnectHost(address: string, port: int = 0, password: string = "", userData: string = "")
 +```
 +
 +> 尝试连接并加载到指定IP地址的服务器
 +>
 +> 方法与CreateHost部分相同，`0`表示默认端口，服务器密码可空
 +>
 +> `UserData`参数可传递给服务器一个前置字符串参数（长度限制0~256，可用Json扩展），可提前告知服务器一些【玩家自身】自定义信息
 +>
 +> **（World脚本可用player.UserData读取内容）**
 +
 +```javascript
 +ConnectHost("127.0.0.1"); 
 +```
 +
 +
 +
 +### Disconnect()
 +
 +> 断开当前正在连接的服务器\房间\世界，并回到入口场景（`Main`）。
 +>
 +> 任何情况下，使用此方法都将**直接断开当前服务器**。
 +
 +```javascript
 +function Disconnect()
 ``` ```
  
行 86: 行 299:
 ### Reconnect() ### Reconnect()
  
-> 重新建立连接当前服务器（重新建立\重连）。+> 断开当前正在连接的服务器\房间\世界，并尝试重新连接到上次的服务器（如果没有记录，则不会生效）。 
 +> 
 +> 任何情况下，使用此方法都将**直接断开当前服务器**。 
 +>
  
 ```javascript ```javascript
行 94: 行 310:
  
  
-### CheckServerMode()+### IsServerMode()
  
-> 获取当前是否为**服务端模式**（仅作为服务器启动）。+> 获取当前是否为**服务端模式**（仅作为专用服务器启动，通常由`bat`格式扩展）。
 > >
  
 ```javascript ```javascript
-function CheckServerMode(): bool+function IsServerMode(): bool 
 +``` 
 + 
 + 
 + 
 +### IsNewPlayer() 
 + 
 +> 判断当前是否为**玩家初次进入此模组**。 
 + 
 +```javascript 
 +function IsNewPlayer(): bool
 ``` ```
  
行 232: 行 458:
  
  
-### Json+### GetMapCount() 
 + 
 +> 获取当前用户本地地图数量，可使用`filter`进行条件过滤。
  
 ```javascript ```javascript
-Json js = new Json();+function GetMapCount( filter: int = 0 ): int
 ``` ```
  
 +| 过滤Filter | 说明                         |
 +| ---------- | ---------------------------- |
 +| 0          | 默认全部（模组>地图>下载）   |
 +| 1          | 只获取模组内置地图           |
 +| 2          | 只获取`Map`地图目录          |
 +| 3          | 只获取`Map\Download`地图目录 |
  
  
-### SQLite+ 
 +### GetMapByIndex() 
 + 
 +> 获取当前用户**指定索引**本地地图**文件名称**，通常搭配`GetMapCount()`遍历使用，可使用`filter`进行条件过滤。
  
 ```javascript ```javascript
-SQLite sql = new SQLite();+function GetMapByIndex( index: int, filter: int = 0 ): string
 ``` ```
  
 +```javascript
 +let mapCount = GetMapCount();
 +for(let i=0;i<mapCount;i++)
 +{
 +    DLog(i + ">" + GetMapByIndex(i));
 +}
 +```
  
  
-### Data+### GenerateUUID()
  
-#### GetGameItemName( model )+> 生成一段唯一的UUID字符串（GUID）。 
 +> 
 +> 在绝大部分情况下，由此方法生成的UUID应该是全球唯一的。
  
-> 获取一个游戏物品的本地化名称（根据模型ID）+```javascript 
 +function GenerateUUID(): string 
 +```
  
-| 参数  | 类型 | 说明   | 
-| ----- | ---- | ------ | 
-| model | int  | 模型ID | 
  
-| 返回   | 说明                               | +### DistancePoint()
-| ------ | ---------------------------------- | +
-| string | 本地化名称（未找到返回“”空字符串） |+
  
-#### GetVehicleName( model )+> 获取两个坐标点之间的距离，单位是沙盘引擎世界距离。
  
-> 获取一个游戏载具的本地化名称（根据模型ID）+```javascript 
 +function DistancePoint( pos: Vector, pos2: Vector ): float 
 +```
  
-| 参数  | 类型 | 说明   | 
-| ----- | ---- | ------ | 
-| model | int  | 模型ID | 
  
-| 返回   | 说明                               | 
-| ------ | ---------------------------------- | 
-| string | 本地化名称（未找到返回“”空字符串） | 
  
-#### GetModelObjectName( model )+### OverlapEntity()
  
-> 获取一个游戏建筑物体的本地化名称（根据模型ID）+> 在指定位置**检测并记录范围检测世界实体**（某坐标指定范围内所有对象），可用于检测指定位置的范围内实体对象（基于`Entity`的核心对象）。 
 +> 
 +> 如果只希望获取`Entity`基础类型中其中的一个或多个子类，可使用`filter`参数进行筛选（位操作）。 
 +> 
 +> **注意：此方法只用于单次记录，==并返回检测到的数量==，应搭配使用`OverlapEntityByIndex()`获取具体索引的对象实例。** 
 +> 
 +> ==（此方法在World\Client脚本有隔离机制，无须担心结果重叠覆盖问题）==
  
-| 参数  | 类型 | 说明   | +```javascript 
-| ----- | ---- | ------ | +function OverlapEntity( pos: Vector, radius: float, filter: int = 0 ): int 
-| model | int  | 模型ID |+```
  
-| 返回   | 说明                               | +| 过滤（Filter） | 说明       | 
-| ------ | ---------------------------------- | +| -------------- | ---------- | 
-| string | 本地化名称（未找到返回“”空字符串） |+| 0              | 默认全部   | 
 +| 1              | Model      | 
 +| 2              | Character  | 
 +| 4              | Vehicle    | 
 +| 8              | Pickup     | 
 +| 16             | Checkpoint |
  
 +```javascript
 +//Only check 'Character' and 'Vehicle'
 +OverlapEntity(Vector(0, 0, 0), 20, 2 + 4)
 +//or
 +OverlapEntity(Vector(0, 0, 0), 20, 6)
 +```
  
  
-### World 
  
-#### GetAreaPoint()+### OverlapEntityByIndex()
  
-> 获取指定坐标所在的Area区域+> 获取由`OverlapEntity()`记录后的**指定索引实例**，如不存在或已销毁则返回`null`。 
 +> 
 +> **注意：此方法使用前必须执行一次`OverlapEntity()`，以此获取最新的范围内检测信息。** 
 +> 
 +> ==（此方法在World\Client脚本有隔离机制，无须担心结果重叠覆盖问题）==
  
 ```javascript ```javascript
-GetAreaPoint( pos: Vector ): SE.Area //条件所匹配的Area区域（未找到返回null）+function OverlapEntityByIndex( index: int ): Entity
 ``` ```
  
-#### DistancePoint( pos1, pos2 )+```javascript 
 +let count = OverlapEntity(Vector(0, 0, 0), 20); 
 +if(count > 0) 
 +{ 
 +    DLog(i + "=" + OverlapEntityByIndex(i)); 
 +} 
 +```
  
-| 参数 | 类型   | 说明            | 
-| ---- | ------ | --------------- | 
-| pos1 | Vector | 比较坐标距离A点 | 
-| pos2 | Vector | 比较坐标距离B点 | 
  
-| 返回  | 说明           | 
-| ----- | -------------- | 
-| float | 两点之间的距离 | 
  
 +### InPoly()
  
 +> 获取某个点是否在多边形点范围内（X\Z是否在某片2D形状范围内）。
 +>
 +> **注意：此方法判断坐标系只需要X\Z轴，Y轴数值可以忽略（最低要求输入3个多边形点，最多支持8个多边形点验证）。**
  
-## 原生数据类型（Native Type）+```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, 0, 0), Vector(-10, 0, -10), Vector(-10, 0, 10), Vector(10, 0, 10), Vector(10, 0, -10))); //返回true 
 +```
  
-### Vector()+ 
 + 
 +### GetLanguage() 
 + 
 +> 获取**当前[引擎语言](developer/mod/language)的==标准英文名称==**（在部分情况下，可能会出现引擎语言与模组语言不同的情况，这里返回的是引擎语言）。 
 +> 
 +> **例如：沙盘引擎本体支持A语言，但当前模组可能仅支持B语言，此时返回的是A语言的标准英文名称。** 
 +> 
 +> ==通常情况下，开发者应该主动参考此方法获得的语言名称。此方法也会在游戏启动时自动识别`GetSystemLanguage()`系统语言兼容。==
  
 ```javascript ```javascript
-let pos = Vector(0, 0, 10); //X, Y, Z+function GetLanguage(): string
 ``` ```
  
-### Color()+ 
 + 
 +### GetModLanguage() 
 + 
 +> 获取**当前[模组语言](developer/mod/language)的==标准英文名称==**（在部分情况下，可能会出现引擎语言与模组语言不同的情况，这里返回的是模组语言）。 
 +> 
 +> **例如：沙盘引擎默认暂不支持A语言，但当前模组支持B语言，此时返回的是B语言的标准英文名称。**
  
 ```javascript ```javascript
-let newColor = Color(255, 255, 255, 255); //R, G, B, A+function GetLanguage(): string
 ``` ```
  
  
  
-## 原生事件（Native Event）+### GetSystemLanguage()
  
-### OnGameOptionUpdate( optionKey )+> 获取**当前[系统识别语言](developer/mod/language)的==标准英文名称==**，此方法仅供参考用户系统语言。 
 +>
  
-> 当游戏配置（通过`SetGameOption`被绑定过的）发生主动更新时触发（或有数值被改变）。+```javascript 
 +function GetLanguage(): string 
 +``` 
 + 
 + 
 + 
 +### GetLanguageText() 
 + 
 +> 获取[游戏语言文件](developer/mod/language)的解析内容（根据Key），**此函数是获取【不同语言文本翻译结果】的正确方法**。 
 + 
 +```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}`占位替换符号，可以根据索引填写后续参数 
 + 
 +> 此方法的使用扩展性比较强，几乎可覆盖大多数多语言文本需求。
 > >
-> 注意：这里事件将在任何GameOption值发生改变时触发，**建议有关GameOption值的更新事件都放在这里执行，而不一定是模组加载完成时**。+> 同时为了方便开发者减少代码量，这里提供了一个简单的映射方法`_Language()`，与此函数作用完全相同。
  
 ```javascript ```javascript
-function OnGameOptionUpdate( optionKey )+GetLanguageText("Native.Common.Exception"); //"发生异常错误！" 
 +_Language("Native.Common.Exception"); //"发生异常错误！" 
 + 
 +_Language("Native.Common.Exception", 1); //"因为异常原因，部分行为没有被执行" 
 +_Language("Native.MapEditor.MultipleDelete", "QWQ") //"即将删除QWQ个对象？此操作不可恢复！" 
 +``` 
 + 
 + 
 + 
 +### GetVectorPointCount() 
 + 
 +> 获取当前世界所有满足`Tag`标签筛选的`VectorPoint`坐标点**数量**。 
 + 
 +```javascript 
 +function GetVectorPointCount( tag: string = "" ): int 
 +``` 
 + 
 + 
 + 
 +### GetVectorPoint() 
 + 
 +> 获取当前世界所有满足`Tag`标签筛选的`VectorPoint`坐标点**对象**，通常搭配`GetVectorPointCount()`遍历使用。 
 +> 
 +> **具体`VectorPoint`数值对象参考本文上方`Type`部分。** 
 +> 
 +> **==注意：通过此方法获取的对象可进行set修改其内部属性，仅限本地使用，不会同步到其他客户端。==** 
 + 
 +```javascript 
 +function GetVectorPoint( tag: string, index: int = 0 ): VectorPoint 
 +``` 
 + 
 +```javascript 
 +//Test Code 
 +let tag = "test"; 
 +let count = GetVectorPointCount(tag); 
 +for(let i=0;i<count;i++)
 { {
-    if(optionKey == null) +    DLog(GetVectorPoint(tag, i).Tag + ": " + GetVectorPoint(tag, i).Pos);
-    { +
-        //如果参数==null，表示不是由某个选项更新触发，而是引擎主动更新 +
-        DLog("Force Update."); +
-    } +
-     +
-    DLog("OnGameOptionUpdate: " + optionKey);+
 } }
 ``` ```
 +
 +
 +
 +### AddVectorPoint()
 +
 +> 增加一条指定`Tag`标签的`VectorPoint`坐标点**对象**，如果不需要`Tag`标签也可以留空（这会导致无法通过`RemoveVectorPoint()`针对删除）。
 +
 +```javascript
 +function AddVectorPoint( tag: string, pos: Vector, angle: Vector = null, scale: Vector = null ): VectorPoint
 +```
 +
 +```javascript
 +//Test Code
 +AddVectorPoint("", Vector(10, 0, 0));
 +AddVectorPoint("HomePos", Vector(10, 0, 0), Vector(0, 0, 0));
 +```
 +
 +
 +
 +### RemoveVectorPoint()
 +
 +> 移除**所有**符合指定`Tag`标签条件的`VectorPoint`坐标点**对象**（也可以留空`Tag`标签，会删除所有没有`Tag`标签的坐标点对象）。
 +
 +```javascript
 +function RemoveVectorPoint( tag: string = "" )
 +```
 +
 +```javascript
 +//Test Code
 +RemoveVectorPoint();
 +RemoveVectorPoint("HomePos");
 +```
 +
 +
 +### FormatRichText()
 +> 格式化指定文本为引擎富文本（并非传统意义的`Richtext`），这将使一段文本执行以下操作：**链接地址标蓝、@玩家名（高亮）、#数字（根据ID转换为Texture图片或Emoji表情）**。
 +
 +```javascript
 +function FormatRichText( text: string, onlyEmoji: bool = false )
 +```
 +
 +- **onlyEmoji：**如果设置为`true`，则`#Number`的行为将被识别为表情（0~74），否则`#Number`将识别全局`TextureID`。
 +
 +```javascript
 +FormatRichText("#0", false); //Out id 0 (Asset Texture_0, not emoji)
 +FormatRichText("#0", true); //Out id 200 (Emoji Texture, 200~274 is emoji texture)
 +```
 +
 +
 +
 +
  
  
 </markdown> </markdown>
scripting/native/main.1693893120.txt.gz · 最后更改: 2023/09/05 13:52 由 bibiboxs

页面工具

除额外注明的地方外，本维基上的内容按下列许可协议发布： CC Attribution-Share Alike 4.0 International
CC Attribution-Share Alike 4.0 International Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki

Copyright 2019-2024 MP-Gamer.com 版权所有
备案号 黑ICP备2020005047号-1 |

黑公网安备 23060402000230号