meta data for this page
  •  

📚 差别

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

到此差别页面的链接

两侧同时换到之前的修订记录前一修订版
后一修订版		前一修订版
scripting:native:core [2025/06/13 08:46] – bibiboxsscripting:native:core [2025/08/29 20:30] (当前版本) – bibiboxs
行 15: 行 15:
 ### VECTOR_NULL ### VECTOR_NULL
  
-> 三维坐标默认“空”坐标。+> 三维坐标默认“空”坐标，通常表示**不合理或者默认值**。
 > >
 > 由于`Vector`是一个**值类型**，所以表示为空时不应该直接设为`null`，在通常情况下应该使用**常量代替**。 > 由于`Vector`是一个**值类型**，所以表示为空时不应该直接设为`null`，在通常情况下应该使用**常量代替**。
行 41: 行 41:
 ``` ```
  
-- `x`：X轴数值（左右） +- `x`X轴数值（左右） 
-- `y`：Y轴数值（上下） +- `y`Y轴数值（上下） 
-- `z`：Z轴数值（前后）+- `z`Z轴数值（前后）
  
  
行 57: 行 57:
 ``` ```
  
-- `x`：X轴数值 +- `x`X轴数值 
-- `y`：Y轴数值+- `y`Y轴数值 
 + 
 + 
 + 
 +### Bounds() 
 + 
 +> 包围盒结构类型，通常用于AABB数据存储。 
 +> 
 +> **==此方法必须使用`Equals()`判断相等。==** 
 + 
 +```javascript 
 +let bounds = Bounds(Vector(0, 0, 0), Vector(0, 0, 0)); //Center, Size 
 +``` 
 + 
 +- `center`中心位置 
 +- `size`尺寸 
 +- `extents`尺寸（一半） 
 +- `min`最小点 
 +- `max`最大点
  
  
行 73: 行 91:
 ``` ```
  
-- `r`：颜色数值 +- `r`颜色数值 
-- `g`：颜色数值 +- `g`颜色数值 
-- `b`：颜色数值 +- `b`颜色数值 
-- `a`：透明度数值+- `a`透明度数值
  
  
行 84: 行 102:
 > （只读）Array检测函数的返回值，属性可获取数组（封装）信息。 > （只读）Array检测函数的返回值，属性可获取数组（封装）信息。
  
-- `GetCount()`：获取数组长度 +- `GetCount()`获取数组长度 
-- `Get(index: int)`：获取指定索引的内容+- `Get(index: int)`获取指定索引的内容
  
  
行 93: 行 111:
 > （只读）射线检测函数的返回值，属性可获取射线检测结果（是否碰撞、最终坐标、检测实体等）。 > （只读）射线检测函数的返回值，属性可获取射线检测结果（是否碰撞、最终坐标、检测实体等）。
  
-- `IsHit`：是否碰撞射线（如果`IsHit == true && Entity == null`，可能表示检测到世界地形） +- `IsHit`是否碰撞射线（如果`IsHit = true && Entity = null`，可能表示检测到世界地形） 
-- `Point`：射线检测坐标（如没有产生碰撞，则坐标即是默认终点） +- `Point`射线检测坐标（如没有产生碰撞，则坐标即是默认终点） 
-- `Entity`：射线碰撞实体（如果对象不是标准的`Entity`实体，或对象为**静态模型（本地静态模型）**，则返回为`null`）+- `Entity`射线碰撞实体（如果对象不是标准的`Entity`实体，或对象为**静态模型（本地静态模型）**，则返回为`null`） 
 +- `Distance`射线实际产生距离 
 +- `Normal`射线检测表面角度
  
  
行 109: 行 129:
 > **注意：结构内的三种Vector类型虽然命名不同，但均是以`Vector`作为属性类型，因此在某些情况下可以忽略命名问题。** > **注意：结构内的三种Vector类型虽然命名不同，但均是以`Vector`作为属性类型，因此在某些情况下可以忽略命名问题。**
  
