📚 World/Main*

📒 Event

📘 OnScriptLoad()

当世界端脚本被完整加载后调用。

如果需要获取到一些初始化传递数据，可通过SetGlobalVars() | GetGlobalVars()以及本地player.UserData等方式来读写。

📘 OnScriptUnload()

当脚本即将被释放时调用。

📘 OnFrameUpdate( deltaTime )

当世界端加载完成后每帧调用。

不应该将过于复杂的函数在此处执行，可能会影响服务器运算。

function OnFrameUpdate( deltaTime：float ) //增量时间

📘 OnFixedUpdate( fixedDeltaTime )

当脚本加载完成后固定增量时间调用（与Unity原理相同）。

此事件会以FixedUpdate的方式每隔固定时间调用，通常情况下可以忽略使用此事件。

fixedDeltaTime：float //增量时间

📘 OnThrowCastTrigger( tag, point)

当ThrowCast触发碰撞后调用。

此方法支持return bool（可选），这将影响一些Throw是否执行其自带绑定Action方法，事件返回值默认为true。

例如：CreateThrowCast()时在末尾参数绑定了一个Action，当ThrowCast发生碰撞后会优先调用当前事件，如果此处代码返回false则会阻止其绑定Action方法执行（如：默认RPG武器等，如果返回false将不会产生爆炸效果）。

function OnThrowCastTrigger( tag: string, point: Vector ): bool

//阻止投掷物引起的爆炸，不会产生爆炸
function OnThrowCastTrigger( tag, point )
{
	//Prop grenade [tag] is "Grenade"
	if(tag == "Grenade")
	{
		DLog("An explosion tagged 'Grenad' was stopped!");
		return false;
	}
}

📘 OnTimeChange( oldTime, newTime )

当世界时间发生改变时调用。

function OnTimeChange( oldTime, newTime )
{
    DLog("OldTime: " + oldTime.Hour + "-" + oldTime.Minute);
    DLog("NewTime: " + newTime.Hour + "-" + newTime.Minute);
}

📘 OnServerQueryReceive( data, address )

当服务器接收到Query\Gamespy数据时调用（格式必须是\xxx\使用反斜杠包围）。

引擎内置数据指令（例如querystats等）不会触发此事件。

function OnServerQueryReceive( data: string, address: string )

📒 Function

📘 Exec()

执行一段脚本代码（Client\World脚本不互通）。

function Exec( jsCode: string )

📘 SetHostName()

设置主机房间名称（当主机房间被公开或查询时，单机游戏可以忽略）。

默认值：Sandtable Engine Server。

function SetHostName( name: string )

• name：主机房间名称文本（最大限制在64字符）。

📘 GetHostName()

获取主机房间名称。

function GetHostName(): string

📘 SetHostInfo()

设置主机房间信息\公告（目前主要用于TAB面板封面部分介绍，以及有关房间的介绍信息等）。

默认值：Mod Version: XXX。

function SetHostInfo( info: string )

• info：主机房间信息\公告（最大限制在64字符）。

📘 GetHostInfo()

获取主机房间信息\公告。

function GetHostInfo(): string

📘 SetPassword()

设置主机房间密码（当主机房间被公开或查询时，单机游戏可以忽略）。

function SetPassword( password: string )

📘 GetPassword()

获取主机房间密码。

function GetPassword(): string

📘 SetMaxPlayers()

设置主机房间最大人数（支持范围1~100人）。

function SetMaxPlayers( num: int )

📘 GetMaxPlayers()

获取主机房间最大玩家数。

function GetMaxPlayers(): int

📘 SetTime()

设置当前游戏世界时间。

注意：每次加载新世界场景后，时间都将重新替换为【地图文件配置——默认时间】。

function SetTime( hour: int, minute: int )

📘 GetTime()

获取游戏世界时间实例（WorldTime）。

let worldTime = GetTime();
DLog("Hour: " + worldTime.Hour + ", Minute: " + worldTime.Minute);

📘 SetTimeRate()

设置当前游戏世界时间速率（游戏时间每分钟的时间间隔），默认为1.0。

此方法是SetGameRule("timerate")的快捷API。

例如：设置为1.0表示【游戏时间每分钟=现实时间1秒】。

function SetTimeRate( rate: float )

📘 GetTimeRate()

获取游戏世界时间速率（游戏时间每分钟的时间间隔）。

function GetTimeRate(): float

📘 SetWeather()

设置游戏世界天气，具体参考天气ID文档。

注意：每次加载新世界场景后，天气都将重新替换为【地图文件配置——随机天气（天气池）】。

function SetWeather( weather: int )

📘 GetWeather()

获取游戏世界天气。

function GetWeather(): int

📘 GetRandomWeather()

随机获取游戏世界天气，获取方式根据参数决定。

