📚 World/Core

📒 Event

📘 OnScriptLoad()

当世界端脚本被完整加载后调用，部分API需要放置在此事件执行才有效，因为至此脚本才加载完毕。

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

注意：此事件是真正意义上的“脚本加载完成”，因此如果有代码放置在JavaScript空白区域，并不一定会按照预期正确执行，有关初始化的代码建议放置在此处执行。

BindKey(...); //Invalid, Script not loaded
 
function OnScriptLoad()
{
	BindKey(...); //Correct
}

📘 OnScriptUnload()

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

📘 OnFrameUpdate( deltaTime )

当世界端加载完成后每逻辑帧（0.1s）调用，不应该将过于复杂的函数在此处执行，可能会影响服务器运算。

注意：此事件与Client同名事件不同，在World端并非每帧执行，而是以固定速率的逻辑帧执行。

function OnFrameUpdate( deltaTime：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 )
{
	//tag: throwcast tag
	//point: collision position
 
	//Prop grenade [tag] is "Grenade"
	if(tag == "Grenade")
	{
		DLog("An explosion tagged 'Grenad' was stopped!");
		return false;
	}
}

📘 OnWorldTimeChange( oldTime, newTime )

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

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

📘 OnWorldWeatherChange( oldWeather, newWeather )

当世界天气发生改变时调用。

function OnWorldWeatherChange( oldWeather: int, newWeather: int )

📘 OnServerQueryReceive( data, address )

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

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

function OnServerQueryReceive( data: string, address: string )

📘 OnConsoleInput( input )

当服务端模式接收到CMD控制台输入时调用，此事件仅在服务端模式下生效。