-- `Tag`：筛选标签（可空`""`） +- `Tag`筛选标签（可空`""`） 
-- `Pos`：坐标（Vector，不可空，至少要有一个） +- `Pos`坐标（Vector，不可空，至少要有一个） 
-- `Angle`：旋转角度（Vector，可空） +- `Angle`旋转角度（Vector，可空） 
-- `Scale`：缩放（Vector，可空）+- `Scale`缩放（Vector，可空）
  
  
行 122: 行 142:
 > 当游戏配置（通过`SetGameOption`被绑定过的）发生主动更新时触发（或有数值被改变）。 > 当游戏配置（通过`SetGameOption`被绑定过的）发生主动更新时触发（或有数值被改变）。
 > >
-> 每次客户端脚本加载完成时，都会自动触发一次（`optionKey==null`）。+> 每次客户端脚本加载完成时，都会自动触发一次（`optionKey = null`）。
  
 ```javascript ```javascript
行 163: 行 183:
 > 退出游戏，关闭沙盘引擎程序。 > 退出游戏，关闭沙盘引擎程序。
 > >
-> **==由于安全考虑，此功能暂不可用，应考虑替换为`UnloadMod()`。==**+> **出于安全考虑，此功能实际效果替换为`UnloadMod()`。**
  
 ```javascript ```javascript
行 187: 行 207:
 > 判断两个对象是否相同（相等）。 > 判断两个对象是否相同（相等）。
 > >
-> **注意：此方法是判断两者相同的最佳方法，同时也是==浮点数据类型（`Vector | Vector2 | Color`）==的唯一判断方法。**+> 注意：此方法是判断两者相同的最佳方法，同时也是**浮点数据类型（`Vector | Vector2 | Color`）**的唯一判断方法。
  
 [note2] [note2]
  
-**对于浮点类型相关的扩展类型，直接使用`==`无法进行有效判断（将始终返回`false`），相关类型必须使用此方法判断相同。+对于浮点类型相关的扩展类型，直接使用`==`无法进行有效判断（将始终返回`false`），必须使用此方法判断相同。
  
 除此之外，常规数据类型可正常使用`==`进行判断。 除此之外，常规数据类型可正常使用`==`进行判断。
行 198: 行 218:
  
 ```javascript ```javascript
-function Equals( a, b ): bool+function Equals( a: any, b: any ): bool
 ``` ```
  
行 218: 行 238:
  
 > 获取字符串分割后字符串结果，通常用于Command指令参数分割等。 > 获取字符串分割后字符串结果，通常用于Command指令参数分割等。
-> +>
 > 注意：此方法出于特性考虑，如果没有找到分割内容，则会返回包含`text[0]`的结果，而不是空结果。 > 注意：此方法出于特性考虑，如果没有找到分割内容，则会返回包含`text[0]`的结果，而不是空结果。
  
行 233: 行 253:
  
  
-### LoadScript()+### Env.LoadScript()
  
 > 加载**脚本目录**下其他脚本文件（js）。 > 加载**脚本目录**下其他脚本文件（js）。
 > >
-> 目标脚本将续写当前代码作用域（续写），**共享**当前脚本环境的代码，开发者应避免主副脚本之间使用相同名称的变量及方法等。+> 目标脚本将续写当前代码作用域（续写），**共享**当前脚本环境的代码，开发者应避免**主副脚本**之间使用**相同名称**的变量及方法等。
 > >
 > **此方法适合对目录规范有需求的开发者，或者制作模块化功能使用。** > **此方法适合对目录规范有需求的开发者，或者制作模块化功能使用。**
  
 [note2] [note2]
-注意：此方法目前不支持[脚本插件](developer/plugins/main "脚本插件")使用，脚本插件无法加载子脚本。+注意：此方法目前不支持[脚本插件](developer/plugin "脚本插件")使用，脚本插件无法加载子脚本。
 [/note] [/note]
  
 ```javascript ```javascript
-function LoadScript( path: string )+function Env.LoadScript( path: string )
 ``` ```
  