function GetRandomWeather( usePool: bool = true ): int

• usePool：是否使用【地图文件天气池】概率随机，否则是索引硬随机

📘 SetGravity()

设置游戏世界物理重力，分别为横向X、纵向Y、前后Z，默认为Vector(0.0, -1.0, 0.0)（正常下落的引力，且没有方向偏移）。

function SetGravity( space: Vector )

📘 GetGravity()

获取游戏世界物理重力。

function GetGravity(): Vector

📘 SetWorldBrightness()

设置游戏世界亮度偏移，默认为1.0。

对于特定的场景或游戏玩法（如丧尸游戏），开发者可能希望将此值调低以营造更好的黑夜效果。

function SetWorldBrightness( brightness: float )

📘 GetWorldBrightness()

获取游戏世界亮度偏移。

function GetWorldBrightness(): float

📘 SetWorldColor()

设置游戏世界叠加色调，默认为白色Color(255, 255, 255)。

function SetWorldColor( color: Color )

📘 GetWorldColor()

获取游戏世界叠加色调。

function GetWorldColor(): Color

📘 SetWorldFogColor()

设置游戏世界雾颜色，默认为白色Color(150, 150, 150)。

此方法是SetGameRule("fogcolor")的快捷方法。

function SetWorldFogColor( color: Color )

📘 GetWorldFogColor()

获取游戏世界雾颜色。

function GetWorldFogColor(): Color

📘 SetSkybox()

设置游戏世界天空盒，默认为0。

function SetSkybox( skybox: int )

📘 GetSkybox()

获取游戏世界天空盒。

function GetSkybox(): int

📘 SetSkyboxColor()

设置游戏世界天空盒叠加色调，默认为Color(128, 128, 128)。

function SetSkyboxColor( color: Color )

📘 GetSkyboxColor()

获取游戏世界天空盒叠加色调。

function GetSkyboxColor(): Color

📘 SetGameRule()

设置指定游戏规则（不区分大小写），可用于修改更多细节内容，具体参考游戏规则Keys文档。

修改时请严格确保Key > Value类型正确，否则可能会引起异常。

此功能不仅可修改《沙盘引擎》内置规则，在有需要情况下，也可以作为自定义规则字典填充（前提：避开内置key值）。

注意：此选项设置的值只在当前世界生效，切换其他世界后将重置。

function SetGameRule( key: string, value: any )

📘 ResetGameRule()

重置指定游戏规则默认数值。

function ResetGameRule( key: string )

📘 ResetAllGameRules()

重置所有游戏规则默认数值。

function ResetAllGameRules()

📘 GetGameRule()

获取指定游戏规则数值（不区分大小写），具体参考游戏规则Keys文档。

function GetGameRule( key: string, defaultValue: any = null )

📘 GetServerTickCount()

获取世界脚本运行时间秒数（float）。

function GetServerTickCount(): float

📘 Message()

给全服在线玩家发送一条公屏消息（在消息框中）。

function Message( text: string )

📘 Announce()

给全服在线玩家发送一条公告\大文字消息，具体类型样式参考《世界资源实例汇总》。

function Announce( text: string, type: int = 0, time: float = 6 )

📘 Subtitle()

给全服在线玩家发送一条底部字幕消息。

function Subtitle( text: string )

📘 RayTrace()

生成一条检测射线，可用于检测两点之间实体对象的碰撞。

多数情况下，建议使用World端方法进行检测，而不是Client端方法。

function RayTrace( start: Vector, over: Vector, flags: int = 0 ): RayTraceResult

• start：起始点

• over：结束点

• flags：筛选layer层，默认为0，可用于筛选判断实体类型层（位）

• RayTraceResult：返回值（类型参考）

//只判断Character + Vehicle
let result = RayTrace(Vector(0, 0, 0), Vector(10, 0, 10), 2 + 4);
DLog(result.IsHit);
DLog(result.Point);
DLog(result.Entity)

📘 CreateDamage()

生成一处范围原生伤害，只有范围伤害的效果。

function CreateDamage( pos: Vector, damage: int, radius: float, from: Entity = null, damageType: int = 0, ignoreSelf = false )

• pos：起始点

• damage：伤害值

• radius：伤害产生范围

• from：发起伤害单位（可空）

• damageType：伤害类型

• ignoreSelf：是否忽略发起伤害单位自身（如from为空则没有意义）

📘 CreateFire()

在指定位置生成一团火焰，火焰将对附近的实体造成燃烧+传播伤害。

function CreateFire( pos: Vector, time: float, radius: float = 1.0 )

📘 CreateExplosion()

在指定位置生成一场爆炸，不同爆炸类型有不同的效果范围和伤害。

function CreateExplosion( pos: Vector, type: int = 0 )

📘 CreateExplosionForce()

