📚 Native/Main

原生脚本是一个内置的通用脚本功能类，此分类下还有更多通用的扩展工具类。

此文档内所代码均可在Client和World脚本及其子脚本直接进行使用。

标注原生（Native）类型的常量、类型、事件、函数方法等，它们都基于原生Native类。

在脚本开发时可省略前缀Native.XXXX，而直接使用XXXX即可。

📒 Const

📘 VECTOR_NULL

三维坐标默认“空”坐标。

由于Vector是一个值类型，所以表示为空时不应该直接设为null，在通常情况下应该使用常量代替。

const VECTOR_NULL = Vector3(-128000, -128000, -128000);

📒 Type

📘 Vector()

三维坐标结构类型，沙盘引擎世界坐标的通用形式，其中Y轴表示高度。

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（可省略）。

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）。

function OnGameOptionUpdate( optionKey: string )

function OnGameOptionUpdate( optionKey )
{
    if(optionKey == null)
    {
        //如果参数==null，表示不是由某个选项更新触发，而是引擎主动刷新
        DLog("Force Update.");
        return;
    }
 
    //如果不为空，则OptionKey返回具体哪个选项发生更新
    DLog("OnGameOptionUpdate: " + optionKey);
}

📒 Function

📘 UnloadMod()

卸载当前引擎，回到沙盘引擎初始界面。

注意：通常情况下，可以考虑优先将【退出游戏】操作替换为此方法，而不是直接QuitGame()关闭游戏。

function UnloadMod()

📘 QuitGame()

退出游戏，关闭沙盘引擎程序。

function QuitGame()

📘 DLog()

输出标准控制台信息（白色文本）。

function DLog("Hello World!");

📘 DWarn()

输出警告类型控制台信息（黄色文本）。

function DWarn("Hello World!");

📘 DError()

输出错误类型控制台信息（红色文本）。

function DError("Hello World!");

📘 LoadScript()

加载脚本目录下其他脚本文件（js）。

目标脚本将被续写在当前代码的作用域，共享当前环境（World或Client脚本）的代码及变量，开发者要自行分配隔离World\Client脚本，避免混用。

此方法适合对目录规范有需求的开发者，或者制作模块化功能、插件时使用。

function LoadScript( path: string )

• path：脚本目录下的 同级或子级 脚本文件路径（例如："Test/MyCode.js"）

//路径规则
LoadScript("Test/MyCode.js"); //正确，读取Test目录下的MyCode.js
LoadScript("Test/MyCode"); //正确，读取Test目录下的MyCode.js（可忽略".js"）
LoadScript("MyCode.js"); //正确，读取脚本目录下的MyCode.js
LoadScript("../MyCode.js"); //错误，安全性考虑无法使用层级符号
 
//举例
//Main脚本
LoadScript("Test.js")
TestAction(); //正常执行，执行Test.js脚本下的TestAction()
 
/*
	扩展解释：如果Main脚本原有一个TestAction()方法，但是后续加载了Test.js脚本，那么执行的应该是Test.js脚本的，因为后续加载覆写了早期方法
*/
 
//Test.js
function TestAction()
{
    DLog("TestMode");
}

📘 CreateHost()

建立一个当前模组的服务器\房间世界。

任何情况下，使用此方法都将直接断开当前服务器并建立新的服务器，请确保相关数据提前保存。

补充：如果不填写任何参数，则表示加载到初始入口世界（Main世界）。

注意：我们建议不指定固定的端口号，而是使用Mod.json -> NetworkPort机制设定模组端口，并设置当前方法参数Port=0（自动识别模组NetworkPort）。

function CreateHost( map: string, script: string, port: int = 0, address: string = "", userData: string = "", additional: bool = true ): bool //是否建立成功

载入并创建一个地图为“test2”且脚本为“Main2”的服务器。

CreateHost("test2", "Main2");

载入并创建一个地图为“test2”且脚本为“Main2”，端口指定为8195的服务器（0为默认端口，并非随机端口）。

默认端口配置文件：Mod.json ["NetworkPort": 8192]。

CreateHost("test2", "Main2", 8195);

载入并创建一个地图为“test2”且脚本为“Main2”，端口随意，但使用SteamP2P网络的房间（地址参数填写steam）。

CreateHost("test2", "Main2", 0, "steam");

UserData参数可传递给服务器一个前置字符串参数（长度限制0~256，可用Json扩展），可提前告知服务器一些【玩家自身】自定义信息。

（World脚本可用player.UserData读取内容）

CreateHost("test2", "Main2", 0, "", "TestStringOrJson...");

additional参数可指定是否使用地图附加内容（例如：地图内创建的载具），默认为true，如果只希望加载纯净的地图则设置为false。

CreateHost("test2", "Main2", 0, "", "", false);

📘 ConnectHost()

连接并加载到指定的多人游戏服务器，开发者应自行编写代码，确保参数信息正确。

任何情况下，使用此方法都将直接断开当前服务器并尝试连接到新的服务器。