-- `path`：脚本目录下的 同级或子级 脚本文件路径（例如：`Test/MyCode.js`）+- `path`脚本目录下的 同级或子级 脚本文件路径（例如：`Test/MyCode.js`）
  
 ```javascript ```javascript
 //Path Rule //Path Rule
-LoadScript("Test/MyCode.js"); //√ 正确，读取Test目录下的MyCode.js +LoadScript("Test/MyCode.js"); //√ 
-LoadScript("Test/MyCode"); //√ 正确，读取Test目录下的MyCode.js（可忽略".js"） +LoadScript("Test/MyCode"); //√ 
-LoadScript("MyCode.js"); //√ 正确，读取脚本目录下的MyCode.js +LoadScript("MyCode.js"); //√ 正确 
-LoadScript("../MyCode.js"); //× 错误，安全性考虑无法使用层级符号+LoadScript("../MyCode.js"); //×
  
 //Test //Test
行 265: 行 285:
 function TestAction() function TestAction()
 { {
-    DLog("TestMode");+    Debug.Log("TestMode");
 } }
 ``` ```
行 295: 行 315:
 ``` ```
  
-- `eventName`：希望监听的`function`名称，通常用于监听引擎原生事件，但也支持自定义事件 +- `eventName`希望监听的`function`名称，通常用于监听引擎原生事件，但也支持自定义事件 
-- `action`：当事件触发时执行的`function`，支持`Lambda`表达式 +- `action`当事件触发时执行的`function`，支持`Lambda`表达式 
-- `sort`：监听方法的执行顺序，**数值越小越靠前**，默认顺序为`1`（在原方法执行后执行），原方法Sort默认保持为`0`（唯一） +- `sort`监听方法的执行顺序，**数值越小越靠前**，默认顺序为`1`（在原方法执行后执行），原方法Sort默认保持为`0`（唯一） 
-- `return`：监听事件的Hash值，可用于取消监听+- `return`监听事件的Hash值，可用于取消监听
  
 ```javascript ```javascript
行 340: 行 360:
 ``` ```
  
-- `eventHash`：希望取消监听的`eventHash`，通过`AddListener()`返回值获取+- `eventHash`希望取消监听的`eventHash`，通过`AddListener()`返回值获取
  
 ```javascript ```javascript
行 352: 行 372:
  
  
-### Emit()+### Env.Emit()
  
 > 手动触发一个`function()`事件及监听。 > 手动触发一个`function()`事件及监听。
行 360: 行 380:
 ``` ```
  
-- `functionName`：触发的函数\事件名称 +- `functionName`触发的函数\事件名称 
-- `params`：附带参数（如存在）+- `params`附带参数（如存在）
  
 ```javascript ```javascript
行 377: 行 397:
 > **补充：如果不填写任何参数，则表示加载到初始入口世界（`Main`世界）。** > **补充：如果不填写任何参数，则表示加载到初始入口世界（`Main`世界）。**
 > >
-> **==注意：我们建议不指定固定的端口号，而是使用`Mod.json -> NetworkPort`机制设定模组端口，并设置当前方法参数`Port=0`（自动识别模组`NetworkPort`）。==**+> 通常**不建议**指定**固定**的端口号，而是使用`Mod.json -> NetworkPort`机制设定模组端口，并设置当前方法参数`Port=0`（自动识别模组`NetworkPort`）。
  
 ```javascript ```javascript
行 565: 行 585:
  
 > 获取**Unix时间戳**（格林威治时间1970年01月01日00时00分00秒）。 > 获取**Unix时间戳**（格林威治时间1970年01月01日00时00分00秒）。
 +> 
 +> 注意：为了方便数值的直接使用，此处目前暂时使用`int32`类型，因此**Unix时间戳**最大支持到`2038-01-19​​`（32位）。
  
 ```javascript ```javascript
-function GetDateTime(): int+function GetTimestamp( utc: bool = false ): int
 ``` ```
 +
 +- `utc`是否使用UTC世界时间，否则为本地时间
  
  