function OnConsoleInput( input : 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

📘 SetHostIcon()

设置主机房间图标形象，ID参考《资源文档——主机图标》，默认值：0。

选择贴合模组玩法主题的图标，可能会更吸引玩家。

function SetHostIcon( icon: int )

📘 GetHostIcon()

获取主机房间图标形象。

function GetHostIcon(): int

📘 SetHostAnnounce()

设置主机服务器搜索可见程度，这将影响服务器是否能被【多人游戏浏览器】成功搜索。

function SetHostAnnounce( announce: int )

类型	说明
0（默认）	公开
1	私有（隐藏互联网列表）

📘 GetHostAnnounce()

获取主机服务器搜索可见程度。

function GetHostAnnounce(): int

📘 SetHostTickRate()

设置主机网络传输率，数值越高网络同步越流畅，同时也会使用更多的宽带，范围限制10~100。

引擎默认网络传输率为30，开发者可根据不同场景玩法动态调整设置。

理论来说，在保证正常游戏的情况下，更低的网络传输率有助于提升游戏性能，但可能会降低网络同步体验。

开发者可以考虑根据自身游戏玩法设定一个最佳数值，或者根据当前游戏性能动态调整数值。

function SetHostTickRate( tickRate: int )

游戏类型	推荐数值
FPS射击、快节奏、高同步率	60+
常规游戏、RPG、普通节奏玩法	30~60
RTS、鸟瞰视角游戏、慢节奏玩法	10~30

注意：TickRate指服务端逻辑速率，实际表现严重受到【主机FPS\Frame】的影响，主机帧数越高（60+）同步性能越好，开发者可以参考《建立专用服务器》。

📘 GetHostTickRate()

获取主机网络传输率。

function GetHostTickRate(): int

📘 SetStreamVisualRange()

设置服务器流计算可视范围（距离），实体相对玩家超过指定距离将被认定为不可见、可见、较远（影响Entity.GetVisualRange()）。

此数值允许设定范围：32.0~128.0，数值越低渲染&计算范围越小，反之可能会使用更多的性能。

function SetStreamVisualRange( range: float )

📘 GetStreamVisualRange()

获取服务器流计算可视范围（距离）。

function GetStreamVisualRange(): float

📘 SetPassword()

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

function SetPassword( password: string )

📘 GetPassword()

获取主机房间密码。

function GetPassword(): string

📘 SetMaxPlayers()

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

function SetMaxPlayers( num: int )

📘 GetMaxPlayers()

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

function GetMaxPlayers(): int

📘 SetTime()

设置当前游戏世界时间。

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

function SetWorldTime( hour: int, minute: int )

📘 GetWorldTime()

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

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

📘 SetWorldTimeRate()

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

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

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

function SetWorldTimeRate( rate: float )

📘 GetWorldTimeRate()

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

function GetWorldTimeRate(): float

📘 SetWorldWeather()

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

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

function SetWorldWeather( weather: int )

📘 GetWorldWeather()

获取游戏世界天气。

function GetWorldWeather(): int

📘 GetRandomWorldWeather()

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

function GetRandomWorldWeather( usePool: bool = true ): int

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

📘 SetWorldGravity()

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

function SetWorldGravity( space: Vector )

📘 GetWorldGravity()

获取游戏世界物理重力。

function GetWorldGravity(): 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(180, 180, 180)。

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

function SetWorldFogColor( color: Color )

📘 GetWorldFogColor()

获取游戏世界雾颜色。

function GetWorldFogColor(): Color

📘 SetWorldSolarColor()

设置游戏世界日月颜色（太阳&月亮），默认为淡黄色Color(255, 253, 235)。

function SetWorldSolarColor( color: Color )

📘 GetWorldSolarColor()

获取游戏世界日月颜色（太阳&月亮）。

function GetWorldSolarColor(): Color

📘 SetWorldSolarScale()

设置游戏世界日月尺寸缩放（太阳&月亮），默认为1.0，限制范围0.0~10.0。

function SetWorldSolarScale( scale: float )

📘 GetWorldSolarScale()

获取游戏世界日月尺寸缩放（太阳&月亮）。

function GetWorldSolarScale(): float

📘 SetWorldCloudColor()

设置游戏世界云层颜色，默认为浅灰色Color(180, 180, 180)。

function SetWorldCloudColor( color: Color )

📘 GetWorldCloudColor()

获取游戏世界云层颜色。

function GetWorldCloudColor(): Color

📘 SetWorldCloudDensity()

设置游戏世界云层密度（强度），默认为0.5，限制范围0.0~1.0。

function SetWorldCloudDensity( density: float )

📘 GetWorldCloudDensity()

获取游戏世界云层密度（强度）。

function GetWorldCloudDensity(): float

📘 SetSkybox()

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

function SetSkybox( skybox: int )

📘 GetSkybox()

获取游戏世界天空盒。

function GetSkybox(): int

📘 SetSkyboxColor()

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

function SetSkyboxColor( color: Color )

📘 GetSkyboxColor()

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

function GetSkyboxColor(): Color

📘 SetSkyboxOffset()

设置游戏世界天空盒偏移（高度），默认1.0。

function SetSkyboxOffset( offset: float )

📘 GetSkyboxOffset()

获取游戏世界天空盒偏移（高度）。

function GetSkyboxOffset(): float

📘 SetSkyboxRotateSpeed()

设置游戏世界天空盒旋转速度，默认1.0。

如果设置为0则固定角度，如果设置为-1则使用地图默认速度。

function SetSkyboxRotateSpeed( speed: float = -1 )

📘 GetSkyboxRotateSpeed()

获取游戏世界天空盒旋转速度。

function GetSkyboxRotateSpeed(): float

📘 SetGameSpeed()

设置游戏世界速度（Beta），默认1.0，范围限制0.1~10.0。

function SetGameSpeed( speed: float )

📘 GetGameSpeed()

获取游戏世界速度。

function GetGameSpeed(): float

📘 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 )

📘 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 )

📘 CreateFireRadius()

在指定位置生成一片火焰（scale x 4），效果类似燃烧瓶，火焰将对附近的实体造成燃烧+传播伤害。

function CreateFireRadius( pos: Vector, time: float, scale: float = 1.0, onGround: bool = false )

📘 CreateSmoke()

在指定位置生成烟雾弹。

function CreateSmoke( pos: Vector, time: float, scale: float = 1.0, color: Color = Color(255, 255, 255) )

📘 CreateFlash()