function ConnectHost(address: string, port: int = 0, password: string = "", userData: string = "")

尝试连接并加载到指定IP地址的服务器

方法与CreateHost部分相同，0表示默认端口，服务器密码可空

UserData参数可传递给服务器一个前置字符串参数（长度限制0~256，可用Json扩展），可提前告知服务器一些【玩家自身】自定义信息

（World脚本可用player.UserData读取内容）

ConnectHost("127.0.0.1"); 

📘 Disconnect()

断开当前正在连接的服务器\房间\世界，并回到入口场景（Main）。

任何情况下，使用此方法都将直接断开当前服务器。

function Disconnect()

📘 Reconnect()

断开当前正在连接的服务器\房间\世界，并尝试重新连接到上次的服务器（如果没有记录，则不会生效）。

任何情况下，使用此方法都将直接断开当前服务器。

function Reconnect()

📘 IsServerMode()

获取当前是否为服务端模式（仅作为专用服务器启动，通常由bat格式扩展）。

function IsServerMode(): bool

📘 IsNewPlayer()

判断当前是否为玩家初次进入此模组。

function IsNewPlayer(): bool

📘 GetEngineTickCount()

获取游戏启动至此已运行的时间（秒）。

function GetEngineTickCount(): float

📘 GetModTickCount()

获取模组启动至此已运行的时间（秒）。

如果期间发生了延迟加载、重载模组等情况，此时间也会被随之重置。

function GetModTickCount(): float

📘 GetDateTime()

获取系统时间。

返回格式会按照yyyy-MM-dd|HH:mm:ss进行字符串处理，开发者可通过split得到的数组获取单独的值。

function GetDateTime(): string

📘 GetTimestamp()

获取Unix时间戳（格林威治时间1970年01月01日00时00分00秒）。

function GetDateTime(): int

📘 GetSystemInfo()

获取系统信息json格式。

你可以在合规的范围内使用这些非隐私的信息，以来进行如游戏配置自适应、反作弊等操作。

function GetDeviceInfo(): Json

📘 SetGlobalVars()

设置一个全局变量（可跨脚本使用），支持绝大部分类型的JavaScript变量（如：数组、对象等）。

此功能可善用扩展，例如：菜单界面设置【服务器名称、服务器模式等】全局变量对象，待服务器加载完毕事件读取，并根据数值来修改逻辑。

如果一个全局变量不再使用，可以将其设置为value = null删除全局变量。

function SetGlobalVars( key: string, value: any )

//设置一个字符串类型的全局变量
SetGlobalVars("myWebsite", "www.abc.com");
 
//设置一个JavaScript扩展对象全局变量
SetGlobalVars("createServerConfig", {
    serverName: "服务器名称",
    gameMode: 1,
    openPVP: false
});

📘 GetGlobalVars()

读取一个全局变量（可跨脚本使用），支持绝大部分类型的JavaScript变量（如：数组、对象等）。

如指定key不存在则返回null。

function GetGlobalVars( key: string ): any

//设置一个JavaScript扩展对象全局变量
SetGlobalVars("createServerConfig", {
    serverName: "服务器名称",
    gameMode: 1,
    openPVP: false
});
 
//读取时可正常进行读取
let getConfig = GetGlobalVars("createServerConfig");
DLog("serverName: " + getConfig.serverName);

📘 GetScriptName()

获取当前加载的脚本名称。

function GetScriptName(): string

📘 GetMapName()

获取当前加载的地图名称（并非地图文件名，而是地图名），可用作判定特定地图。

function GetMapName(): string

📘 GetMapCount()

获取当前用户本地地图数量，可使用filter进行条件过滤。

function GetMapCount( filter: int = 0 ): int

📘 GetMapByIndex()

获取当前用户指定索引本地地图文件名称，通常搭配GetMapCount()遍历使用，可使用filter进行条件过滤。

function GetMapByIndex( index: int, filter: int = 0 ): string

let mapCount = GetMapCount();
for(let i=0;i<mapCount;i++)
{
    DLog(i + ">" + GetMapByIndex(i));
}

📘 GenerateUUID()

生成一段唯一的UUID字符串（GUID）。

在绝大部分情况下，由此方法生成的UUID应该是全球唯一的。

function GenerateUUID(): string

📘 DistancePoint()

获取两个坐标点之间的距离，单位是沙盘引擎世界距离。

function DistancePoint( pos: Vector, pos2: Vector ): float

📘 OverlapEntity()

在指定位置检测并记录范围检测世界实体（某坐标指定范围内所有对象），可用于检测指定位置的范围内实体对象（基于Entity的核心对象）。

如果只希望获取Entity基础类型中其中的一个或多个子类，可使用filter参数进行筛选（位操作）。

注意：此方法只用于单次记录，并返回检测到的数量，应搭配使用OverlapEntityByIndex()获取具体索引的对象实例。

（此方法在World\Client脚本有隔离机制，无须担心结果重叠覆盖问题）

function OverlapEntity( pos: Vector, radius: float, filter: int = 0 ): int