在指定位置生成一场物理爆炸力（没有伤害），附近的物理刚体将受到力影响（类似爆炸冲击力）。

function CreateExplosionForce( pos: Vector, force: float, radius: float )

📘 CreateRayPowerCast()

在指定位置生成一条光线射线（不会穿透物体），与射线检测功能基本相同，但会额外多出光线效果（例如：枪械弹道）。

function CreateRayPowerCast( start: Vector, over: Vector, color: Color, width: float = 0.2, time: float = 0.1 )

📘 CreateThrowCast()

在指定位置生成一条投掷抛物射线（物理），与光线射线功能基本相同，但会额外多出物理效果。

注意：投掷射线将在发生碰撞后销毁，并触发【碰撞后事件】（Event优先级：OnThrowCastTrigger() > BindAction()?）

function CreateThrowCast( 
	start: Vector, 
    direction: Vector, 
    color: Color, 
    width: float = 0.2, 
    speed: float = 1.0, 
    tag: string = "", 
    action: Action<Vector> = null )

CreateThrowCast(Vector(0, 0, 0), Vector(0, 0, 1), Color(255, 0, 0), 0.2, 1, "test_throw", (point) => {
    DLog("Throw Over: " + point);
});

• start：射线起点坐标
• direction：射线发射方向向量
• color：射线颜色
• width：射线宽度
• speed：投掷物理速度
• tag：标签，仅有识别作用，主要用于OnThrowCastTrigger()事件参数
• action：碰撞时触发方法（参数：Vector）

📘 CreateModelThrowCast()

在指定位置生成一条包含模型的投掷抛物射线（物理），与CreateThrowCast()功能基本相同，但会额外多出子模型效果（例如射出的子弹、炮弹、弓箭、手榴弹模型等）。

function CreateModelThrowCast( 
	model: int, 
    localPos: Vector, 
    localAngle: Vector, 
    localScale: Vector, 
    start: Vector, 
    direction: Vector, 
    color: Color, 
    width: float = 0.2, 
    speed: float = 1.0, 
    tag: string = "", 
    action: Action<Vector> = null )

• model：子模型ID
• localPos：子模型的[本地]坐标
• localAngle：子模型的[本地]欧拉角度
• localScale：子模型的[本地]缩放
• 其他参数与CreateThrowCast()相同

📘 PlaySoundForAll()

为所有当前在线的玩家播放一段2D音频。

注意：此操作相当于封装了遍历player.PlaySound()方法，播放的是客户端本地声音，后加入的玩家不会听到此声音。

function PlaySoundForAll( audioID: int, loop: bool = false, volume: float = 1f )

📘 Play3DSoundForAll()

为所有当前在线的玩家播放一段3D音频。

注意：此操作相当于封装了遍历player.Play3DSound()方法，播放的是客户端本地声音，后加入的玩家不会听到此声音。

function Play3DSoundForAll( audioID: int, pos: Vector, radius: float = 80, loop: bool = false, volume: float = 1f )

📘 PlaySound()

在服务器世界播放一段2D音频（与客户端音频方法相似，但播放的声音不受Client\Audio类控制，客户端也无法停止播放）。

即便稍后进入的玩家也会同步播放此声音（播放进度同步），音频实例将一直存在世界中，直到被（自动\手动）销毁。

function PlaySound( audioID: int, loop: bool = false, volume: float = 1f ): string //UUID

📘 Play3DSound()

在服务器世界播放一段2D音频（此方法播放的声音不受Client\Audio类控制，客户端也无法停止播放）。

即使后进入的玩家也会同步播放此声音（播放进度同步），音频实例将一直存在世界中，直到被（自动\手动）销毁。

function Play3DSound( audioID: int, pos: Vector, radius: float, loop: bool = false, volume: float = 1f ): string //UUID

📘 StopSound()

停止并销毁一个服务器世界声音实例。

function StopSound( uuid: string ): bool //返回false表示不存在UUID实例

📘 PauseSound()

暂停播放一个服务器世界声音实例。

注意：此操作不会销毁实例，如果不使用时忘记销毁，可能会一直占用服务器资源。

function PauseSound( uuid: string ): bool //返回false表示不存在UUID实例

📘 ResumeSound()

继续播放一个服务器世界声音实例。

function ResumeSound( uuid: string ): bool //返回false表示不存在UUID实例

📘 SetSoundWorld()

设置一个服务器世界声音实例的网络世界（不同世界将无法听到声音）。

function SetSoundWorld( uuid: string, world: int ): bool //返回false表示不存在UUID实例

📘 BindKey()

绑定一个服务器按键（当前场景有效），可用于监听某个玩家的某键被按下\抬起。

按键参数可填写UnityEngine.KeyCode（Enum）索引或名称作为按键参数。

function BindKey( keyTag: string, key1: string, key2: string = "None", key3: string = "None" )