在指定位置生成闪光弹，由于闪光弹的“白屏”特性，只有真实控制角色的玩家会受到影响。

function CreateFlash( pos: Vector, time: float, scale: float = 1.0, color: Color = Color(255, 255, 255) )

📘 CreateExplosion()

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

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

Type	说明
0	小型爆炸
1	中型爆炸
2	大型爆炸

📘 CreateExplosionForce()

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

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

📘 CreateRayPowerCast()

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

注意：射线移动（发射）速度是基于start ~ over的范围动态决定的。

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

fadeTime：光线存在时间，并非射线发射速度

📘 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()功能基本相同，但会额外多出子模型效果（例如射出的子弹、炮弹、弓箭、手榴弹模型等）。

注意：此处的localPos | localAngle | localScale表示绑定模型的自身本地坐标，默认情况下相关坐标应该保持Vector(0, 0, 0)（localScale除外），只有希望模型本地位置、旋转与射线偏移时才需要修改本地坐标。

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 )

📘 PlayWorldSound()

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

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

注意：通常情况下，除了必要全局同步的声音外，应该首选非WorldSound方法播放声音（例如PlaySoundForAll | Player.PlaySound ...）。

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

type：声音通道类型，表示客户端如何处理此类音频的音量0=Sound | 1=Music | 2=Natural

📘 PlayWorld3DSound()

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

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

注意：通常情况下，除了必要全局同步的声音外，应该首选非WorldSound方法播放声音（例如PlaySoundForAll | Player.PlaySound ...）。

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

type：声音通道类型，表示客户端如何处理此类音频的音量0=Sound | 1=Music | 2=Natural

📘 StopWorldSound()

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

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

📘 PauseWorldSound()

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

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

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

📘 ResumeWorldSound()

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

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

📘 RegisterKeyListener()

监听一个按键触发事件（当前场景有效），可用于监听玩家通过客户端绑定的某键（Client: BindKey | BindNativeKey）被按下\抬起。

相关事件：OnPlayerKeyDown() | OnPlayerKeyUp()

function RegisterKeyListener( keyTag: string )

keyTag：按键标签（需要与客户端绑定的keyTag一致）

📘 UnregisterKeyListener()

取消监听一个按键触发事件，对其按键监听不再生效。

function UnregisterKeyListener( keyTag: string )

📘 UnregisterAllKeyListener()

取消监听所有按键触发事件，对所有按键监听不再生效。

function UnregisterAllKeyListener()

📘 WriteHostFile()

写入文件（或以/结尾的文件夹）到模组主机目录Mod/Host，写入文件尺寸限制4MB，如果文件已存在则会覆盖。

此功能通常用于实现游戏存档\配置等，可以使用Json功能进行序列化。

function WriteHostFile( localPath: string, content: string = null )

📘 ReadHostFile()

从模组主机目录（Mod/Host）读取文件（文本内容），如果文件不存在则返回空白文本。

function ReadHostFile( localPath: string ): string

ReadFile( "Test.txt" ); //read: Mod/Space/Test.txt

📘 CopyHostFile()

从模组主机目录（Mod/Host）复制文件到新位置。

function CopyHostFile( localPath: string, pasteLocalPath: string ): bool

CopyHostFile( "Test.txt", "Test2.txt" );

📘 RenameHostFile()

从模组主机目录（Mod/Host）修改文件名称到新位置。

function RenameHostFile( localPath: string, renameLocalPath: string, isReplace: bool = false ): bool

isReplace如果目标文件已存在，是否强制替换

📘 ExistHostFile()

判断模组主机目录（Mod/Host）文件（或以/结尾的文件夹）是否存在。

function ExistHostFile( localPath: string ): bool

📘 DeleteHostFile()

删除模组主机目录（Mod/Host）文件（或以/结尾的文件夹，以及所有子文件）。

注意：删除操作是不可恢复的，谨慎使用。

function DeleteHostFile( localPath: string )

📘 SetModArchive()

此方法已在V0.83移除。

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

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

function SetModArchive( content: string )

📘 GetModArchive()