行 575: 行 599:
  
 > 获取**服务器同步时间**，服务器至此运行了多长时间（秒）。 > 获取**服务器同步时间**，服务器至此运行了多长时间（秒）。
-> +>
 > **此数值无论是服务端\客户端执行，均取得最新同步后时间。** > **此数值无论是服务端\客户端执行，均取得最新同步后时间。**
  
行 768: 行 792:
 ```javascript ```javascript
 function GenerateUUID(): string function GenerateUUID(): string
-``` 
- 
- 
- 
-### Distance() 
- 
-> 获取两个坐标点之间的距离，单位是沙盘引擎世界距离。 
-> 
-> **注意：此方法将获得精准的距离数据，如果大量调用可能会影响性能，考虑使用距离平方（`DistanceSqrt`）。** 
- 
-```javascript 
-function Distance( pos: Vector, pos2: Vector ): float 
-``` 
- 
- 
- 
-### DistanceSqrt() 
- 
-> 获取两个坐标点之间的距离平方。 
-> 
-> **注意：此方法将获得距离平方，应该使用`Distance * Distance`作为最终距离判断。** 
- 
-```javascript 
-function DistanceSqrt( pos: Vector, pos2: Vector ): float 
-``` 
- 
- 
- 
-### GreaterDistance() 
- 
-> 获取**两个坐标点之间距离**是否**大于目标距离。** 
-> 
-> **注意：此方法内部使用距离平方运算，距离可能不会特别精准（性能会更高），目标距离无需进行平方运算，==可以按照常规`Distance`使用。==** 
- 
-```javascript 
-function GreaterDistance( pos: Vector, pos2: Vector, distance: float ): bool 
 ``` ```
  
行 828: 行 816:
 > 如果只希望获取`Entity`部分类型，可使用`layer`参数进行[实体类型层（位）](reference/instances)（位操作），默认`0`表示检测全部。 > 如果只希望获取`Entity`部分类型，可使用`layer`参数进行[实体类型层（位）](reference/instances)（位操作），默认`0`表示检测全部。
 > >
-> **注意：此方法会检测世界地形（除非参数`includeTerrain = false`），如果`IsHit == true && Entity == null`，表示最终检测到地形**。+> **注意：此方法会检测世界地形（除非参数`includeTerrain = false`），如果`IsHit = true && Entity = null`，表示最终检测到地形**。
  
 ```javascript ```javascript
行 834: 行 822:
 ``` ```
  
--  `start`：起始点 +-  `start`起始点 
--  `over`：结束点 +-  `over`结束点 
--  `layer`：筛选layer层，默认为`0`，可用于筛选判断[实体类型层（位）](reference/instances) +-  `layer`筛选layer层，默认为`0`，可用于筛选判断[实体类型层（位）](reference/instances) 
--  `RayTraceResult`：返回值（[类型参考](scripting/native/main)）+-  `RayTraceResult`返回值（[类型参考](scripting/native/main)）
  
 ```javascript ```javascript
行 911: 行 899:
     DLog(getPlayer.Name);     DLog(getPlayer.Name);
 } }