• keyTag：按键标签（用于识别）
• key1：按键1标准名称（如'H'）
• key2：默认'None'，否则表示组合键
• key3：默认'None'，否则表示组合键

📘 UnbindKey()

取消绑定一个服务器按键，对其按键监听不再生效。

function UnbindKey( keyTag: string )

📘 UnbindAllKey()

取消绑定所有服务器按键，对其按键监听不再生效。

function UnbindAllKey()

📘 BindNativeKey()

绑定一个服务器监听原生公开按键（当前场景有效），只可用于监听某个玩家的某原生按键被按下\抬起，不会远程绑定任何原生公开按键。

此功能需要客户端提前绑定了BindNativeKey()才有监听意义。

function BindNativeKey( keyTag: string )

• keyTag：按键标签（用于识别）

📘 UnbindNativeKey()

取消绑定一个服务器监听原生公开按键，对其按键监听不再生效。

function UnbindNativeKey( keyTag: string )

📘 UnbindAllNativeKey()

取消绑定所有服务器监听原生公开按键，对其按键监听不再生效。

function UnbindAllNativeKey()

📘 WriteFile()

写入一个文件到模组空间目录Mod/Space，安全起见，写入文件尺寸限制2MB，且有最大文件数量限制（Space目录最多可写【20】个文件）。

此功能通常用于实现游戏\服务器存档、配置等写入，建议使用JSON功能进行序列化。

function WriteFile( fileName: string, content: string )

📘 ReadFile()

从模组空间目录读取一个文件，如果文件不存在则返回空白文本。

function ReadFile( fileName: string ): string

📘 SetModArchive()

设置并覆盖当前模组的持久化存储数据（字符串，可通过Json扩展，最长限制512字符）。

数据内容存储到ModArchive.json文件，任意模组之间可相互获取，但只有当前模组可写入自身数据。

（出于安全考虑，此方法仅限World端使用，Client端是只读的）

function SetModArchive( content: string )

📘 GetModArchive()

尝试读取指定模组的持久化存储数据（可通过SetModArchive()写入修改），如不存在则返回空文本。

注意：如果不填写参数，默认获取当前模组的数据。

function GetModArchive( package: string = null ): string

📘 SetSaveItem()

设置并覆盖【存档数据槽（Slot）】指定Key的项目，并以最终Json的格式存储，仅支持基础类型（string\number\bool...）。

存档槽默认参数为0，如果只用于本地持久化数据存储，或者不需要多存档槽的设计，可以忽略Slot参数。

注意：此方法最多支持50个存档槽（文件），以及单文件最大1MB的写入空间。有关持久化存档相关内容，无论是单存档、多存档或其他使用场景，都可尝试此方案进行存储。

（出于安全考虑，此方法仅限World端使用，Client端是只读的）

function SetSaveItem( key: string, value: object, slot: int = 0 )

SetSaveItem("gold", 1000, 0); //Save file to 'SaveData/SaveData_0.json'
SetSaveItem("playerlevel", 3, 5); //Save file to 'SaveData/SaveData_5.json'

📘 RemoveSaveItem()

移除【存档数据槽（Slot）】指定Key的项目（并非删除存档，而是删除存档中的一个项）。

（出于安全考虑，此方法仅限World端使用，Client端是只读的）

function RemoveSaveItem( key: string, slot: int = 0 )

SetSaveItem("playerlevel", 3, 10); //Set level to 3
RemoveSaveItem("playerlevel", 10); //Remove 'playerlevel' item

📘 GetSaveItem()

尝试读取【存档数据槽（Slot）】指定Key的项目内容，如不存在则返回defaultValue。

function GetSaveItem( key: string, slot: int = 0, defaultValue: any = null ): any

SetSaveItem("gold", 1000); //Save file to 'SaveData/SaveData_0.json'
DLog("Your coin: " + GetSaveItem("gold"));

📘 ExistSaveItem()

判断【存档数据槽（Slot）】指定Key的项目内容是否为空（bool）。

function ExistSaveItem( key: string, slot: int = 0 ): bool

DLog(ExistSaveItem("gold"));

📘 ExistSaveData()

判断【存档数据槽（Slot）】存档文件是否已被创建（bool）。

function ExistSaveData( slot: int = 0 ): bool

📘 DeleteSaveData()

删除【存档数据槽（Slot）】存档文件，包括其文件内所有数据。

（出于安全考虑，此方法仅限World端使用）

function DeleteSaveData( slot: int = 0 ): bool

📘 SendSocketData()

发送Socket\Network网络通信数据。

在当前版本下，此方法主要用于外部UDP传输。

对应接收事件：OnDataServerReceive

//Address=IP:Port
function SendSocketData( address: string, data: string )

SendSocketData("127.0.0.1:8192", "Test");