//Only check 'Character' and 'Vehicle'
OverlapEntity(Vector(0, 0, 0), 20, 2 + 4)
//or
OverlapEntity(Vector(0, 0, 0), 20, 6)

📘 OverlapEntityByIndex()

获取由OverlapEntity()记录后的指定索引实例，如不存在或已销毁则返回null。

注意：此方法使用前必须执行一次OverlapEntity()，以此获取最新的范围内检测信息。

（此方法在World\Client脚本有隔离机制，无须担心结果重叠覆盖问题）

function OverlapEntityByIndex( index: int ): Entity

let count = OverlapEntity(Vector(0, 0, 0), 20);
if(count > 0)
{
    DLog(i + "=" + OverlapEntityByIndex(i));
}

📘 InPoly()

获取某个点是否在多边形点范围内（X\Z是否在某片2D形状范围内）。

注意：此方法判断坐标系只需要X\Z轴，Y轴数值可以忽略（最低要求输入3个多边形点，最多支持8个多边形点验证）。

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

DLog(InPoly(Vector(0, 0, 0), Vector(-10, 0, -10), Vector(-10, 0, 10), Vector(10, 0, 10), Vector(10, 0, -10))); //返回true

📘 GetLanguage()

获取当前引擎语言的标准英文名称（在部分情况下，可能会出现引擎语言与模组语言不同的情况，这里返回的是引擎语言）。

例如：沙盘引擎本体支持A语言，但当前模组可能仅支持B语言，此时返回的是A语言的标准英文名称。

通常情况下，开发者应该主动参考此方法获得的语言名称。此方法也会在游戏启动时自动识别GetSystemLanguage()系统语言兼容。

function GetLanguage(): string

📘 GetModLanguage()

获取当前模组语言的标准英文名称（在部分情况下，可能会出现引擎语言与模组语言不同的情况，这里返回的是模组语言）。

例如：沙盘引擎默认暂不支持A语言，但当前模组支持B语言，此时返回的是B语言的标准英文名称。

function GetLanguage(): string

📘 GetSystemLanguage()

获取当前系统识别语言的标准英文名称，此方法仅供参考用户系统语言。

function GetLanguage(): string

📘 GetLanguageText()

获取游戏语言文件的解析内容（根据Key），此函数是获取【不同语言文本翻译结果】的正确方法。

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()，与此函数作用完全相同。

GetLanguageText("Native.Common.Exception"); //"发生异常错误！"
_Language("Native.Common.Exception"); //"发生异常错误！"
 
_Language("Native.Common.Exception", 1); //"因为异常原因，部分行为没有被执行"
_Language("Native.MapEditor.MultipleDelete", "QWQ") //"即将删除QWQ个对象？此操作不可恢复！"

📘 GetVectorPointCount()

获取当前世界所有满足Tag标签筛选的VectorPoint坐标点数量。

function GetVectorPointCount( tag: string = "" ): int

📘 GetVectorPoint()

获取当前世界所有满足Tag标签筛选的VectorPoint坐标点对象，通常搭配GetVectorPointCount()遍历使用。

具体VectorPoint数值对象参考本文上方Type部分。

注意：通过此方法获取的对象可进行set修改其内部属性，仅限本地使用，不会同步到其他客户端。

function GetVectorPoint( tag: string, index: int = 0 ): VectorPoint

//Test Code
let tag = "test";
let count = GetVectorPointCount(tag);
for(let i=0;i<count;i++)
{
    DLog(GetVectorPoint(tag, i).Tag + ": " + GetVectorPoint(tag, i).Pos);
}

📘 AddVectorPoint()

增加一条指定Tag标签的VectorPoint坐标点对象，如果不需要Tag标签也可以留空（这会导致无法通过RemoveVectorPoint()针对删除）。

function AddVectorPoint( tag: string, pos: Vector, angle: Vector = null, scale: Vector = null ): VectorPoint

//Test Code
AddVectorPoint("", Vector(10, 0, 0));
AddVectorPoint("HomePos", Vector(10, 0, 0), Vector(0, 0, 0));

📘 RemoveVectorPoint()

移除所有符合指定Tag标签条件的VectorPoint坐标点对象（也可以留空Tag标签，会删除所有没有Tag标签的坐标点对象）。

function RemoveVectorPoint( tag: string = "" )

//Test Code
RemoveVectorPoint();
RemoveVectorPoint("HomePos");

📘 FormatRichText()

格式化指定文本为引擎富文本（并非传统意义的Richtext），这将使一段文本执行以下操作：链接地址标蓝、@玩家名（高亮）、#数字（根据ID转换为Texture图片或Emoji表情）。

function FormatRichText( text: string, onlyEmoji: bool = false )

• onlyEmoji：如果设置为true，则#Number的行为将被识别为表情（0~74），否则#Number将识别全局TextureID。

FormatRichText("#0", false); //Out id 0 (Asset Texture_0, not emoji)
FormatRichText("#0", true); //Out id 200 (Emoji Texture, 200~274 is emoji texture)