-``` 
- 
- 
- 
-### 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, 0, 0), Vector(-10, 0, -10), Vector(-10, 0, 10), Vector(10, 0, 10), Vector(10, 0, -10))); //返回true 
 ``` ```
  
行 969: 行 942:
 ### GetLanguageText() ### GetLanguageText()
  
-> 获取[游戏语言文件](developer/mod/language)的解析内容（根据Key），**此函数是获取【不同语言文本翻译结果】的正确方法**。+> 获取[游戏语言文件](developer/mod/language)的解析内容（根据Key），此函数是获取**文本翻译结果**的正确方法。
  
 ```javascript ```javascript
行 977: 行 950:
  
 - `key`：游戏语言文件内的完整路径 - `key`：游戏语言文件内的完整路径
-- `index`：可省略参数，表示语言结构数组索引，默认或省略为`0`+- `index`：可省略参数，表示语言结构数组索引，默认为`0`，如果设置为`-1`则表示随机取索引
 - `params`：如果目标语言文本拥有`{0}{1}{2}`占位替换符号，可以根据索引填写后续参数 - `params`：如果目标语言文本拥有`{0}{1}{2}`占位替换符号，可以根据索引填写后续参数
  
-> 此方法的使用扩展性比较强，几乎可覆盖大多数多语言文本需求。 +> 此方法的使用扩展性较强，几乎可覆盖大多数多语言文本需求。
-> +
-> 同时为了方便开发者减少代码量，这里提供了一个简单的映射方法`_Language()`，与此函数作用完全相同。+
  
 ```javascript ```javascript
 GetLanguageText("Native.Common.Exception"); //"发生异常错误！" GetLanguageText("Native.Common.Exception"); //"发生异常错误！"
-_Language("Native.Common.Exception"); //"发生异常错误！"+```
  
-_Language("Native.Common.Exception", 1); //"因为异常原因，部分行为没有被执行" + 
-_Language("Native.MapEditor.MultipleDelete", "QWQ") //"即将删除QWQ个对象？此操作不可恢复！"+ 
 +### GetLanguageTextCount() 
 + 
 +> 获取[游戏语言文件](developer/mod/language)的解析内容的结果数量。 
 + 
 +```javascript 
 +function GetLanguageTextCount( key: string ): int
 ``` ```
  
行 1048: 行 1025:
 RemoveVectorPoint("HomePos"); RemoveVectorPoint("HomePos");
 ``` ```
 +
 +
 +
 +### FormatPlainText()
 +
 +> 格式化指定文本为纯文本（去除`HTML|UBB`），可用于获取除表情外等真实文本及长度。
 +
 +```javascript
 +function FormatPlainText( text: string, includeUBB: bool = true ): string
 +```
 +
 +- `includeUBB`：如果设置为`true`，则允许包含`UBB`（忽略处理）。
  
  
行 1058: 行 1047:
  
 ```javascript ```javascript
-function FormatRichText( text: string, onlyEmoji: bool = false )+function FormatRichText( text: string, onlyEmoji: bool = false ): string
 ``` ```
  
行 1075: 行 1064:
  
 ```javascript ```javascript
-function FormatDefineText( text: string, includeColor: bool = true )+function FormatDefineText( text: string, includeColor: bool = true ): string
 ``` ```
  
行 1102: 行 1091:
  
  
-### GetRandomPoint()+### SamplePoint()
  
-> 获取指定坐标范围内的随机坐标点（受建筑碰撞影响）。 +> 获取**指定坐标**的**碰撞坐标**点（贴近地面或建筑），如果不存在则返回`VECTOR_NULL`。
->  +
-> 与常规坐标增加随机偏移的方式不同，此方法将尝试**最终定位坐标点在任何地面上**。+
  
 ```javascript ```javascript
-function GetRandomPoint( pos: Vector, radius: float, changeHeight: bool = false )+function SamplePoint( pos: Vector, sampleAll: bool = true ): Vector
 ``` ```
  
-- `changeHeight`：高度坐标是否参与随机，默认为`false`（即只计算X\Z轴）+- `sampleAll`是否采样所有静态对象，否则仅采样地面对象（陆地）。 
 + 
 + 
 + 
 +### SampleRandomPoint() 
 + 
 +> 获取**指定坐标范围**内的随机**碰撞坐标**点（贴近地面或建筑），如果不存在则返回`VECTOR_NULL`。 
 +> 
 + 
 +```javascript 
 +function SampleRandomPoint( pos: Vector, radius: float, sampleAll: bool = true ): Vector 
 +``` 
 + 
 +- `sampleAll`是否采样所有静态对象，否则仅采样地面对象（陆地）。 
 + 
 + 
 + 
 + 
 + 
 + 
 + 
 + 
 + 
 + 
 +