Frost Scripting API#

New to FrostEngine? Start with the Developer Guide: lessons from a first project to a shipped game and an MMO realm. Its website opens from the editor's Help > Developer Guide; the release package ships it as Guide/index.html, and in the engine's repository python Scripts/Guide/BuildGuideSite.py --out build/<preset>/guide-site builds it.

Scripts are Lua 5.4 modules that return a class table. The Script class section describes what a script defines for the engine (callbacks, property declarations, RPC methods); every name in the other sections is available in every script.

Globals#

Member	Kind	Summary
`Wait(seconds: number)`	GlobalFunction	Inside a coroutine started with self:StartCoroutine: resumes after the given scaled seconds (at the earliest the next frame).
`WaitFrames(frames: integer)`	GlobalFunction	Inside an engine coroutine: resumes after the given number of frames (>= 1).
`WaitUntil(predicate: function)`	GlobalFunction	Inside an engine coroutine: resumes in the first later frame in which predicate() returns a true value (checked once per frame).
`_G: table`	GlobalValue	The script's own global environment (each script and module has its own).
`_VERSION: string`	GlobalValue	The Lua version ("Lua 5.4").
`assert(v: any, message?: any, ...: any): any`	GlobalFunction	Raises an error when v is false or nil (message defaults to "assertion failed!"); otherwise returns all its arguments.
`error(message: any, level?: integer)`	GlobalFunction	Raises an error with message.
`getmetatable(object: any): any`	GlobalFunction	The metatable of object, or its __metatable field when present (engine values and tables report a protected value).
`ipairs(t: table): function, table, integer`	GlobalFunction	Iterator over the pairs (1, t[1]), (2, t[2]), ...
`load(chunk: string, chunkName?: string, mode?: string, env?: table): function?, string?`	GlobalFunction	Compiles a chunk of Lua source text into a function, which runs in env or, by default, in the environment of the calling script.
`next(t: table, index?: any): any, any`	GlobalFunction	The key and value that follow index in t (the first pair when index is nil); nil after the last pair.
`pairs(t: table): function, table, any`	GlobalFunction	Iterator over all key/value pairs of t (honors a __pairs metamethod).
`pcall(f: function, ...: any): boolean, any`	GlobalFunction	Calls f in protected mode: returns true and f's results, or false and the error object.
`print(...: any)`	GlobalFunction	Logs the arguments (converted with tostring and separated by tabs) as an info message prefixed with the script location.
`rawequal(a: any, b: any): boolean`	GlobalFunction	Equality without the __eq metamethod.
`rawget(t: table, key: any): any`	GlobalFunction	t[key] without the __index metamethod.
`rawlen(v: table\|string): integer`	GlobalFunction	Length without the __len metamethod.
`rawset(t: table, key: any, value: any): table`	GlobalFunction	t[key] = value without the __newindex metamethod; returns t.
`require(moduleName: string): any`	GlobalFunction	Loads a project module: "Utils.Math" (or "Utils/Math") runs Assets/Scripts/Utils/Math.lua once in its own environment and returns (and caches) its result, true when it returns nothing.
`select(index: integer\|string, ...: any): any`	GlobalFunction	The arguments after position index (negative counts from the end), or their count when index is "#".
`setmetatable(t: table, metatable: table?): table`	GlobalFunction	Sets (or removes, with nil) the metatable of a table and returns the table.
`tonumber(value: any, base?: integer): number?`	GlobalFunction	Converts a number or numeric string (in the given base, 2-36) to a number; nil when not convertible.
`tostring(value: any): string`	GlobalFunction	Human-readable string for any value (honors __tostring and __name).
`type(value: any): string`	GlobalFunction	The basic type name: "nil", "number", "string", "boolean", "table", "function", "thread" or "userdata".
`xpcall(f: function, handler: function, ...: any): boolean, any`	GlobalFunction	Like pcall, calling handler with the error object (e.g.

Wait#

lua

Wait(seconds: number)

Inside a coroutine started with self:StartCoroutine: resumes after the given scaled seconds (at the earliest the next frame).

Parameters

seconds (number)

Example

lua

Wait(0.25)

WaitFrames#

lua

WaitFrames(frames: integer)

Inside an engine coroutine: resumes after the given number of frames (>= 1).

Parameters

frames (integer)

WaitUntil#

lua

WaitUntil(predicate: function)

Inside an engine coroutine: resumes in the first later frame in which predicate() returns a true value (checked once per frame).

Parameters

predicate (function)

Example

lua

WaitUntil(function() return self.Target == nil end)

_G#

lua

_G: table

The script's own global environment (each script and module has its own).

_VERSION#

lua

_VERSION: string

The Lua version ("Lua 5.4").

assert#

lua

assert(v: any, message?: any, ...: any): any

Raises an error when v is false or nil (message defaults to "assertion failed!"); otherwise returns all its arguments.

Parameters

v (any)
message? (any)
...? (any)

Returns any

error#

lua

error(message: any, level?: integer)

Raises an error with message. Level 1 (default) prefixes the position where error was called, 2 the position of its caller, 0 no position.

Parameters

message (any)
level? (integer)

getmetatable#

lua

getmetatable(object: any): any

The metatable of object, or its __metatable field when present (engine values and tables report a protected value).

Parameters

object (any)

Returns any

ipairs#

lua

ipairs(t: table): function, table, integer

Iterator over the pairs (1, t[1]), (2, t[2]), ... up to the first nil value.

Parameters

t (table)

Returns function, table, integer

load#

lua

load(chunk: string, chunkName?: string, mode?: string, env?: table): function?, string?

Compiles a chunk of Lua source text into a function, which runs in env or, by default, in the environment of the calling script. Only text chunks are accepted (binary chunks and reader functions are rejected). Returns nil and the error message for syntax errors.

Parameters

chunk (string)
chunkName? (string): Name used in error messages.
mode? (string): Must allow text ("t").
env? (table)

Returns function?, string?: The compiled function, or nil and an error message.

Example

lua

local f = load("return 1 + 2")
print(f()) -- 3

next#

lua

next(t: table, index?: any): any, any

The key and value that follow index in t (the first pair when index is nil); nil after the last pair.

Parameters

t (table)
index? (any)

Returns any, any

pairs#

lua

pairs(t: table): function, table, any

Iterator over all key/value pairs of t (honors a __pairs metamethod).

Parameters

t (table)

Returns function, table, any

pcall#

lua

pcall(f: function, ...: any): boolean, any

Calls f in protected mode: returns true and f's results, or false and the error object.

Parameters

f (function)
...? (any)

Returns boolean, any

print#

lua

print(...: any)

Logs the arguments (converted with tostring and separated by tabs) as an info message prefixed with the script location. The editor shows info messages; a game running on its own (an exported game or a server of the release) drops them: use Log.Warn/Log.Error for messages players' logs must keep.

Parameters

...? (any)

Example

lua

print("Spawned", count, "enemies")

rawequal#

lua

rawequal(a: any, b: any): boolean

Equality without the __eq metamethod.

Parameters

a (any)
b (any)

Returns boolean

rawget#

lua

rawget(t: table, key: any): any

t[key] without the __index metamethod.

Parameters

t (table)
key (any)

Returns any

rawlen#

lua

rawlen(v: table|string): integer

Length without the __len metamethod.

Parameters

v (table|string)

Returns integer

rawset#

lua

rawset(t: table, key: any, value: any): table

t[key] = value without the __newindex metamethod; returns t.

Parameters

t (table)
key (any)
value (any)

Returns table

require#

lua

require(moduleName: string): any

Loads a project module: "Utils.Math" (or "Utils/Math") runs Assets/Scripts/Utils/Math.lua once in its own environment and returns (and caches) its result, true when it returns nothing. Names may not leave Assets/Scripts; circular requires are errors. A module's changes reload the scripts that use it.

Parameters

moduleName (string)

Returns any: The module's result.

Example

lua

local Utils = require("Utils.Math")

select#

lua

select(index: integer|string, ...: any): any

The arguments after position index (negative counts from the end), or their count when index is "#".

Parameters

index (integer|string)
...? (any)

Returns any

setmetatable#

lua

setmetatable(t: table, metatable: table?): table

Sets (or removes, with nil) the metatable of a table and returns the table. Protected metatables cannot be changed, and metatables with a __gc field are rejected (finalizers would run outside the script watchdog).

Parameters

t (table)
metatable (table?)

Returns table

tonumber#

lua

tonumber(value: any, base?: integer): number?

Converts a number or numeric string (in the given base, 2-36) to a number; nil when not convertible.

Parameters

value (any)
base? (integer)

Returns number?

tostring#

lua

tostring(value: any): string

Human-readable string for any value (honors __tostring and __name).

Parameters

value (any)

Returns string

type#

lua

type(value: any): string

The basic type name: "nil", "number", "string", "boolean", "table", "function", "thread" or "userdata".

Parameters

value (any)

Returns string

xpcall#

lua

xpcall(f: function, handler: function, ...: any): boolean, any

Like pcall, calling handler with the error object (e.g. debug.traceback) before the stack unwinds. When the watchdog stopped the call, the handler is skipped and the error passes through.

Parameters

f (function)
handler (function)
...? (any)

Returns boolean, any

Script class#

What a script defines for the engine: a script asset returns a class table; the engine creates an instance of it per Script component, fills it with the declared properties and calls the callback methods the class defines. These are not Lua globals: the names below are what the engine looks for in the class. In the script editor's language server definitions (.frost/lua-api/frost.lua) the Script part is the class FrostScript (annotate a script's class table with ---@class Player : FrostScript to get its callbacks and fields typed), a property declaration is a FrostPropertyDefinition and a property type a FrostPropertyType.

Script#

A script is a Lua module that returns its class table; the class name is the file name. The engine creates one instance per Script component: a table with self.Entity (the entity) and the declared properties (Properties: the override set on the component, else the default), whose metatable reads the class's methods, so the methods below and any others take self. The engine calls the callbacks a class defines (a class needs none of them); other methods run when scripts call them, through Entity:SendMessage(name, ...), as a UIButton's OnClick method, or as an RPC.

Order within a frame: pending work first (removed components get OnDestroy, new instances OnCreate), then OnFixedUpdate for each fixed step, then OnUpdate (followed by the coroutines started with StartCoroutine, then the timers), then OnLateUpdate; collision and trigger callbacks run after each physics step, animation events while the animation system advances, network callbacks at the network update. Callbacks reach only instances whose OnCreate ran; an error in a callback is logged with its traceback and disables that instance (a hot reload of its script enables it again).

RPC methods: only methods whose names end in ServerRpc or ClientRpc can run remotely (self:ServerRpc("DamageServerRpc", ...), self:ClientRpc("FlashClientRpc", target, ...); ScriptInstance). A ServerRpc runs on the server and needs the caller to own the entity unless the class declares RpcOptions = { DamageServerRpc = { RequireOwnership = false } }; a ClientRpc is sent by the server to all clients, one client or all but the owner. Calls go reliably and in order unless the class declares RpcOptions = { AimServerRpc = { Reliable = false } } for that method (a ServerRpc or a ClientRpc): such calls may be lost or overtaken. Calls that arrive before the instance's OnCreate wait for it.

Reserved names: Entity, Properties, the callback names and the ScriptInstance methods (StartCoroutine, StopCoroutine, StopAllCoroutines, ServerRpc, ClientRpc) cannot be properties.

lua

local Player = {}

Player.Properties = {
	Speed = { Type = "Float", Default = 5.0, Min = 0, Max = 20, Tooltip = "Move speed" },
	Mode = { Type = "Enum", Options = { "Walk", "Run" }, Default = "Walk" },
	Waypoints = { Type = "Array", ElementType = "Vec2", MaxCount = 8, Header = "Path" },
	Bullet = { Type = "Prefab", Default = "Assets/Prefabs/Bullet.fprefab" },
	Health = { Type = "Int", Default = 100, Replicated = true },
}

function Player:OnCreate()
	self.Body = self.Entity:GetComponent("Rigidbody2D")
end

function Player:OnUpdate(dt)
	local move = Input.GetAxis("Horizontal") * self.Speed
	self.Body:SetLinearVelocity(Vec2(move, 0))
end

function Player:OnCollisionBegin(other, contact)
	if other.Name == "Coin" then other:Destroy() end
end

function Player:DamageServerRpc(amount)
	self.Health = self.Health - amount
end

return Player

Member	Kind	Summary
`Script.Entity: Entity`	ClassField	The instance's entity (`self.Entity`), set by the engine before OnCreate.
`Script.Properties: table<string, FrostPropertyDefinition\|boolean\|number\|string\|Vec2\|Vec3\|Vec4\|Color>?`	ClassField	The class's property declarations (see Properties): a declaration table or the shorthand default value per property name.
`Script.RpcOptions: table<string, { RequireOwnership?: boolean, Reliable?: boolean }>?`	ClassField	Per RPC method, by name: RequireOwnership = false lets any client call a ServerRpc (default: only the entity's owner); Reliable = false sends the calls of a ServerRpc or ClientRpc unreliably - they may be lost or overtaken (default: reliable and ordered).
`Script.UpdateMode: "EveryTick"\|"Sliced"?`	ClassField	How the class's instances get OnUpdate: "EveryTick" (the default) every frame; "Sliced" round robin within the project's Server.Scripts.SlicedUpdateBudgetMs per frame, each instance with the time since its own previous OnUpdate as dt - for thousands of instances (NPC rules) that need not all update every frame.
`Script.Budget: { MsPerTick: number }?`	ClassField	The class's cost budget per frame (all its instances' callbacks, coroutines and timers together; default: the project's Server.Scripts.ClassBudgetMs).
`function Script:OnCreate()`	Callback	Called once per instance before its first update callback: at runtime start for the components of the scene (in scene order) and at the next update phase for components added or scripts assigned later.
`function Script:OnUpdate(dt: number)`	Callback	Called once per frame while the scene plays, with the frame's scaled delta time in seconds (0 while Time.TimeScale is 0; a paused scene runs no callbacks).
`function Script:OnFixedUpdate(dt: number)`	Callback	Called once per fixed step of the scene (zero, one or several times per frame), before the physics step, with the scene's FixedTimestep: apply forces and move bodies here.
`function Script:OnLateUpdate(dt: number)`	Callback	Called once per frame after every instance's OnUpdate, the coroutines and timers and the other systems' updates (animation, particles): follow cameras and read final positions here.
`function Script:OnDestroy()`	Callback	Called once when an instance whose OnCreate ran goes away: its entity is destroyed, its Script component is removed or gets another script, or the scene stops (in reverse creation order).
`function Script:OnGameTick(tick: integer)`	Callback	Called on every instance that defines it at each game tick of the scene: a whole number of fixed steps set by the project's Server.GameTickMs or the scene's GameTickMs (RuneScape-style rules: 600 ms).
`function Script:OnThink(dt: number)`	Callback	Called by the AI scheduler when the entity's AIAgent is due to think and names no native handler: often near players (NearIntervalMs), rarely far from them (FarIntervalMs), never while it sleeps beyond SleepDistance.
`function Script:OnCollisionBegin(other: Entity, contact: Contact)`	Callback	Two colliders started touching (once per entity pair), after the physics step: called on both collider entities and, for child colliders, on their body entities.
`function Script:OnCollisionEnd(other: Entity)`	Callback	Two colliders stopped touching (also when one was destroyed or disabled), after the physics step; called like OnCollisionBegin.
`function Script:OnTriggerEnter(other: Entity)`	Callback	A collider entered a sensor collider (IsSensor), after the physics step: called on both entities (and their body entities).
`function Script:OnTriggerExit(other: Entity)`	Callback	A collider left a sensor collider, after the physics step; called like OnTriggerEnter.
`function Script:OnAnimationEvent(name: string, clip: integer)`	Callback	The playhead of the entity's SpriteAnimator crossed an event of its AnimationClip: every event crossed in an animation update is delivered once, in playback order, after the animators of the frame were updated.
`function Script:OnNetworkSpawn()`	Callback	The instance's entity became part of the network session (after OnCreate): a runtime spawn (Net.Spawn on the server, received by a client) or, for an entity placed in the scene with a NetworkIdentity, when the session binds the scene (a server starting or loading it, a client entering it).
`function Script:OnClientConnected(clientId: integer)`	Callback	Called on every instance of the scene when a client joined the session (on a host also for its own player, client 0), and on a client once its own connection is established.
`function Script:OnClientDisconnected(clientId: integer?, reason: string, message: string)`	Callback	Called on every instance of the scene when a client left the session, and on a client when its own connection ended (clientId is nil when the connection failed before it was established).
`function Script:OnReplicatedChanged(propertyName: string)`	Callback	A Replicated property's value from the server changed (clients; on a host the local player sees the server's values once they are sent).
`function Script:OnAdminAction(action: string, target: integer, actor: integer)`	Callback	Zone servers: a GM action succeeded on this zone - an operator's through the Admin Console or a GM's in-game command.
`function Script:OnBehaviorEvent(name: string)`	Callback	An event the NPC's tree handled (BehaviorTree.SendEvent, a SendEvent node of any NPC, a command): called on the NPC's script after the think that handled it, in think order, once per event.
`function Script:OnBorderEvent(sender: Entity?, event: string, args: table, fromZone: string)`	Callback	Server: a neighbouring zone forwarded an interaction with this entity across a seamless border (Border.Send there, on this entity's ghost).
`function Script:OnDataReloaded(table: string)`	Callback	A new version of a data table was swapped in (a hot reload: live content on a server, a saved file in a play session): `table` is its path below Assets/.
`function Script:OnHotReload()`	Callback	A new version of the instance's script class (or of a module or data table it requires) was activated on this server (a staged hot reload, content.activate) or rolled back: the instance kept its property values and now runs the new methods.
`function Script:OnGatewayConnected()`	Callback	Called on every script of the scene when the secure channel to the gateway is up (Gateway.Connect): create an account or log in now.
`function Script:OnGatewayResult(requestId: integer, ok: boolean, result: table)`	Callback	Called on every script of the scene when a Gateway request finished: requestId is what the request returned, result is { Kind ("login", "createAccount", "listRealms", "listCharacters", "createCharacter", "deleteCharacter", "enterWorld", "leaveQueue", "logout"), Code ("ok" or an error code), Message (for players; never internal details), RetryAfterMs, Data (by kind; see each request) }.
`function Script:OnQueueUpdate(realm: string, position: integer, waitSeconds: integer)`	Callback	Called on every script of the scene while EnterWorld waits in a full realm's queue (every few seconds): the 1-based position and an estimated wait; position 0 = admitted (the grant follows as OnGatewayResult).
`function Script:OnGatewayDisconnected(reason: string, message: string)`	Callback	Called on every script of the scene when the gateway connection ended or could not be made: reason is a disconnect reason ("AuthenticationFailed" when the gateway is not the one the game pins, "Timeout", "ConnectFailed", "ServerShutdown", ...), message its text.
`function Script:OnMovementStep(state: MovementState, command: MovementCommand, dt: number)`	Callback	CharacterMovement with ScriptExtension: called after each native step of the entity (kinematic: every fixed step; Grid: every game tick) on whichever peer simulates it - the server, and the owner's client while it predicts and replays.
`function Script:OnNavArrived()`	Callback	The entity's NavAgent arrived where its MoveTo or MoveToEntity sent it (its state is "Arrived").
`function Script:OnNavFailed()`	Callback	The entity's NavAgent gave up (its state is "Failed"): no path leads to the goal, it reached the end of a partial path, its followed target is gone, or it stayed stuck after three repaths.
`function Script:OnRelevancyChanged(relevant: boolean)`	Callback	Clients: a scene-placed networked entity started (true) or stopped (false) being replicated to this client - interest management (NetworkRelevancy).
`function Script:OnPerceived(target: Entity, sense: string)`	Callback	The NPC's perception acquired a target ("Sight" or "Hearing").
`function Script:OnTargetLost(target: Entity?)`	Callback	The NPC lost a tracked target: out of range, unseen for 5 seconds, disabled, forgotten - or destroyed (nil then).
`function Script:OnSpawned(spawner: Entity)`	Callback	On a spawned NPC's script, once its OnCreate ran: the spawner that made it (its home, leash, patrol path and phase are set).
`function Script:OnSpawnerSpawned(npc: Entity)`	Callback	On a spawner's script: one of its slots spawned `npc`.
`function Script:OnSpawnerDepleted()`	Callback	On a spawner's script: its last living NPC died (every slot waits to respawn).
`function Script:OnSpawnerRespawnDue(slot: integer): boolean`	Callback	On a spawner with RespawnRule Scripted, when a dead slot's delay ran out: return false to keep it dead (until Spawner.Respawn); true, nil or no such method respawns it.
`function Script:OnLeash()`	Callback	The NPC ran past its leash and evades home (its target cleared, its tree paused).
`function Script:OnLeashEnd()`	Callback	The evading NPC is home: Idle, its tree restarted.
`function Script:OnServiceTransferResult(transferId: integer, ok: boolean, error: string)`	Callback	A Persistence.Transact call with service operands finished its central escrow transaction.
`function Script:OnPersistentLoaded()`	Callback	The entity's persistent state was restored (its Persistence component's record: Persistent component fields and script properties, and the data fields Persistence.Get reads).
`function Script:OnPersistentSaved()`	Callback	A save of the entity's record became durable on the server's disk (autosave, Persistence.SaveNow, logout).
`function Script:OnCharacterLoaded(client: integer, characterId: integer)`	Callback	Server (and offline games): a player's character finished loading - every script of the scene gets it, like OnClientConnected.
`function Script:OnBeforeHandoff(player: integer, destination: string): boolean?`	Callback	Server: before a handoff reserves its destination.
`function Script:OnHandoffOut(player: integer, destination: string)`	Callback	Source server: the destination accepted the character state and the player is told to switch sessions.
`function Script:OnHandoffIn(player: integer, source: string)`	Callback	Destination server: the source handed over the player.
`function Script:OnHandoffFailed(player: integer, destination: string, reason: string)`	Callback	Source server: a handoff failed and the connected player remains here.
`function Script:OnZoneChanged(zone: string, mode: string, player: integer)`	Callback	Client: the destination's initial relevant set arrived and the client atomically switched sessions.
`function Script:OnZoneSwitchFailed(reason: string, message: string)`	Callback	Client: a pending zone switch failed.
`function Script:OnEffectApplied(effect: string, caster: Entity?, stacks: integer)`	Callback	Servers: a status effect was applied to (or stacked, refreshed on) the actor; delivered at the tick's RpgEvents stage.
`function Script:OnEffectRemoved(effect: string, caster: Entity?, stacks: integer)`	Callback	Servers: a status effect ended on the actor (expired, removed, dispelled, broken by damage, death).
`function Script:OnStatChanged(stat: string, value: number, previous: number)`	Callback	Servers: a stat Stats.Subscribe subscribed to changed - its final value, a Resource stat's current value - at the tick's RpgEvents stage.
`function Script:OnDeath(killer: Entity?)`	Callback	Servers: the actor died (its health reached 0 or Rpg.Kill).
`function Script:OnRespawn()`	Callback	Servers: the player came back to life (Rpg.Respawn, the automatic respawn after Rpg.RespawnSeconds); with Rpg.Respawn = Script this is where the game moves it.
`function Script:OnRpgEvent(event: table)`	Callback	Servers: an event of the RPG event bus about the actor or with it as the target - { Kind ("Damage", "Heal", "Death", "Kill", "EffectApplied", ..., "Custom"), Tick, SourceSystem, Actor, Source, Target, KeyHash, Key (the effect or faction key when known), Amount, Value, Flags }.
`function Script:OnRpgRequestResult(id: integer, status: string, code: integer, message: string)`	Callback	Clients: the server answered a request of this client (Rpg.SetTarget, Rpg.Interact, Rpg.Respawn and the other RPG modules' requests); on every script that defines it, at the next update.
`function Script:OnOwnerSectionChanged(section: string)`	Callback	Clients: a section of the local character's private state changed ("Stats", "Effects", "Cooldowns", "Inventory", ...): refresh the UI that shows it.
`function Script:OnPublicStateChanged(entity: Entity)`	Callback	Clients: the server sent new visible state of an entity (its visible status effects, its ground cast's point).
`function Script:OnDamaged(source: Entity?, hit: { Amount: number, Ability: string?, School: string?, Crit: boolean, Miss: boolean, Absorbed: boolean, Immune: boolean, Killing: boolean })`	Callback	Scenes with authority: the actor took a hit that the combat step resolved (an ability, an auto-attack swing, a periodic effect, a projectile or Combat.DealDamage) - also a miss and a hit an immune actor ignored.
`function Script:OnHealed(source: Entity?, hit: { Amount: number, Ability: string?, Crit: boolean })`	Callback	Scenes with authority: the actor was healed by `source` (nil for the world) for Amount (what it gained).
`function Script:OnKilled(victim: Entity?, template: string?, level: integer)`	Callback	Scenes with authority: a kill credited this player character (its tagger's party near the victim shares it): the victim (nil once it no longer exists), its NpcTemplate key (nil for a player) and its level.
`function Script:OnAbilityCast(ability: string, target: Entity?)`	Callback	Scenes with authority: the actor completed a cast of the ability (an instant one when it resolved, a cast at its end, a channel after its last tick); `target` is its target actor, if any.
`function Script:OnCastInterrupted(ability: string, source: Entity?)`	Callback	Scenes with authority: an Interrupt effect or Combat.Interrupt ended the actor's cast or channel of the ability; `source` is the interrupter (nil for a script without one).
`function Script:OnItemAdded(item: string, quantity: integer)`	Callback	On a character's script: items entered its containers (loot, rewards, trade, purchases), once the operation that changed them is complete; these callbacks may change the inventory again (their own callbacks follow in order).
`function Script:OnItemRemoved(item: string, quantity: integer)`	Callback	On a character's script: items left its containers (used, destroyed, sold, traded).
`function Script:OnEquipmentChanged(slot: string, item: string?)`	Callback	On a character's script: the item in an equipment slot changed (nil: the slot became empty).
`function Script:OnLootAvailable(source: Entity)`	Callback	On a player's script: a corpse or ground item has loot it may take.
`function Script:OnTradeChanged(trade: integer, state: string)`	Callback	On both traders' scripts: Opened, Changed (an offer, or a trader's backpack or wallet, changed: both accept again), Accepted, Completed, Failed or Cancelled.
`function Script:OnXpGained(xp: integer, source: string)`	Callback	On a player character's script (servers and offline games): it gained character XP - from a kill (its share of the party's), a quest, a craft or gather without a skill, a first visit of a region, a script or a GM.
`function Script:OnLevelUp(level: integer)`	Callback	On a player character's script: it reached a character level (RpgActor.Level was raised and the class abilities of the level were learned).
`function Script:OnSkillLevelUp(skill: string, level: integer)`	Callback	On a player character's script: it reached a level in a skill (once per level, in order).
`function Script:OnCrafted(recipe: string, remaining: integer)`	Callback	On a player character's script: one craft of a batch completed (the inputs were taken, the outputs whose chance came up were given and the recipe's XP granted, all in one inventory transaction).
`function Script:OnGathered(node: Entity?, nodeKey: string)`	Callback	On a player character's script: a gather completed - the node's loot table rolled into the backpack, the skill XP was granted and a charge spent (at its last charge the node is Depleted until it respawns).
`function Script:OnReputationChanged(faction: string, standing: integer, change: integer)`	Callback	On a player character's script: its standing with a tracked faction changed (a kill's template, a quest, a script, a GM).
`function Script:OnActionEnded(kind: string, reason: string)`	Callback	On a player character's script: its craft batch or gather ended - every craft done or the gather completed, a cancel (the owner's CancelCraft request or the game's code), a move farther than Combat.MoveCancelDistance, its death, or a check that failed at completion (inputs, tools, station, space, a depleted node).
`function Script:OnQuestAccepted(quest: string)`	Callback	On a player's script: a quest entered its log (the start step began).
`function Script:OnQuestStepCompleted(quest: string, step: string)`	Callback	On a player's script: a step of an active quest was completed (the quest moved on).
`function Script:OnQuestCompleted(quest: string)`	Callback	On a player's script: a quest was turned in and its rewards granted.
`function Script:OnQuestFailed(quest: string, reason: string)`	Callback	On a player's script: an active quest ended unfinished: Failed (a link to fail), TimedOut, EscortDied or Abandoned.
`function Script:OnDialogueStarted(npc: Entity?, dialogue: string)`	Callback	On a player's script: a conversation began (npc nil: a quest step's dialogue).
`function Script:OnDialogueNode(dialogue: string, node: string)`	Callback	On a player's script: the conversation reached a Line or Choice node, or ran an Action node.
`function Script:OnDialogueEnded(npc: Entity?, reason: string)`	Callback	On a player's script: the conversation ended: End, Player, Distance, Timeout, Replaced, Error.
`function Script:OnServiceResult(requestId: integer, ok: boolean, result: table)`	Callback	Called on every script of the scene when a player-services request finished (exactly once per request id): result is { Kind ("chat.send", "friends.add", "party.invite", ...), Code ("ok" or an error: "notFound", "quotaExceeded", "overloaded", "unavailable", ...), Message, RetryAfterMs } plus by kind MessageId, Friends and Ignored, Friend, Party.
`function Script:OnChatMessage(message: table)`	Callback	Called on every script of the scene for a chat message: { MessageId, Channel, Kind ("Say", "Yell", "Emote", "Whisper", "Party", "Raid", "Guild", "Officer", "RealmChannel", "System"), SenderId, SenderName, Text, SentAtUnixMs }.
`function Script:OnPresenceChanged(friends: table)`	Callback	Called on every script of the scene when friends' presence changed: a list of { CharacterId, Name, Status, Zone } (at most one update per friend per presence interval).
`function Script:OnPartyChanged(event: table)`	Callback	Called on every script of the scene for party events: { Kind = "Changed", Party }, { Kind = "Invite", PartyId, FromName }, { Kind = "Disbanded", PartyId } (the party ended, or you are no longer in it), { Kind = "ReadyCheck", PartyId, ReadyCheck = { PartyId, InitiatorId, DeadlineUnixMs, Ready, NotReady, Finished } }.
`function Script:OnGuildChanged(event: table)`	Callback	Guild event Kind: Changed (Guild), MemberChanged (Member: a joined, promoted, demoted or new leader member; Rank 255 when the member left or was removed), Invited (GuildId,GuildName,FromName), Motd, BankChanged (Tab,Version), or Left (GuildId).
`function Script:OnMailReceived(mail: table)`	Callback	A mail delivery summary with Kind Received, or Kind Returned with MailId.
`function Script:OnMarketResult(requestId: integer, ok: boolean, result: table)`	Callback	Called on every script of the scene when a Market request finished: result = { Kind ("search", "myListings", "myOffers", "priceHistory", "createListing", "bid", "buyout", "cancelListing", "placeOffer", "cancelOffer", "collect", "confirmTransfer"), Code ("ok" or an error code), Message, RetryAfterMs } plus the request's data (see each function).
`function Script:OnLeaderboardResult(requestId: integer, ok: boolean, result: table)`	Callback	Called on every script of the scene when a Leaderboards request finished: { Kind ("top", "rank", "around", "submit"), Code, Message, RetryAfterMs, Entries, Total }.
`function Script:OnMatchmakingResult(requestId: integer, ok: boolean, result: table)`	Callback	Called on every script of the scene when a Matchmaking request finished: { Kind ("join", "leave", "ready"), Code, Message, RetryAfterMs, Ticket }.
`function Script:OnMarketEvent(event: table)`	Callback	Called on every script of the scene for a market event of the player: { Kind = "Outbid" \| "Sold" (Price) \| "Won" \| "Expired" \| "Cancelled" (an operator cancelled the listing), ListingId } or { Kind = "OfferFilled", Offer }.
`function Script:OnMatchFound(matchId: integer, queue: string, readySeconds: integer, role: string)`	Callback	Called on every script of the scene when a group formed for the player: answer with Matchmaking.RespondReady within readySeconds.
`function Script:OnMatchReady(matchId: integer, instance: table)`	Callback	Called on every script of the scene when everyone accepted and the coordinator created the instance ({ Zone, Shard, Layer, InstanceId }); the coordinator moves the group there.
`function Script:OnMatchCancelled(matchId: integer, reason: string)`	Callback	Called on every script of the scene when a found match ended without an instance (a decline, a timeout, the coordinator's refusal) or the party left the queue (matchId 0).
`function Script:OnQueuePosition(queue: string, estimatedWaitSeconds: integer)`	Callback	Called on every script of the scene every few seconds while the player waits in a queue (0: no estimate yet).
`function Script:OnUIPointerEnter(position: Vec2, pointerId: integer)`	Callback	A pointer's UI target became this element: the nearest button or slider at or above the front-most element that blocks the pointer (its raycast target).
`function Script:OnUIPointerExit(position: Vec2, pointerId: integer)`	Callback	A pointer's UI target was this element and became another one (or none).
`function Script:OnUIPointerDown(position: Vec2, pointerId: integer)`	Callback	The left mouse button or the primary finger went down while this element was the pointer's target.
`function Script:OnUIPointerUp(position: Vec2, pointerId: integer)`	Callback	The left mouse button or the finger that went down on this element was released (wherever the pointer is then); a release over an interactable button that is still the target also clicks it (UIButton.OnClick, click listeners).
`function Script:OnUIValueChanged(value: number)`	Callback	A pointer moved this UISlider to a new value (the slider's script gets it).
`function Script:OnUIScroll(offset: Vec2)`	Callback	This UIScrollView scrolled (a drag, a fling or the mouse wheel; the scroll view's script gets it).
`function Script:OnUIFocusGained()`	Callback	The button got the keyboard/gamepad focus (UI.SetFocus, a UICanvas with AutoFocus, navigation).
`function Script:OnUIFocusLost()`	Callback	The button lost the focus (another one got it, or it was hidden, disabled or destroyed).
`function Script:OnUICancel(focused: Entity)`	Callback	The Cancel input (Escape, gamepad B) while a button has the focus: the focused button's script gets it first, else the nearest element or canvas above it (up to its root canvas) whose script defines it.
`function Script:OnUITextChanged(text: string, field: Entity)`	Callback	The player changed a UIInputField's text (typing, deleting, pasting, undo; once per frame; UIInputField:SetText sends none).
`function Script:OnUISubmit(text: string, field: Entity)`	Callback	Enter in a single-line UIInputField (Ctrl+Enter in a multi-line one, or the gamepad's Submit while it has the focus).
`function Script:OnUIDragBegin(source: Entity, pointerId: integer)`	Callback	A drag of a UIDraggable began (the pointer moved past its DragThreshold, or the gamepad picked it up).
`function Script:OnUIDrop(payload: string, source: Entity, target: Entity, payloadType: string)`	Callback	A drag was dropped on this UIDropTarget (it accepts the payload's type).
`function Script:OnUIDragEnd(source: Entity, target: Entity?)`	Callback	The drag of this element ended: after OnUIDrop with its target, or with nil when it was released elsewhere or cancelled (Cancel, the element hidden or disabled).
`function Script:OnUIToggleChanged(isOn: boolean, toggle: Entity)`	Callback	A click or Submit switched a UIToggle, or turning on another toggle of its radio group turned it off (UIToggle:SetOn sends none).
`function Script:OnUIDropdownChanged(index: integer, option: string, dropdown: Entity)`	Callback	The player selected another option of a UIDropdown (a click on a row of its popup, or the arrows and Submit; UIDropdown:SetSelected sends none).
`function Script:OnUITooltipShown(owner: Entity, content: Entity?)`	Callback	The tooltip of an element with UITooltip showed (the pointer, or the keyboard/gamepad focus, rested on it for its Delay): fill its Content element here (an item's name and stats).
`function Script:OnUITooltipHidden(owner: Entity)`	Callback	The element's tooltip was hidden (the pointer left it, a press or a drag, UI.HideTooltip).
`function Script:OnVolumeEnter(volume: Entity, entity: Entity)`	Callback	A tracked entity (a player, or a VolumeTracker entity) entered a TriggerVolume whose Filter accepts it, at a fixed step of this frame (Once: only the first entry of any entity; CooldownSeconds: no entry of any entity before it passed - both belong to the volume).
`function Script:OnVolumeExit(volume: Entity, entity: Entity)`	Callback	An entity whose OnVolumeEnter was raised left that TriggerVolume (or stopped being tracked).
`function Script:OnRegionChanged(entity: Entity, region: string?, previous: string?)`	Callback	The highest-priority RegionVolume containing a tracked entity changed: region and previous are RegionVolume Names (nil: outside every region).
`function Script:OnPhaseVolumeEntered(player: Entity, phase: integer)`	Callback	A player entered a PhaseVolume: the game may put the player's client in the phase (Net.SetClientPhase).
`function Script:OnCellLoaded(x: integer, y: integer, layer: string)`	Callback	A cell of the scene's world finished loading: every entity of it exists (their scripts' OnCreate follows).
`function Script:OnCellUnloaded(x: integer, y: integer, layer: string)`	Callback	A cell of the scene's world that OnCellLoaded announced is unloading: its entities are destroyed from this frame on, as many a frame as the streaming budget allows (World-scope persistent entities save first).
`function Script:OnWorldOriginShifted(dx: number, dy: number)`	Callback	The scene's origin moved by (dx, dy) world units (SceneSettings.OriginShiftDistance on clients, or Scene rebasing): every entity moved by (-dx, -dy) so positions near the camera keep full precision.

Script.Entity#

lua

Script.Entity: Entity

The instance's entity (self.Entity), set by the engine before OnCreate.

Script.Properties#

lua

Script.Properties: table<string, FrostPropertyDefinition|boolean|number|string|Vec2|Vec3|Vec4|Color>?

The class's property declarations (see Properties): a declaration table or the shorthand default value per property name.

Script.RpcOptions#

lua

Script.RpcOptions: table<string, { RequireOwnership?: boolean, Reliable?: boolean }>?

Per RPC method, by name: RequireOwnership = false lets any client call a ServerRpc (default: only the entity's owner); Reliable = false sends the calls of a ServerRpc or ClientRpc unreliably - they may be lost or overtaken (default: reliable and ordered).

Script.UpdateMode#

lua

Script.UpdateMode: "EveryTick"|"Sliced"?

How the class's instances get OnUpdate: "EveryTick" (the default) every frame; "Sliced" round robin within the project's Server.Scripts.SlicedUpdateBudgetMs per frame, each instance with the time since its own previous OnUpdate as dt - for thousands of instances (NPC rules) that need not all update every frame. Sliced updates run after the other instances' OnUpdate; the ones the budget does not reach update first next frame (Server.GetScriptStats reports them as DeferredUpdates). Any other value is reported and treated as "EveryTick".

Script.Budget#

lua

Script.Budget: { MsPerTick: number }?

The class's cost budget per frame (all its instances' callbacks, coroutines and timers together; default: the project's Server.Scripts.ClassBudgetMs). A class over it is reported (at most once per Server.Scripts.ReportIntervalSeconds) and counted (Server.GetScriptStats, the Tick Profiler panel); nothing is stopped - the per-call watchdog stops runaway calls. Server.SetScriptBudget overrides it at runtime.

Script:OnCreate#

lua

function Script:OnCreate()

Called once per instance before its first update callback: at runtime start for the components of the scene (in scene order) and at the next update phase for components added or scripts assigned later. The properties are set when it runs; start coroutines and cache components here.

Example

lua

function Enemy:OnCreate()
	self.Sprite = self.Entity:GetComponent("SpriteRenderer")
end

Script:OnUpdate#

lua

function Script:OnUpdate(dt: number)

Called once per frame while the scene plays, with the frame's scaled delta time in seconds (0 while Time.TimeScale is 0; a paused scene runs no callbacks). The coroutines and timers run after every instance's OnUpdate.

Parameters

dt (number): Scaled seconds since the previous frame.

Script:OnFixedUpdate#

lua

function Script:OnFixedUpdate(dt: number)

Called once per fixed step of the scene (zero, one or several times per frame), before the physics step, with the scene's FixedTimestep: apply forces and move bodies here.

Parameters

dt (number): The fixed step in seconds.

Script:OnLateUpdate#

lua

function Script:OnLateUpdate(dt: number)

Called once per frame after every instance's OnUpdate, the coroutines and timers and the other systems' updates (animation, particles): follow cameras and read final positions here.

Parameters

dt (number): Scaled seconds since the previous frame.

Script:OnDestroy#

lua

function Script:OnDestroy()

Called once when an instance whose OnCreate ran goes away: its entity is destroyed, its Script component is removed or gets another script, or the scene stops (in reverse creation order). Its coroutines and timers stop with it.

Script:OnGameTick#

lua

function Script:OnGameTick(tick: integer)

Called on every instance that defines it at each game tick of the scene: a whole number of fixed steps set by the project's Server.GameTickMs or the scene's GameTickMs (RuneScape-style rules: 600 ms). Game ticks happen during the fixed update of the step that completes them, after the native game-tick listeners (grid movement, AI). Scenes without game ticks never call it.

Parameters

tick (integer): The game tick's number, 1 for the first one since the scene started.

Example

lua

function Mine:OnGameTick(tick)
	if tick % 4 == 0 then self.Ore = self.Ore + 1 end
end

Script:OnThink#

lua

function Script:OnThink(dt: number)

Called by the AI scheduler when the entity's AIAgent is due to think and names no native handler: often near players (NearIntervalMs), rarely far from them (FarIntervalMs), never while it sleeps beyond SleepDistance. Thinks run within the project's Server.AI.BudgetMs per fixed step, higher Priority first; AI.Wake makes an agent think at once.

Parameters

dt (number): Seconds since the agent's previous think (0 for the first one).

Example

lua

function Wolf:OnThink(dt)
	self.Hunger = self.Hunger + dt
	if self.Hunger > 10 then self:Hunt() end
end

Script:OnCollisionBegin#

lua

function Script:OnCollisionBegin(other: Entity, contact: Contact)

Two colliders started touching (once per entity pair), after the physics step: called on both collider entities and, for child colliders, on their body entities. other is the other collider's entity (IsValid() is false once it was destroyed).

Parameters

other (Entity): The other collider's entity.
contact (Contact): The contact: Point, Normal (towards other), PointCount, Collider, OtherBody.

Script:OnCollisionEnd#

lua

function Script:OnCollisionEnd(other: Entity)

Two colliders stopped touching (also when one was destroyed or disabled), after the physics step; called like OnCollisionBegin.

Parameters

other (Entity): The other collider's entity.

Script:OnTriggerEnter#

lua

function Script:OnTriggerEnter(other: Entity)

A collider entered a sensor collider (IsSensor), after the physics step: called on both entities (and their body entities).

Parameters

other (Entity): The other collider's entity.

Script:OnTriggerExit#

lua

function Script:OnTriggerExit(other: Entity)

A collider left a sensor collider, after the physics step; called like OnTriggerEnter.

Parameters

other (Entity): The other collider's entity.

Script:OnAnimationEvent#

lua

function Script:OnAnimationEvent(name: string, clip: integer)

The playhead of the entity's SpriteAnimator crossed an event of its AnimationClip: every event crossed in an animation update is delivered once, in playback order, after the animators of the frame were updated.

Parameters

name (string): The event's name in the clip.
clip (integer): The AnimationClip asset's handle.

Example

lua

function Hero:OnAnimationEvent(name)
	if name == "Footstep" then Audio.PlayOneShot(self.Step) end
end

Script:OnNetworkSpawn#

lua

function Script:OnNetworkSpawn()

The instance's entity became part of the network session (after OnCreate): a runtime spawn (Net.Spawn on the server, received by a client) or, for an entity placed in the scene with a NetworkIdentity, when the session binds the scene (a server starting or loading it, a client entering it).

Script:OnClientConnected#

lua

function Script:OnClientConnected(clientId: integer)

Called on every instance of the scene when a client joined the session (on a host also for its own player, client 0), and on a client once its own connection is established.

Parameters

clientId (integer): The client's id.

Script:OnClientDisconnected#

lua

function Script:OnClientDisconnected(clientId: integer?, reason: string, message: string)

Called on every instance of the scene when a client left the session, and on a client when its own connection ended (clientId is nil when the connection failed before it was established). The player is already gone from the session: Net.GetPlayerName(clientId) returns nil here, so a script that names leaving players keeps the name it read in OnClientConnected. A session the game ends itself reports nothing to its own scripts.

Parameters

clientId (integer?): The client's id, or nil.
reason (string): Why it ended: "ClientDisconnected" (the client left), "Kicked", "ServerShutdown", "AuthenticationFailed", "ConnectionLost", "Timeout", ...
message (string): The reason's text on a client (the kick reason, "Wrong password", the server's shutdown notice); empty on the server.

Example

lua

function Lobby:OnClientDisconnected(id, reason, message)
	Log.Info(string.format("%s left: %s %s", tostring(id), reason, message))
end

Script:OnReplicatedChanged#

lua

function Script:OnReplicatedChanged(propertyName: string)

A Replicated property's value from the server changed (clients; on a host the local player sees the server's values once they are sent). Values that arrive with the spawn are set before OnCreate and not announced.

Parameters

propertyName (string): The property's name.

Script:OnAdminAction#

lua

function Script:OnAdminAction(action: string, target: integer, actor: integer)

Zone servers: a GM action succeeded on this zone - an operator's through the Admin Console or a GM's in-game command. action is its name ("teleport", "spawn", a script command), target the character it acted on (0: none), actor the operator's or GM's account id. Every scripted entity of the scene gets it.

Parameters

action (string)
target (integer)
actor (integer)

Script:OnBehaviorEvent#

lua

function Script:OnBehaviorEvent(name: string)

An event the NPC's tree handled (BehaviorTree.SendEvent, a SendEvent node of any NPC, a command): called on the NPC's script after the think that handled it, in think order, once per event.

Parameters

name (string): The event's name.

Example

lua

function Guard:OnBehaviorEvent(name)
	if name == "Alarm" then self.Alarmed = true end
end

Script:OnBorderEvent#

lua

function Script:OnBorderEvent(sender: Entity?, event: string, args: table, fromZone: string)

Server: a neighbouring zone forwarded an interaction with this entity across a seamless border (Border.Send there, on this entity's ghost). sender is the sending entity's ghost on this zone when it has one (else nil), args the values it sent (scene entities by reference; runtime-spawned ones arrive as nil), fromZone the neighbour's process key. Events are bounded (64-byte names, 4 KiB of arguments) and rate-limited per link (Network.Borders EventsPerSecond, EventBurst): treat them like client input, not like trusted calls.

Parameters

sender (Entity?): The sender's ghost here, or nil.
event (string): The event's name.
args (table): The arguments (an array).
fromZone (string): The neighbour that forwarded it ("Lumbridge@1.1").

Example

lua

function Door:OnBorderEvent(sender, event, args, fromZone)
	if event == "Open" then self:Open() end
end

Script:OnDataReloaded#

lua

function Script:OnDataReloaded(table: string)

A new version of a data table was swapped in (a hot reload: live content on a server, a saved file in a play session): table is its path below Assets/. Rows read through DataRow proxies already see the new version; rebuild what was derived from the old data here. Called once per table on every script instance that defines it, at the next update after the swap.

Parameters

table (string)

Example

lua

function Shop:OnDataReloaded(table)
	if table == "Data/Prices.ftable" then self:RebuildPrices() end
end

Script:OnHotReload#

lua

function Script:OnHotReload()

A new version of the instance's script class (or of a module or data table it requires) was activated on this server (a staged hot reload, content.activate) or rolled back: the instance kept its property values and now runs the new methods. Called once per active instance at the tick boundary of the swap; rebuild what was derived from the old code or data here.

Example

lua

function Shop:OnHotReload()
	self.Prices = require("Data.Prices")
end

Script:OnGatewayConnected#

lua

function Script:OnGatewayConnected()

Called on every script of the scene when the secure channel to the gateway is up (Gateway.Connect): create an account or log in now.

Script:OnGatewayResult#

lua

function Script:OnGatewayResult(requestId: integer, ok: boolean, result: table)

Called on every script of the scene when a Gateway request finished: requestId is what the request returned, result is { Kind ("login", "createAccount", "listRealms", "listCharacters", "createCharacter", "deleteCharacter", "enterWorld", "leaveQueue", "logout"), Code ("ok" or an error code), Message (for players; never internal details), RetryAfterMs, Data (by kind; see each request) }.

Parameters

requestId (integer)
ok (boolean)
result (table)

Script:OnQueueUpdate#

lua

function Script:OnQueueUpdate(realm: string, position: integer, waitSeconds: integer)

Called on every script of the scene while EnterWorld waits in a full realm's queue (every few seconds): the 1-based position and an estimated wait; position 0 = admitted (the grant follows as OnGatewayResult).

Parameters

realm (string)
position (integer)
waitSeconds (integer)

Script:OnGatewayDisconnected#

lua

function Script:OnGatewayDisconnected(reason: string, message: string)

Called on every script of the scene when the gateway connection ended or could not be made: reason is a disconnect reason ("AuthenticationFailed" when the gateway is not the one the game pins, "Timeout", "ConnectFailed", "ServerShutdown", ...), message its text. Not called for Gateway.Disconnect or when the zone connection takes over.

Parameters

reason (string)
message (string)

Script:OnMovementStep#

lua

function Script:OnMovementStep(state: MovementState, command: MovementCommand, dt: number)

CharacterMovement with ScriptExtension: called after each native step of the entity (kinematic: every fixed step; Grid: every game tick) on whichever peer simulates it - the server, and the owner's client while it predicts and replays. Change state to change the step's result (rules such as mud or a dash); it must be deterministic for the same inputs, since replays run it again. Non-finite values written to it are ignored. dt: the step's length in seconds.

Parameters

state (MovementState)
command (MovementCommand)
dt (number)

Example

lua

function Player:OnMovementStep(state, command, dt)
	if command.Run then state.Velocity = state.Velocity * 1.1 end
end

Script:OnNavArrived#

lua

function Script:OnNavArrived()

The entity's NavAgent arrived where its MoveTo or MoveToEntity sent it (its state is "Arrived"). Called on the agent's script one fixed step after the arrival, before OnFixedUpdate.

Example

lua

function Guard:OnNavArrived()
	self.Waypoint = self.Waypoint % #self.Route + 1
	self.Agent:MoveTo(self.Route[self.Waypoint])
end

Script:OnNavFailed#

lua

function Script:OnNavFailed()

The entity's NavAgent gave up (its state is "Failed"): no path leads to the goal, it reached the end of a partial path, its followed target is gone, or it stayed stuck after three repaths. Called on the agent's script one fixed step later, before OnFixedUpdate.

Script:OnRelevancyChanged#

lua

function Script:OnRelevancyChanged(relevant: boolean)

Clients: a scene-placed networked entity started (true) or stopped (false) being replicated to this client - interest management (NetworkRelevancy). While it is not relevant the entity keeps its last state (its renderers are hidden when NetworkRelevancy HideWhenIrrelevant is set). Runtime-spawned entities are spawned and despawned instead (OnNetworkSpawn, OnDestroy).

Parameters

relevant (boolean)

Example

lua

function Door:OnRelevancyChanged(relevant)
	self.Entity:GetComponent("SpriteRenderer").Color = relevant and Color(1, 1, 1, 1) or Color(1, 1, 1, 0.3)
end

Script:OnPerceived#

lua

function Script:OnPerceived(target: Entity, sense: string)

The NPC's perception acquired a target ("Sight" or "Hearing"). Delivered in the update after the perception step.

Parameters

target (Entity): The perceived entity.
sense (string): How it was sensed: "Sight" or "Hearing".

Script:OnTargetLost#

lua

function Script:OnTargetLost(target: Entity?)

The NPC lost a tracked target: out of range, unseen for 5 seconds, disabled, forgotten - or destroyed (nil then).

Parameters

target (Entity?): The lost entity, nil when it no longer exists.

Script:OnSpawned#

lua

function Script:OnSpawned(spawner: Entity)

On a spawned NPC's script, once its OnCreate ran: the spawner that made it (its home, leash, patrol path and phase are set).

Parameters

spawner (Entity): The spawner entity.

Script:OnSpawnerSpawned#

lua

function Script:OnSpawnerSpawned(npc: Entity)

On a spawner's script: one of its slots spawned npc.

Parameters

npc (Entity): The new NPC.

Script:OnSpawnerDepleted#

lua

function Script:OnSpawnerDepleted()

On a spawner's script: its last living NPC died (every slot waits to respawn).

Script:OnSpawnerRespawnDue#

lua

function Script:OnSpawnerRespawnDue(slot: integer): boolean

On a spawner with RespawnRule Scripted, when a dead slot's delay ran out: return false to keep it dead (until Spawner.Respawn); true, nil or no such method respawns it.

Parameters

slot (integer): The slot, from 0.

Returns boolean

Script:OnLeash#

lua

function Script:OnLeash()

The NPC ran past its leash and evades home (its target cleared, its tree paused).

Script:OnLeashEnd#

lua

function Script:OnLeashEnd()

The evading NPC is home: Idle, its tree restarted.

Script:OnServiceTransferResult#

lua

function Script:OnServiceTransferResult(transferId: integer, ok: boolean, error: string)

A Persistence.Transact call with service operands finished its central escrow transaction. Only ok=true means the character and service records committed together; Guild and Mail transfers are confirmed with their service automatically; confirm Market transfers with Market.ConfirmTransfer.

Parameters

transferId (integer)
ok (boolean)
error (string)

Script:OnPersistentLoaded#

lua

function Script:OnPersistentLoaded()

The entity's persistent state was restored (its Persistence component's record: Persistent component fields and script properties, and the data fields Persistence.Get reads). Runs after OnCreate, once the record is loaded: a character's record arrives after its avatar spawned, so its OnCreate still sees the declared defaults and Persistence.Get raises there - read saved values here. A new character or world object gets it too, with the defaults.

Script:OnPersistentSaved#

lua

function Script:OnPersistentSaved()

A save of the entity's record became durable on the server's disk (autosave, Persistence.SaveNow, logout).

Script:OnCharacterLoaded#

lua

function Script:OnCharacterLoaded(client: integer, characterId: integer)

Server (and offline games): a player's character finished loading - every script of the scene gets it, like OnClientConnected. Spawn the player's avatar here (Net.Spawn(prefab, position, client)): a Character-scope entity the player owns gets the character's state the frame it appears. Offline the local player's character loads when the scene starts (client 0).

Parameters

client (integer): The player's client id (0: the host's or offline game's own player).
characterId (integer): The character's id (the session token's, or the local player's: 1).

Example

lua

function Game:OnCharacterLoaded(client, characterId)
	Net.Spawn("Assets/Prefabs/Hero.fprefab", Vec2(0, 0), client)
end

Script:OnBeforeHandoff#

lua

function Script:OnBeforeHandoff(player: integer, destination: string): boolean?

Server: before a handoff reserves its destination. Every active script is consulted in scene order. False or an error refuses travel; true, nil or an absent callback permits it. destination describes the requested zone, layer, instance, shard or border.

Parameters

player (integer)
destination (string)

Returns boolean?

Script:OnHandoffOut#

lua

function Script:OnHandoffOut(player: integer, destination: string)

Source server: the destination accepted the character state and the player is told to switch sessions.

Parameters

player (integer)
destination (string)

Script:OnHandoffIn#

lua

function Script:OnHandoffIn(player: integer, source: string)

Destination server: the source handed over the player. source is the source zone process key; the avatar and transferred properties are present.

Parameters

player (integer)
source (string)

Script:OnHandoffFailed#

lua

function Script:OnHandoffFailed(player: integer, destination: string, reason: string)

Source server: a handoff failed and the connected player remains here. The reason explains the refusal or timeout.

Parameters

player (integer)
destination (string)
reason (string)

Script:OnZoneChanged#

lua

function Script:OnZoneChanged(zone: string, mode: string, player: integer)

Client: the destination's initial relevant set arrived and the client atomically switched sessions. zone is the destination's zone process key ("Draynor@1.1", "Crypt@1#42"; empty when its server did not name it), mode is "Seamless" (the same scene, nothing reloaded) or "Loading" (the destination's scene was loaded), player is the new local network client id.

Parameters

zone (string)
mode (string)
player (integer)

Script:OnZoneSwitchFailed#

lua

function Script:OnZoneSwitchFailed(reason: string, message: string)

Client: a pending zone switch failed. The source session remains usable while it is still connected.

Parameters

reason (string)
message (string)

Script:OnEffectApplied#

lua

function Script:OnEffectApplied(effect: string, caster: Entity?, stacks: integer)

Servers: a status effect was applied to (or stacked, refreshed on) the actor; delivered at the tick's RpgEvents stage.

Parameters

effect (string): The effect's key.
caster (Entity?): Who applied it (nil: no caster).
stacks (integer): Its stacks after the change.

Script:OnEffectRemoved#

lua

function Script:OnEffectRemoved(effect: string, caster: Entity?, stacks: integer)

Servers: a status effect ended on the actor (expired, removed, dispelled, broken by damage, death).

Parameters

effect (string): The effect's key.
caster (Entity?): Who had applied it.
stacks (integer): The stacks it had.

Script:OnStatChanged#

lua

function Script:OnStatChanged(stat: string, value: number, previous: number)

Servers: a stat Stats.Subscribe subscribed to changed - its final value, a Resource stat's current value - at the tick's RpgEvents stage.

Parameters

stat (string): The stat's key.
value (number): Its new value.
previous (number): The value reported before.

Script:OnDeath#

lua

function Script:OnDeath(killer: Entity?)

Servers: the actor died (its health reached 0 or Rpg.Kill).

Parameters

killer (Entity?): Who killed it (nil: nobody, or it no longer exists).

Script:OnRespawn#

lua

function Script:OnRespawn()

Servers: the player came back to life (Rpg.Respawn, the automatic respawn after Rpg.RespawnSeconds); with Rpg.Respawn = Script this is where the game moves it.

Script:OnRpgEvent#

lua

function Script:OnRpgEvent(event: table)

Servers: an event of the RPG event bus about the actor or with it as the target - { Kind ("Damage", "Heal", "Death", "Kill", "EffectApplied", ..., "Custom"), Tick, SourceSystem, Actor, Source, Target, KeyHash, Key (the effect or faction key when known), Amount, Value, Flags }. Clients: a transient event of the lane - { Kind ("CombatText", "CastStart", "CastStop", "ProjectileSpawn", "ProjectileImpact", "Loot", "LevelUp", "EffectFlash"), Tick, Source, Target, KeyHash, Key, Amount, Flags, Point, Speed, Priority, Admitted } on every script that defines it.

Parameters

event (table): The event's fields.

Script:OnRpgRequestResult#

lua

function Script:OnRpgRequestResult(id: integer, status: string, code: integer, message: string)

Clients: the server answered a request of this client (Rpg.SetTarget, Rpg.Interact, Rpg.Respawn and the other RPG modules' requests); on every script that defines it, at the next update.

Parameters

id (integer): The request's id.
status (string): "Ok", "Refused", "RateLimited", "OutOfRange", ...
code (integer): The handler's detail code.
message (string): A short explanation (empty for Ok).

Script:OnOwnerSectionChanged#

lua

function Script:OnOwnerSectionChanged(section: string)

Clients: a section of the local character's private state changed ("Stats", "Effects", "Cooldowns", "Inventory", ...): refresh the UI that shows it. Once per section and update.

Parameters

section (string): The section's name.

Script:OnPublicStateChanged#

lua

function Script:OnPublicStateChanged(entity: Entity)

Clients: the server sent new visible state of an entity (its visible status effects, its ground cast's point). Once per entity and update.

Parameters

entity (Entity): The entity.

Script:OnDamaged#

lua

function Script:OnDamaged(source: Entity?, hit: { Amount: number, Ability: string?, School: string?, Crit: boolean, Miss: boolean, Absorbed: boolean, Immune: boolean, Killing: boolean })

Scenes with authority: the actor took a hit that the combat step resolved (an ability, an auto-attack swing, a periodic effect, a projectile or Combat.DealDamage) - also a miss and a hit an immune actor ignored. source is the attacker (nil for the world or an attacker that no longer exists); Amount is what the actor lost after mitigation and absorbs, Ability and School name what hit (nil for scripted or periodic damage without them). Delivered during the RPG events' dispatch of the fixed step, in its order.

Parameters

source (Entity?)
hit ({ Amount: number, Ability: string?, School: string?, Crit: boolean, Miss: boolean, Absorbed: boolean, Immune: boolean, Killing: boolean })

Example

lua

function Boss:OnDamaged(source, hit)
	if hit.Crit then Log.Info("ouch: " .. hit.Amount) end
end

Script:OnHealed#

lua

function Script:OnHealed(source: Entity?, hit: { Amount: number, Ability: string?, Crit: boolean })

Scenes with authority: the actor was healed by source (nil for the world) for Amount (what it gained).

Parameters

source (Entity?)
hit ({ Amount: number, Ability: string?, Crit: boolean })

Example

lua

function Player:OnHealed(source, hit)
	Log.Info("+" .. hit.Amount)
end

Script:OnKilled#

lua

function Script:OnKilled(victim: Entity?, template: string?, level: integer)

Scenes with authority: a kill credited this player character (its tagger's party near the victim shares it): the victim (nil once it no longer exists), its NpcTemplate key (nil for a player) and its level.

Parameters

victim (Entity?)
template (string?)
level (integer)

Example

lua

function Player:OnKilled(victim, template, level)
	if template == "wolf" then self.Wolves = self.Wolves + 1 end
end

Script:OnAbilityCast#

lua

function Script:OnAbilityCast(ability: string, target: Entity?)

Scenes with authority: the actor completed a cast of the ability (an instant one when it resolved, a cast at its end, a channel after its last tick); target is its target actor, if any.

Parameters

ability (string)
target (Entity?)

Example

lua

function Mage:OnAbilityCast(ability, target)
	if ability == "blink" then self.Blinks = self.Blinks + 1 end
end

Script:OnCastInterrupted#

lua

function Script:OnCastInterrupted(ability: string, source: Entity?)

Scenes with authority: an Interrupt effect or Combat.Interrupt ended the actor's cast or channel of the ability; source is the interrupter (nil for a script without one). Delivered in the fixed step after the RPG events.

Parameters

ability (string)
source (Entity?)

Example

lua

function Boss:OnCastInterrupted(ability, source)
	self.Enraged = true
end

Script:OnItemAdded#

lua

function Script:OnItemAdded(item: string, quantity: integer)

On a character's script: items entered its containers (loot, rewards, trade, purchases), once the operation that changed them is complete; these callbacks may change the inventory again (their own callbacks follow in order).

Parameters

item (string): The item key.
quantity (integer): How many.

Script:OnItemRemoved#

lua

function Script:OnItemRemoved(item: string, quantity: integer)

On a character's script: items left its containers (used, destroyed, sold, traded).

Parameters

item (string): The item key.
quantity (integer): How many.

Script:OnEquipmentChanged#

lua

function Script:OnEquipmentChanged(slot: string, item: string?)

On a character's script: the item in an equipment slot changed (nil: the slot became empty).

Parameters

slot (string): The EquipSlot key.
item (string?): The item key now worn, or nil.

Script:OnLootAvailable#

lua

function Script:OnLootAvailable(source: Entity)

On a player's script: a corpse or ground item has loot it may take.

Parameters

source (Entity): The corpse or the GroundItem entity.

Script:OnTradeChanged#

lua

function Script:OnTradeChanged(trade: integer, state: string)

On both traders' scripts: Opened, Changed (an offer, or a trader's backpack or wallet, changed: both accept again), Accepted, Completed, Failed or Cancelled.

Parameters

trade (integer): The trade.
state (string): What happened.

Script:OnXpGained#

lua

function Script:OnXpGained(xp: integer, source: string)

On a player character's script (servers and offline games): it gained character XP - from a kill (its share of the party's), a quest, a craft or gather without a skill, a first visit of a region, a script or a GM. Delivered at the end of the progression step, before the OnLevelUp calls the XP caused. XP stops at the max level's: then nothing is gained.

Parameters

xp (integer): The XP gained (after the max level's cap).
source (string): "Kill", "Quest", "Craft", "Gather", "Exploration", "Script" or "Gm".

Example

lua

function Player:OnXpGained(xp, source)
	Log.Info("+" .. xp .. " XP from " .. source)
end

Script:OnLevelUp#

lua

function Script:OnLevelUp(level: integer)

On a player character's script: it reached a character level (RpgActor.Level was raised and the class abilities of the level were learned). XP across several levels at once calls it once per level, in order. A GM's or a script's lower level calls nothing.

Parameters

level (integer): The level reached.

Example

lua

function Player:OnLevelUp(level)
	Log.Info("reached level " .. level)
end

Script:OnSkillLevelUp#

lua

function Script:OnSkillLevelUp(skill: string, level: integer)

On a player character's script: it reached a level in a skill (once per level, in order).

Parameters

skill (string): The Skill row key.
level (integer): The level reached.

Example

lua

function Player:OnSkillLevelUp(skill, level)
	Log.Info(skill .. " is now level " .. level)
end

Script:OnCrafted#

lua

function Script:OnCrafted(recipe: string, remaining: integer)

On a player character's script: one craft of a batch completed (the inputs were taken, the outputs whose chance came up were given and the recipe's XP granted, all in one inventory transaction).

Parameters

recipe (string): The Recipe row key.
remaining (integer): The crafts of the batch still to come (0 for the last).

Example

lua

function Player:OnCrafted(recipe, remaining)
	if remaining == 0 then Log.Info("done: " .. recipe) end
end

Script:OnGathered#

lua

function Script:OnGathered(node: Entity?, nodeKey: string)

On a player character's script: a gather completed - the node's loot table rolled into the backpack, the skill XP was granted and a charge spent (at its last charge the node is Depleted until it respawns).

Parameters

node (Entity?): The ResourceNode entity, nil when it no longer exists.
nodeKey (string): The GatheringNode row key.

Example

lua

function Player:OnGathered(node, nodeKey)
	Log.Info("gathered from " .. nodeKey)
end

Script:OnReputationChanged#

lua

function Script:OnReputationChanged(faction: string, standing: integer, change: integer)

On a player character's script: its standing with a tracked faction changed (a kill's template, a quest, a script, a GM). The tier the standing falls in decides the faction's relation to the player.

Parameters

faction (string): The Faction row key.
standing (integer): The new standing.
change (integer): The change (negative for a loss).

Example

lua

function Player:OnReputationChanged(faction, standing, change)
	Log.Info(faction .. ": " .. standing)
end

Script:OnActionEnded#

lua

function Script:OnActionEnded(kind: string, reason: string)

On a player character's script: its craft batch or gather ended - every craft done or the gather completed, a cancel (the owner's CancelCraft request or the game's code), a move farther than Combat.MoveCancelDistance, its death, or a check that failed at completion (inputs, tools, station, space, a depleted node).

Parameters

kind (string): "Craft" or "Gather".
reason (string): "Completed", "Cancelled", "Moved", "Interrupted" or "Failed".

Example

lua

function Player:OnActionEnded(kind, reason)
	if reason == "Moved" then Log.Info(kind .. " interrupted") end
end

Script:OnQuestAccepted#

lua

function Script:OnQuestAccepted(quest: string)

On a player's script: a quest entered its log (the start step began).

Parameters

quest (string): The quest's Id.

Script:OnQuestStepCompleted#

lua

function Script:OnQuestStepCompleted(quest: string, step: string)

On a player's script: a step of an active quest was completed (the quest moved on).

Parameters

quest (string): The quest's Id.
step (string): The completed step's id.

Script:OnQuestCompleted#

lua

function Script:OnQuestCompleted(quest: string)

On a player's script: a quest was turned in and its rewards granted.

Parameters

quest (string): The quest's Id.

Script:OnQuestFailed#

lua

function Script:OnQuestFailed(quest: string, reason: string)

On a player's script: an active quest ended unfinished: Failed (a link to fail), TimedOut, EscortDied or Abandoned.

Parameters

quest (string): The quest's Id.
reason (string): Why.

Script:OnDialogueStarted#

lua

function Script:OnDialogueStarted(npc: Entity?, dialogue: string)

On a player's script: a conversation began (npc nil: a quest step's dialogue).

Parameters

npc (Entity?): Who speaks.
dialogue (string): The dialogue's Id.

Script:OnDialogueNode#

lua

function Script:OnDialogueNode(dialogue: string, node: string)

On a player's script: the conversation reached a Line or Choice node, or ran an Action node.

Parameters

dialogue (string): The dialogue's Id.
node (string): The node's id.

Script:OnDialogueEnded#

lua

function Script:OnDialogueEnded(npc: Entity?, reason: string)

On a player's script: the conversation ended: End, Player, Distance, Timeout, Replaced, Error.

Parameters

npc (Entity?): Who spoke.
reason (string): Why it ended.

Script:OnServiceResult#

lua

function Script:OnServiceResult(requestId: integer, ok: boolean, result: table)

Called on every script of the scene when a player-services request finished (exactly once per request id): result is { Kind ("chat.send", "friends.add", "party.invite", ...), Code ("ok" or an error: "notFound", "quotaExceeded", "overloaded", "unavailable", ...), Message, RetryAfterMs } plus by kind MessageId, Friends and Ignored, Friend, Party. "unavailable" also when the zone did not answer in time or the session ended. Request ids count per family of services: Chat, Friends, Party, Social, Guild and Mail requests share one sequence (their results arrive here), Market, Leaderboards and Matchmaking requests another (OnMarketResult, OnLeaderboardResult, OnMatchmakingResult) - so a Mail.Send and a Leaderboards.Submit may both answer 1: match a result by its callback and its id together.

Parameters

requestId (integer)
ok (boolean)
result (table)

Script:OnChatMessage#

lua

function Script:OnChatMessage(message: table)

Called on every script of the scene for a chat message: { MessageId, Channel, Kind ("Say", "Yell", "Emote", "Whisper", "Party", "Raid", "Guild", "Officer", "RealmChannel", "System"), SenderId, SenderName, Text, SentAtUnixMs }. Mutes and notices arrive with Kind "System" (a mute also with MutedUntilUnixMs). Messages of ignored players are not delivered.

Parameters

message (table)

Script:OnPresenceChanged#

lua

function Script:OnPresenceChanged(friends: table)

Called on every script of the scene when friends' presence changed: a list of { CharacterId, Name, Status, Zone } (at most one update per friend per presence interval).

Parameters

friends (table)

Script:OnPartyChanged#

lua

function Script:OnPartyChanged(event: table)

Called on every script of the scene for party events: { Kind = "Changed", Party }, { Kind = "Invite", PartyId, FromName }, { Kind = "Disbanded", PartyId } (the party ended, or you are no longer in it), { Kind = "ReadyCheck", PartyId, ReadyCheck = { PartyId, InitiatorId, DeadlineUnixMs, Ready, NotReady, Finished } }.

Parameters

event (table)

Script:OnGuildChanged#

lua

function Script:OnGuildChanged(event: table)

Guild event Kind: Changed (Guild), MemberChanged (Member: a joined, promoted, demoted or new leader member; Rank 255 when the member left or was removed), Invited (GuildId,GuildName,FromName), Motd, BankChanged (Tab,Version), or Left (GuildId).

Parameters

event (table)

Script:OnMailReceived#

lua

function Script:OnMailReceived(mail: table)

A mail delivery summary with Kind Received, or Kind Returned with MailId.

Parameters

mail (table)

Script:OnMarketResult#

lua

function Script:OnMarketResult(requestId: integer, ok: boolean, result: table)

Called on every script of the scene when a Market request finished: result = { Kind ("search", "myListings", "myOffers", "priceHistory", "createListing", "bid", "buyout", "cancelListing", "placeOffer", "cancelOffer", "collect", "confirmTransfer"), Code ("ok" or an error code), Message, RetryAfterMs } plus the request's data (see each function). Market, Leaderboards and Matchmaking requests share one sequence of ids, separate from the player services' of OnServiceResult.

Parameters

requestId (integer)
ok (boolean)
result (table)

Script:OnLeaderboardResult#

lua

function Script:OnLeaderboardResult(requestId: integer, ok: boolean, result: table)

Called on every script of the scene when a Leaderboards request finished: { Kind ("top", "rank", "around", "submit"), Code, Message, RetryAfterMs, Entries, Total }. Its ids come from the sequence Market and Matchmaking requests share, separate from the player services' of OnServiceResult.

Parameters

requestId (integer)
ok (boolean)
result (table)

Script:OnMatchmakingResult#

lua

function Script:OnMatchmakingResult(requestId: integer, ok: boolean, result: table)

Called on every script of the scene when a Matchmaking request finished: { Kind ("join", "leave", "ready"), Code, Message, RetryAfterMs, Ticket }. Its ids come from the sequence Market and Leaderboards requests share, separate from the player services' of OnServiceResult.

Parameters

requestId (integer)
ok (boolean)
result (table)

Script:OnMarketEvent#

lua

function Script:OnMarketEvent(event: table)

Called on every script of the scene for a market event of the player: { Kind = "Outbid" | "Sold" (Price) | "Won" | "Expired" | "Cancelled" (an operator cancelled the listing), ListingId } or { Kind = "OfferFilled", Offer }.

Parameters

event (table)

Script:OnMatchFound#

lua

function Script:OnMatchFound(matchId: integer, queue: string, readySeconds: integer, role: string)

Called on every script of the scene when a group formed for the player: answer with Matchmaking.RespondReady within readySeconds. role is the queue's role the player fills in the group (one of those it joined with; "" for queues without roles).

Parameters

matchId (integer)
queue (string)
readySeconds (integer)
role (string)

Script:OnMatchReady#

lua

function Script:OnMatchReady(matchId: integer, instance: table)

Called on every script of the scene when everyone accepted and the coordinator created the instance ({ Zone, Shard, Layer, InstanceId }); the coordinator moves the group there.

Parameters

matchId (integer)
instance (table)

Script:OnMatchCancelled#

lua

function Script:OnMatchCancelled(matchId: integer, reason: string)

Called on every script of the scene when a found match ended without an instance (a decline, a timeout, the coordinator's refusal) or the party left the queue (matchId 0).

Parameters

matchId (integer)
reason (string)

Script:OnQueuePosition#

lua

function Script:OnQueuePosition(queue: string, estimatedWaitSeconds: integer)

Called on every script of the scene every few seconds while the player waits in a queue (0: no estimate yet).

Parameters

queue (string)
estimatedWaitSeconds (integer)

Script:OnUIPointerEnter#

lua

function Script:OnUIPointerEnter(position: Vec2, pointerId: integer)

A pointer's UI target became this element: the nearest button or slider at or above the front-most element that blocks the pointer (its raycast target). A finger hovers only while it touches.

Parameters

position (Vec2): The pointer in framebuffer pixels (origin top-left, +Y down).
pointerId (integer): 0 for the mouse, else the touch contact's id.

Script:OnUIPointerExit#

lua

function Script:OnUIPointerExit(position: Vec2, pointerId: integer)

A pointer's UI target was this element and became another one (or none).

Parameters

position (Vec2): The pointer in framebuffer pixels.
pointerId (integer): 0 for the mouse, else the touch contact's id.

Script:OnUIPointerDown#

lua

function Script:OnUIPointerDown(position: Vec2, pointerId: integer)

The left mouse button or the primary finger went down while this element was the pointer's target.

Parameters

position (Vec2): The pointer in framebuffer pixels.
pointerId (integer): 0 for the mouse, else the touch contact's id.

Script:OnUIPointerUp#

lua

function Script:OnUIPointerUp(position: Vec2, pointerId: integer)

The left mouse button or the finger that went down on this element was released (wherever the pointer is then); a release over an interactable button that is still the target also clicks it (UIButton.OnClick, click listeners).

Parameters

position (Vec2): The pointer in framebuffer pixels.
pointerId (integer): 0 for the mouse, else the touch contact's id.

Script:OnUIValueChanged#

lua

function Script:OnUIValueChanged(value: number)

A pointer moved this UISlider to a new value (the slider's script gets it).

Parameters

value (number): The slider's new Value.

Script:OnUIScroll#

lua

function Script:OnUIScroll(offset: Vec2)

This UIScrollView scrolled (a drag, a fling or the mouse wheel; the scroll view's script gets it).

Parameters

offset (Vec2): The new ScrollOffset.

Script:OnUIFocusGained#

lua

function Script:OnUIFocusGained()

The button got the keyboard/gamepad focus (UI.SetFocus, a UICanvas with AutoFocus, navigation).

Script:OnUIFocusLost#

lua

function Script:OnUIFocusLost()

The button lost the focus (another one got it, or it was hidden, disabled or destroyed).

Script:OnUICancel#

lua

function Script:OnUICancel(focused: Entity)

The Cancel input (Escape, gamepad B) while a button has the focus: the focused button's script gets it first, else the nearest element or canvas above it (up to its root canvas) whose script defines it.

Parameters

focused (Entity): The button that has the focus.

Example

lua

function Menu:OnUICancel(focused)
	self:Close()
end

Script:OnUITextChanged#

lua

function Script:OnUITextChanged(text: string, field: Entity)

The player changed a UIInputField's text (typing, deleting, pasting, undo; once per frame; UIInputField:SetText sends none). The field's script gets it first, else the nearest entity above it whose script defines it.

Parameters

text (string): The field's new text.
field (Entity): The input field.

Script:OnUISubmit#

lua

function Script:OnUISubmit(text: string, field: Entity)

Enter in a single-line UIInputField (Ctrl+Enter in a multi-line one, or the gamepad's Submit while it has the focus). The field keeps the focus: UI.SetFocus(nil) gives the keys back to the game. Bubbles like OnUITextChanged.

Parameters

text (string): The field's text.
field (Entity): The input field.

Example

lua

function Chat:OnUISubmit(text, field)
	self:Send(text)
	field:GetComponent("UIInputField"):SetText("")
	UI.SetFocus(nil)
end

Script:OnUIDragBegin#

lua

function Script:OnUIDragBegin(source: Entity, pointerId: integer)

A drag of a UIDraggable began (the pointer moved past its DragThreshold, or the gamepad picked it up). UI.SetDragPayload may change what it carries now. Bubbles from the dragged element.

Parameters

source (Entity): The dragged element.
pointerId (integer): 0 for the mouse, the touch contact's id, or 4294967295 for the gamepad.

Script:OnUIDrop#

lua

function Script:OnUIDrop(payload: string, source: Entity, target: Entity, payloadType: string)

A drag was dropped on this UIDropTarget (it accepts the payload's type). Bubbles from the drop target, so a panel's script can handle the drops on all of its slots.

Parameters

payload (string): What the drag carries (UIDraggable.Payload, or UI.SetDragPayload).
source (Entity): The dragged element.
target (Entity): The drop target.
payloadType (string): The payload's type.

Example

lua

function Inventory:OnUIDrop(payload, source, target)
	self:Move(tonumber(payload), target.Name)
end

Script:OnUIDragEnd#

lua

function Script:OnUIDragEnd(source: Entity, target: Entity?)

The drag of this element ended: after OnUIDrop with its target, or with nil when it was released elsewhere or cancelled (Cancel, the element hidden or disabled). Bubbles from the dragged element.

Parameters

source (Entity): The dragged element.
target (Entity?): The drop target, or nil.

Script:OnUIToggleChanged#

lua

function Script:OnUIToggleChanged(isOn: boolean, toggle: Entity)

A click or Submit switched a UIToggle, or turning on another toggle of its radio group turned it off (UIToggle:SetOn sends none). The toggle's script gets it first, else the nearest entity above it whose script defines it.

Parameters

isOn (boolean): The toggle's new state.
toggle (Entity): The toggle.

Example

lua

function Options:OnUIToggleChanged(isOn, toggle)
	self.Settings[toggle.Name] = isOn
end

Script:OnUIDropdownChanged#

lua

function Script:OnUIDropdownChanged(index: integer, option: string, dropdown: Entity)

The player selected another option of a UIDropdown (a click on a row of its popup, or the arrows and Submit; UIDropdown:SetSelected sends none). Bubbles like OnUIToggleChanged.

Parameters

index (integer): The selected option's index, 0-based like UIDropdown.Selected.
option (string): The selected option's text.
dropdown (Entity): The dropdown.

Example

lua

function Options:OnUIDropdownChanged(index, option, dropdown)
	self.Quality = option
end

Script:OnUITooltipShown#

lua

function Script:OnUITooltipShown(owner: Entity, content: Entity?)

The tooltip of an element with UITooltip showed (the pointer, or the keyboard/gamepad focus, rested on it for its Delay): fill its Content element here (an item's name and stats). Bubbles from the owner, so an inventory's script fills the tooltips of all its slots.

Parameters

owner (Entity): The element with the UITooltip.
content (Entity?): Its Content element, or nil for a text tooltip.

Example

lua

function Bag:OnUITooltipShown(owner, content)
	UI.FindElement("ItemTooltip/Name"):GetComponent("UIText"):SetText(self:ItemName(owner))
end

Script:OnUITooltipHidden#

lua

function Script:OnUITooltipHidden(owner: Entity)

The element's tooltip was hidden (the pointer left it, a press or a drag, UI.HideTooltip). Bubbles like OnUITooltipShown.

Parameters

owner (Entity): The element with the UITooltip.

Script:OnVolumeEnter#

lua

function Script:OnVolumeEnter(volume: Entity, entity: Entity)

A tracked entity (a player, or a VolumeTracker entity) entered a TriggerVolume whose Filter accepts it, at a fixed step of this frame (Once: only the first entry of any entity; CooldownSeconds: no entry of any entity before it passed - both belong to the volume). The trigger volume's own script gets it first, then every other script of the scene whose OnCreate ran.

Parameters

volume (Entity): The trigger volume.
entity (Entity): The entity that entered.

Example

lua

function Gate:OnVolumeEnter(volume, entity)
	if volume == self.Entity then self:Open() end
end

Script:OnVolumeExit#

lua

function Script:OnVolumeExit(volume: Entity, entity: Entity)

An entity whose OnVolumeEnter was raised left that TriggerVolume (or stopped being tracked). Not raised when the volume or the entity no longer exists (its cell unloaded, it was destroyed). The volume's script first, then every other script.

Parameters

volume (Entity): The trigger volume.
entity (Entity): The entity that left.

Script:OnRegionChanged#

lua

function Script:OnRegionChanged(entity: Entity, region: string?, previous: string?)

The highest-priority RegionVolume containing a tracked entity changed: region and previous are RegionVolume Names (nil: outside every region). The entity's own script first, then every other script of the scene.

Parameters

entity (Entity): The tracked entity.
region (string?): The region it is in now, or nil.
previous (string?): The region it was in, or nil.

Example

lua

function Hud:OnRegionChanged(entity, region, previous)
	if entity == self.Player and region then self:ShowBanner(region) end
end

Script:OnPhaseVolumeEntered#

lua

function Script:OnPhaseVolumeEntered(player: Entity, phase: integer)

A player entered a PhaseVolume: the game may put the player's client in the phase (Net.SetClientPhase). The player's script first, then every other script of the scene.

Parameters

player (Entity): The player's entity.
phase (integer): The volume's Phase.

Example

lua

function Quests:OnPhaseVolumeEntered(player, phase)
	local client = player:GetOwner()
	if client then Net.SetClientPhase(client, phase) end
end

Script:OnCellLoaded#

lua

function Script:OnCellLoaded(x: integer, y: integer, layer: string)

A cell of the scene's world finished loading: every entity of it exists (their scripts' OnCreate follows). Every script of the scene whose OnCreate ran gets it, in the frame the cell loaded.

Parameters

x (integer): The cell's x.
y (integer): The cell's y.
layer (string): The name of the cell's layer.

Script:OnCellUnloaded#

lua

function Script:OnCellUnloaded(x: integer, y: integer, layer: string)

A cell of the scene's world that OnCellLoaded announced is unloading: its entities are destroyed from this frame on, as many a frame as the streaming budget allows (World-scope persistent entities save first). Every script of the scene whose OnCreate ran gets it.

Parameters

x (integer): The cell's x.
y (integer): The cell's y.
layer (string): The name of the cell's layer.

Script:OnWorldOriginShifted#

lua

function Script:OnWorldOriginShifted(dx: number, dy: number)

The scene's origin moved by (dx, dy) world units (SceneSettings.OriginShiftDistance on clients, or Scene rebasing): every entity moved by (-dx, -dy) so positions near the camera keep full precision. Scene positions a script stored (not entities) must move by (-dx, -dy) too; world positions (World.ToWorld) stay valid. Every script whose OnCreate ran gets it at the next update.

Parameters

dx (number): How far the origin moved along X.
dy (number): How far the origin moved along Y.

Example

lua

function Patrol:OnWorldOriginShifted(dx, dy)
	self.Target = self.Target - Vec2.new(dx, dy)
end

Properties#

The keys of a property declaration in the class's Properties table: Name = { Type = "...", Default = ..., ... }, or the shorthand Name = <default value> (Bool, Int, Float, String, Vec2/3/4 or Color, inferred from the value). Properties are shown in the inspector, set per entity (the Script component's overrides, also through component.set) and copied into every instance before OnCreate. Unknown keys are warned about; unusable declarations are skipped with an error.

lua

Properties = {
	Speed = { Type = "Float", Default = 5, Min = 0, Max = 20, Tooltip = "Units per second" },
	Lives = 3,
}

Member	Kind	Description
`Type = FrostPropertyType`	PropertyKey	The property type, a name of the PropertyType part (FrostPropertyType). Optional when Default is given: a boolean, integer, float, string, Vec2/3/4 or Color default implies Bool, Int, Float, String, Vec2/3/4 or Color.
`Default = any`	PropertyKey	The value instances start with unless the Script component overrides it: a value of the type (asset types: an asset handle or path; Enum: one of the Options; Array: a sequence table of element values). Without it: zero values, false, "", the first option, nil references, MinCount zero elements.
`Min = number`	PropertyKey	Float and Int properties (and Arrays of them, per element): the smallest value. Overrides below it are clamped.
`Max = number`	PropertyKey	Float and Int properties (and Arrays of them, per element): the largest value. Overrides above it are clamped.
`Tooltip = string`	PropertyKey	Shown when the pointer rests on the property in the inspector.
`Replicated = boolean`	PropertyKey	Synchronized from the server to every client as the replicated value Script.<name>: values that arrive with the spawn are set before OnCreate, later ones call OnReplicatedChanged(name). Enum values travel as their option names (a client refuses names that are not options), Arrays as flat tables of their elements, limited by the session's network value limits (64 table entries by default).
`Persistent = boolean`	PropertyKey	Saved with the entity's persistent record when it has a Persistence component (the character or world record of a server, as the field Script.<Class>.<name> of the generated schema) and restored when the record loads, which can be after OnCreate (a character's record arrives after its avatar spawned, so OnCreate sees the default): read it in OnPersistentLoaded(), which runs once it is set. Every type but Entity (and Arrays of Entity): entity references do not survive a reload.
`Transfer = boolean`	PropertyKey	Carried to the destination zone during a handoff and restored before OnCreate. Persistent and Replicated properties also travel. Entity references cannot be transferred.
`Order = integer`	PropertyKey	Inspector order: properties sort by ascending Order, then by name.
`Options = string[]`	PropertyKey	Enum properties and Arrays of Enum: the option names in order (1 to 256 unique, non-empty UTF-8 strings). The value is the chosen option's name.
`ElementType = FrostPropertyType`	PropertyKey	Array properties: the type of every element (any type but Array).
`MinCount = integer`	PropertyKey	Array properties: the fewest elements (0 to 1024, default 0); shorter overrides are padded with new elements.
`MaxCount = integer`	PropertyKey	Array properties: the most elements (MinCount to 1024, default 1024); longer overrides are cut.
`Header = string`	PropertyKey	A section title the inspector draws above the property: the section holds it and the properties after it up to the next Header, and folds.
`Hidden = boolean`	PropertyKey	true hides the property in the inspector; commands and saved overrides still set it.
`ReadOnly = boolean`	PropertyKey	true shows the property in the inspector without letting it be edited there; commands still set it.
`Delivery = string`	PropertyKey	Replicated properties: "Reliable" or "Snapshot"; without it the project's "Script.<name>" rule decides (Project Settings > Network > Replication), else Reliable. In this version every script property travels Reliable whatever it says: every change arrives, exactly and in order with spawns and RPCs, and calls OnReplicatedChanged(name). Snapshot is accepted and checked (Bool, Int, Float, Vec2, Vec3, Vec4 or Color only), but the value is not sent in the per-tick unreliable snapshot, which carries the transform and component fields.
`Quantization = string`	PropertyKey	Snapshot properties: a quantization profile of the project (Network.Replication.Quantizations, e.g. "Percent": 8 bits for 0..1). It is checked like a component field's - a name the project does not have, or a profile the type cannot take, is reported by script.validate and when a session starts - but in this version a script property's value always travels exactly (32-bit floats, 64-bit integers): only snapshot-delivered component fields are quantized.

PropertyType#

The values of a declaration's Type (and of an Array's ElementType), with the Lua value an instance's property holds.

lua

Target = { Type = "Entity" },
Level = { Type = "Scene", Default = "Assets/Scenes/Level2.fscene" }

Member	Kind	Description
`Type = "Float" -- number`	PropertyType	A number (inspector: a drag field; Min and Max clamp it). Shorthand: a float default (`Speed = 5.0`).
`Type = "Int" -- integer`	PropertyType	An integer (integral floats are accepted; Min and Max clamp it). Shorthand: an integer default (`Lives = 3`).
`Type = "Bool" -- boolean`	PropertyType	true or false (inspector: a checkbox). Shorthand: a boolean default.
`Type = "String" -- string`	PropertyType	A UTF-8 string (inspector: a text field). Shorthand: a string default.
`Type = "Vec2" -- Vec2`	PropertyType	A Vec2 (inspector: X and Y fields). Shorthand: a Vec2 default.
`Type = "Vec3" -- Vec3`	PropertyType	A Vec3. Shorthand: a Vec3 default.
`Type = "Vec4" -- Vec4`	PropertyType	A Vec4. Shorthand: a Vec4 default.
`Type = "Color" -- Color`	PropertyType	A Color (inspector: a color picker; a Vec4 default is accepted). Shorthand: a Color default.
`Type = "Entity" -- Entity?`	PropertyType	A reference to an entity of the scene, picked in the inspector or set by commands (the UUID is stored and remapped when the entity is duplicated or instantiated from a prefab). The instance gets the Entity, or nil when none is set or the referenced entity does not exist. It has no Default.
`Type = "Enum" -- string`	PropertyType	One of the declaration's Options (inspector: a drop-down). The instance gets the option's name as a string; overrides store the name, so reordering the options keeps the chosen values. The Default must be one of the options (the first one when there is no Default).
`Type = "Array" -- table`	PropertyType	A list of ElementType values (any type but Array) with MinCount to MaxCount elements (at most 1024). The instance gets a new Lua sequence table (indices 1..n); elements that reference nothing (no asset, no entity, an entity that does not exist) are false, so the table stays a sequence. The Default is a sequence of element values (asset elements may be paths; Entity arrays start with MinCount empty references). Min, Max and Options apply to the elements. In the inspector elements are added, removed, reordered and edited one by one.
`Type = "Prefab" -- integer?`	PropertyType	A Prefab asset (its handle: an integer, or nil). The Default may be its path.
`Type = "Texture" -- integer?`	PropertyType	A Texture2D asset (its handle, or nil). The Default may be its path.
`Type = "Sprite" -- integer?`	PropertyType	A SpriteSheet asset (its handle, or nil). The Default may be its path.
`Type = "AudioClip" -- integer?`	PropertyType	An AudioClip asset (its handle, or nil). The Default may be its path.
`Type = "Scene" -- integer?`	PropertyType	A Scene asset (its handle, or nil), e.g. for Scene.LoadScene. The Default may be its path.
`Type = "Font" -- integer?`	PropertyType	A Font asset (its handle, or nil). The Default may be its path.
`Type = "Material" -- integer?`	PropertyType	A Material asset (its handle, or nil). The Default may be its path.
`Type = "AnimationClip" -- integer?`	PropertyType	An AnimationClip asset (its handle, or nil). The Default may be its path.
`Type = "Tileset" -- integer?`	PropertyType	A Tileset asset (its handle, or nil). The Default may be its path.
`Type = "RenderTexture" -- integer?`	PropertyType	A RenderTexture asset (its handle, or nil), e.g. for a camera's Target. The Default may be its path.
`Type = "PostProcessProfile" -- integer?`	PropertyType	A PostProcessProfile asset (its handle, or nil). The Default may be its path.
`Type = "Script" -- integer?`	PropertyType	A Script asset (its handle, or nil), e.g. to assign to a Script component. The Default may be its path.
`Type = "Shader" -- integer?`	PropertyType	A Shader asset (its handle, or nil). The Default may be its path.

BotBehaviour#

A bot behaviour (Assets/Bots/<Name>.lua, named in a load-test scenario's Behaviours): the script returns a table with a Run method. Every bot that runs the behaviour gets its own instance (self) holding the scenario's Parameters for it, and runs Run as a coroutine once it joined the session: Wait, WaitFrames, WaitUntil and coroutine.yield pause it, returning ends it, an error ends it and counts as a behaviour error. All bots of a process share one Lua state, resumed round robin within the scenario's Bot.LuaBudgetMsPerTick. Run (required) is the behaviour's body, function(self): self is the bot's instance, the table's fields overridden by the scenario's Parameters.

lua

local Chat = {}
Chat.Lines = { "hello", "lfg" }
function Chat:Run()
	while true do
		Wait(5 + Bot.Random() * 5)
		Bot.Say(self.Lines[1 + math.floor(Bot.Random() * #self.Lines)])
	end
end
return Chat

Namespaces#

Global tables of functions, properties and constants. They are read-only.

AI#

The AI scheduler: entities with an AIAgent component think - their script's OnThink(dt), or a native handler - at intervals that grow with the distance to the nearest player, sleep far from every player and share a per-step think budget (Server.AI.BudgetMs) with the other agents.

lua

function Wolf:OnDamaged(attacker)
	self.Target = attacker
	AI.Wake(self.Entity)
end

Member	Kind	Summary
`AI.Wake(entity: Entity): boolean`	Function	Makes the agent think at once - in the scheduler's next pass (this fixed step's, when the scheduler has not run yet), ahead of every other agent, also when it sleeps or is disabled.
`AI.SetInterval(entity: Entity, nearMs: number, farMs: number)`	Function	Sets the agent's think intervals (its AIAgent's NearIntervalMs and FarIntervalMs) from its next think on.
`AI.IsSleeping(entity: Entity): boolean`	Function	Whether the agent sleeps: its last check found every player beyond its SleepDistance.
`AI.GetStats(): { Agents: integer, Sleeping: integer, ThinksLastTick: integer, DeferredLastTick: integer, TotalThinks: integer, LastTickMs: number, AverageLatenessMs: number, MaxLatenessMs: number }`	Function	The scheduler's agents, how many sleep, the last fixed step's thinks and deferred agents (the budget did not reach them: they think first next step), the thinks since the scene started, the last pass's time and how late its thinks ran after their due time (average and maximum, milliseconds).

AI.Wake#

lua

AI.Wake(entity: Entity): boolean

Makes the agent think at once - in the scheduler's next pass (this fixed step's, when the scheduler has not run yet), ahead of every other agent, also when it sleeps or is disabled. Raises an error for an entity without AIAgent and in a scene without the AI scheduler; returns false while the scheduler does not run.

Parameters

entity (Entity)

Returns boolean

Example

lua

AI.Wake(guard)

AI.SetInterval#

lua

AI.SetInterval(entity: Entity, nearMs: number, farMs: number)

Sets the agent's think intervals (its AIAgent's NearIntervalMs and FarIntervalMs) from its next think on. Intervals are in [1, 3600000] ms and farMs is at least nearMs.

Parameters

entity (Entity)
nearMs (number): Milliseconds between thinks near players.
farMs (number): Milliseconds between thinks far from them.

Example

lua

AI.SetInterval(self.Entity, 50, 500) -- in combat

AI.IsSleeping#

lua

AI.IsSleeping(entity: Entity): boolean

Whether the agent sleeps: its last check found every player beyond its SleepDistance.

Parameters

entity (Entity)

Returns boolean

AI.GetStats#

lua

AI.GetStats(): { Agents: integer, Sleeping: integer, ThinksLastTick: integer, DeferredLastTick: integer, TotalThinks: integer, LastTickMs: number, AverageLatenessMs: number, MaxLatenessMs: number }

The scheduler's agents, how many sleep, the last fixed step's thinks and deferred agents (the budget did not reach them: they think first next step), the thinks since the scene started, the last pass's time and how late its thinks ran after their due time (average and maximum, milliseconds).

Returns { Agents: integer, Sleeping: integer, ThinksLastTick: integer, DeferredLastTick: integer, TotalThinks: integer, LastTickMs: number, AverageLatenessMs: number, MaxLatenessMs: number }

Example

lua

local ai = AI.GetStats()
print(ai.Agents, ai.Sleeping, ai.DeferredLastTick)

Abilities#

Abilities of RPG actors (the scene's Combat system: servers, hosts and offline games): casting with its cooldowns, charges, global cooldown and queue, auto-attack, the abilities a player knows and the definitions of the Ability tables (built-in schema Ability). Refusals answer false and the reason's name ("OnCooldown", "OutOfRange", "NotAnActor", ...). On a client's scenes the client read API answers from the RPG lane - GetCooldown, GetCooldowns, GetKnown and Knows for the local character (its Cooldowns section; the Rpg namespace says which actor that is), GetCast and IsCasting for every replicated actor, GetInfo from the client's own data - and Cast, CancelCast, StartAttack and StopAttack send requests the server answers; the other functions raise an error there.

lua

local ok, reason = Abilities.Cast(self.Entity, "fireball", target)
if not ok then Log.Info("no fireball: " .. reason) end

Member	Kind	Summary
`Abilities.Cast(caster: Entity, ability: string, target?: Entity \| Vec2): boolean, string?, integer?`	Function	Casts an ability by key, with every check of a client's Cast request (knowledge, state, cooldowns, charges, costs, target, range, line of sight, facing).
`Abilities.CanCast(caster: Entity, ability: string, target?: Entity \| Vec2): boolean, string?`	Function	Every check of Cast without casting: true when the cast would start now, false and the refusal's name otherwise (a cast that would only be queued answers Busy or GlobalCooldown).
`Abilities.CancelCast(caster: Entity): boolean`	Function	Cancels the actor's cast or channel and its queued cast (nothing is paid, no cooldown starts); false when it was not casting.
`Abilities.IsCasting(caster: Entity): boolean`	Function	Whether the actor is casting or channeling (on a client: the cast its replicated state shows; instant casts never show).
`Abilities.GetCast(caster: Entity): { State: string, Ability: string?, Target: Entity?, Point: Vec2?, StartTick: integer?, EndTick: integer?, Duration: number?, Remaining: number?, Progress: number?, Queued: string? }?`	Function	The actor's current cast: its State ("Casting" or "Channeling"; "Idle" when only a queued cast waits), the ability's key, its target or point, the fixed steps it started at and ends at, its length and the seconds left, its progress from 0 to 1 and the key of the cast queued behind it.
`Abilities.GetCooldown(actor: Entity, ability: string): number?`	Function	Seconds until the ability (or its cooldown group) is ready again; 0 when it is ready (an ability with charges: when a charge is left).
`Abilities.GetCooldowns(actor: Entity): { { Key: string, Group: boolean, Remaining: number, Duration: number, Charges: integer, MaxCharges: integer } }`	Function	The actor's running cooldowns (at most 64): each ability's key - or its cooldown group's name (Group true), which every ability of the group shares - with the seconds left of its cooldown (or of the next charge), its length and the charges available.
`Abilities.GetGlobalCooldown(actor: Entity): number`	Function	Seconds of the actor's global cooldown left (Combat.GlobalCooldownSeconds after a cast of an ability with GlobalCooldown); 0 when there is none.
`Abilities.Learn(actor: Entity, ability: string): boolean, string?`	Function	Teaches a player character an ability (kept with the character, Rpg.Abilities); true also when it knew it already.
`Abilities.Forget(actor: Entity, ability: string): boolean`	Function	Makes a player character forget a learned ability; false when it had not learned it.
`Abilities.Knows(actor: Entity, ability: string): boolean`	Function	Whether the actor may cast the ability: a player what it learned and its class's auto-attack, an NPC its template's abilities and auto-attack, an actor without class or template (traps, dummies) every ability.
`Abilities.GetKnown(actor: Entity): { string }`	Function	The keys of the abilities a player character learned, sorted (its class's auto-attack is known without being learned).
`Abilities.GrantClassAbilities(actor: Entity, level: integer): integer`	Function	Teaches a player character every ability its class grants up to `level` (the class's Abilities list) that it does not know yet, as character creation and level-ups do; returns how many it learned (0 for entities without a class).
`Abilities.StartAttack(actor: Entity, target: Entity): boolean, string?, integer?`	Function	Starts auto-attacking: the actor swings its class's or template's AutoAttack ability at the target every swing (the main-hand weapon's speed, else the ability's cooldown) between casts, while the target lives and is in range, until StopAttack, death, Pacified or Disarmed.
`Abilities.StopAttack(actor: Entity)`	Function	Stops the actor's auto-attack (nothing happens when it does not swing).
`Abilities.IsAttacking(actor: Entity): boolean`	Function	Whether the actor auto-attacks.
`Abilities.GetAttackTarget(actor: Entity): Entity?`	Function	The target the actor auto-attacks; nil when it does not swing.
Abilities.GetInfo(ability: string): { Key: string, Name: string, Description: string, School: string, Targeting: string, Range: number, MinRange: number, Radius: number, ConeDegrees: number, MaxTargets: integer, CastSeconds: number, Channel: boolean, ChannelTicks: integer, CooldownSeconds: number, Charges: integer, ChargeSeconds: number, GlobalCooldown: boolean, CooldownGroup: string, Costs: { { Stat: string, Amount: number, Percent: boolean } }, Effects: { string }, Projectile: boolean, Interruptible: boolean, CastWhileMoving: boolean, RequiresLineOfSight: boolean, Facing: boolean, ThreatScale: number, Animation: string, AiRange: number, AiPriority: integer, Tags: { string } }?	Function	An ability's definition as the combat system reads it from the RPG database (the Ability tables' row, its defaults filled in; Effects lists each effect entry's kind in order, AiRange falls back to Range); on a client, from the client's own copy of the game's data.

Abilities.Cast#

lua

Abilities.Cast(caster: Entity, ability: string, target?: Entity | Vec2): boolean, string?, integer?

Casts an ability by key, with every check of a client's Cast request (knowledge, state, cooldowns, charges, costs, target, range, line of sight, facing). target is the actor of an Enemy, Ally or Any ability (an Ally ability without one heals the caster) or the point of a Point, Direction or Area ability. True when the cast started (an instant one resolves in this tick's combat step) or was queued behind the current cast or the global cooldown (within Combat.SpellQueueSeconds); false and the refusal's name otherwise: NotAnActor, Dead, UnknownAbility, NotKnown, Stunned, Silenced, Pacified, Disarmed, SchoolLocked, Requirement, OnCooldown, GlobalCooldown, Busy, NotEnoughResource, NoTarget, InvalidTarget, TargetDead, OutOfRange, TooClose, NoLineOfSight, NotFacing or NoDefinitions (no RPG database yet). On a client: sends a Cast request for its character (or an actor it controls) and answers three values, true, nil and the request id (local ok, why, id = Abilities.Cast(...)) - the server's Rpg.Result answers it, and an accepted cast shows in GetCast - or false and why it could not be sent.

Parameters

caster (Entity)
ability (string)
target? (Entity | Vec2)

Returns boolean, string?, integer?

Example

lua

local ok, reason = Abilities.Cast(boss, "meteor", Vec2(10, 4))

Abilities.CanCast#

lua

Abilities.CanCast(caster: Entity, ability: string, target?: Entity | Vec2): boolean, string?

Every check of Cast without casting: true when the cast would start now, false and the refusal's name otherwise (a cast that would only be queued answers Busy or GlobalCooldown).

Parameters

caster (Entity)
ability (string)
target? (Entity | Vec2)

Returns boolean, string?

Example

lua

button.Interactable = Abilities.CanCast(player, "heal", player)

Abilities.CancelCast#

lua

Abilities.CancelCast(caster: Entity): boolean

Cancels the actor's cast or channel and its queued cast (nothing is paid, no cooldown starts); false when it was not casting. On a client: sends a CancelCast request (true when it was sent).

Parameters

caster (Entity)

Returns boolean

Example

lua

Abilities.CancelCast(self.Entity)

Abilities.IsCasting#

lua

Abilities.IsCasting(caster: Entity): boolean

Whether the actor is casting or channeling (on a client: the cast its replicated state shows; instant casts never show).

Parameters

caster (Entity)

Returns boolean

Example

lua

if Abilities.IsCasting(boss) then Log.Info("interrupt now") end

Abilities.GetCast#

lua

Abilities.GetCast(caster: Entity): { State: string, Ability: string?, Target: Entity?, Point: Vec2?, StartTick: integer?, EndTick: integer?, Duration: number?, Remaining: number?, Progress: number?, Queued: string? }?

The actor's current cast: its State ("Casting" or "Channeling"; "Idle" when only a queued cast waits), the ability's key, its target or point, the fixed steps it started at and ends at, its length and the seconds left, its progress from 0 to 1 and the key of the cast queued behind it. Nil when the actor neither casts nor has a cast queued. On a client: the cast the actor's replicated state shows (no queue; Target is the actor's selected target), its progress on the client's clock from when the cast arrived.

Parameters

caster (Entity)

Returns { State: string, Ability: string?, Target: Entity?, Point: Vec2?, StartTick: integer?, EndTick: integer?, Duration: number?, Remaining: number?, Progress: number?, Queued: string? }?

Example

lua

local cast = Abilities.GetCast(boss)
if cast and cast.State ~= "Idle" then bar.Value = cast.Progress end

Abilities.GetCooldown#

lua

Abilities.GetCooldown(actor: Entity, ability: string): number?

Seconds until the ability (or its cooldown group) is ready again; 0 when it is ready (an ability with charges: when a charge is left). Nil for unknown abilities and entities that are not RPG actors. On a client: the local character's abilities it knows (its Cooldowns section, counted down on the client's clock); nil for others.

Parameters

actor (Entity)
ability (string)

Returns number?

Example

lua

local left = Abilities.GetCooldown(player, "fireball")

Abilities.GetCooldowns#

lua

Abilities.GetCooldowns(actor: Entity): { { Key: string, Group: boolean, Remaining: number, Duration: number, Charges: integer, MaxCharges: integer } }

The actor's running cooldowns (at most 64): each ability's key - or its cooldown group's name (Group true), which every ability of the group shares - with the seconds left of its cooldown (or of the next charge), its length and the charges available. Empty for actors without running cooldowns and for other entities. On a client: the local character's known abilities that cool down (one entry per ability, Group false).

Parameters

actor (Entity)

Returns { { Key: string, Group: boolean, Remaining: number, Duration: number, Charges: integer, MaxCharges: integer } }

Example

lua

for _, cooldown in ipairs(Abilities.GetCooldowns(player)) do Log.Info(cooldown.Key .. ": " .. cooldown.Remaining) end

Abilities.GetGlobalCooldown#

lua

Abilities.GetGlobalCooldown(actor: Entity): number

Seconds of the actor's global cooldown left (Combat.GlobalCooldownSeconds after a cast of an ability with GlobalCooldown); 0 when there is none.

Parameters

actor (Entity)

Returns number

Example

lua

local gcd = Abilities.GetGlobalCooldown(player)

Abilities.Learn#

lua

Abilities.Learn(actor: Entity, ability: string): boolean, string?

Teaches a player character an ability (kept with the character, Rpg.Abilities); true also when it knew it already. False and the reason for unknown abilities, NPCs (they cast their template's abilities), entities that are not RPG actors and a character that knows 256 abilities.

Parameters

actor (Entity)
ability (string)

Returns boolean, string?

Example

lua

function Trainer:OnInteract(player)
	Abilities.Learn(player, "whirlwind")
end

Abilities.Forget#

lua

Abilities.Forget(actor: Entity, ability: string): boolean

Makes a player character forget a learned ability; false when it had not learned it.

Parameters

actor (Entity)
ability (string)

Returns boolean

Example

lua

Abilities.Forget(player, "whirlwind")

Abilities.Knows#

lua

Abilities.Knows(actor: Entity, ability: string): boolean

Whether the actor may cast the ability: a player what it learned and its class's auto-attack, an NPC its template's abilities and auto-attack, an actor without class or template (traps, dummies) every ability. On a client: whether the local character learned it (false for other actors).

Parameters

actor (Entity)
ability (string)

Returns boolean

Example

lua

if Abilities.Knows(player, "fireball") then slot.Visible = true end

Abilities.GetKnown#

lua

Abilities.GetKnown(actor: Entity): { string }

The keys of the abilities a player character learned, sorted (its class's auto-attack is known without being learned). Empty for NPCs and other entities. On a client: the local character's (its Cooldowns section).

Parameters

actor (Entity)

Returns { string }

Example

lua

for _, key in ipairs(Abilities.GetKnown(player)) do Log.Info(key) end

Abilities.GrantClassAbilities#

lua

Abilities.GrantClassAbilities(actor: Entity, level: integer): integer

Teaches a player character every ability its class grants up to level (the class's Abilities list) that it does not know yet, as character creation and level-ups do; returns how many it learned (0 for entities without a class). Raises an error for a level outside the RpgActor's range.

Parameters

actor (Entity)
level (integer)

Returns integer

Example

lua

function Player:OnLevelUp(level)
	Abilities.GrantClassAbilities(self.Entity, level)
end

Abilities.StartAttack#

lua

Abilities.StartAttack(actor: Entity, target: Entity): boolean, string?, integer?

Starts auto-attacking: the actor swings its class's or template's AutoAttack ability at the target every swing (the main-hand weapon's speed, else the ability's cooldown) between casts, while the target lives and is in range, until StopAttack, death, Pacified or Disarmed. False and the refusal's name (as Cast's) when the actor has no auto-attack (NotKnown), no target (NoTarget), a friendly target (InvalidTarget), ... On a client: sends a StartAttack request and answers true and its request id, or false and why it could not be sent.

Parameters

actor (Entity)
target (Entity)

Returns boolean, string?, integer?

Example

lua

Abilities.StartAttack(self.Entity, target)

Abilities.StopAttack#

lua

Abilities.StopAttack(actor: Entity)

Stops the actor's auto-attack (nothing happens when it does not swing). On a client: sends a StopAttack request.

Parameters

actor (Entity)

Example

lua

Abilities.StopAttack(self.Entity)

Abilities.IsAttacking#

lua

Abilities.IsAttacking(actor: Entity): boolean

Whether the actor auto-attacks.

Parameters

actor (Entity)

Returns boolean

Example

lua

if not Abilities.IsAttacking(self.Entity) then Abilities.StartAttack(self.Entity, target) end

Abilities.GetAttackTarget#

lua

Abilities.GetAttackTarget(actor: Entity): Entity?

The target the actor auto-attacks; nil when it does not swing.

Parameters

actor (Entity)

Returns Entity?

Example

lua

local target = Abilities.GetAttackTarget(self.Entity)

Abilities.GetInfo#

lua

Abilities.GetInfo(ability: string): { Key: string, Name: string, Description: string, School: string, Targeting: string, Range: number, MinRange: number, Radius: number, ConeDegrees: number, MaxTargets: integer, CastSeconds: number, Channel: boolean, ChannelTicks: integer, CooldownSeconds: number, Charges: integer, ChargeSeconds: number, GlobalCooldown: boolean, CooldownGroup: string, Costs: { { Stat: string, Amount: number, Percent: boolean } }, Effects: { string }, Projectile: boolean, Interruptible: boolean, CastWhileMoving: boolean, RequiresLineOfSight: boolean, Facing: boolean, ThreatScale: number, Animation: string, AiRange: number, AiPriority: integer, Tags: { string } }?

An ability's definition as the combat system reads it from the RPG database (the Ability tables' row, its defaults filled in; Effects lists each effect entry's kind in order, AiRange falls back to Range); on a client, from the client's own copy of the game's data. Nil for keys no table has and before the RPG database is built.

Parameters

ability (string)

Returns { Key: string, Name: string, Description: string, School: string, Targeting: string, Range: number, MinRange: number, Radius: number, ConeDegrees: number, MaxTargets: integer, CastSeconds: number, Channel: boolean, ChannelTicks: integer, CooldownSeconds: number, Charges: integer, ChargeSeconds: number, GlobalCooldown: boolean, CooldownGroup: string, Costs: { { Stat: string, Amount: number, Percent: boolean } }, Effects: { string }, Projectile: boolean, Interruptible: boolean, CastWhileMoving: boolean, RequiresLineOfSight: boolean, Facing: boolean, ThreatScale: number, Animation: string, AiRange: number, AiPriority: integer, Tags: { string } }?

Example

lua

local fireball = Abilities.GetInfo("fireball")
tooltip.Text = fireball.Name .. " (" .. fireball.CastSeconds .. " s)"

Admin#

Live operations on zone servers (Docs/Operations.md, "Admin console, GM tools, permissions and audit"): the permission level a player's session carries, and game-specific GM commands operators run from the Admin Console (gm.run) and GMs type in game ("/gm <name> ..."), checked, routed and audited like the built-in actions. On clients and offline the queries answer nil or false and RegisterCommand returns false.

lua

Admin.RegisterCommand("heal-all", "GameMaster", { { Name = "amount", Type = "Int", Required = true } },
    function(target, params, actor)
        for _, player in ipairs(Net.GetPlayers()) do Heal(player.Client, params.amount) end
        return { healed = #Net.GetPlayers() }
    end, "Heals every player of the zone.")

Member	Kind	Summary
`Admin.GetRoles(client: integer): integer?`	Function	Servers: the role bits of the client's verified session token (1 Player, 2 Moderator, 4 GameMaster, 8 Administrator; 0 without a session token); nil for an unknown client, on clients and offline.
`Admin.GetLevel(client: integer): string?`	Function	Servers: the client's permission level - "Player", "Moderator", "GameMaster" or "Administrator" (the highest role of its session); nil for an unknown client, on clients and offline.
`Admin.HasLevel(client: integer, level: string): boolean`	Function	Servers: whether the client's session reaches the level ("Player", "Moderator", "GameMaster", "Administrator"); false for an unknown client, on clients and offline.
`Admin.RegisterCommand(name: string, minLevel: string, params: table?, fn: function, description?: string): boolean`	Function	Zone servers: a game-specific GM command.

Admin.GetRoles#

lua

Admin.GetRoles(client: integer): integer?

Servers: the role bits of the client's verified session token (1 Player, 2 Moderator, 4 GameMaster, 8 Administrator; 0 without a session token); nil for an unknown client, on clients and offline.

Parameters

client (integer)

Returns integer?

Admin.GetLevel#

lua

Admin.GetLevel(client: integer): string?

Servers: the client's permission level - "Player", "Moderator", "GameMaster" or "Administrator" (the highest role of its session); nil for an unknown client, on clients and offline.

Parameters

client (integer)

Returns string?

Admin.HasLevel#

lua

Admin.HasLevel(client: integer, level: string): boolean

Servers: whether the client's session reaches the level ("Player", "Moderator", "GameMaster", "Administrator"); false for an unknown client, on clients and offline. An unknown level name raises an error.

Parameters

client (integer)
level (string)

Returns boolean

Admin.RegisterCommand#

lua

Admin.RegisterCommand(name: string, minLevel: string, params: table?, fn: function, description?: string): boolean

Zone servers: a game-specific GM command. name: 1-64 of [a-z0-9-], not an engine action. minLevel: "Moderator", "GameMaster" or "Administrator" (Operations.Admin.Permissions may raise or lower it). params: a list of { Name, Type ("Bool", "Int", "Float", "String", "Entity", "Character", "Position", "Duration"), Required?, Description? }. fn(target, params, actor) runs when an operator (gm.run) or a GM in game ("/gm <name> [<player>] key=value") uses it on this zone: target is the character id (0: none), params the checked values, actor { Account, Level, Name, Origin, Character, TargetAccount, Zone }; return nothing or a table (the result), or nil/false and a message to refuse. Every use is audited. Returns false on clients and offline (nothing registered); registering a name again replaces the function. The command lives while the script state does.

Parameters

name (string)
minLevel (string)
params (table?)
fn (function)
description? (string)

Returns boolean

Analytics#

Analytics events (Docs/Operations.md, "Analytics"): what players do, as data for the people who balance and run the game. Every event is defined by a row of an AnalyticsEvent table (its fields and types, which are personal data, its sample rate, whether it is on); the engine's own events (login, level_up, item_acquired, ...) are built in and a row of the same name replaces them. Emitting validates the fields, samples by account, replaces personal fields by a keyed hash and queues the event for the server's analytics files and collector - it never waits for a disk or a network.

lua

Analytics.Emit("boss_killed", { Boss = "Ragnaros", Seconds = 312.5, Group = 5 }, player)

Member	Kind	Summary
`Analytics.Emit(name: string, fields?: table, player?: integer\|Entity): boolean, string?`	Function	Emits the event `name` with { Field = value } fields (integers, numbers, strings of at most 256 bytes, booleans) for `player` (an account id or a player's character entity; nil for events without an account).
`Analytics.IsEnabled(name: string): boolean`	Function	Whether the process emits `name`: analytics runs here, the event is defined and its row enables it (skip building expensive fields for events that are off).
`Analytics.GetStats(): table`	Function	The process's analytics counters { Emitted, Sampled, Disabled, Invalid, Dropped, Written, Forwarded, ForwardDropped, ForwardRetries } since analytics started (Dropped: the queue was full or a file could not be written; ForwardDropped: the collector did not take them).

Analytics.Emit#

lua

Analytics.Emit(name: string, fields?: table, player?: integer|Entity): boolean, string?

Emits the event name with { Field = value } fields (integers, numbers, strings of at most 256 bytes, booleans) for player (an account id or a player's character entity; nil for events without an account). Returns true when the event was accepted (also when its definition is disabled or sampling skips it: both are counted), false and the reason when it is invalid - an unknown event or field, a missing required field, a mistyped value - or when analytics does not run in this process. Only servers write and forward events: a client validates and counts its own, nothing leaves it. Invalid events are counted, never raised.

Parameters

name (string): The event's Name in an AnalyticsEvent table.
fields? (table): The event's fields by name.
player? (integer|Entity): An account id or a player's Entity (optional).

Returns boolean, string?: true, or false and the reason.

Example

lua

local ok, reason = Analytics.Emit("shop_opened", { Shop = self.Name })
if not ok then Log.Warn(reason) end

Analytics.IsEnabled#

lua

Analytics.IsEnabled(name: string): boolean

Whether the process emits name: analytics runs here, the event is defined and its row enables it (skip building expensive fields for events that are off).

Parameters

name (string)

Returns boolean

Analytics.GetStats#

lua

Analytics.GetStats(): table

The process's analytics counters { Emitted, Sampled, Disabled, Invalid, Dropped, Written, Forwarded, ForwardDropped, ForwardRetries } since analytics started (Dropped: the queue was full or a file could not be written; ForwardDropped: the collector did not take them).

Returns table

Appearance#

Character appearance layers (the CharacterAppearance component): up to eight sprite sheets drawn with the animator's frame - body, clothes, equipment, hair - in their Order, each with a tint. A layer's sheet must have the frame layout of the sheet the character's animator plays (the same frames: names, sizes, pivots; X003), so one animator frame shows every layer. Layers are numbered 0-7.

lua

Appearance.SetLayer(self.Entity, 2, "Assets/Characters/Chest_Plate.fsheet")

Member	Kind	Summary
`Appearance.SetLayer(entity: Entity, layer: integer, sheet?: integer\|string, tint?: Color): boolean`	Function	Sets layer `layer` (0-7) to the sprite sheet `sheet` (a handle or a path; nil clears the layer) and, when given, its tint.
`Appearance.GetLayer(entity: Entity, layer: integer): { Sheet: integer?, Tint: Color, Order: integer, Hidden: boolean }`	Function	Layer `layer` (0-7): its sheet's handle (nil when empty), tint, draw order and whether it is hidden.
`Appearance.SetOrder(entity: Entity, layer: integer, order: integer): boolean`	Function	The draw order of a layer inside the character, -64 to 64: lower orders draw behind (ties by layer index) - a cloak moves in front of the body when the character turns away.
`Appearance.SetHidden(entity: Entity, layer: integer, hidden: boolean): boolean`	Function	Hides or shows a layer without clearing its sheet (a helmet hiding the hair).
`Appearance.GetDrawOrder(entity: Entity): { integer }`	Function	The layers that are drawn (a sheet, not hidden), back to front.

Appearance.SetLayer#

lua

Appearance.SetLayer(entity: Entity, layer: integer, sheet?: integer|string, tint?: Color): boolean

Sets layer layer (0-7) to the sprite sheet sheet (a handle or a path; nil clears the layer) and, when given, its tint. Raises an error for an entity without a CharacterAppearance, a layer outside 0-7, an asset that is not a sprite sheet and a sheet whose frames do not match the animator's sheet (X003; the sheets are loaded if needed).

Parameters

entity (Entity)
layer (integer)
sheet? (integer|string)
tint? (Color)

Returns boolean

Example

lua

Appearance.SetLayer(self.Entity, 3, "Assets/Characters/Hair_Red.fsheet", Color(1, 0.8, 0.8, 1))

Appearance.GetLayer#

lua

Appearance.GetLayer(entity: Entity, layer: integer): { Sheet: integer?, Tint: Color, Order: integer, Hidden: boolean }

Layer layer (0-7): its sheet's handle (nil when empty), tint, draw order and whether it is hidden.

Parameters

entity (Entity)
layer (integer)

Returns { Sheet: integer?, Tint: Color, Order: integer, Hidden: boolean }

Example

lua

local chest = Appearance.GetLayer(self.Entity, 2)
if chest.Sheet == nil then Log.Info("no chest armour") end

Appearance.SetOrder#

lua

Appearance.SetOrder(entity: Entity, layer: integer, order: integer): boolean

The draw order of a layer inside the character, -64 to 64: lower orders draw behind (ties by layer index) - a cloak moves in front of the body when the character turns away.

Parameters

entity (Entity)
layer (integer)
order (integer)

Returns boolean

Example

lua

Appearance.SetOrder(self.Entity, 5, facingAway and 10 or -1)

Appearance.SetHidden#

lua

Appearance.SetHidden(entity: Entity, layer: integer, hidden: boolean): boolean

Hides or shows a layer without clearing its sheet (a helmet hiding the hair).

Parameters

entity (Entity)
layer (integer)
hidden (boolean)

Returns boolean

Example

lua

Appearance.SetHidden(self.Entity, 4, wearsHelmet)

Appearance.GetDrawOrder#

lua

Appearance.GetDrawOrder(entity: Entity): { integer }

The layers that are drawn (a sheet, not hidden), back to front.

Parameters

entity (Entity)

Returns { integer }

Example

lua

for _, layer in ipairs(Appearance.GetDrawOrder(self.Entity)) do Log.Info(layer) end

Application#

The running game: quitting, frame counter, environment, and its window (fullscreen, resolution, VSync). Window requests take effect at the end of the frame (read the new state from the next frame on); the editor's play mode refuses them (they return false: the window belongs to the editor, the exported game applies them), and a headless run has a virtual screen whose resolution is the headless viewport.

lua

if Input.IsKeyPressed(Key.F11) then
	Application.SetFullscreen(not Application.IsFullscreen())
end

Member	Kind	Summary
`Application.Quit()`	Function	Asks the application to close after the current frame (in the editor: stops play mode).
`Application.GetFrameCount(): integer`	Function	Frames the application has run (frames of the script runtime when there is no application).
`Application.IsEditor: boolean (read-only)`	Property	True when the game runs inside the editor (play mode).
`Application.Platform: string (read-only)`	Property	The operating system: "Windows", "Linux" or "macOS".
`Application.SetFullscreen(fullscreen: boolean): boolean`	Function	Switches the game window to borderless fullscreen on the monitor it is on (true) or back to its windowed size and position (false), at the end of the frame.
`Application.IsFullscreen(): boolean`	Function	Whether the game window is fullscreen (as of the last applied request).
`Application.SetResolution(width: integer, height: integer): boolean`	Function	Resizes the game window so it renders width x height framebuffer pixels (64 to 16384 per axis; other sizes raise an error), at the end of the frame; while fullscreen, the size the window gets when it leaves fullscreen.
`Application.GetResolution(): integer, integer`	Function	The width and height in framebuffer pixels of what the game renders to: the window, the editor's Game view, or the headless screen (0, 0 when there is none).
`Application.SetVSync(enabled: boolean): boolean`	Function	Turns vertical synchronization of the game window's presentation on or off (at the end of the frame).
`Application.IsVSync(): boolean`	Function	Whether vertical synchronization is on (as of the last applied request).

Application.Quit#

lua

Application.Quit()

Asks the application to close after the current frame (in the editor: stops play mode). Logs a warning where quitting is not available.

Application.GetFrameCount#

lua

Application.GetFrameCount(): integer

Frames the application has run (frames of the script runtime when there is no application).

Returns integer

Application.IsEditor#

lua

Application.IsEditor: boolean (read-only)

True when the game runs inside the editor (play mode).

Application.Platform#

lua

Application.Platform: string (read-only)

The operating system: "Windows", "Linux" or "macOS".

Application.SetFullscreen#

lua

Application.SetFullscreen(fullscreen: boolean): boolean

Switches the game window to borderless fullscreen on the monitor it is on (true) or back to its windowed size and position (false), at the end of the frame. Returns whether the request was accepted: false in the editor's play mode and where the engine has no window or screen.

Parameters

fullscreen (boolean)

Returns boolean

Example

lua

Application.SetFullscreen(true)

Application.IsFullscreen#

lua

Application.IsFullscreen(): boolean

Whether the game window is fullscreen (as of the last applied request).

Returns boolean

Application.SetResolution#

lua

Application.SetResolution(width: integer, height: integer): boolean

Resizes the game window so it renders width x height framebuffer pixels (64 to 16384 per axis; other sizes raise an error), at the end of the frame; while fullscreen, the size the window gets when it leaves fullscreen. A headless run resizes its virtual screen. The operating system may limit the size (read GetResolution afterwards). Returns whether the request was accepted (false in the editor's play mode).

Parameters

width (integer)
height (integer)

Returns boolean

Example

lua

Application.SetResolution(1280, 720)

Application.GetResolution#

lua

Application.GetResolution(): integer, integer

The width and height in framebuffer pixels of what the game renders to: the window, the editor's Game view, or the headless screen (0, 0 when there is none).

Returns integer, integer

Example

lua

local width, height = Application.GetResolution()

Application.SetVSync#

lua

Application.SetVSync(enabled: boolean): boolean

Turns vertical synchronization of the game window's presentation on or off (at the end of the frame). Returns whether the request was accepted (false in the editor's play mode).

Parameters

enabled (boolean)

Returns boolean

Application.IsVSync#

lua

Application.IsVSync(): boolean

Whether vertical synchronization is on (as of the last applied request).

Returns boolean

Audio#

Sound playback of the running scene: fire-and-forget one-shots and the mixer groups (Master, Music, SFX, UI by default; more in the project's audio settings). Mixer settings are engine-wide (shared by every scene). Needs the scene's Audio system.

lua

Audio.PlayOneShot(self.JumpSound, 0.8)
Audio.SetGroupVolume("Music", 0.5)

Member	Kind	Summary
`Audio.PlayOneShot(clip: integer\|string, volume?: number, group?: string, position?: Vec2): boolean`	Function	Plays an AudioClip once (an asset handle such as an AudioClip property, or a virtual path) in the mixer group (default "SFX") at volume (default 1; above 4 it is clamped to 4, a negative volume raises an error) times the clip's default volume.
`Audio.SetMasterVolume(volume: number)`	Function	Sets the master volume (clamped to [0, 1]); negative or non-finite values raise an error.
`Audio.GetMasterVolume(): number`	Function	The master volume in [0, 1].
`Audio.SetGroupVolume(group: string, volume: number)`	Function	Sets a mixer group's volume (clamped to [0, 1]).
`Audio.GetGroupVolume(group: string): number`	Function	A mixer group's volume.
`Audio.SetGroupMuted(group: string, muted: boolean)`	Function	Mutes or unmutes a mixer group (its volume is kept for unmuting).
`Audio.IsGroupMuted(group: string): boolean`	Function	Whether a mixer group is muted.

Audio.PlayOneShot#

lua

Audio.PlayOneShot(clip: integer|string, volume?: number, group?: string, position?: Vec2): boolean

Plays an AudioClip once (an asset handle such as an AudioClip property, or a virtual path) in the mixer group (default "SFX") at volume (default 1; above 4 it is clamped to 4, a negative volume raises an error) times the clip's default volume. With a position the sound is spatial at that world point. One-shots pause with the scene and stop with it. When all 64 voices play, the oldest sound that does not loop is stopped to make room. Returns false when no voice could be started: the clip failed to load, or all 64 voices play looping sounds.

Parameters

clip (integer|string)
volume? (number)
group? (string)
position? (Vec2)

Returns boolean

Example

lua

Audio.PlayOneShot("Assets/Audio/Explosion.wav", 1, "SFX", self.Entity.WorldPosition)

Audio.SetMasterVolume#

lua

Audio.SetMasterVolume(volume: number)

Sets the master volume (clamped to [0, 1]); negative or non-finite values raise an error.

Parameters

volume (number)

Audio.GetMasterVolume#

lua

Audio.GetMasterVolume(): number

The master volume in [0, 1].

Returns number

Audio.SetGroupVolume#

lua

Audio.SetGroupVolume(group: string, volume: number)

Sets a mixer group's volume (clamped to [0, 1]). Unknown groups raise an error.

Parameters

group (string)
volume (number)

Example

lua

Audio.SetGroupVolume("Music", Storage.Get("MusicVolume") or 1)

Audio.GetGroupVolume#

lua

Audio.GetGroupVolume(group: string): number

A mixer group's volume. Unknown groups raise an error.

Parameters

group (string)

Returns number

Audio.SetGroupMuted#

lua

Audio.SetGroupMuted(group: string, muted: boolean)

Mutes or unmutes a mixer group (its volume is kept for unmuting). Unknown groups raise an error.

Parameters

group (string)
muted (boolean)

Example

lua

Audio.SetGroupMuted("Music", true)

Audio.IsGroupMuted#

lua

Audio.IsGroupMuted(group: string): boolean

Whether a mixer group is muted. Unknown groups raise an error.

Parameters

group (string)

Returns boolean

Bank#

The bank (Items.BankSlots) and account bank of characters: reached in game through a Bank interactable.

lua

Bank.Deposit(player, 1)

Member	Kind	Summary
`Bank.GetSlots(actor: Entity): table`	Function	The occupied bank slots: a list of { Slot, Item }.
`Bank.Deposit(actor: Entity, slot: integer, quantity?: integer): boolean, string?`	Function	Moves a backpack stack (or quantity of it) into the bank's first free slot.
`Bank.Withdraw(actor: Entity, slot: integer, quantity?: integer): boolean, string?`	Function	Moves a bank stack (or quantity of it) into the backpack's first free slot.

Bank.GetSlots#

lua

Bank.GetSlots(actor: Entity): table

The occupied bank slots: a list of { Slot, Item }. On a client: the local character's, from the RPG lane (the first read asks for the lazily sent bank: empty until it arrived); empty for anyone else.

Parameters

actor (Entity): The character.

Returns table

Example

lua

local stored = #Bank.GetSlots(player)

Bank.Deposit#

lua

Bank.Deposit(actor: Entity, slot: integer, quantity?: integer): boolean, string?

Moves a backpack stack (or quantity of it) into the bank's first free slot.

Parameters

actor (Entity): The character.
slot (integer): The backpack slot, from 1.
quantity? (integer): How many (default all).

Returns boolean, string?

Example

lua

Bank.Deposit(player, 4)

Bank.Withdraw#

lua

Bank.Withdraw(actor: Entity, slot: integer, quantity?: integer): boolean, string?

Moves a bank stack (or quantity of it) into the backpack's first free slot.

Parameters

actor (Entity): The character.
slot (integer): The bank slot, from 1.
quantity? (integer): How many (default all).

Returns boolean, string?

Example

lua

Bank.Withdraw(player, 1)

BehaviorTree#

The NPCs' behaviour trees (Docs/AI.md): an NPC is an entity with a BehaviorTree component (its .fbtree asset) and an AIAgent whose Handler is "BehaviorTree". Trees run where the scene has authority (servers, hosts and offline games); there every function works on the NPC's running tree, and the functions other than IsRunning raise an error elsewhere (clients) and for entities that run no tree. A tree's Lua nodes call scripts on the main thread after the parallel thinks: LuaAction's and LuaCondition's Function is "self:Method" (a method of the NPC's own script, called as self:Method()) or "Module.Function" (the function of the game module require("Module") returns, called with the NPC's Entity). LuaAction returns "Success", "Failure" or "Running", LuaCondition a boolean; anything else, a missing function or an error fails the node.

lua

-- Assets/Scripts/Guard.lua, the NPC's script; its tree has a LuaAction with Function "self:Bark"
function Guard:Bark()
	if self.Barks >= 3 then return "Success" end
	self.Barks = self.Barks + 1
	return "Running"
end

function Guard:OnBehaviorEvent(name)
	if name == "Alarm" then BehaviorTree.SetValue(self.Entity, "Alert", true) end
end

Member	Kind	Summary
`BehaviorTree.GetValue(npc: Entity, key: string): any`	Function	The value of a key of the NPC's blackboard: a boolean (Bool), an integer (Int), a number (Float), a Vec2, an Entity, a string (Name) or an asset handle (Asset); nil while the key is unset.
`BehaviorTree.SetValue(npc: Entity, key: string, value: any)`	Function	Sets a key of the NPC's blackboard; nil unsets it.
`BehaviorTree.SendEvent(npc: Entity, name: string)`	Function	Queues an event (1-128 bytes) for the NPC's next think and wakes the NPC: OnEvent nodes and state machine transitions react to it, and the NPC's script hears it in OnBehaviorEvent once a think handled it.
`BehaviorTree.SetTree(npc: Entity, tree?: integer\|string)`	Function	Gives the NPC another tree (a BehaviorTree asset handle or virtual path; nil stops its tree): the running nodes are aborted and the new tree starts with its defaults and the component's blackboard values.
`BehaviorTree.Restart(npc: Entity)`	Function	Starts the NPC's tree over: the running nodes are aborted (movement stops), the blackboard goes back to the tree's defaults and the component's values, and queued events are dropped.
`BehaviorTree.IsRunning(npc: Entity): boolean`	Function	True when the NPC thinks with its tree here: an enabled BehaviorTree component whose tree loads, not paused.
`BehaviorTree.GetActiveNodes(npc: Entity): { { Id: integer, Type: string } }`	Function	The NPC's running nodes, root first in depth-first order: each node's id in the .fbtree and its type (for scripted debugging and tests).

BehaviorTree.GetValue#

lua

BehaviorTree.GetValue(npc: Entity, key: string): any

The value of a key of the NPC's blackboard: a boolean (Bool), an integer (Int), a number (Float), a Vec2, an Entity, a string (Name) or an asset handle (Asset); nil while the key is unset. Raises an error for a key the tree does not declare.

Parameters

npc (Entity)
key (string)

Returns any

Example

lua

local target = BehaviorTree.GetValue(guard, "Target")
if target ~= nil and target:IsValid() then Log.Info(target.Name) end

BehaviorTree.SetValue#

lua

BehaviorTree.SetValue(npc: Entity, key: string, value: any)

Sets a key of the NPC's blackboard; nil unsets it. The value must fit the key's type: a boolean, an integer in the 32-bit range, a finite number, a Vec2, an Entity (or an entity ID), a string of 1-128 bytes, or an asset handle or path. The tree sees it at its next think.

Parameters

npc (Entity)
key (string)
value (any)

Example

lua

BehaviorTree.SetValue(guard, "Home", self.Entity.Position)
BehaviorTree.SetValue(guard, "Target", nil)

BehaviorTree.SendEvent#

lua

BehaviorTree.SendEvent(npc: Entity, name: string)

Queues an event (1-128 bytes) for the NPC's next think and wakes the NPC: OnEvent nodes and state machine transitions react to it, and the NPC's script hears it in OnBehaviorEvent once a think handled it. At most 4 events wait; a fifth raises an error.

Parameters

npc (Entity)
name (string)

Example

lua

BehaviorTree.SendEvent(guard, "Alarm")

BehaviorTree.SetTree#

lua

BehaviorTree.SetTree(npc: Entity, tree?: integer|string)

Gives the NPC another tree (a BehaviorTree asset handle or virtual path; nil stops its tree): the running nodes are aborted and the new tree starts with its defaults and the component's blackboard values. Writes the component's Tree. Raises an error for a tree that does not load.

Parameters

npc (Entity)
tree? (integer|string)

Example

lua

BehaviorTree.SetTree(guard, "Assets/AI/Flee.fbtree")

BehaviorTree.Restart#

lua

BehaviorTree.Restart(npc: Entity)

Starts the NPC's tree over: the running nodes are aborted (movement stops), the blackboard goes back to the tree's defaults and the component's values, and queued events are dropped.

Parameters

npc (Entity)

BehaviorTree.IsRunning#

lua

BehaviorTree.IsRunning(npc: Entity): boolean

True when the NPC thinks with its tree here: an enabled BehaviorTree component whose tree loads, not paused. False where no trees run (clients).

Parameters

npc (Entity)

Returns boolean

BehaviorTree.GetActiveNodes#

lua

BehaviorTree.GetActiveNodes(npc: Entity): { { Id: integer, Type: string } }

The NPC's running nodes, root first in depth-first order: each node's id in the .fbtree and its type (for scripted debugging and tests). Empty between thinks when the tree finished.

Parameters

npc (Entity)

Returns { { Id: integer, Type: string } }

Example

lua

for _, node in ipairs(BehaviorTree.GetActiveNodes(guard)) do Log.Info(node.Id .. " " .. node.Type) end

Border#

Seamless borders between zone servers: entities near a border are shown on the neighbouring zone as ghosts - read-only mirrors its clients see like any other entity (Entity:IsGhost()). A script that interacts with a ghost forwards the interaction to the entity's authority with Border.Send; it arrives there as OnBorderEvent. Players cross by walking: the zones hand them off on their own. Every function works on any peer; without border links (single zones, clients) Send returns false and GetStats nil.

lua

function Sword:OnHit(target)
	if target:IsGhost() then
		Border.Send(target, "Damage", { 10 }, self.Entity)
	else
		target:GetScript():Damage(10)
	end
end

Member	Kind	Summary
`Border.Send(ghost: Entity, event: string, args?: table, sender?: Entity): boolean, string?`	Function	Forwards an interaction to the authority of a ghost (its zone delivers OnBorderEvent(sender, event, args, fromZone) to the entity's script).
`Border.GetSourceZone(entity: Entity): string?`	Function	The zone process that owns a ghost ("Lumbridge@1.1"), or nil for an entity that is not a ghost.
`Border.GetGlobalId(entity: Entity): integer?`	Function	The realm-wide id of a networked entity: the same on every zone that shows it (its ghosts included) and, for a player's avatar, across handoffs.
`Border.GetStats(): { Links: integer, LinksConnected: integer, GhostsIn: integer, GhostsOut: integer, BytesInPerSecond: integer, BytesOutPerSecond: integer, BatchesSent: integer, BatchesReceived: integer, BatchesRefused: integer, EventsForwarded: integer, EventsDelivered: integer, EventsRefused: integer, Crossings: integer, Preconnects: integer, GhostsTimedOut: integer, GhostsSkipped: integer }?`	Function	The zone's border links: neighbours and those connected, ghosts shown here (In) and mirrored to neighbours (Out), bytes per second, ghost batches (Refused: malformed ones from a neighbour, which closes its link), forwarded events, crossings and pre-connects handed to the handoff, ghosts removed because their link went silent and entities near a border that cannot be mirrored (no prefab).
`Border.GetLinks(): { BorderId: integer, Neighbour: string, State: string, GhostsIn: integer, GhostsOut: integer, Connections: integer, LastError: string }[]`	Function	The zone's seamless neighbours: the border's id, the neighbour's process key, the link's state (Waiting, Connecting, Connected, Backoff), ghosts each way, link sessions so far and the last problem.

Border.Send#

lua

Border.Send(ghost: Entity, event: string, args?: table, sender?: Entity): boolean, string?

Forwards an interaction to the authority of a ghost (its zone delivers OnBorderEvent(sender, event, args, fromZone) to the entity's script). Returns true when it is queued (it goes out with the next tick), false and the reason when the link is down, the link's rate (Network.Borders EventsPerSecond) is exceeded, too many wait or the arguments encode to more than 4 KiB. Raises an error for an entity that is not a ghost, a name that is not 1-64 bytes of text and arguments that cannot travel (functions, more than 64 values).

Parameters

ghost (Entity)
event (string)
args? (table)
sender? (Entity)

Returns boolean, string?

Example

lua

local ok, reason = Border.Send(chest, "Open", { self.Entity.Name }, self.Entity)
if not ok then Log.Warn(reason) end

Border.GetSourceZone#

lua

Border.GetSourceZone(entity: Entity): string?

The zone process that owns a ghost ("Lumbridge@1.1"), or nil for an entity that is not a ghost.

Parameters

entity (Entity)

Returns string?

Border.GetGlobalId#

lua

Border.GetGlobalId(entity: Entity): integer?

The realm-wide id of a networked entity: the same on every zone that shows it (its ghosts included) and, for a player's avatar, across handoffs. Player ids have the top bit set and read as negative integers. nil for entities without one (not networked, or the zone has no border links and the entity is no ghost).

Parameters

entity (Entity)

Returns integer?

Border.GetStats#

lua

Border.GetStats(): { Links: integer, LinksConnected: integer, GhostsIn: integer, GhostsOut: integer, BytesInPerSecond: integer, BytesOutPerSecond: integer, BatchesSent: integer, BatchesReceived: integer, BatchesRefused: integer, EventsForwarded: integer, EventsDelivered: integer, EventsRefused: integer, Crossings: integer, Preconnects: integer, GhostsTimedOut: integer, GhostsSkipped: integer }?

The zone's border links: neighbours and those connected, ghosts shown here (In) and mirrored to neighbours (Out), bytes per second, ghost batches (Refused: malformed ones from a neighbour, which closes its link), forwarded events, crossings and pre-connects handed to the handoff, ghosts removed because their link went silent and entities near a border that cannot be mirrored (no prefab). nil when the zone has no border links.

Returns { Links: integer, LinksConnected: integer, GhostsIn: integer, GhostsOut: integer, BytesInPerSecond: integer, BytesOutPerSecond: integer, BatchesSent: integer, BatchesReceived: integer, BatchesRefused: integer, EventsForwarded: integer, EventsDelivered: integer, EventsRefused: integer, Crossings: integer, Preconnects: integer, GhostsTimedOut: integer, GhostsSkipped: integer }?

Border.GetLinks#

lua

Border.GetLinks(): { BorderId: integer, Neighbour: string, State: string, GhostsIn: integer, GhostsOut: integer, Connections: integer, LastError: string }[]

The zone's seamless neighbours: the border's id, the neighbour's process key, the link's state (Waiting, Connecting, Connected, Backoff), ghosts each way, link sessions so far and the last problem. Empty without border links.

Returns { BorderId: integer, Neighbour: string, State: string, GhostsIn: integer, GhostsOut: integer, Connections: integer, LastError: string }[]

Bot#

Bot behaviours (Assets/Bots/*.lua, run by loadtest.run, the Load Test panel and "bots" play-test peers): what the bot whose behaviour runs does as a real client of the session - walk its avatar (the root networked entity it owns), call ServerRpcs, chat, travel to another server and look around. Entities a bot sees are its own copies: pass them to Bot functions (their Entity methods need a scene, which the shared bot Lua state does not have). Outside a bot behaviour every function raises an error.

lua

function Fighter:Run()
	while true do
		local npc = Bot.GetNearby(20, "Npcs")[1]
		if npc then
			Bot.MoveTo(Bot.GetEntityPosition(npc))
			Bot.Attack(npc)
		else
			Bot.Wander(10)
		end
		Wait(1)
	end
end

Member	Kind	Summary
`Bot.GetId(): integer`	Function	The bot's id in the run: 1 to the number of bots, unique across the run's bot processes.
`Bot.IsConnected(): boolean`	Function	True while the bot is in a session and has loaded the server's scene (false while it travels or after the server dropped it).
`Bot.GetAvatar(): Entity?`	Function	The bot's avatar: the root networked entity it owns (the first the server spawned for it), or nil while it has none.
`Bot.GetPosition(): Vec2?`	Function	The position of the bot's avatar (the root networked entity it owns), or nil while it has none (before the server spawned it, while travelling).
`Bot.MoveTo(position: Vec2)`	Function	Walks the avatar in a straight line to the position at the scenario's Bot.MoveSpeed and stops there (owner-authoritative: the bot moves its own avatar, the server checks the speed).
`Bot.Wander(radius: number)`	Function	Keeps walking to random points (the bot's seeded generator) within radius world units of where the avatar is now, until Stop or MoveTo.
`Bot.Stop()`	Function	Stops walking (MoveTo and Wander).
`Bot.IsMoving(): boolean`	Function	True while the bot walks to a MoveTo target or wanders.
`Bot.Attack(target: Entity): boolean`	Function	Calls the scenario's attack ServerRpc (Bot.AttackRpc, "AttackServerRpc" by default) on the bot's avatar with the target entity: the game's script on the server decides what an attack does.
`Bot.ServerRpc(entity: Entity, method: string, ...: any): boolean`	Function	Runs method(self, ...) of the entity's script on the server, as Script:ServerRpc does for a player (the method name ends in "ServerRpc"; unless the server's class allows it, only the entity's owner may call it - the bot owns its avatar).
`Bot.Say(text: string): boolean`	Function	Calls the scenario's chat ServerRpc (Bot.ChatRpc, "ChatServerRpc" by default) on the bot's avatar with the text (at most 512 bytes of UTF-8).
`Bot.Travel(address?: string): boolean`	Function	Leaves the session and joins another server ("host:port" with real sockets; the name of an in-process zone in in-process runs); nil or "" rejoins the run's server.
`Bot.GetNearby(radius: number, kind?: string): Entity[]`	Function	The networked entities the bot sees within radius world units of its avatar, nearest first (ties by id), without the avatar itself.
`Bot.GetEntityPosition(entity: Entity): Vec2?`	Function	Where an entity the bot sees is, in its copy of the world; nil once the entity left it.
`Bot.Random(): number`	Function	Uniform in [0, 1) from the bot's own generator, seeded by the scenario's Seed and the bot's id: the same scenario makes the same choices.
`Bot.Request(kind: string, arguments?: table): integer \| false`	Function	Sends a request of the RPG lane (Rpg.Request, Docs/Rpg.md) as the bot's client: kind is an RpgRequestKind name and arguments its fields - Cast { Ability, Target?, Point? }, SetTarget { Target? }, StartAttack { Target }, StopAttack, CancelCast, Interact { Target }, Respawn, LootTake { Corpse, Index }, LootTakeAll { Corpse }, MoveItem { From, To, Quantity? }, SplitStack { From, To, Quantity }, DestroyItem { Slot, Quantity? }, UseItem { Slot, Target? }, Equip { Slot, EquipSlot }, Unequip { EquipSlot, To }, SortContainer { Container }, VendorBuy { Vendor, Entry, Quantity? }, VendorSell { Vendor, Slot, Quantity? }, VendorBuyBack { Vendor, Index }, VendorRepair { Vendor, All?, Slot? }, TradeRequest { Target }, TradeOffer { Slot?, Quantity?, Currency?, Amount? }, TradeAccept, TradeCancel, QuestAccept { Quest, Giver? }, QuestAbandon { Quest }, QuestTurnIn { Quest, Npc?, Choice? }, DialogueStart { Npc }, DialogueChoose { Option }, DialogueEnd, Craft { Recipe, Count?, Station? }, CancelCraft, Gather { Node }, GmCommand { Line }, Script { Name, Payload? }, Resync { Section }, SectionVersions { Versions }.
`Bot.GetResult(requestId: integer): table?`	Function	The server's answer to a request Bot.Request sent in the bot's current session (an Rpg.Result): { Ok = boolean, Status = the RpgStatus name ("Ok", "Refused", "OutOfRange", "UnknownKey", ...), Code = the module's code, Message = its text }; nil while no answer arrived, for ids of an earlier session (a zone switch starts a new one) and on thin bots (they count the lane's messages without decoding them).

Bot.GetId#

lua

Bot.GetId(): integer

The bot's id in the run: 1 to the number of bots, unique across the run's bot processes. Its player name is the scenario's Bot.NamePrefix followed by the id ("Bot7").

Returns integer

Example

lua

if Bot.GetId() % 10 == 0 then Bot.Say("hello") end

Bot.IsConnected#

lua

Bot.IsConnected(): boolean

True while the bot is in a session and has loaded the server's scene (false while it travels or after the server dropped it).

Returns boolean

Example

lua

WaitUntil(Bot.IsConnected)

Bot.GetAvatar#

lua

Bot.GetAvatar(): Entity?

The bot's avatar: the root networked entity it owns (the first the server spawned for it), or nil while it has none. Pass it to Bot.ServerRpc to call the avatar's own RPCs.

Returns Entity?

Example

lua

local avatar = Bot.GetAvatar()
if avatar then Bot.ServerRpc(avatar, "EmoteServerRpc", "wave") end

Bot.GetPosition#

lua

Bot.GetPosition(): Vec2?

The position of the bot's avatar (the root networked entity it owns), or nil while it has none (before the server spawned it, while travelling).

Returns Vec2?

Example

lua

local here = Bot.GetPosition()

Bot.MoveTo#

lua

Bot.MoveTo(position: Vec2)

Walks the avatar in a straight line to the position at the scenario's Bot.MoveSpeed and stops there (owner-authoritative: the bot moves its own avatar, the server checks the speed). Returns at once; replaces a Wander.

Parameters

position (Vec2)

Example

lua

Bot.MoveTo(Vec2(10, 4))
WaitUntil(function() return not Bot.IsMoving() end)

Bot.Wander#

lua

Bot.Wander(radius: number)

Keeps walking to random points (the bot's seeded generator) within radius world units of where the avatar is now, until Stop or MoveTo. Returns at once.

Parameters

radius (number)

Example

lua

Bot.Wander(12)

Bot.Stop#

lua

Bot.Stop()

Stops walking (MoveTo and Wander).

Bot.IsMoving#

lua

Bot.IsMoving(): boolean

True while the bot walks to a MoveTo target or wanders.

Returns boolean

Bot.Attack#

lua

Bot.Attack(target: Entity): boolean

Calls the scenario's attack ServerRpc (Bot.AttackRpc, "AttackServerRpc" by default) on the bot's avatar with the target entity: the game's script on the server decides what an attack does. False when it was not sent (not connected, no avatar, the target left the bot's world).

Parameters

target (Entity)

Returns boolean

Example

lua

local npc = Bot.GetNearby(8, "Npcs")[1]
if npc then Bot.Attack(npc) end

Bot.ServerRpc#

lua

Bot.ServerRpc(entity: Entity, method: string, ...: any): boolean

Runs method(self, ...) of the entity's script on the server, as Script:ServerRpc does for a player (the method name ends in "ServerRpc"; unless the server's class allows it, only the entity's owner may call it - the bot owns its avatar). Arguments as for Script:ServerRpc. False when it was not sent (not connected, the entity left the bot's world).

Parameters

entity (Entity)
method (string)
...? (any)

Returns boolean

Example

lua

Bot.ServerRpc(door, "OpenServerRpc", true)

Bot.Say#

lua

Bot.Say(text: string): boolean

Calls the scenario's chat ServerRpc (Bot.ChatRpc, "ChatServerRpc" by default) on the bot's avatar with the text (at most 512 bytes of UTF-8). False when it was not sent (not connected, no avatar).

Parameters

text (string)

Returns boolean

Example

lua

Bot.Say("anyone selling iron?")

Bot.Travel#

lua

Bot.Travel(address?: string): boolean

Leaves the session and joins another server ("host:port" with real sockets; the name of an in-process zone in in-process runs); nil or "" rejoins the run's server. The bot is disconnected meanwhile (IsConnected is false) and gets a new avatar there. Returns at once; false when the bot is travelling already.

Parameters

address? (string)

Returns boolean

Example

lua

Bot.Travel(self.Zones[1 + math.floor(Bot.Random() * #self.Zones)])
WaitUntil(Bot.IsConnected)

Bot.GetNearby#

lua

Bot.GetNearby(radius: number, kind?: string): Entity[]

The networked entities the bot sees within radius world units of its avatar, nearest first (ties by id), without the avatar itself. kind: "All" (default), "Npcs" (server-owned entities) or "Players" (entities other clients own). Empty without an avatar.

Parameters

radius (number)
kind? (string)

Returns Entity[]

Example

lua

for _, player in ipairs(Bot.GetNearby(15, "Players")) do Bot.Say("hi") end

Bot.GetEntityPosition#

lua

Bot.GetEntityPosition(entity: Entity): Vec2?

Where an entity the bot sees is, in its copy of the world; nil once the entity left it.

Parameters

entity (Entity)

Returns Vec2?

Example

lua

Bot.MoveTo(Bot.GetEntityPosition(target))

Bot.Random#

lua

Bot.Random(): number

Uniform in [0, 1) from the bot's own generator, seeded by the scenario's Seed and the bot's id: the same scenario makes the same choices.

Returns number

Example

lua

Wait(1 + Bot.Random() * 2)

Bot.Request#

lua

Bot.Request(kind: string, arguments?: table): integer | false

Sends a request of the RPG lane (Rpg.Request, Docs/Rpg.md) as the bot's client: kind is an RpgRequestKind name and arguments its fields - Cast { Ability, Target?, Point? }, SetTarget { Target? }, StartAttack { Target }, StopAttack, CancelCast, Interact { Target }, Respawn, LootTake { Corpse, Index }, LootTakeAll { Corpse }, MoveItem { From, To, Quantity? }, SplitStack { From, To, Quantity }, DestroyItem { Slot, Quantity? }, UseItem { Slot, Target? }, Equip { Slot, EquipSlot }, Unequip { EquipSlot, To }, SortContainer { Container }, VendorBuy { Vendor, Entry, Quantity? }, VendorSell { Vendor, Slot, Quantity? }, VendorBuyBack { Vendor, Index }, VendorRepair { Vendor, All?, Slot? }, TradeRequest { Target }, TradeOffer { Slot?, Quantity?, Currency?, Amount? }, TradeAccept, TradeCancel, QuestAccept { Quest, Giver? }, QuestAbandon { Quest }, QuestTurnIn { Quest, Npc?, Choice? }, DialogueStart { Npc }, DialogueChoose { Option }, DialogueEnd, Craft { Recipe, Count?, Station? }, CancelCraft, Gather { Node }, GmCommand { Line }, Script { Name, Payload? }, Resync { Section }, SectionVersions { Versions }. Keys (Ability, Quest, Recipe, Currency) are row keys, entities are Entities the bot sees, slots are { Container = "Backpack" | "Equipment" | "Bank" | "AccountBank", Slot = n }. Returns the request's id (the server answers it with an Rpg.Result of the same id), false when it was not sent (not connected, the entity left the bot's world). Unknown kinds or arguments raise an error.

Parameters

kind (string)
arguments? (table)

Returns integer | false

Example

lua

local npc = Bot.GetNearby(6, "Npcs")[1]
if npc then
	Bot.Request("StartAttack", { Target = npc })
	Bot.Request("Cast", { Ability = "Fireball", Target = npc })
end

Bot.GetResult#

lua

Bot.GetResult(requestId: integer): table?

The server's answer to a request Bot.Request sent in the bot's current session (an Rpg.Result): { Ok = boolean, Status = the RpgStatus name ("Ok", "Refused", "OutOfRange", "UnknownKey", ...), Code = the module's code, Message = its text }; nil while no answer arrived, for ids of an earlier session (a zone switch starts a new one) and on thin bots (they count the lane's messages without decoding them). Full bots keep the newest 64 answers.

Parameters

requestId (integer)

Returns table?

Example

lua

local id = Bot.Request("QuestAccept", { Quest = "mm_arrival", Giver = elder })
local result
WaitUntil(function() result = Bot.GetResult(id); return result ~= nil end)
if not result.Ok then error(result.Status .. ": " .. result.Message) end

Camera#

The scene's cameras: the primary camera and conversion between screen positions (framebuffer pixels, origin top-left, +Y down: the space of Input.GetMousePosition) and world positions. Conversions use the camera's current world pose, its Camera component and the size of the output it renders to (Camera.GetViewportSize), like the rendered image: a pixel-perfect camera the host renders in Upscale mode converts through its reference-resolution image (snapped to the texel grid, unrotated, scaled by a whole factor and centered in its viewport), every other camera through its orthographic view.

lua

local target = Camera.ScreenToWorld(Input.GetMousePosition())

Member	Kind	Summary
`Camera.Main(): Entity?`	Function	The primary camera (Primary with the highest Priority, ties: the first in scene order), or nil when there is none.
`Camera.ScreenToWorld(screenPosition: Vec2, camera?: Entity): Vec2`	Function	The world position (relative to the scene origin) under a screen position, seen through camera (default: the primary camera).
`Camera.WorldToScreen(worldPosition: Vec2, camera?: Entity): Vec2`	Function	The screen position (framebuffer pixels, origin top-left) of a world position, seen through camera (default: the primary camera).
`Camera.GetViewportSize(): Vec2`	Function	The size in framebuffer pixels of the output the cameras render to (the window, or the editor's game view).

Camera.Main#

lua

Camera.Main(): Entity?

The primary camera (Primary with the highest Priority, ties: the first in scene order), or nil when there is none.

Returns Entity?

Example

lua

local camera = Camera.Main()
if camera then camera.Position = self.Entity.Position end

Camera.ScreenToWorld#

lua

Camera.ScreenToWorld(screenPosition: Vec2, camera?: Entity): Vec2

The world position (relative to the scene origin) under a screen position, seen through camera (default: the primary camera). Positions outside the camera's viewport are extrapolated.

Parameters

screenPosition (Vec2)
camera? (Entity)

Returns Vec2

Example

lua

local clicked = Camera.ScreenToWorld(Input.GetMousePosition())

Camera.WorldToScreen#

lua

Camera.WorldToScreen(worldPosition: Vec2, camera?: Entity): Vec2

The screen position (framebuffer pixels, origin top-left) of a world position, seen through camera (default: the primary camera).

Parameters

worldPosition (Vec2)
camera? (Entity)

Returns Vec2

Camera.GetViewportSize#

lua

Camera.GetViewportSize(): Vec2

The size in framebuffer pixels of the output the cameras render to (the window, or the editor's game view).

Returns Vec2

Characters#

Backend service scripts (Assets/Services/*.lua on FrostServices) add the game's rules to character creation, after the character template's own checks (name rules, option lists, the per-realm limit).

lua

Characters.OnValidate(function(account, request)
    if request.Fields.Class == "Necromancer" and request.Realm == "Kids" then
        return false, "Not on this realm"
    end
end)

Member	Kind	Summary
`Characters.OnValidate(fn?: function): function?`	Function	Installs fn(account, request) for every creation request (request: { Realm, Name, Roles, Fields = { name = option } }): return false and a message (or just the message) to refuse - the player sees the message -, true or nil to accept.
`Characters.OnCreate(fn?: function): function?`	Function	Installs fn(account, request, data) for every accepted creation: data is the template's InitialData; return the new character's initial persistent data (a table of the persistent schema's Character fields; nil keeps data).

Characters.OnValidate#

lua

Characters.OnValidate(fn?: function): function?

Installs fn(account, request) for every creation request (request: { Realm, Name, Roles, Fields = { name = option } }): return false and a message (or just the message) to refuse - the player sees the message -, true or nil to accept. An error refuses. nil removes the hook. Returns the previous hook. In game scripts it only records the function.

Parameters

fn? (function)

Returns function?

Characters.OnCreate#

lua

Characters.OnCreate(fn?: function): function?

Installs fn(account, request, data) for every accepted creation: data is the template's InitialData; return the new character's initial persistent data (a table of the persistent schema's Character fields; nil keeps data). An error refuses the creation. nil removes the hook. Returns the previous hook. In game scripts it only records the function.

Parameters

fn? (function)

Returns function?

Example

lua

Characters.OnCreate(function(account, request, data)
    data.Weapon = request.Fields.Class == "Mage" and "Staff" or "Sword"
    return data
end)

Chat#

Chat with the cross-server player services. Clients send; results arrive as OnServiceResult (requestId, ok, result) and messages as OnChatMessage(message). Say, Yell and Emote reach the players near the speaker in its zone; Party, Raid, Guild and Officer the sender's group; any other name a channel the player joined (World, Trade, LookingForGroup, the game's own and channels players create). Every message goes through the moderation chain (mutes, rate limits, repetition, the word filter, the game's hook). Zone servers announce; the services' Lua host filters.

lua

self.Sent = Chat.Send("World", "Anyone for the crypt?")
Chat.Whisper("Merlin", "Meet me at the gate")

Member	Kind	Summary
`Chat.Send(channel: string, text: string): integer?, string?`	Function	Sends a chat message: channel "Say", "Yell" or "Emote" (the players near you), "Party", "Raid", "Guild", "Officer" (your group) or the name of a joined channel; text is 1-255 bytes of UTF-8 without control characters.
`Chat.Whisper(name: string, text: string): integer?, string?`	Function	Whispers to a player by character name (anywhere in the realm).
`Chat.Join(channel: string): integer?, string?`	Function	Joins a realm channel; a name the game does not define creates a channel (when Chat.json allows it) that its creator moderates.
`Chat.Leave(channel: string): integer?, string?`	Function	Leaves a joined channel.
`Chat.Report(messageId: integer, reason: string): integer?, string?`	Function	Reports a message the player received (OnChatMessage's MessageId) to the operators, with the conversation's recent context.
`Chat.Moderate(channel: string, name: string, action: string, seconds?: integer): integer?, string?`	Function	A channel moderator (who created a custom channel, or whom it promoted) acts on a member: "Kick" removes it, "Mute" silences it in the channel for seconds (1-86400), "Unmute", "Promote" makes it a moderator.
`Chat.Announce(channel?: string, text: string): boolean`	Function	Zone servers: a system message (Kind "System") to every member of a realm channel, or to every player of the realm (channel nil), through the Social host.
`Chat.AnnounceZone(text: string): boolean?, string?`	Function	Zone servers: a system message to the players of this zone only (no Social host involved).
`Chat.SetFilterHook(fn?: function): function?`	Function	Backend service scripts (Assets/Services/*.lua on FrostServices): fn(message) sees every message a Social host sends on (message: { SenderId, AccountId, SenderName, Channel, Kind, Text }) after the word filter, and returns the text to send (changed or not) or nil to refuse it.

Chat.Send#

lua

Chat.Send(channel: string, text: string): integer?, string?

Sends a chat message: channel "Say", "Yell" or "Emote" (the players near you), "Party", "Raid", "Guild", "Officer" (your group) or the name of a joined channel; text is 1-255 bytes of UTF-8 without control characters. Returns the request id (OnServiceResult reports it with MessageId, or the refusal: "quotaExceeded" for flooding, "permissionDenied" while muted, "notFound" outside the channel), or nil and why it was not sent (no zone session, too many requests waiting).

Parameters

channel (string)
text (string)

Returns integer?, string?

Chat.Whisper#

lua

Chat.Whisper(name: string, text: string): integer?, string?

Whispers to a player by character name (anywhere in the realm). Unknown, offline, hidden and ignoring players are answered alike: "notFound". Both sides receive the message as OnChatMessage (Kind "Whisper", Channel the recipient's name).

Parameters

name (string)
text (string)

Returns integer?, string?

Chat.Join#

lua

Chat.Join(channel: string): integer?, string?

Joins a realm channel; a name the game does not define creates a channel (when Chat.json allows it) that its creator moderates. The channel's recent messages follow as OnChatMessage.

Parameters

channel (string)

Returns integer?, string?

Chat.Leave#

lua

Chat.Leave(channel: string): integer?, string?

Leaves a joined channel.

Parameters

channel (string)

Returns integer?, string?

Chat.Report#

lua

Chat.Report(messageId: integer, reason: string): integer?, string?

Reports a message the player received (OnChatMessage's MessageId) to the operators, with the conversation's recent context. Only recent messages the player could see can be reported.

Parameters

messageId (integer)
reason (string)

Returns integer?, string?

Chat.Moderate#

lua

Chat.Moderate(channel: string, name: string, action: string, seconds?: integer): integer?, string?

A channel moderator (who created a custom channel, or whom it promoted) acts on a member: "Kick" removes it, "Mute" silences it in the channel for seconds (1-86400), "Unmute", "Promote" makes it a moderator.

Parameters

channel (string)
name (string)
action (string)
seconds? (integer)

Returns integer?, string?

Chat.Announce#

lua

Chat.Announce(channel?: string, text: string): boolean

Zone servers: a system message (Kind "System") to every member of a realm channel, or to every player of the realm (channel nil), through the Social host. Returns false without a zone router; true when queued. An asynchronous refusal is logged.

Parameters

channel? (string)
text (string)

Returns boolean

Chat.AnnounceZone#

lua

Chat.AnnounceZone(text: string): boolean?, string?

Zone servers: a system message to the players of this zone only (no Social host involved).

Parameters

text (string)

Returns boolean?, string?

Chat.SetFilterHook#

lua

Chat.SetFilterHook(fn?: function): function?

Backend service scripts (Assets/Services/*.lua on FrostServices): fn(message) sees every message a Social host sends on (message: { SenderId, AccountId, SenderName, Channel, Kind, Text }) after the word filter, and returns the text to send (changed or not) or nil to refuse it. An error refuses the message (failing closed). nil removes the hook. Returns the previous hook. In game scripts it only records the function: the player services' local host (inside a game server, Social.json's LocalHost) never calls it; only FrostServices filters chat through the hook.

Parameters

fn? (function)

Returns function?

Example

lua

Chat.SetFilterHook(function(message)
    if message.Text:find("buy gold") then return nil end
    return message.Text
end)

Combat#

The combat pipeline of the scene's Combat system (servers, hosts and offline games): scripted damage and healing that resolve through the combat formulas like an ability's (hit, crit, mitigation, absorbs, threat, deaths and kill credit), interrupts, the experience a kill gives, the combat log and the system's counters. Every function raises an error in a scene without the Combat system (clients). The formulas: Combat.FormulaModule names a Lua module whose functions HitChance, CritChance, Damage, Heal, Mitigation, Threat and XpForKill (each optional; the others stay native) are called as F(ctx) and return a number. ctx = { Formula, Source and Target (Entities, Source nil for sourceless damage), AbilityHash, EffectIndex, SchoolHash and School, StatHash and Stat (the scaling stat), BaseAmount, Flags, Random }: BaseAmount is the effect's base amount for Damage and Heal (before the crit multiplier and mitigation), the amount before mitigation for Mitigation, the amount applied for Threat and the native experience for XpForKill; ctx:Random() is a number in [0, 1) of the source actor's random stream, which only the formulas of a hit have (XpForKill raises an error for it). HitChance, CritChance and Mitigation are clamped to [0, 1], the others to at least 0; a formula that raises or returns no finite number gives way to the native one (logged once per formula and ability).

lua

function Trap:OnTriggerEnter(other)
	Combat.DealDamage(nil, other, 25, "fire")
end

Member	Kind	Summary
`Combat.DealDamage(source: Entity?, target: Entity, amount: number, school?: string): boolean, string?`	Function	Damage of `amount` (before mitigation) in a damage school (by key; without one, or for a school the RPG database does not have, no resistance applies) from `source` (nil: the world) to `target`; it resolves in this tick's combat step through the formulas (dodge, crit, the school's resistance, absorbs) and counts for threat and kill credit like an ability's.
`Combat.Heal(source: Entity?, target: Entity, amount: number): boolean, string?`	Function	Healing of `amount` from `source` (nil: the world) that resolves in this tick's combat step through the heal formula (crits) and gives the healer threat with the NPCs engaged with the target.
`Combat.Interrupt(target: Entity, source?: Entity, lockSeconds?: number): boolean`	Function	Interrupts the target's interruptible cast or channel (nothing is paid; the combat log's CastInterrupted entry names `source`) and locks the cast's damage school for `lockSeconds` (default 0).
`Combat.GetXpForKill(killer: Entity, victim: Entity): integer`	Function	The experience killing `victim` gives `killer`: the XpForKill formula (Combat.FormulaModule's, else the victim's template's Xp, else 45 + 5 x its level); 0 when the victim is not an RPG actor.
`Combat.GetLog(actor?: Entity, count?: integer): { { Tick: integer, Kind: string, Source: Entity?, Target: Entity?, Ability: string?, Effect: string?, Amount: number?, Absorbed: number?, Overkill: number?, Crit: boolean?, Miss: boolean?, Immune: boolean?, Killing: boolean? } }`	Function	The newest entries of the combat log (oldest first; `count` 1 to 4096, default 20) that `actor` caused or took (every actor's without one): Kind Effect (a resolved hit, heal, periodic tick or other effect, with its amount after mitigation and absorbs and its flags), CastStart, CastComplete, CastCancelled, CastInterrupted or Kill.
`Combat.GetStats(): { Actors: integer, CastsStarted: integer, CastsCompleted: integer, CastsCancelled: integer, CastsInterrupted: integer, CastsRefused: integer, CastsQueued: integer, Swings: integer, EventsResolved: integer, Kills: integer, LuaFormulaCalls: integer, FormulaFallbacks: integer, ProjectilesLaunched: integer, ProjectilesHit: integer, ProjectilesInFlight: integer, ThreatTables: integer }`	Function	The combat system's counters since the scene started: casts by outcome, auto-attack swings, resolved events, kills, Lua formula calls and the ones that fell back to the native formula, projectiles, and the actors and threat tables it keeps now.

Combat.DealDamage#

lua

Combat.DealDamage(source: Entity?, target: Entity, amount: number, school?: string): boolean, string?

Damage of amount (before mitigation) in a damage school (by key; without one, or for a school the RPG database does not have, no resistance applies) from source (nil: the world) to target; it resolves in this tick's combat step through the formulas (dodge, crit, the school's resistance, absorbs) and counts for threat and kill credit like an ability's. True when it was queued; false and the reason when the target or the source is not an RPG actor. Raises an error for an amount that is negative or not finite.

Parameters

source (Entity?)
target (Entity)
amount (number)
school? (string)

Returns boolean, string?

Example

lua

Combat.DealDamage(nil, player, 10, "fire")

Combat.Heal#

lua

Combat.Heal(source: Entity?, target: Entity, amount: number): boolean, string?

Healing of amount from source (nil: the world) that resolves in this tick's combat step through the heal formula (crits) and gives the healer threat with the NPCs engaged with the target. True when it was queued; false and the reason when the target or the source is not an RPG actor. Raises an error for an amount that is negative or not finite.

Parameters

source (Entity?)
target (Entity)
amount (number)

Returns boolean, string?

Example

lua

Combat.Heal(fountain, player, 50)

Combat.Interrupt#

lua

Combat.Interrupt(target: Entity, source?: Entity, lockSeconds?: number): boolean

Interrupts the target's interruptible cast or channel (nothing is paid; the combat log's CastInterrupted entry names source) and locks the cast's damage school for lockSeconds (default 0). False when the target was not casting something interruptible. Raises an error for a lock outside [0, 3600] seconds.

Parameters

target (Entity)
source? (Entity)
lockSeconds? (number)

Returns boolean

Example

lua

Combat.Interrupt(boss, self.Entity, 4)

Combat.GetXpForKill#

lua

Combat.GetXpForKill(killer: Entity, victim: Entity): integer

The experience killing victim gives killer: the XpForKill formula (Combat.FormulaModule's, else the victim's template's Xp, else 45 + 5 x its level); 0 when the victim is not an RPG actor.

Parameters

killer (Entity)
victim (Entity)

Returns integer

Example

lua

Log.Info("worth " .. Combat.GetXpForKill(player, wolf) .. " xp")

Combat.GetLog#

lua

Combat.GetLog(actor?: Entity, count?: integer): { { Tick: integer, Kind: string, Source: Entity?, Target: Entity?, Ability: string?, Effect: string?, Amount: number?, Absorbed: number?, Overkill: number?, Crit: boolean?, Miss: boolean?, Immune: boolean?, Killing: boolean? } }

The newest entries of the combat log (oldest first; count 1 to 4096, default 20) that actor caused or took (every actor's without one): Kind Effect (a resolved hit, heal, periodic tick or other effect, with its amount after mitigation and absorbs and its flags), CastStart, CastComplete, CastCancelled, CastInterrupted or Kill. Raises an error for a count outside [1, 4096].

Parameters

actor? (Entity)
count? (integer)

Returns { { Tick: integer, Kind: string, Source: Entity?, Target: Entity?, Ability: string?, Effect: string?, Amount: number?, Absorbed: number?, Overkill: number?, Crit: boolean?, Miss: boolean?, Immune: boolean?, Killing: boolean? } }

Example

lua

for _, entry in ipairs(Combat.GetLog(player, 5)) do Log.Info(entry.Kind .. " " .. (entry.Amount or 0)) end

Combat.GetStats#

lua

Combat.GetStats(): { Actors: integer, CastsStarted: integer, CastsCompleted: integer, CastsCancelled: integer, CastsInterrupted: integer, CastsRefused: integer, CastsQueued: integer, Swings: integer, EventsResolved: integer, Kills: integer, LuaFormulaCalls: integer, FormulaFallbacks: integer, ProjectilesLaunched: integer, ProjectilesHit: integer, ProjectilesInFlight: integer, ThreatTables: integer }

The combat system's counters since the scene started: casts by outcome, auto-attack swings, resolved events, kills, Lua formula calls and the ones that fell back to the native formula, projectiles, and the actors and threat tables it keeps now.

Returns { Actors: integer, CastsStarted: integer, CastsCompleted: integer, CastsCancelled: integer, CastsInterrupted: integer, CastsRefused: integer, CastsQueued: integer, Swings: integer, EventsResolved: integer, Kills: integer, LuaFormulaCalls: integer, FormulaFallbacks: integer, ProjectilesLaunched: integer, ProjectilesHit: integer, ProjectilesInFlight: integer, ThreatTables: integer }

Example

lua

Log.Info(Combat.GetStats().Kills .. " kills so far")

Crafting#

Recipes (Recipe rows) and crafting: a craft is a timed action at a station (an Interactable of kind CraftingStation with the recipe's Station) that takes the inputs and gives the outputs in one inventory transaction and grants the recipe's XP; a batch repeats until its count, the inputs or the space run out, and moving cancels it. On a client Craft is a request of the RPG lane.

lua

local ok, why = Crafting.Craft(player, "bronze_bar", 5)
if not ok then Log.Warn(why) end

Member	Kind	Summary
`Crafting.Learn(player: Entity, recipe: string): boolean, string?`	Function	Teaches a recipe (one with Learned must be learned before it can be crafted; a trainer, a recipe scroll's use hook).
`Crafting.Forget(player: Entity, recipe: string): boolean`	Function	Removes a learned recipe; false when the character had not learned it.
`Crafting.Knows(player: Entity, recipe: string): boolean`	Function	Whether the character may craft the recipe as far as learning goes (recipes without Learned always).
`Crafting.GetRecipes(player: Entity): table`	Function	The keys of the recipes the character learned (recipes without Learned need no learning and are not listed).
`Crafting.GetInfo(recipe: string): table`	Function	A recipe's definition: { Key, Name, Skill?, Level, Xp, Seconds, Station?, Learned, Inputs = { { Item, Quantity } }, Outputs = { { Item, Quantity, Chance } }, Tools = { item keys } }.
`Crafting.Craft(player: Entity, recipe: string, count?: integer, station?: Entity): boolean, string\|integer?`	Function	Starts a batch of `count` crafts (each a timed action of the recipe's Seconds; OnCrafted per craft, OnActionEnded at the end).

Crafting.Learn#

lua

Crafting.Learn(player: Entity, recipe: string): boolean, string?

Teaches a recipe (one with Learned must be learned before it can be crafted; a trainer, a recipe scroll's use hook). Learning a known recipe succeeds again. False and why for an unknown recipe or a character that knows 1,024 recipes. Authority only.

Parameters

player (Entity): The player character.
recipe (string): The Recipe row key.

Returns boolean, string?

Example

lua

Crafting.Learn(player, "steel_bar")

Crafting.Forget#

lua

Crafting.Forget(player: Entity, recipe: string): boolean

Removes a learned recipe; false when the character had not learned it. Authority only.

Parameters

player (Entity): The player character.
recipe (string): The Recipe row key.

Returns boolean

Example

lua

Crafting.Forget(player, "steel_bar")

Crafting.Knows#

lua

Crafting.Knows(player: Entity, recipe: string): boolean

Whether the character may craft the recipe as far as learning goes (recipes without Learned always). On a client the local character's, from the lazily sent Recipes section (the first call asks for it).

Parameters

player (Entity): The player character.
recipe (string): The Recipe row key.

Returns boolean

Example

lua

if Crafting.Knows(player, "steel_bar") then Log.Info("known") end

Crafting.GetRecipes#

lua

Crafting.GetRecipes(player: Entity): table

The keys of the recipes the character learned (recipes without Learned need no learning and are not listed). On a client the Recipes section is sent lazily: the first call asks the server for it and returns an empty list until it arrives (OnOwnerSectionChanged("Recipes")).

Parameters

player (Entity): The player character.

Returns table

Example

lua

for _, key in ipairs(Crafting.GetRecipes(player)) do Log.Info(key) end

Crafting.GetInfo#

lua

Crafting.GetInfo(recipe: string): table

A recipe's definition: { Key, Name, Skill?, Level, Xp, Seconds, Station?, Learned, Inputs = { { Item, Quantity } }, Outputs = { { Item, Quantity, Chance } }, Tools = { item keys } }. Unknown recipes raise an error.

Parameters

recipe (string): The Recipe row key.

Returns table

Example

lua

local recipe = Crafting.GetInfo("bronze_bar")
Log.Info(recipe.Name .. " takes " .. recipe.Seconds .. " s")

Crafting.Craft#

lua

Crafting.Craft(player: Entity, recipe: string, count?: integer, station?: Entity): boolean, string|integer?

Starts a batch of count crafts (each a timed action of the recipe's Seconds; OnCrafted per craft, OnActionEnded at the end). Checked at the start and again at each completion: the recipe known, the skill level, the inputs, the tools held, a station of the recipe's Station in range (without station the nearest), space for the outputs. Where the scene has authority: true, or false and why. On a client: a Craft request; true and its request id when sent (the server's answer carries the checks).

Parameters

player (Entity): The player character (on a client: one it controls).
recipe (string): The Recipe row key.
count? (integer): Crafts in the batch, in [1, 1,000] (default 1).
station? (Entity): The crafting station (default: the nearest in range).

Returns boolean, string|integer?

Example

lua

Crafting.Craft(player, "bronze_bar", 10, Scene.FindEntityByName("Furnace"))

Crowds#

Client crowds: the effect budgets, detail levels, the crowd observer and statistics (the scene's Crowds system, on clients and offline; on a dedicated server RequestEffect returns false and the other functions raise an error).

lua

if Crowds.RequestEffect({ Kind = "CombatText", Priority = "Own", Position = self.Entity.Position }) then ShowDamage(amount) end

Member	Kind	Summary
`Crowds.RequestEffect(request: { Kind: string, Priority?: string, Position?: Vec2, Prefab?: integer\|string, Particles?: integer, Velocity?: Vec2, Duration?: number, Source?: Entity }): boolean`	Function	Asks the frame's effect budgets for room for one effect: Kind "Emitter", "CombatText" or "Projectile"; Priority "Own" > "Target" > "Party" > "Others" (default), then the distance to the observer, decide who gets the room (Crowds.MaxEmitters, MaxParticles, MaxCombatTexts).
`Crowds.SetObserver(entity?: Entity)`	Function	The entity distances are measured from (the local player): animation level of detail, nameplate fading and effect ranks.
`Crowds.GetDetailLevel(entity: Entity): string`	Function	"Near", "Mid" or "Far": how much the crowds show of the entity (its distance to the observer against Crowds.NearDistance and MidDistance, and on clients the network's detail level of remote entities - the coarser).
Crowds.GetStats(): { Characters: integer, Animators: integer, AnimatorsFullRate: integer, AnimatorsHalfRate: integer, AnimatorsQuarterRate: integer, OffscreenAnimators: integer, Near: integer, Mid: integer, Far: integer, SpawnedEffects: integer, ActiveEmitters: integer, ActiveParticles: integer, CombatTexts: integer, EffectRequests: integer, EffectsAdmitted: integer, EffectsEvicted: integer, EffectsRefused: integer, DrawnCharacters: integer, LayerItems: integer, Nameplates: integer, NameplatesHidden: integer }	Function	What the crowds did in the last frame: characters and their animators by rate (level of detail), characters by detail level, effect budgets (counts since the scene started), and what the last rendered frame drew (zero where nothing renders).

Crowds.RequestEffect#

lua

Crowds.RequestEffect(request: { Kind: string, Priority?: string, Position?: Vec2, Prefab?: integer|string, Particles?: integer, Velocity?: Vec2, Duration?: number, Source?: Entity }): boolean

Asks the frame's effect budgets for room for one effect: Kind "Emitter", "CombatText" or "Projectile"; Priority "Own" > "Target" > "Party" > "Others" (default), then the distance to the observer, decide who gets the room (Crowds.MaxEmitters, MaxParticles, MaxCombatTexts). With a Prefab the visual is spawned at Position, moved by Velocity (projectiles), kept while its particles live (at most Duration seconds) and stopped early for requests of higher rank. Without one only room is reserved: show your visual when it returns true. Source names the entity the effect belongs to: an Others effect of a source in Far detail is refused before the budget. Returns false without an error where no crowd system runs (dedicated servers, edit mode: nothing is shown there); raises an error for invalid fields.

Parameters

request ({ Kind: string, Priority?: string, Position?: Vec2, Prefab?: integer|string, Particles?: integer, Velocity?: Vec2, Duration?: number, Source?: Entity })

Returns boolean

Example

lua

Crowds.RequestEffect({ Kind = "Emitter", Priority = "Target", Position = target.Position, Prefab = HitSpark, Particles = 40 })

Crowds.SetObserver#

lua

Crowds.SetObserver(entity?: Entity)

The entity distances are measured from (the local player): animation level of detail, nameplate fading and effect ranks. nil: the primary camera.

Parameters

entity? (Entity)

Example

lua

Crowds.SetObserver(self.Entity)

Crowds.GetDetailLevel#

lua

Crowds.GetDetailLevel(entity: Entity): string

"Near", "Mid" or "Far": how much the crowds show of the entity (its distance to the observer against Crowds.NearDistance and MidDistance, and on clients the network's detail level of remote entities - the coarser).

Parameters

entity (Entity)

Returns string

Example

lua

if Crowds.GetDetailLevel(npc) == "Far" then return end

Crowds.GetStats#

lua

Crowds.GetStats(): { Characters: integer, Animators: integer, AnimatorsFullRate: integer, AnimatorsHalfRate: integer, AnimatorsQuarterRate: integer, OffscreenAnimators: integer, Near: integer, Mid: integer, Far: integer, SpawnedEffects: integer, ActiveEmitters: integer, ActiveParticles: integer, CombatTexts: integer, EffectRequests: integer, EffectsAdmitted: integer, EffectsEvicted: integer, EffectsRefused: integer, DrawnCharacters: integer, LayerItems: integer, Nameplates: integer, NameplatesHidden: integer }

What the crowds did in the last frame: characters and their animators by rate (level of detail), characters by detail level, effect budgets (counts since the scene started), and what the last rendered frame drew (zero where nothing renders).

Returns { Characters: integer, Animators: integer, AnimatorsFullRate: integer, AnimatorsHalfRate: integer, AnimatorsQuarterRate: integer, OffscreenAnimators: integer, Near: integer, Mid: integer, Far: integer, SpawnedEffects: integer, ActiveEmitters: integer, ActiveParticles: integer, CombatTexts: integer, EffectRequests: integer, EffectsAdmitted: integer, EffectsEvicted: integer, EffectsRefused: integer, DrawnCharacters: integer, LayerItems: integer, Nameplates: integer, NameplatesHidden: integer }

Example

lua

local stats = Crowds.GetStats()
Log.Info(stats.Nameplates .. " nameplates")

Data#

Data tables (Assets/**/*.ftable with their .fschema schemas): typed rows by key, read-only, the same data the server and the tools use. A table or schema is named by its path ("Data/Weapons.ftable"), a schema's Name ("Weapon": every table of that schema and of the schemas derived from it, keys unique across them), a built-in alias ("Builtin/ItemSchema") or a handle. Tables hot-reload (OnDataReloaded).

lua

local sword = Data.Get("Weapon", "iron_sword")
for _, weapon in ipairs(Data.Rows("Weapon")) do
	Log.Info(weapon:GetKey())
end

Member	Kind	Summary
`Data.Get(tableOrSchema: string\|integer, key: string): DataRow?`	Function	The row with the key in a table, or in any table of a schema's family; nil when there is none.
`Data.Rows(tableOrSchema: string\|integer): DataRow[]`	Function	Every row of a table, or of every table of a schema's family (by table path, then by key), as a list to iterate with ipairs.
`Data.Count(tableOrSchema: string\|integer): integer`	Function	The number of rows of a table, or of every table of a schema's family.
`Data.Find(tableOrSchema: string\|integer, column: string, value: string\|number\|boolean): DataRow?`	Function	The first row (by table path, then key) whose column equals the value: a linear scan of every row, meant for tools and setup code, not for every frame.

Data.Get#

lua

Data.Get(tableOrSchema: string|integer, key: string): DataRow?

The row with the key in a table, or in any table of a schema's family; nil when there is none. An error for a name no loaded table or schema has.

Parameters

tableOrSchema (string|integer): A table or schema: path, schema Name, built-in alias or handle.
key (string): The row's key.

Returns DataRow?

Example

lua

local potion = Data.Get("Data/Potions.ftable", "potion_small")

Data.Rows#

lua

Data.Rows(tableOrSchema: string|integer): DataRow[]

Every row of a table, or of every table of a schema's family (by table path, then by key), as a list to iterate with ipairs. Builds one proxy per row: prefer Data.Get in code that runs every frame.

Parameters

tableOrSchema (string|integer): A table or schema.

Returns DataRow[]

Example

lua

for _, row in ipairs(Data.Rows("Weapon")) do
	total = total + row.Damage
end

Data.Count#

lua

Data.Count(tableOrSchema: string|integer): integer

The number of rows of a table, or of every table of a schema's family.

Parameters

tableOrSchema (string|integer): A table or schema.

Returns integer

Example

lua

Log.Info(Data.Count("Item") .. " items")

Data.Find#

lua

Data.Find(tableOrSchema: string|integer, column: string, value: string|number|boolean): DataRow?

The first row (by table path, then key) whose column equals the value: a linear scan of every row, meant for tools and setup code, not for every frame. Enum columns compare their value names, Ref columns their row keys, Asset columns handles; struct fields are named "Struct.Field". List, Struct, Color and Vec2 columns cannot be compared.

Parameters

tableOrSchema (string|integer): A table or schema.
column (string): The column ("Rolls.Min" for a struct field).
value (string|number|boolean): The value to look for.

Returns DataRow?

Example

lua

local legendary = Data.Find("Item", "Quality", "legendary")

Debug#

Debugging helpers. Log, LogWarning and LogError are aliases of Log.Info, Log.Warn and Log.Error; the renderer adds debug drawing functions to this namespace.

lua

Debug.Log("velocity", velocity)

Member	Kind	Summary
`Debug.Log(...: any)`	Function	Same as Log.Info.
`Debug.LogWarning(...: any)`	Function	Same as Log.Warn.
`Debug.LogError(...: any)`	Function	Same as Log.Error.
`Debug.DrawLine(from: Vec2, to: Vec2, color?: Color, options?: number\|table)`	Function	Draws a line from `from` to `to` (world positions; screen pixels with ScreenSpace) in color (default white).
`Debug.DrawArrow(from: Vec2, to: Vec2, color?: Color, options?: number\|table)`	Function	Draws an arrow from `from` to `to` with its head at `to`.
`Debug.DrawRect(center: Vec2, size: Vec2, color?: Color, options?: number\|table)`	Function	Draws the outline of a rectangle of `size` centered on `center`.
`Debug.DrawCircle(center: Vec2, radius: number, color?: Color, options?: number\|table)`	Function	Draws a circle outline (a ring the thickness wide) of `radius` around `center`.
`Debug.DrawCapsule(from: Vec2, to: Vec2, radius: number, color?: Color, options?: number\|table)`	Function	Draws the outline of a capsule: the segment from `from` to `to` with round ends `radius` around it.
`Debug.DrawPolygon(points: Vec2[], color?: Color, options?: number\|table): boolean`	Function	Draws the closed outline of the polygon through 3 to 4096 points.
`Debug.DrawPolyline(points: Vec2[], color?: Color, options?: number\|table)`	Function	Draws connected segments through 2 to 4096 points with round joints.
`Debug.DrawPoint(position: Vec2, color?: Color, options?: number\|table)`	Function	Draws a dot at position, Size screen pixels wide (option, default 6) at every zoom.
`Debug.DrawCross(position: Vec2, size: number, color?: Color, options?: number\|table)`	Function	Draws an axis-aligned cross `size` wide (world units; pixels with ScreenSpace) centered on position.
`Debug.DrawText(position: Vec2, text: string, color?: Color, options?: number\|table): boolean`	Function	Draws text centered on position (at most 4096 bytes of UTF-8) with a thin dark outline, in the engine's default font.

Debug.Log#

lua

Debug.Log(...: any)

Same as Log.Info.

Parameters

...? (any)

Debug.LogWarning#

lua

Debug.LogWarning(...: any)

Same as Log.Warn.

Parameters

...? (any)

Debug.LogError#

lua

Debug.LogError(...: any)

Same as Log.Error.

Parameters

...? (any)

Debug.DrawLine#

lua

Debug.DrawLine(from: Vec2, to: Vec2, color?: Color, options?: number|table)

Draws a line from from to to (world positions; screen pixels with ScreenSpace) in color (default white). Shapes appear in the next rendered frame, over the scene, and stay until their duration has passed (one frame by default); they go away when the scene stops. options is the duration in seconds or a table of: Duration (seconds, 0 to 1000000, default 0 = one frame), Thickness (default 2), PixelUnits (thickness in screen pixels, default true; false = world units), ScreenSpace (positions and sizes in pixels of each view's output, origin top-left, +Y down; default false), DepthTest (sorted with the scene by Layer, OrderInLayer and Z instead of drawn on top; default false), Layer (render layer 0-31, default 0: views whose culling mask leaves it out do not show the shape), OrderInLayer, Z (-1000000 to 1000000). Unknown options raise an error. Engines that do not render (dedicated servers, headless runs) draw nothing.

Parameters

from (Vec2)
to (Vec2)
color? (Color)
options? (number|table): The duration in seconds, or a table of options.

Example

lua

Debug.DrawLine(self.Entity.Position, target.Position, Color.Red)
Debug.DrawLine(Vec2(0, 0), Vec2(5, 0), Color.Green, { Duration = 2, Thickness = 4 })

Debug.DrawArrow#

lua

Debug.DrawArrow(from: Vec2, to: Vec2, color?: Color, options?: number|table)

Draws an arrow from from to to with its head at to. Options as for DrawLine, plus HeadLength and HeadWidth (in the units of the thickness; 0 = 4 x and 3 x the thickness, the default).

Parameters

from (Vec2)
to (Vec2)
color? (Color)
options? (number|table)

Example

lua

Debug.DrawArrow(position, position + velocity, Color.Yellow)

Debug.DrawRect#

lua

Debug.DrawRect(center: Vec2, size: Vec2, color?: Color, options?: number|table)

Draws the outline of a rectangle of size centered on center. Options as for DrawLine, plus Rotation (radians, counter-clockwise around the center, -1000000 to 1000000) and Filled (draws the filled rectangle instead). Negative sizes raise an error.

Parameters

center (Vec2)
size (Vec2)
color? (Color)
options? (number|table)

Example

lua

Debug.DrawRect(self.Entity.Position, Vec2(2, 1), Color.Cyan, { Filled = true, Duration = 0.5 })

Debug.DrawCircle#

lua

Debug.DrawCircle(center: Vec2, radius: number, color?: Color, options?: number|table)

Draws a circle outline (a ring the thickness wide) of radius around center. Options as for DrawLine, plus Filled (draws a disc instead).

Parameters

center (Vec2)
radius (number)
color? (Color)
options? (number|table)

Example

lua

Debug.DrawCircle(self.Entity.Position, self.AttackRange, Color.Red)

Debug.DrawCapsule#

lua

Debug.DrawCapsule(from: Vec2, to: Vec2, radius: number, color?: Color, options?: number|table)

Draws the outline of a capsule: the segment from from to to with round ends radius around it. Options as for DrawLine, plus Filled.

Parameters

from (Vec2)
to (Vec2)
radius (number)
color? (Color)
options? (number|table)

Example

lua

Debug.DrawCapsule(Vec2(0, -0.5), Vec2(0, 0.5), 0.25, Color.Green)

Debug.DrawPolygon#

lua

Debug.DrawPolygon(points: Vec2[], color?: Color, options?: number|table): boolean

Draws the closed outline of the polygon through 3 to 4096 points. Options as for DrawLine, plus Filled (a filled simple polygon, convex or concave, any winding). Returns whether it is drawn: false for a filled polygon that is degenerate or self-intersecting, and when the scene is not drawn.

Parameters

points (Vec2[])
color? (Color)
options? (number|table)

Returns boolean

Example

lua

Debug.DrawPolygon({ Vec2(0, 0), Vec2(2, 0), Vec2(1, 1.5) }, Color.Magenta, { Filled = true })

Debug.DrawPolyline#

lua

Debug.DrawPolyline(points: Vec2[], color?: Color, options?: number|table)

Draws connected segments through 2 to 4096 points with round joints. Options as for DrawLine, plus Closed (also connects the last point to the first).

Parameters

points (Vec2[])
color? (Color)
options? (number|table)

Example

lua

Debug.DrawPolyline(self.Path, Color.White, { Duration = 1 })

Debug.DrawPoint#

lua

Debug.DrawPoint(position: Vec2, color?: Color, options?: number|table)

Draws a dot at position, Size screen pixels wide (option, default 6) at every zoom. Other options as for DrawLine.

Parameters

position (Vec2)
color? (Color)
options? (number|table)

Example

lua

Debug.DrawPoint(hit.Point, Color.Red, { Size = 10, Duration = 1 })

Debug.DrawCross#

lua

Debug.DrawCross(position: Vec2, size: number, color?: Color, options?: number|table)

Draws an axis-aligned cross size wide (world units; pixels with ScreenSpace) centered on position. Options as for DrawLine.

Parameters

position (Vec2)
size (number)
color? (Color)
options? (number|table)

Example

lua

Debug.DrawCross(self.Target, 0.5, Color.Yellow)

Debug.DrawText#

lua

Debug.DrawText(position: Vec2, text: string, color?: Color, options?: number|table): boolean

Draws text centered on position (at most 4096 bytes of UTF-8) with a thin dark outline, in the engine's default font. options is the duration in seconds or a table of: Duration (seconds, default 0 = one frame), Size (em size: world units, default 0.5; pixels with ScreenSpace, default 16), Layer (render layer 0-31, default 31, drawn at the highest order of the layer; ignored with ScreenSpace) and ScreenSpace (default false). World text is drawn with the scene's sprites, not in the overlay of the debug shapes: views whose culling mask leaves its layer out do not show it, and the fog of war and the camera's post-processing (bloom, color grading, vignette) apply to it like to any sprite. ScreenSpace text is placed in framebuffer pixels of the screen (origin top-left, +Y down, like Input.GetMousePosition and Camera.WorldToScreen) and drawn over the screen UI, untouched by culling masks, fog and post-processing. Returns whether the text is queued: false when the engine draws no text (dedicated servers, headless runs; ScreenSpace also without UI rendering) and when 1024 debug texts are already queued (until some expire).

Parameters

position (Vec2)
text (string)
color? (Color)
options? (number|table)

Returns boolean

Example

lua

Debug.DrawText(self.Entity.Position + Vec2(0, 1), "HP " .. self.Health, Color.White, { Size = 0.3 })
Debug.DrawText(Vec2(80, 24), "FPS " .. math.floor(1 / Time.UnscaledDeltaTime), Color.Yellow, { ScreenSpace = true })

Dialogue#

Conversations of player characters with NPCs (.fdialogue assets), run by the scene's Quests system: one per player. Line and Choice nodes wait for the player, the others run at once; distance, Quests.DialogueTimeoutSeconds and End nodes end them. On a client GetCurrent answers for the local character from the RPG lane and changes are refused.

lua

Dialogue.Start(player, npc)
local node = Dialogue.GetCurrent(player)
Dialogue.Choose(player, node.Options[1].Index)

Member	Kind	Summary
`Dialogue.Start(player: Entity, npc?: Entity, dialogue?: string\|integer): boolean, string?`	Function	Starts a conversation (a running one ends): the dialogue asset given, else the NPC's Interactable.Dialogue.
`Dialogue.StartById(player: Entity, npc: Entity?, id: string): boolean, string?`	Function	Starts the dialogue with this Id (of the RPG database's loaded dialogues).
`Dialogue.Choose(player: Entity, option: integer): boolean, string?`	Function	Chooses an option of the current Choice node (an Index of GetCurrent's Options); an option the player is not shown is refused (InvalidOption).
`Dialogue.Continue(player: Entity): boolean, string?`	Function	Continues past the current Line node.
`Dialogue.End(player: Entity)`	Function	Ends the player's conversation (OnDialogueEnded(npc, "Player")).
`Dialogue.GetCurrent(player: Entity): table?`	Function	The node the conversation waits at: { Npc?, Dialogue, Node, Kind ("Line" or "Choice"), Speaker, Text, Options = { { Index, Text } } } with {Player}, {Npc} and {Flag:Key} substituted; nil without a conversation.
`Dialogue.GetFlag(player: Entity, key: string): integer`	Function	A dialogue flag of the character (0 when unset).
`Dialogue.SetFlag(player: Entity, key: string, value: integer): boolean, string?`	Function	Sets a dialogue flag of the character (persisted, at most 512 per character; Flag.Is conditions read them).

Dialogue.Start#

lua

Dialogue.Start(player: Entity, npc?: Entity, dialogue?: string|integer): boolean, string?

Starts a conversation (a running one ends): the dialogue asset given, else the NPC's Interactable.Dialogue. The NPC must be within its Interactable's Range.

Parameters

player (Entity): The player character.
npc? (Entity): Who speaks (nil: nobody, the dialogue alone).
dialogue? (string|integer): A .fdialogue asset (path or handle; default the NPC's).

Returns boolean, string?

Example

lua

Dialogue.Start(player, npc)

Dialogue.StartById#

lua

Dialogue.StartById(player: Entity, npc: Entity?, id: string): boolean, string?

Starts the dialogue with this Id (of the RPG database's loaded dialogues).

Parameters

player (Entity): The player character.
npc (Entity?): Who speaks (nil: nobody).
id (string): The dialogue's Id.

Returns boolean, string?

Example

lua

Dialogue.StartById(player, nil, "D_Intro")

Dialogue.Choose#

lua

Dialogue.Choose(player: Entity, option: integer): boolean, string?

Chooses an option of the current Choice node (an Index of GetCurrent's Options); an option the player is not shown is refused (InvalidOption).

Parameters

player (Entity): The player character.
option (integer): The option's Index (from 1).

Returns boolean, string?

Example

lua

Dialogue.Choose(player, 2)

Dialogue.Continue#

lua

Dialogue.Continue(player: Entity): boolean, string?

Continues past the current Line node.

Parameters

player (Entity): The player character.

Returns boolean, string?

Example

lua

Dialogue.Continue(player)

Dialogue.End#

lua

Dialogue.End(player: Entity)

Ends the player's conversation (OnDialogueEnded(npc, "Player")).

Parameters

player (Entity): The player character.

Example

lua

Dialogue.End(player)

Dialogue.GetCurrent#

lua

Dialogue.GetCurrent(player: Entity): table?

The node the conversation waits at: { Npc?, Dialogue, Node, Kind ("Line" or "Choice"), Speaker, Text, Options = { { Index, Text } } } with {Player}, {Npc} and {Flag:Key} substituted; nil without a conversation. On a client: the local character's conversation from the RPG lane, without Dialogue (Kind is "Choice" when the node offers options); nil for anyone else.

Parameters

player (Entity): The player character.

Returns table?

Example

lua

local node = Dialogue.GetCurrent(player)
if node then text:GetComponent("UIText"):SetText(node.Text) end

Dialogue.GetFlag#

lua

Dialogue.GetFlag(player: Entity, key: string): integer

A dialogue flag of the character (0 when unset).

Parameters

player (Entity): The player character.
key (string): The flag's key.

Returns integer

Example

lua

if Dialogue.GetFlag(player, "MetCaptain") ~= 0 then ... end

Dialogue.SetFlag#

lua

Dialogue.SetFlag(player: Entity, key: string, value: integer): boolean, string?

Sets a dialogue flag of the character (persisted, at most 512 per character; Flag.Is conditions read them).

Parameters

player (Entity): The player character.
key (string): The flag's key.
value (integer): Its value.

Returns boolean, string?

Example

lua

Dialogue.SetFlag(player, "MetCaptain", 1)

Effects#

Status effects (the StatusEffect table's rows): buffs, debuffs, auras, shields and periodic effects with their stacking rules. Servers apply and remove them; a client reads its own character's effects (its owner section) and the visible effects of others (Rpg.GetEffects).

lua

Effects.Apply(target, "Burning", self.Entity)

Member	Kind	Summary
`Effects.Apply(target: Entity, effect: string, caster?: Entity, stacks?: integer): integer`	Function	Applies a status effect by its Stacking rule (Refresh, Extend, Stack, PerCaster, Replace) with `stacks` stacks (default 1): its modifiers, states, absorb, periodic ticks and aura start; OnEffectApplied follows on the target's script.
`Effects.Remove(target: Entity, effect: string): integer`	Function	Removes every instance of the effect from the target; returns how many.
`Effects.RemoveInstance(target: Entity, id: integer): boolean`	Function	Removes one instance (an id of Effects.Apply or Effects.GetAll); false when it already ended.
`Effects.Dispel(target: Entity, type: string, count?: integer): integer`	Function	Removes up to `count` effects (0 or nil: all) whose Dispel type is `type` ("Magic", "Poison", ...), the most recent first; returns how many.
`Effects.Has(entity: Entity, effect: string, minStacks?: integer): boolean`	Function	Whether the entity has the effect with at least `minStacks` stacks (default 1).
`Effects.GetAll(entity: Entity): { { Effect: string?, EffectHash: integer, Stacks: integer, Remaining: number, Duration: number, Caster: Entity?, Instance: integer } }`	Function	Every status effect of the entity, hidden ones included (servers also give Kind, Absorb and FromAura).

Effects.Apply#

lua

Effects.Apply(target: Entity, effect: string, caster?: Entity, stacks?: integer): integer

Applies a status effect by its Stacking rule (Refresh, Extend, Stack, PerCaster, Replace) with stacks stacks (default 1): its modifiers, states, absorb, periodic ticks and aura start; OnEffectApplied follows on the target's script. Returns the instance's id (Effects.RemoveInstance). Raises an error when it is refused (an immune target, a pacified caster of a harmful effect, a dead target, an unknown effect). Servers only.

Parameters

target (Entity)
effect (string)
caster? (Entity)
stacks? (integer)

Returns integer

Example

lua

local id = Effects.Apply(target, "Burning", self.Entity)

Effects.Remove#

lua

Effects.Remove(target: Entity, effect: string): integer

Removes every instance of the effect from the target; returns how many. Servers only.

Parameters

target (Entity)
effect (string)

Returns integer

Example

lua

Effects.Remove(self.Entity, "Burning")

Effects.RemoveInstance#

lua

Effects.RemoveInstance(target: Entity, id: integer): boolean

Removes one instance (an id of Effects.Apply or Effects.GetAll); false when it already ended. Servers only.

Parameters

target (Entity)
id (integer)

Returns boolean

Example

lua

Effects.RemoveInstance(target, self.ShieldId)

Effects.Dispel#

lua

Effects.Dispel(target: Entity, type: string, count?: integer): integer

Removes up to count effects (0 or nil: all) whose Dispel type is type ("Magic", "Poison", ...), the most recent first; returns how many. Servers only.

Parameters

target (Entity)
type (string)
count? (integer)

Returns integer

Example

lua

Effects.Dispel(ally, "Magic", 1)

Effects.Has#

lua

Effects.Has(entity: Entity, effect: string, minStacks?: integer): boolean

Whether the entity has the effect with at least minStacks stacks (default 1). Clients know their own character's effects and the visible effects of others.

Parameters

entity (Entity)
effect (string)
minStacks? (integer)

Returns boolean

Example

lua

if Effects.Has(self.Entity, "Frenzy", 3) then self:Roar() end

Effects.GetAll#

lua

Effects.GetAll(entity: Entity): { { Effect: string?, EffectHash: integer, Stacks: integer, Remaining: number, Duration: number, Caster: Entity?, Instance: integer } }

Every status effect of the entity, hidden ones included (servers also give Kind, Absorb and FromAura). Clients: their own character's effects section, the visible effects of other entities.

Parameters

entity (Entity)

Returns { { Effect: string?, EffectHash: integer, Stacks: integer, Remaining: number, Duration: number, Caster: Entity?, Instance: integer } }

Example

lua

for _, effect in ipairs(Effects.GetAll(self.Entity)) do Log.Info(effect.Effect) end

Equipment#

What characters wear (EquipSlot rows): equipping applies the item's modifiers and its appearance layer; two-handed items keep the slot they block empty. Changes return true, or false and the reason.

lua

Equipment.Equip(player, 1)
local weapon = Equipment.GetItem(player, "main_hand")

Member	Kind	Summary
`Equipment.Equip(actor: Entity, slot: integer, equipSlot?: string): boolean, string?`	Function	Equips the item of a backpack slot into its slot (or equipSlot); the slot's item goes back to the backpack.
`Equipment.Unequip(actor: Entity, equipSlot: string): boolean, string?`	Function	Moves the item of an equipment slot into the backpack's first free slot.
`Equipment.GetItem(actor: Entity, equipSlot: string): table?`	Function	The item table worn in an equipment slot; nil when it is empty or not a slot.
`Equipment.GetSlots(actor: Entity): table`	Function	Every worn item by EquipSlot key ({ main_hand = { Key = ...

Equipment.Equip#

lua

Equipment.Equip(actor: Entity, slot: integer, equipSlot?: string): boolean, string?

Equips the item of a backpack slot into its slot (or equipSlot); the slot's item goes back to the backpack.

Parameters

actor (Entity): The character.
slot (integer): The backpack slot, from 1.
equipSlot? (string): An EquipSlot key (default the best fit).

Returns boolean, string?

Example

lua

Equipment.Equip(player, 1, "ring_2")

Equipment.Unequip#

lua

Equipment.Unequip(actor: Entity, equipSlot: string): boolean, string?

Moves the item of an equipment slot into the backpack's first free slot.

Parameters

actor (Entity): The character.
equipSlot (string): The EquipSlot key.

Returns boolean, string?

Example

lua

Equipment.Unequip(player, "head")

Equipment.GetItem#

lua

Equipment.GetItem(actor: Entity, equipSlot: string): table?

The item table worn in an equipment slot; nil when it is empty or not a slot.

Parameters

actor (Entity): The character.
equipSlot (string): The EquipSlot key.

Returns table?

Example

lua

local helmet = Equipment.GetItem(player, "head")

Equipment.GetSlots#

lua

Equipment.GetSlots(actor: Entity): table

Every worn item by EquipSlot key ({ main_hand = { Key = ... }, ... }). On a client: the local character's, from the RPG lane; empty for anyone else.

Parameters

actor (Entity): The character.

Returns table

Example

lua

for slot, item in pairs(Equipment.GetSlots(player)) do Log.Info(slot .. ": " .. item.Key) end

Factions#

Factions (the Faction table's rows): who an actor belongs to, how factions stand towards each other and who may attack whom.

lua

if Factions.Get(npc) == "guards" then self:Salute() end

Member	Kind	Summary
`Factions.Get(entity: Entity): string?`	Function	The actor's faction key (RpgActor.Faction, else its template's or class's); nil without one.
`Factions.GetRelation(from: string, to: string): string`	Function	How members of faction `from` stand towards members of `to` in the faction matrix (Faction.Relations, else its Default): "Hostile", "Unfriendly", "Neutral", "Friendly" or "Allied".
`Factions.CanAttack(attacker: Entity, target: Entity): boolean`	Function	Whether the attacker may harm the target: their relation (factions, reputation tiers), PvP flags and the PvPVolume mode at the target's position.
`Factions.GetTeam(faction: string): integer`	Function	The faction's Team (0-31): the Perceptible.Team its actors get, which NPC perception filters by.
`Factions.GetAll(): { { Key: string, Name: string, Team: integer, Hidden: boolean, Reputation: boolean } }`	Function	Every faction of the RPG database (Reputation: players earn standing with it; Hidden: not shown in reputation UIs).

Factions.Get#

lua

Factions.Get(entity: Entity): string?

The actor's faction key (RpgActor.Faction, else its template's or class's); nil without one.

Parameters

entity (Entity)

Returns string?

Example

lua

local faction = Factions.Get(self.Entity)

Factions.GetRelation#

lua

Factions.GetRelation(from: string, to: string): string

How members of faction from stand towards members of to in the faction matrix (Faction.Relations, else its Default): "Hostile", "Unfriendly", "Neutral", "Friendly" or "Allied". Raises an error for unknown factions.

Parameters

from (string)
to (string)

Returns string

Example

lua

Log.Info(Factions.GetRelation("guards", "goblins"))

Factions.CanAttack#

lua

Factions.CanAttack(attacker: Entity, target: Entity): boolean

Whether the attacker may harm the target: their relation (factions, reputation tiers), PvP flags and the PvPVolume mode at the target's position. Servers only (clients estimate with Rpg.GetRelation).

Parameters

attacker (Entity)
target (Entity)

Returns boolean

Example

lua

if Factions.CanAttack(self.Entity, other) then self:Attack(other) end

Factions.GetTeam#

lua

Factions.GetTeam(faction: string): integer

The faction's Team (0-31): the Perceptible.Team its actors get, which NPC perception filters by.

Parameters

faction (string)

Returns integer

Example

lua

local team = Factions.GetTeam("goblins")

Factions.GetAll#

lua

Factions.GetAll(): { { Key: string, Name: string, Team: integer, Hidden: boolean, Reputation: boolean } }

Every faction of the RPG database (Reputation: players earn standing with it; Hidden: not shown in reputation UIs).

Returns { { Key: string, Name: string, Team: integer, Hidden: boolean, Reputation: boolean } }

Example

lua

for _, faction in ipairs(Factions.GetAll()) do Log.Info(faction.Name) end

Features#

Feature flags (Assets/Live/Features.json): switch features on and off per realm, shard or zone, roll them out to a percentage of accounts and change them at run time without a restart (content.set-flag; the coordinator pushes the change to every zone, applied at the next tick). The same account gets the same answer on every zone.

lua

if Features.IsEnabled("Events.Halloween") then
	self:SpawnPumpkins()
end
if Features.IsEnabled("NewQuestLog", player) then
	UI.SetVisible(self.NewLog, true)
end

Member	Kind	Summary
`Features.IsEnabled(name: string, player?: integer\|Entity): boolean`	Function	Whether the flag is on here (this realm, shard and zone, with the coordinator's runtime overrides).
`Features.GetAll(): table`	Function	Every flag as { Name, Enabled, RolloutPercent, ClientVisible, Overridden, Description }, sorted by name (debug screens, admin tools).

Features.IsEnabled#

lua

Features.IsEnabled(name: string, player?: integer|Entity): boolean

Whether the flag is on here (this realm, shard and zone, with the coordinator's runtime overrides). With player (an account id, or a player's character entity) a partial rollout decides by the account; without it, whether the flag is on at all. A flag the data does not declare is off. Connected clients receive the server's ClientVisible flags at tick boundaries; server-only flags are omitted from that snapshot. In the services' Lua host (Assets/Services/*.lua) the flags are the data's, resolved for the realm.

Parameters

name (string): The flag's name in Assets/Live/Features.json.
player? (integer|Entity): An account id or a player's Entity (optional).

Returns boolean

Example

lua

if Features.IsEnabled("DoubleXp", player) then xp = xp * 2 end

Features.GetAll#

lua

Features.GetAll(): table

Every flag as { Name, Enabled, RolloutPercent, ClientVisible, Overridden, Description }, sorted by name (debug screens, admin tools). Overridden is true while a runtime override (content.set-flag) applies.

Returns table

FogOfWar#

The scene's fog of war: a grid of cells over the world defined by the FogOfWar component with the smallest entity id (GridOrigin, GridSize in cells, CellSize, InitiallyHidden). Cells are Hidden, Explored or Visible; positions and radii are world units relative to the scene origin, cells are (x, y) from the grid's bottom-left cell (0, 0). Changes to the component apply at once (a new size or initial state rebuilds the grid). Without a FogOfWar component the queries report nothing and the changes do nothing. A typical update hides what was visible, then reveals the current sight circles every frame.

lua

function Player:OnUpdate(dt)
	FogOfWar.HideAll()
	FogOfWar.Reveal(self.Entity.Position, self.SightRadius)
end

Member	Kind	Summary
`FogOfWar.HasGrid(): boolean`	Function	True when the scene has a fog grid (a FogOfWar component with a usable size).
`FogOfWar.GetGridSize(): integer, integer`	Function	The number of cells along X and Y (0, 0 without a grid).
`FogOfWar.Reveal(center: Vec2, radius: number): integer`	Function	Makes every cell whose center lies within radius of center Visible (and so explored).
`FogOfWar.Hide(center: Vec2, radius: number): integer`	Function	Visible cells whose centers lie within the circle become Explored (no longer seen).
`FogOfWar.HideAll(): integer`	Function	Every Visible cell becomes Explored (call it before revealing this frame's sight circles).
`FogOfWar.Clear()`	Function	Puts every cell back into the component's initial state: Hidden, or Visible when InitiallyHidden is off.
`FogOfWar.SetCell(x: integer, y: integer, state: FogCellState): boolean`	Function	Sets the state of cell (x, y).
`FogOfWar.GetCellState(x: integer, y: integer): FogCellState`	Function	The state of cell (x, y); Hidden outside the grid and without one.
`FogOfWar.WorldToCell(position: Vec2): integer?, integer?`	Function	The cell (x, y) containing a world position, or nil, nil outside the grid and without one.
`FogOfWar.IsVisible(position: Vec2): boolean`	Function	Whether the cell at a world position is Visible now.
`FogOfWar.IsExplored(position: Vec2): boolean`	Function	Whether the cell at a world position was ever seen (Explored or Visible).
`FogOfWar.ExploredOpacity: number`	Property	Opacity of explored cells relative to hidden ones, in [0, 1] (0 = explored cells are clear, 1 = as dark as hidden ones; default 0.5).

FogOfWar.HasGrid#

lua

FogOfWar.HasGrid(): boolean

True when the scene has a fog grid (a FogOfWar component with a usable size).

Returns boolean

FogOfWar.GetGridSize#

lua

FogOfWar.GetGridSize(): integer, integer

The number of cells along X and Y (0, 0 without a grid).

Returns integer, integer

FogOfWar.Reveal#

lua

FogOfWar.Reveal(center: Vec2, radius: number): integer

Makes every cell whose center lies within radius of center Visible (and so explored). Returns the number of cells that changed. A negative or non-finite radius raises an error.

Parameters

center (Vec2)
radius (number)

Returns integer

Example

lua

FogOfWar.Reveal(self.Entity.Position, 6)

FogOfWar.Hide#

lua

FogOfWar.Hide(center: Vec2, radius: number): integer

Visible cells whose centers lie within the circle become Explored (no longer seen). Returns the number of cells that changed.

Parameters

center (Vec2)
radius (number)

Returns integer

FogOfWar.HideAll#

lua

FogOfWar.HideAll(): integer

Every Visible cell becomes Explored (call it before revealing this frame's sight circles). Returns the number of cells that changed.

Returns integer

FogOfWar.Clear#

lua

FogOfWar.Clear()

Puts every cell back into the component's initial state: Hidden, or Visible when InitiallyHidden is off.

FogOfWar.SetCell#

lua

FogOfWar.SetCell(x: integer, y: integer, state: FogCellState): boolean

Sets the state of cell (x, y). Returns false outside the grid or without one.

Parameters

x (integer)
y (integer)
state (FogCellState)

Returns boolean

Example

lua

FogOfWar.SetCell(0, 0, FogCellState.Explored)

FogOfWar.GetCellState#

lua

FogOfWar.GetCellState(x: integer, y: integer): FogCellState

The state of cell (x, y); Hidden outside the grid and without one.

Parameters

x (integer)
y (integer)

Returns FogCellState

FogOfWar.WorldToCell#

lua

FogOfWar.WorldToCell(position: Vec2): integer?, integer?

The cell (x, y) containing a world position, or nil, nil outside the grid and without one.

Parameters

position (Vec2)

Returns integer?, integer?

Example

lua

local x, y = FogOfWar.WorldToCell(Camera.ScreenToWorld(Input.GetMousePosition()))

FogOfWar.IsVisible#

lua

FogOfWar.IsVisible(position: Vec2): boolean

Whether the cell at a world position is Visible now. False outside the grid.

Parameters

position (Vec2)

Returns boolean

Example

lua

if FogOfWar.IsVisible(enemy.Position) then enemy:GetComponent("SpriteRenderer").Color = Color.White end

FogOfWar.IsExplored#

lua

FogOfWar.IsExplored(position: Vec2): boolean

Whether the cell at a world position was ever seen (Explored or Visible). False outside the grid.

Parameters

position (Vec2)

Returns boolean

FogOfWar.ExploredOpacity#

lua

FogOfWar.ExploredOpacity: number

Opacity of explored cells relative to hidden ones, in [0, 1] (0 = explored cells are clear, 1 = as dark as hidden ones; default 0.5). Assigned values are clamped; non-finite values raise an error.

Example

lua

FogOfWar.ExploredOpacity = 0.7

Friends#

Friends and ignore lists, per character or per account as the game's Social.json says. Results arrive as OnServiceResult, friends' presence changes as OnPresenceChanged.

lua

self.FriendsRequest = Friends.Get()
Friends.Add("Merlin")

Member	Kind	Summary
`Friends.Get(): integer?, string?`	Function	The friends and ignore lists: OnServiceResult's result has Friends and Ignored, lists of { CharacterId, Name, Status ("Online", "Away", "Busy", "Offline"), Zone (when the friend shows it), Note, Mutual }.
`Friends.Add(name: string): integer?, string?`	Function	Adds a character by name; the result's Friend is the new entry.
`Friends.Remove(characterId: integer): integer?, string?`	Function	Removes a friend.
`Friends.Ignore(name: string): integer?, string?`	Function	Ignores a character: its whispers are answered as if you were offline, its messages and invitations no longer reach you.
`Friends.Unignore(characterId: integer): integer?, string?`	Function	Stops ignoring a character.

Friends.Get#

lua

Friends.Get(): integer?, string?

The friends and ignore lists: OnServiceResult's result has Friends and Ignored, lists of { CharacterId, Name, Status ("Online", "Away", "Busy", "Offline"), Zone (when the friend shows it), Note, Mutual }.

Returns integer?, string?

Friends.Add#

lua

Friends.Add(name: string): integer?, string?

Adds a character by name; the result's Friend is the new entry. Unknown and private names are answered alike ("notFound"); "quotaExceeded" beyond MaxFriends or the lookup rate.

Parameters

name (string)

Returns integer?, string?

Friends.Remove#

lua

Friends.Remove(characterId: integer): integer?, string?

Removes a friend.

Parameters

characterId (integer)

Returns integer?, string?

Friends.Ignore#

lua

Friends.Ignore(name: string): integer?, string?

Ignores a character: its whispers are answered as if you were offline, its messages and invitations no longer reach you. The result's Friend names the ignored character.

Parameters

name (string)

Returns integer?, string?

Friends.Unignore#

lua

Friends.Unignore(characterId: integer): integer?, string?

Stops ignoring a character.

Parameters

characterId (integer)

Returns integer?, string?

Gateway#

The MMO login flow: connect to the realm's gateway through the secure channel against the game's pinned gateway keys (Project Settings > Network > Gateway), create an account, log in, pick a realm and a character, and enter the world. Every request returns an id at once; its outcome arrives as OnGatewayResult(requestId, ok, result) on every script of the scene, where result is { Kind, Code, Message, RetryAfterMs, Data }. EnterWorld's grant connects the game to the zone with a one-time session token, then the zone connection takes over (OnClientConnected). The backend's service scripts use SetQueuePriority.

lua

Gateway.Connect()
function Menu:OnGatewayConnected()
    self.Login = Gateway.Login(self.Name, self.Password)
end

Member	Kind	Summary
`Gateway.Connect(address?: string, options?: table): boolean, string?`	Function	Starts connecting to the gateway at "host:port" (default: the project's Network > Gateway > Address) and opens the secure channel; the gateway must prove it holds one of the pinned keys (the project's Gateway keys, or options.Keys), so a password never reaches an impostor.
`Gateway.CreateAccount(name: string, password: string, email?: string): integer`	Function	Creates an account (login names: 3-64 ASCII letters, digits and ._-@+, case-insensitive; passwords: the realm's policy, 10-256 bytes by default).
`Gateway.Login(name: string, password: string, code?: string): integer`	Function	Logs in.
`Gateway.GetRealms(): integer`	Function	Requests the realm list.
`Gateway.GetCharacters(realm: string): integer`	Function	Requests the account's characters in a realm (logged in).
`Gateway.GetCharacterTemplate(): table?`	Function	The project's character template (Assets/Accounts/CharacterTemplate.json) for the character creation screen: { Name = { MinLength, MaxLength, Allowed, Reserved }, Fields = { { Name, Options, Visible }, ...
`Gateway.CreateCharacter(realm: string, name: string, fields: table): integer`	Function	Creates a character (logged in): fields maps the template's field names to chosen options ({ Class = "Mage" }).
`Gateway.DeleteCharacter(id: integer): integer`	Function	Deletes one of the account's characters (logged in, not queued).
`Gateway.EnterWorld(id: integer): integer`	Function	Enters the world with a listed character.
`Gateway.LeaveQueue()`	Function	Gives up waiting in a realm queue: the waiting EnterWorld is answered ("unavailable").
`Gateway.Logout(): integer`	Function	Logs out and stays connected (back to the login screen): a queued EnterWorld is answered, listed characters are forgotten.
`Gateway.Disconnect()`	Function	Closes the gateway connection (no OnGatewayDisconnected for it); pending requests are answered "unavailable".
`Gateway.GetState(): string`	Function	"Disconnected", "Connecting" (transport and secure channel), "Connected" (log in or create an account), "LoggedIn", "Queued" (waiting for a realm slot) or "Entering" (granted: the zone connection takes over).
`Gateway.SetQueuePriority(fn?: function): function?`	Function	Backend service scripts (Assets/Services/*.lua on FrostServices): ranks realm queue entries with fn(account, roles, character, realm) -> number (higher is admitted first, equal ones in arrival order; an error ranks 0).

Gateway.Connect#

lua

Gateway.Connect(address?: string, options?: table): boolean, string?

Starts connecting to the gateway at "host:port" (default: the project's Network > Gateway > Address) and opens the secure channel; the gateway must prove it holds one of the pinned keys (the project's Gateway keys, or options.Keys), so a password never reaches an impostor. options: TimeoutMs (connecting and the channel, default 10000), Keys (a list of "ed25519-public:..." keys). Returns true when the attempt started, or false and why (no address or keys configured, already connected). OnGatewayConnected follows when the channel is up, OnGatewayDisconnected(reason, message) when it fails. Requests made meanwhile wait for the channel.

Parameters

address? (string): The gateway's public endpoint, "login.example.com:27015".
options? (table)

Returns boolean, string?

Example

lua

local ok, problem = Gateway.Connect()
if not ok then Log.Warn(problem) end

Gateway.CreateAccount#

lua

Gateway.CreateAccount(name: string, password: string, email?: string): integer

Creates an account (login names: 3-64 ASCII letters, digits and ._-@+, case-insensitive; passwords: the realm's policy, 10-256 bytes by default). Returns the request id; OnGatewayResult reports ok, or a Code such as "alreadyExists", "invalidArgument" (Message says which rule), "permissionDenied" (creation closed) or "quotaExceeded" (too many attempts from this address; RetryAfterMs).

Parameters

name (string)
password (string)
email? (string)

Returns integer

Example

lua

self.Create = Gateway.CreateAccount("ann@example.com", password)

Gateway.Login#

lua

Gateway.Login(name: string, password: string, code?: string): integer

Logs in. Returns the request id; OnGatewayResult reports ok with Data { AccountId, Roles }, or Code "unauthenticated" (wrong name or password - the same for names that do not exist; with Data.NeedsSecondFactor true when the password was right and a second-factor code is needed: call Login again with the code), "lockedOut" (too many failures: Data.LockedUntilUnixMs, RetryAfterMs) or "overloaded" (retry after RetryAfterMs).

Parameters

name (string)
password (string)
code? (string)

Returns integer

Example

lua

self.LoginRequest = Gateway.Login(name, password, self.TotpCode)

Gateway.GetRealms#

lua

Gateway.GetRealms(): integer

Requests the realm list. OnGatewayResult's Data is a list of { Name, DisplayName, Population ("Low", "Medium", "High", "Full", "Offline"), QueueLength, Tags, RequiredClientContentVersion }. An empty requirement means unrestricted or mixed versions; EnterWorld validates the selected zone against the installed client content.

Returns integer

Gateway.GetCharacters#

lua

Gateway.GetCharacters(realm: string): integer

Requests the account's characters in a realm (logged in). OnGatewayResult's Data is a list of { Id, Name, Realm, Zone, Indexed (the persistent schema's indexed values: level, class, ...), Appearance (the template's Visible fields), LastPlayedUnixMs }. Only listed (or created) characters can enter the world.

Parameters

realm (string)

Returns integer

Gateway.GetCharacterTemplate#

lua

Gateway.GetCharacterTemplate(): table?

The project's character template (Assets/Accounts/CharacterTemplate.json) for the character creation screen: { Name = { MinLength, MaxLength, Allowed, Reserved }, Fields = { { Name, Options, Visible }, ... }, Start = { Zone, Prefab, Position }, InitialData, MaxCharactersPerRealm }. nil when the project has none. The gateway checks every creation request against the same template.

Returns table?

Example

lua

for _, field in ipairs(Gateway.GetCharacterTemplate().Fields) do self:AddChoice(field.Name, field.Options) end

Gateway.CreateCharacter#

lua

Gateway.CreateCharacter(realm: string, name: string, fields: table): integer

Creates a character (logged in): fields maps the template's field names to chosen options ({ Class = "Mage" }). The gateway checks the name rules and options, then the game's rules (Characters.OnValidate on the backend). OnGatewayResult's Data is the new character; failures: "invalidArgument" (Message names the field), "alreadyExists" (the name is taken in the realm), "quotaExceeded" (MaxCharactersPerRealm).

Parameters

realm (string)
name (string)
fields (table)

Returns integer

Example

lua

self.Create = Gateway.CreateCharacter("Avalon", "Merlin", { Class = "Mage", Hair = "White" })

Gateway.DeleteCharacter#

lua

Gateway.DeleteCharacter(id: integer): integer

Deletes one of the account's characters (logged in, not queued). OnGatewayResult reports ok or "notFound".

Parameters

id (integer)

Returns integer

Gateway.EnterWorld#

lua

Gateway.EnterWorld(id: integer): integer

Enters the world with a listed character. When the realm is full the request waits in the realm's queue (OnQueueUpdate(realm, position, waitSeconds) as it moves; LeaveQueue gives up). On admission the gateway grants a one-time session token for the character's zone and the engine connects to the zone with it (the current network session ends first): OnGatewayResult reports ok with Data { ZoneAddress, ExpiresAtUnixMs }, then OnClientConnected(ownId) once the zone admitted the player; the gateway connection closes then. Failures: "unavailable" (the zone is offline; left the queue), "notFound" (not a listed character).

Parameters

id (integer)

Returns integer

Gateway.LeaveQueue#

lua

Gateway.LeaveQueue()

Gives up waiting in a realm queue: the waiting EnterWorld is answered ("unavailable").

Gateway.Logout#

lua

Gateway.Logout(): integer

Logs out and stays connected (back to the login screen): a queued EnterWorld is answered, listed characters are forgotten. Returns the request id.

Returns integer

Gateway.Disconnect#

lua

Gateway.Disconnect()

Closes the gateway connection (no OnGatewayDisconnected for it); pending requests are answered "unavailable". Nothing happens when not connected.

Gateway.GetState#

lua

Gateway.GetState(): string

"Disconnected", "Connecting" (transport and secure channel), "Connected" (log in or create an account), "LoggedIn", "Queued" (waiting for a realm slot) or "Entering" (granted: the zone connection takes over).

Returns string

Gateway.SetQueuePriority#

lua

Gateway.SetQueuePriority(fn?: function): function?

Backend service scripts (Assets/Services/*.lua on FrostServices): ranks realm queue entries with fn(account, roles, character, realm) -> number (higher is admitted first, equal ones in arrival order; an error ranks 0). nil removes the hook. Returns the previous hook. In game scripts it only records the function.

Parameters

fn? (function)

Returns function?

Example

lua

Gateway.SetQueuePriority(function(account, roles, character, realm)
    return Subscribers[account] and 10 or 0
end)

Gathering#

Resource nodes (the ResourceNode component naming a GatheringNode row): a gather is a timed action that checks the skill level, the tool (an item in the backpack or equipped with the node's Tool among its WeaponTags) and the range, rolls the node's loot table into the backpack, grants the skill XP and spends a charge; at zero charges the node is Depleted until it respawns. On a client Start is a request of the RPG lane.

lua

local ok, why = Gathering.Start(player, Scene.FindEntityByName("CopperVein"))

Member	Kind	Summary
`Gathering.Start(player: Entity, node: Entity): boolean, string\|integer?`	Function	Starts gathering from a resource node (OnGathered when it completes, OnActionEnded after).
`Gathering.GetNode(node: Entity): table?`	Function	A resource node's state: { Key (its GatheringNode row), Depleted } and, where the scene has authority, Charges (gathers left) and RespawnIn (seconds until a depleted node respawns, else 0); nil for entities without ResourceNode.
`Gathering.Respawn(node: Entity): boolean, string?`	Function	Ends a node's depletion now (an event, a GM's tool): its charges are full again.

Gathering.Start#

lua

Gathering.Start(player: Entity, node: Entity): boolean, string|integer?

Starts gathering from a resource node (OnGathered when it completes, OnActionEnded after). Where the scene has authority: true, or false and why (no tool, a low skill, out of range, depleted, busy). On a client: a Gather request; true and its request id when sent.

Parameters

player (Entity): The player character (on a client: one it controls).
node (Entity): The ResourceNode entity.

Returns boolean, string|integer?

Example

lua

Gathering.Start(player, vein)

Gathering.GetNode#

lua

Gathering.GetNode(node: Entity): table?

A resource node's state: { Key (its GatheringNode row), Depleted } and, where the scene has authority, Charges (gathers left) and RespawnIn (seconds until a depleted node respawns, else 0); nil for entities without ResourceNode.

Parameters

node (Entity): The ResourceNode entity.

Returns table?

Example

lua

local state = Gathering.GetNode(vein)
if state.Depleted then Log.Info("come back later") end

Gathering.Respawn#

lua

Gathering.Respawn(node: Entity): boolean, string?

Ends a node's depletion now (an event, a GM's tool): its charges are full again. False and why for entities that are no active resource node. Authority only.

Parameters

node (Entity): The ResourceNode entity.

Returns boolean, string?

Example

lua

Gathering.Respawn(vein)

Graphics#

Rendering from scripts: the renderer's statistics, its debug visualizations (SetDebugView), its texture memory budget and occlusion culling (graphics options of a game), and the clear color and ambient light of a camera (the scene's primary camera unless one is passed). Every other camera setting is a field of its Camera component - post-processing (BloomEnabled, BloomIntensity, Exposure, Contrast, Saturation, VignetteIntensity, Tonemapping by name: "None", "ACES" or "Reinhard", ...), LightingEnabled, pixel-perfect rendering and InternalResolutionScale.

lua

Graphics.SetClearColor(Color.Black)
local camera = Camera.Main():GetComponent("Camera")
camera.BloomEnabled = true
camera.BloomIntensity = 1.5
camera.Tonemapping = "ACES"

Member	Kind	Summary
`Graphics.GetStats(): table?`	Function	The statistics of the last frame the renderer finished (a new table per call), or nil when the scene is not rendered (dedicated servers, headless runs).
`Graphics.SetDebugView(view: string): boolean`	Function	Shows a debug visualization of the renderer from the next frame on: "Overdraw" (a heat map of how many sprites cover each pixel: black for none, blue for one, through cyan, green, yellow and red to white for many layers), "Batches" (every draw batch in its own flat color), "Culling" (the image with the bounds of every visible sprite and every camera's culling rectangle), "LightTiles" (a heat map of the lights per light-culling tile over lit cameras), or "None" (the image as usual).
`Graphics.GetDebugView(): string?`	Function	The renderer's debug visualization (Graphics.SetDebugView): "None", "Overdraw", "Batches", "Culling" or "LightTiles"; nil when the scene is not rendered.
`Graphics.SetTextureMemoryBudget(megabytes: integer): boolean`	Function	Sets the texture memory the renderer keeps asset textures under, in MB (0 = unlimited), from the next frame on: over it, the least recently drawn textures lose their top mips until they are drawn again (a graphics-quality option for machines with little video memory).
`Graphics.GetTextureMemoryBudget(): integer?`	Function	The renderer's texture memory budget in MB (0 = unlimited; Graphics.SetTextureMemoryBudget, initially the project's Render.TextureBudgetMB); nil when the scene is not rendered.
`Graphics.SetOcclusionCulling(enabled: boolean): boolean`	Function	Turns GPU occlusion culling on or off from the next frame on: static sprite batches and GPU particles that lie entirely behind opaque sprites are skipped (it never changes the image; it pays off when large opaque sprites hide many of them, and costs a depth pyramid per camera otherwise).
`Graphics.IsOcclusionCullingEnabled(): boolean?`	Function	Whether the renderer culls with GPU occlusion culling (Graphics.SetOcclusionCulling, initially the project's Render.OcclusionCulling); nil when the scene is not rendered.
`Graphics.GetClearColor(camera?: Entity): Color`	Function	The background color of a camera (default: the primary camera), used when its ClearFlags is "Color".
`Graphics.SetClearColor(color: Color, camera?: Entity)`	Function	Sets the background color of a camera (default: the primary camera); the renderer clamps it to [0, 1].
`Graphics.GetAmbientLight(camera?: Entity): Color`	Function	The ambient light color of a camera (default: the primary camera): the light lit sprites receive before 2D lights are added (Camera.AmbientColor).
`Graphics.SetAmbientLight(color: Color, camera?: Entity)`	Function	Sets the ambient light of a camera (default: the primary camera; HDR: components may exceed 1).

Graphics.GetStats#

lua

Graphics.GetStats(): table?

The statistics of the last frame the renderer finished (a new table per call), or nil when the scene is not rendered (dedicated servers, headless runs). Fields: Frame (the renderer's frame number), Views, DrawCalls, Batches, Instances (sprite instances drawn, all views), Triangles, Sprites (sprites submitted before culling: scene sprites, text glyphs, particles, ...), VisibleSprites and CulledSprites (all views), SceneSprites (SpriteRenderer components the scene extraction sent: those in or near a view; Static sprites, drawn from the renderer's render world, are not counted), CpuFrameMs (render-thread time), GpuFrameMs (GPU time, -1 until measured; it lags a few frames), DynamicResolutionScale and GpuMemoryBytes (estimated memory of the renderer's resources).

Returns table?

Example

lua

local stats = Graphics.GetStats()
if stats then Log.Info("draw calls:", stats.DrawCalls, "gpu ms:", stats.GpuFrameMs) end

Graphics.SetDebugView#

lua

Graphics.SetDebugView(view: string): boolean

Shows a debug visualization of the renderer from the next frame on: "Overdraw" (a heat map of how many sprites cover each pixel: black for none, blue for one, through cyan, green, yellow and red to white for many layers), "Batches" (every draw batch in its own flat color), "Culling" (the image with the bounds of every visible sprite and every camera's culling rectangle), "LightTiles" (a heat map of the lights per light-culling tile over lit cameras), or "None" (the image as usual). Names ignore case; an unknown name raises an error. Returns false (and changes nothing) when the scene is not rendered (dedicated servers, headless runs). It applies to every camera of the game; in the editor the Game view shows it while its Render mode is "Game", and it lasts until play mode stops (every play session starts without one). FrostRuntime --debug-view sets the first value.

Parameters

view (string)

Returns boolean

Example

lua

Graphics.SetDebugView("Overdraw") -- find where sprites pile up
Graphics.SetDebugView("None")

Graphics.GetDebugView#

lua

Graphics.GetDebugView(): string?

The renderer's debug visualization (Graphics.SetDebugView): "None", "Overdraw", "Batches", "Culling" or "LightTiles"; nil when the scene is not rendered.

Returns string?

Example

lua

if Graphics.GetDebugView() == "Overdraw" then Graphics.SetDebugView("None") end

Graphics.SetTextureMemoryBudget#

lua

Graphics.SetTextureMemoryBudget(megabytes: integer): boolean

Sets the texture memory the renderer keeps asset textures under, in MB (0 = unlimited), from the next frame on: over it, the least recently drawn textures lose their top mips until they are drawn again (a graphics-quality option for machines with little video memory). The project's Render.TextureBudgetMB is the value a game starts with. An integer outside [0, 1048576] raises an error. Returns false (and changes nothing) when the scene is not rendered (dedicated servers, headless runs). In the editor it lasts until play mode stops (every play session starts with the project's value).

Parameters

megabytes (integer): The budget in MB, 0 for unlimited.

Returns boolean

Example

lua

Graphics.SetTextureMemoryBudget(256) -- "low" texture quality

Graphics.GetTextureMemoryBudget#

lua

Graphics.GetTextureMemoryBudget(): integer?

The renderer's texture memory budget in MB (0 = unlimited; Graphics.SetTextureMemoryBudget, initially the project's Render.TextureBudgetMB); nil when the scene is not rendered.

Returns integer?

Example

lua

if Graphics.GetTextureMemoryBudget() == 0 then Log.Info("textures are not budgeted") end

Graphics.SetOcclusionCulling#

lua

Graphics.SetOcclusionCulling(enabled: boolean): boolean

Turns GPU occlusion culling on or off from the next frame on: static sprite batches and GPU particles that lie entirely behind opaque sprites are skipped (it never changes the image; it pays off when large opaque sprites hide many of them, and costs a depth pyramid per camera otherwise). The project's Render.OcclusionCulling is the value a game starts with. Returns false (and changes nothing) when the scene is not rendered, or when the GPU cannot sample the depth buffer the renderer started with (logged; a project with Render.OcclusionCulling on always starts with one it can). A value that is not a boolean raises an error. In the editor it lasts until play mode stops.

Parameters

enabled (boolean): true to cull, false to draw everything.

Returns boolean

Example

lua

Graphics.SetOcclusionCulling(true) -- a level with a large opaque foreground

Graphics.IsOcclusionCullingEnabled#

lua

Graphics.IsOcclusionCullingEnabled(): boolean?

Whether the renderer culls with GPU occlusion culling (Graphics.SetOcclusionCulling, initially the project's Render.OcclusionCulling); nil when the scene is not rendered.

Returns boolean?

Example

lua

Log.Info("occlusion culling:", Graphics.IsOcclusionCullingEnabled())

Graphics.GetClearColor#

lua

Graphics.GetClearColor(camera?: Entity): Color

The background color of a camera (default: the primary camera), used when its ClearFlags is "Color".

Parameters

camera? (Entity)

Returns Color

Graphics.SetClearColor#

lua

Graphics.SetClearColor(color: Color, camera?: Entity)

Sets the background color of a camera (default: the primary camera); the renderer clamps it to [0, 1]. Non-finite components raise an error.

Parameters

color (Color)
camera? (Entity)

Example

lua

Graphics.SetClearColor(Color(0.05, 0.05, 0.1))

Graphics.GetAmbientLight#

lua

Graphics.GetAmbientLight(camera?: Entity): Color

The ambient light color of a camera (default: the primary camera): the light lit sprites receive before 2D lights are added (Camera.AmbientColor).

Parameters

camera? (Entity)

Returns Color

Graphics.SetAmbientLight#

lua

Graphics.SetAmbientLight(color: Color, camera?: Entity)

Sets the ambient light of a camera (default: the primary camera; HDR: components may exceed 1). It applies while the camera's LightingEnabled is on. Negative or non-finite components raise an error.

Parameters

color (Color)
camera? (Entity)

Example

lua

Graphics.SetAmbientLight(Color(0.2, 0.2, 0.35))
Camera.Main():GetComponent("Camera").LightingEnabled = true

Guild#

Guild membership, ranks and bank access. Requests return an id or nil,error; results arrive in OnServiceResult.

Member	Kind	Summary
`Guild.Create(name: string): integer?, string?`	Function	Creates a guild with the caller as its leader.
`Guild.Invite(name: string): integer?, string?`	Function	Invites a character of the guild's realm by name, online or not (unknown names and members of other guilds are answered alike).
`Guild.Respond(guildId: integer, accept: boolean): integer?, string?`	Function	Accepts or refuses a pending guild invitation.
`Guild.Get(): integer?, string?`	Function	Returns Guild (identity, ranks, currency) and Members (identity, rank, presence, note).
`Guild.Leave(): integer?, string?`	Function	Leaves the guild.
`Guild.Disband(): integer?, string?`	Function	The leader disbands a guild once its bank is empty and no deposit or withdrawal is in flight (conflict with RetryAfterMs otherwise).
`Guild.Kick(characterId: integer): integer?, string?`	Function	Removes a lower-ranked member when the caller has Kick permission.
`Guild.TransferLeadership(characterId: integer): integer?, string?`	Function	Transfers leadership to another current member.
`Guild.SetRank(characterId: integer, rank: integer): integer?, string?`	Function	Promotes or demotes a member within the caller's rank and permission limits.
`Guild.SetMotd(text: string): integer?, string?`	Function	Changes the message of the day with EditMotd permission.
`Guild.GetBankTab(tab: integer): integer?, string?`	Function	Returns BankTab with Index, Name, Version and Slots (Slot, Item, Quantity).
`Guild.SetBankTab(tab: integer, name: string): integer?, string?`	Function	Adds or renames a bank tab with EditBankTabs permission, within Guilds.json limits.
`Guild.GetEvents(limit?: integer): integer?, string?`	Function	Returns up to 100 recent Events (AtUnixMs, Kind, Actor, Target, Detail).
`Guild.SetItemValidator(fn?: function): function?`	Function	Service scripts: fn({Context,CharacterId,Item,Quantity}) returns a normalized item table or nil to refuse it.
`Guild.EditRank(rank: table): integer?, string?`	Function	Changes a rank's Name,Permissions bit mask,WithdrawItemsPerDay list and WithdrawCurrencyPerDay.
`Guild.Deposit(clientId: integer, data: table): integer?, string?`	Function	Zone scripts: authorize a guild-bank deposit for this authenticated client.
`Guild.Withdraw(clientId: integer, data: table): integer?, string?`	Function	Zone scripts: authorize Tab,Slot,Quantity,Currency within the client's guild rank and daily limits.
`Guild.ConfirmTransfer(transferId: integer, committed: boolean): boolean`	Function	Zone scripts: tells the guild service the outcome of a Deposit or Withdraw authorization.

Guild.Create#

lua

Guild.Create(name: string): integer?, string?

Creates a guild with the caller as its leader. The service validates the name and membership.

Parameters

name (string)

Returns integer?, string?

Guild.Invite#

lua

Guild.Invite(name: string): integer?, string?

Invites a character of the guild's realm by name, online or not (unknown names and members of other guilds are answered alike). Requires the Invite permission.

Parameters

name (string)

Returns integer?, string?

Guild.Respond#

lua

Guild.Respond(guildId: integer, accept: boolean): integer?, string?

Accepts or refuses a pending guild invitation.

Parameters

guildId (integer)
accept (boolean)

Returns integer?, string?

Guild.Get#

lua

Guild.Get(): integer?, string?

Returns Guild (identity, ranks, currency) and Members (identity, rank, presence, note).

Returns integer?, string?

Guild.Leave#

lua

Guild.Leave(): integer?, string?

Leaves the guild. A leader must transfer leadership or disband first.

Returns integer?, string?

Guild.Disband#

lua

Guild.Disband(): integer?, string?

The leader disbands a guild once its bank is empty and no deposit or withdrawal is in flight (conflict with RetryAfterMs otherwise).

Returns integer?, string?

Guild.Kick#

lua

Guild.Kick(characterId: integer): integer?, string?

Removes a lower-ranked member when the caller has Kick permission.

Parameters

characterId (integer)

Returns integer?, string?

Guild.TransferLeadership#

lua

Guild.TransferLeadership(characterId: integer): integer?, string?

Transfers leadership to another current member.

Parameters

characterId (integer)

Returns integer?, string?

Guild.SetRank#

lua

Guild.SetRank(characterId: integer, rank: integer): integer?, string?

Promotes or demotes a member within the caller's rank and permission limits.

Parameters

characterId (integer)
rank (integer)

Returns integer?, string?

Guild.SetMotd#

lua

Guild.SetMotd(text: string): integer?, string?

Changes the message of the day with EditMotd permission.

Parameters

text (string)

Returns integer?, string?

Guild.GetBankTab#

lua

Guild.GetBankTab(tab: integer): integer?, string?

Returns BankTab with Index, Name, Version and Slots (Slot, Item, Quantity). Indices begin at zero.

Parameters

tab (integer)

Returns integer?, string?

Guild.SetBankTab#

lua

Guild.SetBankTab(tab: integer, name: string): integer?, string?

Adds or renames a bank tab with EditBankTabs permission, within Guilds.json limits.

Parameters

tab (integer)
name (string)

Returns integer?, string?

Guild.GetEvents#

lua

Guild.GetEvents(limit?: integer): integer?, string?

Returns up to 100 recent Events (AtUnixMs, Kind, Actor, Target, Detail). Default 100.

Parameters

limit? (integer)

Returns integer?, string?

Guild.SetItemValidator#

lua

Guild.SetItemValidator(fn?: function): function?

Service scripts: fn({Context,CharacterId,Item,Quantity}) returns a normalized item table or nil to refuse it. Errors refuse the transfer. Context is guild-bank, mail or system-mail. Returns the previous validator; nil removes it.

Parameters

fn? (function)

Returns function?

Guild.EditRank#

lua

Guild.EditRank(rank: table): integer?, string?

Changes a rank's Name,Permissions bit mask,WithdrawItemsPerDay list and WithdrawCurrencyPerDay. Index begins at zero. The service enforces the caller's rank and EditRanks permission.

Parameters

rank (table)

Returns integer?, string?

Guild.Deposit#

lua

Guild.Deposit(clientId: integer, data: table): integer?, string?

Zone scripts: authorize a guild-bank deposit for this authenticated client. data: Tab,Slot,Item,Quantity,Currency. OnServiceResult supplies TransferId and Operand; commit the matching character debit using Persistence.Transact(changes,ledger,{result.Operand}), which also tells the service the outcome; drop it with Guild.ConfirmTransfer(TransferId, false). A request only authorizes the transfer.

Parameters

clientId (integer)
data (table)

Returns integer?, string?

Guild.Withdraw#

lua

Guild.Withdraw(clientId: integer, data: table): integer?, string?

Zone scripts: authorize Tab,Slot,Quantity,Currency within the client's guild rank and daily limits. Result includes Item,Quantity,Operand,TransferId; commit the matching character credit through Persistence.Transact (or drop it with Guild.ConfirmTransfer(TransferId, false)). Central completion decides the outcome.

Parameters

clientId (integer)
data (table)

Returns integer?, string?

Guild.ConfirmTransfer#

lua

Guild.ConfirmTransfer(transferId: integer, committed: boolean): boolean

Zone scripts: tells the guild service the outcome of a Deposit or Withdraw authorization. Persistence.Transact confirms the transfers it commits by itself; call ConfirmTransfer(transferId, false) when the script drops an authorization (the character cannot take the item, the player left), which frees the bank tab at once instead of when the authorization expires. The service decides from the central store either way. Returns false when the scene awaits no such guild transfer.

Parameters

transferId (integer)
committed (boolean)

Returns boolean

Input#

Keyboard, mouse and gamepad state of the current frame, and the project's input actions and axes. Keys and buttons are the values of the Key, MouseButton, GamepadButton and GamepadAxis tables or their names ("Space"). "Pressed" and "Released" are true only in the frame the change happened; mouse positions are framebuffer pixels from the top-left of the window.

lua

if Input.IsKeyPressed(Key.Space) or Input.IsActionPressed("Jump") then
	self:Jump()
end
local move = Input.GetAxis("Horizontal")

Member	Kind	Summary
`Input.IsKeyDown(key: integer\|string): boolean`	Function	True while the key is held.
`Input.IsKeyPressed(key: integer\|string): boolean`	Function	True in the frame the key went down (key repeats do not count).
`Input.IsKeyReleased(key: integer\|string): boolean`	Function	True in the frame the key went up.
`Input.IsMouseButtonDown(button: integer\|string): boolean`	Function	True while the mouse button is held.
`Input.IsMouseButtonPressed(button: integer\|string): boolean`	Function	True in the frame the mouse button went down.
`Input.IsMouseButtonReleased(button: integer\|string): boolean`	Function	True in the frame the mouse button went up.
`Input.GetMousePosition(): Vec2`	Function	The cursor in framebuffer pixels from the top-left of the window (+Y down).
`Input.GetMouseDelta(): Vec2`	Function	Cursor movement this frame in framebuffer pixels.
`Input.GetScrollDelta(): Vec2`	Function	Scrolling this frame (+Y = away from the user).
`Input.GetTextInput(): string`	Function	The text typed this frame (UTF-8), for text fields.
`Input.IsGamepadConnected(index?: integer): boolean`	Function	True when a gamepad is connected in the slot (0 to 3, default 0).
`Input.IsGamepadButtonDown(button: integer\|string, index?: integer): boolean`	Function	True while the button of gamepad `index` (default 0) is held.
`Input.IsGamepadButtonPressed(button: integer\|string, index?: integer): boolean`	Function	True in the frame the button went down.
`Input.IsGamepadButtonReleased(button: integer\|string, index?: integer): boolean`	Function	True in the frame the button went up.
`Input.GetGamepadAxis(axis: integer\|string, index?: integer): number`	Function	The axis with the deadzone applied: sticks in [-1, 1] (+Y down), triggers in [0, 1].
`Input.IsActionDown(action: string): boolean`	Function	True while any binding of the input action (project settings) is held.
`Input.IsActionPressed(action: string): boolean`	Function	True in the frame the action went down.
`Input.IsActionReleased(action: string): boolean`	Function	True in the frame the action went up.
`Input.GetAxis(axis: string): number`	Function	The value of an input axis in [-1, 1] (keys and gamepad combined, project settings).
`Input.SetCursorMode(mode: integer\|string): boolean`	Function	Shows, hides or locks the cursor over the game window (a CursorMode value or its name), at the end of the frame.
`Input.GetCursorMode(): integer`	Function	The cursor mode in effect (a CursorMode value; as of the last applied request).
`Input.GetTouchCount(): integer`	Function	The number of touch contacts this frame: those that are down and those that lifted or were cancelled this frame (Input.GetTouch(1) to Input.GetTouch(count), in the order they touched down).
`Input.GetTouch(index: integer): Touch`	Function	The touch contact at `index` (1 to Input.GetTouchCount(), in the order they touched down).
`Input.GetTouches(): Touch[]`	Function	Every touch contact of this frame as a list (the same contacts as Input.GetTouch(1) to Input.GetTouch(Input.GetTouchCount())).
`Input.FindTouch(id: integer): Touch?`	Function	The contact of this frame with the id (Touch.Id), or nil when it is no longer listed: a script follows one finger across frames this way.
`Input.IsTouchAvailable(): boolean`	Function	Whether the window has a touch screen that reports contacts (on Windows; Linux and macOS report no touch input yet, so this is false there).
`Input.TouchEmulatesMouse: boolean`	Property	Whether the primary touch contact also acts as the mouse (default true): it moves Input.GetMousePosition and holds the left mouse button, so mouse-driven gameplay works on touch screens.

Input.IsKeyDown#

lua

Input.IsKeyDown(key: integer|string): boolean

True while the key is held.

Parameters

key (integer|string)

Returns boolean

Input.IsKeyPressed#

lua

Input.IsKeyPressed(key: integer|string): boolean

True in the frame the key went down (key repeats do not count).

Parameters

key (integer|string)

Returns boolean

Example

lua

if Input.IsKeyPressed(Key.Space) then jump() end

Input.IsKeyReleased#

lua

Input.IsKeyReleased(key: integer|string): boolean

True in the frame the key went up.

Parameters

key (integer|string)

Returns boolean

Input.IsMouseButtonDown#

lua

Input.IsMouseButtonDown(button: integer|string): boolean

True while the mouse button is held.

Parameters

button (integer|string)

Returns boolean

Input.IsMouseButtonPressed#

lua

Input.IsMouseButtonPressed(button: integer|string): boolean

True in the frame the mouse button went down.

Parameters

button (integer|string)

Returns boolean

Input.IsMouseButtonReleased#

lua

Input.IsMouseButtonReleased(button: integer|string): boolean

True in the frame the mouse button went up.

Parameters

button (integer|string)

Returns boolean

Input.GetMousePosition#

lua

Input.GetMousePosition(): Vec2

The cursor in framebuffer pixels from the top-left of the window (+Y down).

Returns Vec2

Input.GetMouseDelta#

lua

Input.GetMouseDelta(): Vec2

Cursor movement this frame in framebuffer pixels.

Returns Vec2

Input.GetScrollDelta#

lua

Input.GetScrollDelta(): Vec2

Scrolling this frame (+Y = away from the user).

Returns Vec2

Input.GetTextInput#

lua

Input.GetTextInput(): string

The text typed this frame (UTF-8), for text fields.

Returns string

Input.IsGamepadConnected#

lua

Input.IsGamepadConnected(index?: integer): boolean

True when a gamepad is connected in the slot (0 to 3, default 0).

Parameters

index? (integer)

Returns boolean

Input.IsGamepadButtonDown#

lua

Input.IsGamepadButtonDown(button: integer|string, index?: integer): boolean

True while the button of gamepad index (default 0) is held.

Parameters

button (integer|string)
index? (integer)

Returns boolean

Input.IsGamepadButtonPressed#

lua

Input.IsGamepadButtonPressed(button: integer|string, index?: integer): boolean

True in the frame the button went down.

Parameters

button (integer|string)
index? (integer)

Returns boolean

Input.IsGamepadButtonReleased#

lua

Input.IsGamepadButtonReleased(button: integer|string, index?: integer): boolean

True in the frame the button went up.

Parameters

button (integer|string)
index? (integer)

Returns boolean

Input.GetGamepadAxis#

lua

Input.GetGamepadAxis(axis: integer|string, index?: integer): number

The axis with the deadzone applied: sticks in [-1, 1] (+Y down), triggers in [0, 1].

Parameters

axis (integer|string)
index? (integer)

Returns number

Input.IsActionDown#

lua

Input.IsActionDown(action: string): boolean

True while any binding of the input action (project settings) is held. Unknown names are false (warned once).

Parameters

action (string)

Returns boolean

Input.IsActionPressed#

lua

Input.IsActionPressed(action: string): boolean

True in the frame the action went down.

Parameters

action (string)

Returns boolean

Example

lua

if Input.IsActionPressed("Jump") then jump() end

Input.IsActionReleased#

lua

Input.IsActionReleased(action: string): boolean

True in the frame the action went up.

Parameters

action (string)

Returns boolean

Input.GetAxis#

lua

Input.GetAxis(axis: string): number

The value of an input axis in [-1, 1] (keys and gamepad combined, project settings). Unknown names are 0 (warned once).

Parameters

axis (string)

Returns number

Example

lua

local horizontal = Input.GetAxis("Horizontal")

Input.SetCursorMode#

lua

Input.SetCursorMode(mode: integer|string): boolean

Shows, hides or locks the cursor over the game window (a CursorMode value or its name), at the end of the frame. Returns whether the request was accepted: false in the editor's play mode (the cursor belongs to the editor) and where the engine has no window. A headless run records the mode.

Parameters

mode (integer|string)

Returns boolean

Example

lua

Input.SetCursorMode(CursorMode.Locked)

Input.GetCursorMode#

lua

Input.GetCursorMode(): integer

The cursor mode in effect (a CursorMode value; as of the last applied request).

Returns integer

Example

lua

if Input.GetCursorMode() == CursorMode.Locked then look(Input.GetMouseDelta()) end

Input.GetTouchCount#

lua

Input.GetTouchCount(): integer

The number of touch contacts this frame: those that are down and those that lifted or were cancelled this frame (Input.GetTouch(1) to Input.GetTouch(count), in the order they touched down). 0 without a touch screen.

Returns integer

Example

lua

for i = 1, Input.GetTouchCount() do
	local touch = Input.GetTouch(i)
end

Input.GetTouch#

lua

Input.GetTouch(index: integer): Touch

The touch contact at index (1 to Input.GetTouchCount(), in the order they touched down). Raises an error for other indices.

Parameters

index (integer): 1-based position in this frame's contacts.

Returns Touch

Example

lua

local first = Input.GetTouch(1)

Input.GetTouches#

lua

Input.GetTouches(): Touch[]

Every touch contact of this frame as a list (the same contacts as Input.GetTouch(1) to Input.GetTouch(Input.GetTouchCount())). Empty without a touch screen.

Returns Touch[]

Example

lua

for _, touch in ipairs(Input.GetTouches()) do
	if touch.Phase == TouchPhase.Began then self:Spark(touch.Position) end
end

Input.FindTouch#

lua

Input.FindTouch(id: integer): Touch?

The contact of this frame with the id (Touch.Id), or nil when it is no longer listed: a script follows one finger across frames this way.

Parameters

id (integer): A Touch.Id seen in an earlier frame.

Returns Touch?

Example

lua

local finger = Input.FindTouch(self.AimTouchId)
if finger == nil or finger.Phase == TouchPhase.Ended then self.AimTouchId = nil end

Input.IsTouchAvailable#

lua

Input.IsTouchAvailable(): boolean

Whether the window has a touch screen that reports contacts (on Windows; Linux and macOS report no touch input yet, so this is false there). Games show touch controls when it is true.

Returns boolean

Input.TouchEmulatesMouse#

lua

Input.TouchEmulatesMouse: boolean

Whether the primary touch contact also acts as the mouse (default true): it moves Input.GetMousePosition and holds the left mouse button, so mouse-driven gameplay works on touch screens. Games that read the touches themselves turn it off; turning it off releases an emulated hold at once. The UI handles touches either way.

Example

lua

Input.TouchEmulatesMouse = false

Inventory#

The containers of characters (servers, hosts and offline games: the scene's Items system; on a client the read functions of Inventory, Equipment, Bank, Wallet, Vendor, LootDrops and Trade that say so answer for the local character from the RPG lane's sections, and changes are refused): the backpack (Items.BackpackSlots plus the equipped bags' Slots), the equipment, the bank and the account bank. Slots count from 1. Changes return true, or false and "<Refusal>: <why>" (Full, Insufficient, InvalidSlot, ...) and change nothing; wrong arguments raise errors. Item tables ({ Key, Qty, Id, Durability, Binding, Affixes, Data }, defaults left out: Qty is nil for a single item) carry a unique item's 64-bit Id as an integer: ids at or above 2^63 read as negative integers (the bit pattern, as UUIDs), which every function taking an item table reads back exactly.

lua

local ok, why = Inventory.Give(player, "wolf_pelt", 3)
if not ok then Log.Warn(why) end

Member	Kind	Summary
`Inventory.Create(entity: Entity): boolean, string?`	Function	Gives an entity empty containers unless it has them (characters - an RpgActor with a Class - get theirs on first use; chests, pack animals and test fixtures through this).
`Inventory.Give(actor: Entity, item: string\|table, quantity?: integer): boolean, string?`	Function	Adds items to the actor's backpack (stacking with what stacks; a currency item goes to the wallet).
`Inventory.Take(actor: Entity, key: string, quantity: integer): boolean, string?`	Function	Removes items from the backpack, plain stacks first; false when the actor holds fewer.
`Inventory.Count(actor: Entity, key: string, container?: string): integer`	Function	How many items with the key a container holds (default the backpack).
`Inventory.GetSlot(actor: Entity, container: string, slot: integer): table?`	Function	The item table in a slot ({ Key, Qty?, Id?, Durability?, Binding?, Affixes?, Data? }); nil when the slot is empty.
`Inventory.GetSlots(actor: Entity, container: string): table`	Function	The occupied slots of a container in slot order: a list of { Slot, Item }.
`Inventory.GetSlotCount(actor: Entity, container: string): integer`	Function	The number of slots of a container (0 for an actor without containers).
`Inventory.GetFreeSlots(actor: Entity, container?: string): integer`	Function	The empty slots of a container (default the backpack).
`Inventory.Move(actor: Entity, fromContainer: string, fromSlot: integer, toContainer: string, toSlot: integer, quantity?: integer): boolean, string?`	Function	Moves a stack (or quantity of it) between slots of the backpack, the bank and the account bank: onto an empty slot, merging with the same item, or swapping whole stacks.
`Inventory.Destroy(actor: Entity, container: string, slot: integer, quantity?: integer): boolean, string?`	Function	Destroys the stack in a slot (or quantity of it).
`Inventory.Sort(actor: Entity, container: string): boolean, string?`	Function	Sorts a container's stacks by item key and merges what stacks (Backpack, Bank, AccountBank).
`Inventory.Use(actor: Entity, slot: integer, target?: Entity): boolean, string?`	Function	Uses the item in a backpack slot: a consumable casts its ability and uses a charge, a currency item goes to the wallet, an item with a Use hook calls it.
`Inventory.Drop(item: string\|table, position: Vec2, owner?: Entity): Entity?, string?`	Function	Puts an item on the ground as a GroundItem entity: visible to its owner for Items.GroundOwnerSeconds, then to everyone for Items.GroundPublicSeconds (no owner: public at once).
`Inventory.ServiceItem(actor: Entity, container: string, slot: integer, quantity?: integer): table?`	Function	The item table a guild bank, mail or market request carries for a slot's stack (or a quantity of it): the Item of Guild.Deposit, of Mail.Send's attachments and of Market.CreateListing.
`Inventory.Escrow(actor: Entity, transfer: table, operands: string[]): boolean, string?`	Function	The character side of a guild bank, mail or market transfer with real slots (servers): transfer = { Kind = "mail" \| "guild-bank" \| "market", Take = { { Container?, Slot, Quantity?, Item } } (no Quantity: the whole stack; Item: the ServiceItem table the request carried), Give = { item tables }, Currency = { gold = -50 } }; operands are the Operand strings of the service's result (one transfer).

Inventory.Create#

lua

Inventory.Create(entity: Entity): boolean, string?

Gives an entity empty containers unless it has them (characters - an RpgActor with a Class - get theirs on first use; chests, pack animals and test fixtures through this).

Parameters

entity (Entity): The entity.

Returns boolean, string?

Example

lua

Inventory.Create(chest)
Inventory.Give(chest, "iron_ore", 20)

Inventory.Give#

lua

Inventory.Give(actor: Entity, item: string|table, quantity?: integer): boolean, string?

Adds items to the actor's backpack (stacking with what stacks; a currency item goes to the wallet). All or nothing: false with the reason when they do not fit.

Parameters

actor (Entity): A character (an RpgActor with a Class).
item (string|table): An item key, or an item table { Key, Qty, Binding, Affixes, Data }.
quantity? (integer): How many when item is a key (default 1).

Returns boolean, string?

Example

lua

Inventory.Give(player, "potion", 5)

Inventory.Take#

lua

Inventory.Take(actor: Entity, key: string, quantity: integer): boolean, string?

Removes items from the backpack, plain stacks first; false when the actor holds fewer.

Parameters

actor (Entity): The character.
key (string): The item key.
quantity (integer): How many.

Returns boolean, string?

Example

lua

if Inventory.Take(player, "wolf_pelt", 4) then Quest.Complete() end

Inventory.Count#

lua

Inventory.Count(actor: Entity, key: string, container?: string): integer

How many items with the key a container holds (default the backpack).

Parameters

actor (Entity): The character.
key (string): The item key.
container? (string): Backpack, Equipment, Bank or AccountBank.

Returns integer

Example

lua

local ore = Inventory.Count(player, "iron_ore")

Inventory.GetSlot#

lua

Inventory.GetSlot(actor: Entity, container: string, slot: integer): table?

The item table in a slot ({ Key, Qty?, Id?, Durability?, Binding?, Affixes?, Data? }); nil when the slot is empty. Fields at their defaults are left out: Qty is nil for a single item, so read the count as item.Qty or 1. An item the data no longer has shows Key = "".

Parameters

actor (Entity): The character.
container (string): Backpack, Equipment, Bank or AccountBank.
slot (integer): The slot, from 1.

Returns table?

Example

lua

local item = Inventory.GetSlot(player, "Backpack", 1)

Inventory.GetSlots#

lua

Inventory.GetSlots(actor: Entity, container: string): table

The occupied slots of a container in slot order: a list of { Slot, Item }. On a client: the local character's, from the RPG lane; empty for anyone else.

Parameters

actor (Entity): The character.
container (string): Backpack, Equipment, Bank or AccountBank.

Returns table

Example

lua

for _, entry in ipairs(Inventory.GetSlots(player, "Backpack")) do Log.Info(entry.Slot .. ": " .. entry.Item.Key) end

Inventory.GetSlotCount#

lua

Inventory.GetSlotCount(actor: Entity, container: string): integer

The number of slots of a container (0 for an actor without containers). On a client: the local character's, from the project's Items settings, the worn bags and the EquipSlot rows; 0 for anyone else.

Parameters

actor (Entity): The character.
container (string): Backpack, Equipment, Bank or AccountBank.

Returns integer

Example

lua

local size = Inventory.GetSlotCount(player, "Backpack")

Inventory.GetFreeSlots#

lua

Inventory.GetFreeSlots(actor: Entity, container?: string): integer

The empty slots of a container (default the backpack).

Parameters

actor (Entity): The character.
container? (string): Backpack, Bank or AccountBank.

Returns integer

Example

lua

if Inventory.GetFreeSlots(player) == 0 then UI.Toast("Your bags are full") end

Inventory.Move#

lua

Inventory.Move(actor: Entity, fromContainer: string, fromSlot: integer, toContainer: string, toSlot: integer, quantity?: integer): boolean, string?

Moves a stack (or quantity of it) between slots of the backpack, the bank and the account bank: onto an empty slot, merging with the same item, or swapping whole stacks.

Parameters

actor (Entity): The character.
fromContainer (string): The source container.
fromSlot (integer): The source slot, from 1.
toContainer (string): The target container.
toSlot (integer): The target slot, from 1.
quantity? (integer): How many (default the whole stack).

Returns boolean, string?

Example

lua

Inventory.Move(player, "Backpack", 1, "Bank", 1)

Inventory.Destroy#

lua

Inventory.Destroy(actor: Entity, container: string, slot: integer, quantity?: integer): boolean, string?

Destroys the stack in a slot (or quantity of it).

Parameters

actor (Entity): The character.
container (string): The container.
slot (integer): The slot, from 1.
quantity? (integer): How many (default all).

Returns boolean, string?

Example

lua

Inventory.Destroy(player, "Backpack", 3)

Inventory.Sort#

lua

Inventory.Sort(actor: Entity, container: string): boolean, string?

Sorts a container's stacks by item key and merges what stacks (Backpack, Bank, AccountBank).

Parameters

actor (Entity): The character.
container (string): The container.

Returns boolean, string?

Example

lua

Inventory.Sort(player, "Backpack")

Inventory.Use#

lua

Inventory.Use(actor: Entity, slot: integer, target?: Entity): boolean, string?

Uses the item in a backpack slot: a consumable casts its ability and uses a charge, a currency item goes to the wallet, an item with a Use hook calls it.

Parameters

actor (Entity): The character.
slot (integer): The backpack slot, from 1.
target? (Entity): The target (default the actor).

Returns boolean, string?

Example

lua

Inventory.Use(player, 2)

Inventory.Drop#

lua

Inventory.Drop(item: string|table, position: Vec2, owner?: Entity): Entity?, string?

Puts an item on the ground as a GroundItem entity: visible to its owner for Items.GroundOwnerSeconds, then to everyone for Items.GroundPublicSeconds (no owner: public at once).

Parameters

item (string|table): An item key or an item table.
position (Vec2): Where, in world units.
owner? (Entity): Who may take it first.

Returns Entity?, string?

Example

lua

local bag = Inventory.Drop("iron_ore", self.Entity:GetPosition(), killer)

Inventory.ServiceItem#

lua

Inventory.ServiceItem(actor: Entity, container: string, slot: integer, quantity?: integer): table?

The item table a guild bank, mail or market request carries for a slot's stack (or a quantity of it): the Item of Guild.Deposit, of Mail.Send's attachments and of Market.CreateListing. nil for an empty slot, an unknown item or more than the stack holds.

Parameters

actor (Entity): The character.
container (string): Backpack, Bank or AccountBank.
slot (integer): The slot, from 1.
quantity? (integer): How many (default the whole stack).

Returns table?

Example

lua

Guild.Deposit(client, { Tab = 0, Slot = 3, Item = Inventory.ServiceItem(player, "Backpack", 1, 5), Quantity = 5 })

Inventory.Escrow#

lua

Inventory.Escrow(actor: Entity, transfer: table, operands: string[]): boolean, string?

The character side of a guild bank, mail or market transfer with real slots (servers): transfer = { Kind = "mail" | "guild-bank" | "market", Take = { { Container?, Slot, Quantity?, Item } } (no Quantity: the whole stack; Item: the ServiceItem table the request carried), Give = { item tables }, Currency = { gold = -50 } }; operands are the Operand strings of the service's result (one transfer). The stacks and currency leave or arrive at once and commit with the operands in one central transaction; until it is done the character's containers refuse other changes, and a failed or expired transfer restores everything. True when the transfer started: OnServiceTransferResult(transferId, ok, message) reports the outcome (OnItemAdded and OnItemRemoved follow a commit). False and "<Refusal>: <why>" when the request does not fit (bound items, no room, too little currency, a transfer in flight) or the operands are not a service's authorization (NotAllowed). NotAllowed too when a slot no longer holds its Take's Item (the player moved another stack into it while the service decided) or the stacks that would leave are not exactly the ones the operands take from the character: nothing changes, and the script drops the authorization (Guild.ConfirmTransfer or Mail.ConfirmTransfer with false).

Parameters

actor (Entity): The character.
transfer (table): What leaves and arrives.
operands (string[]): The service result's Operand strings.

Returns boolean, string?

Example

lua

function Banker:OnServiceResult(requestId, ok, result)
	if ok and result.Operand then
		Inventory.Escrow(self.Hero, { Kind = "guild-bank", Take = { { Slot = self.Slot, Quantity = 5, Item = self.Item } } }, { result.Operand })
	end
end

Items#

The item database: every table whose schema is the built-in Item schema or derives from it (Weapon, Armor, ...), keys unique across them. Items are DataRows with the Item columns (Name, Description, Icon, Quality, Category, MaxStack, Value, Weight, EquipSlot, Tradable, Tags, Use) and their own schema's.

lua

local item = Items.Get("iron_sword")
if item then Log.Info(item.Name .. " is worth " .. item.Value) end

Member	Kind	Summary
`Items.Get(key: string): DataRow?`	Function	The item with the key; nil when there is none.
`Items.GetQuality(key: string): DataRow?`	Function	The ItemQuality row of the item with the key (its Name, Color, Order); nil when the item does not exist or has no quality.

Items.Get#

lua

Items.Get(key: string): DataRow?

The item with the key; nil when there is none.

Parameters

key (string): The item's key.

Returns DataRow?

Example

lua

local item = Items.Get("bronze_dagger")

Items.GetQuality#

lua

Items.GetQuality(key: string): DataRow?

The ItemQuality row of the item with the key (its Name, Color, Order); nil when the item does not exist or has no quality.

Parameters

key (string): The item's key.

Returns DataRow?

Example

lua

local quality = Items.GetQuality("iron_sword")
if quality then label.Color = quality.Color end

Leaderboards#

Ranked boards of the game (Assets/Services/Leaderboards.json): zone scripts submit scores for their players, everyone reads the top, a rank and the window around it. Periods (AllTime, Daily, Weekly, Season) roll over at UTC boundaries. Results arrive as OnLeaderboardResult(requestId, ok, result).

lua

function Arena:OnWin(client, characterId)
    Leaderboards.Submit("Wins", characterId, 1, Net.GetPlayerName(client))
end

Member	Kind	Summary
`Leaderboards.GetTop(board: string, count: integer, period?: string\|integer): integer`	Function	The best count (1-100) entries: OnLeaderboardResult's Entries ({ Rank, CharacterId, Name, Score }) and Total.
`Leaderboards.GetRank(board: string, characterId?: integer, period?: string\|integer): integer`	Function	A character's entry with its rank (Entries[1]); characterId nil: the player's own.
`Leaderboards.GetAround(board: string, characterId?: integer, count: integer, period?: string\|integer): integer`	Function	count entries centered on a character's (the character in the middle where the board allows); characterId nil: the player's own.
`Leaderboards.Submit(board: string, characterId: integer, score: integer, name: string): integer`	Function	Zone scripts only (clients never submit): records a score for a character of this zone under the board's rule (Best keeps the better one, Latest the last, Sum adds), in the current period.
`Leaderboards.SubmitPlayer(client: integer, board: string, score: integer): integer`	Function	Zone scripts only: Submit for a connected player, whose character and name come from its verified identity (the session token).

Leaderboards.GetTop#

lua

Leaderboards.GetTop(board: string, count: integer, period?: string|integer): integer

The best count (1-100) entries: OnLeaderboardResult's Entries ({ Rank, CharacterId, Name, Score }) and Total. period: nil for the current one, "previous", or a period number.

Parameters

board (string)
count (integer)
period? (string|integer)

Returns integer

Leaderboards.GetRank#

lua

Leaderboards.GetRank(board: string, characterId?: integer, period?: string|integer): integer

A character's entry with its rank (Entries[1]); characterId nil: the player's own. "notFound" without an entry in the period.

Parameters

board (string)
characterId? (integer)
period? (string|integer)

Returns integer

Leaderboards.GetAround#

lua

Leaderboards.GetAround(board: string, characterId?: integer, count: integer, period?: string|integer): integer

count entries centered on a character's (the character in the middle where the board allows); characterId nil: the player's own.

Parameters

board (string)
characterId? (integer)
count (integer)
period? (string|integer)

Returns integer

Leaderboards.Submit#

lua

Leaderboards.Submit(board: string, characterId: integer, score: integer, name: string): integer

Zone scripts only (clients never submit): records a score for a character of this zone under the board's rule (Best keeps the better one, Latest the last, Sum adds), in the current period. Scores outside the board's MinScore-MaxScore are refused. The result (Kind "submit") arrives once the score is stored.

Parameters

board (string)
characterId (integer)
score (integer)
name (string)

Returns integer

Leaderboards.SubmitPlayer#

lua

Leaderboards.SubmitPlayer(client: integer, board: string, score: integer): integer

Zone scripts only: Submit for a connected player, whose character and name come from its verified identity (the session token). A client without one gets an "unavailable" result (Kind "submit").

Parameters

client (integer)
board (string)
score (integer)

Returns integer

Log#

Messages in the engine log (editor console, log file), prefixed with the script location "[Assets/Scripts/Player.lua:12]". Arguments are converted with tostring and separated by tabs. The editor shows every message (its Console, log.get and play-test results); a game running on its own - an exported game or a server of the release - logs only Log.Warn and Log.Error.

lua

Log.Info("Score:", score)
Log.Warn("Health is low")

Member	Kind	Summary
`Log.Info(...: any)`	Function	Logs an informational message.
`Log.Warn(...: any)`	Function	Logs a warning.
`Log.Error(...: any)`	Function	Logs an error without stopping the script (use error() to stop it).

Log.Info#

lua

Log.Info(...: any)

Logs an informational message.

Parameters

...? (any)

Example

lua

Log.Info("Spawned", count, "enemies")

Log.Warn#

lua

Log.Warn(...: any)

Logs a warning.

Parameters

...? (any)

Log.Error#

lua

Log.Error(...: any)

Logs an error without stopping the script (use error() to stop it).

Parameters

...? (any)

Backend service scripts (Assets/Services/*.lua on FrostServices) extend the login service: a game's own second factor (hardware tokens, e-mail codes) beside or instead of the built-in TOTP.

lua

Login.SetSecondFactorHook(function(account, code)
    if code == nil then return Vip[account] == true end
    return Codes.Check(account, code)
end)

Member	Kind	Summary
`Login.SetSecondFactorHook(fn?: function): function?`	Function	Installs fn(account, code): called with code nil to ask whether the account needs a second factor (true or false; nil = the built-in rules: an enrolled TOTP secret or a privileged role), and with the code the player typed to check it (true accepts, false refuses and counts as a failed login, nil = the built-in TOTP decides).

Login.SetSecondFactorHook#

lua

Login.SetSecondFactorHook(fn?: function): function?

Installs fn(account, code): called with code nil to ask whether the account needs a second factor (true or false; nil = the built-in rules: an enrolled TOTP secret or a privileged role), and with the code the player typed to check it (true accepts, false refuses and counts as a failed login, nil = the built-in TOTP decides). An error refuses the login. nil removes the hook. Returns the previous hook. In game scripts it only records the function.

Parameters

fn? (function)

Returns function?

Loot#

Loot tables (rows of tables of the built-in LootTable schema): the deterministic roller the server uses - Guaranteed entries always drop, Independent ones roll their Chance, Rolls picks among the Weighted ones, Table entries roll nested tables; every Condition passes here.

lua

for _, drop in ipairs(Loot.Roll("goblin", seed)) do
	Log.Info(drop.Quantity .. " x " .. drop.Item)
end

Member	Kind	Summary
`Loot.Roll(lootTable: string\|DataRow, seed: integer, rolls?: integer): { Item: string, Quantity: integer }[]`	Function	Rolls a loot table `rolls` times (1-1000, default 1) with a generator seeded with `seed`: the same seed always gives the same drops, in roll order.
`Loot.Simulate(lootTable: string\|DataRow, kills: integer, seed: integer): { Kills: integer, Items: { Item: string, DropRate: number, AverageQuantity: number, Chance: number, Conditional: boolean }[] }`	Function	Rolls a loot table for `kills` kills (1-1,000,000) and reports per item (by key) the share of kills that dropped it, the average quantity per kill and its exact drop chance (Conditional: an entry it drops through has a Condition, assumed to pass).

Loot.Roll#

lua

Loot.Roll(lootTable: string|DataRow, seed: integer, rolls?: integer): { Item: string, Quantity: integer }[]

Rolls a loot table rolls times (1-1000, default 1) with a generator seeded with seed: the same seed always gives the same drops, in roll order. An error for a table that cannot be rolled (nested too deep, or more than 65,536 picks in one roll: nested Rolls multiply) or more than 1024 drops in one roll.

Parameters

lootTable (string|DataRow): The loot table's key (LootTable family) or its DataRow.
seed (integer): The generator's seed (>= 0).
rolls? (integer): How many times to roll (default 1).

Returns { Item: string, Quantity: integer }[]

Example

lua

local drops = Loot.Roll("goblin", 42)

Loot.Simulate#

lua

Loot.Simulate(lootTable: string|DataRow, kills: integer, seed: integer): { Kills: integer, Items: { Item: string, DropRate: number, AverageQuantity: number, Chance: number, Conditional: boolean }[] }

Rolls a loot table for kills kills (1-1,000,000) and reports per item (by key) the share of kills that dropped it, the average quantity per kill and its exact drop chance (Conditional: an entry it drops through has a Condition, assumed to pass). The same seed gives the same report as loot.simulate. An error like Loot.Roll's, or for more than 4096 drops in one kill.

Parameters

lootTable (string|DataRow): The loot table's key or DataRow.
kills (integer): The number of kills.
seed (integer): The generator's seed.

Returns { Kills: integer, Items: { Item: string, DropRate: number, AverageQuantity: number, Chance: number, Conditional: boolean }[] }

Example

lua

local report = Loot.Simulate("goblin", 10000, 7)
for _, item in ipairs(report.Items) do
	Log.Info(item.Item .. ": " .. item.DropRate)
end

LootDrops#

Loot of dead NPCs and items on the ground (Items.LootMode: Personal, Shared, RoundRobin, Ground): rolled from the NPC template's loot table when the kill is credited, or created by scripts.

lua

LootDrops.Create(chest, { player }, "chest_drops")
LootDrops.Take(player, chest)

Member	Kind	Summary
`LootDrops.Create(corpse: Entity, players: Entity[], table: string, seconds?: number): boolean, string?`	Function	Rolls a LootTable row onto an entity for the credited players (in party order) under Items.LootMode, lootable for seconds (default 300).
`LootDrops.Add(corpse: Entity, players: Entity[], items: (string\|table)[]): boolean, string?`	Function	Adds items to an entity's loot: each player gets its own copy; an empty players list shares them among the credited players.
`LootDrops.Get(corpse: Entity, looter: Entity): table`	Function	The item tables the looter may take from the entity, in take order.
`LootDrops.Take(looter: Entity, corpse: Entity, index?: integer): boolean, string?`	Function	Takes one item (index, from 1, in Get's order) or everything that fits into the looter's backpack.
`LootDrops.HasLoot(corpse: Entity): boolean`	Function	Whether anyone may still take something from the entity.
`LootDrops.PickUp(player: Entity, groundItem: Entity): boolean, string?`	Function	Picks up a ground item in range that the player may see (its owner first, everyone later).
`LootDrops.CanSee(groundItem: Entity, player: Entity): boolean`	Function	Whether the player may see and take the ground item now.

LootDrops.Create#

lua

LootDrops.Create(corpse: Entity, players: Entity[], table: string, seconds?: number): boolean, string?

Rolls a LootTable row onto an entity for the credited players (in party order) under Items.LootMode, lootable for seconds (default 300). The roll is deterministic for the entity and the tick.

Parameters

corpse (Entity): The entity holding the loot.
players (Entity[]): The credited players.
table (string): The LootTable row key.
seconds? (number): How long the loot lasts.

Returns boolean, string?

Example

lua

LootDrops.Create(chest, { player }, "chest_drops", 60)

LootDrops.Add#

lua

LootDrops.Add(corpse: Entity, players: Entity[], items: (string|table)[]): boolean, string?

Adds items to an entity's loot: each player gets its own copy; an empty players list shares them among the credited players. All or nothing: refused, adding nothing, when a stack is not an item or the entity would hold more than 64 entries.

Parameters

corpse (Entity): The entity holding the loot.
players (Entity[]): Who may take the items.
items ((string|table)[]): Item keys or item tables.

Returns boolean, string?

Example

lua

LootDrops.Add(boss, { player }, { "boss_key" })

LootDrops.Get#

lua

LootDrops.Get(corpse: Entity, looter: Entity): table

The item tables the looter may take from the entity, in take order. On a client: the local character's loot window from the RPG lane when it shows this entity; empty otherwise and for any other looter.

Parameters

corpse (Entity): The entity holding the loot.
looter (Entity): The player.

Returns table

Example

lua

for index, item in ipairs(LootDrops.Get(wolf, player)) do Log.Info(index .. ": " .. item.Key) end

LootDrops.Take#

lua

LootDrops.Take(looter: Entity, corpse: Entity, index?: integer): boolean, string?

Takes one item (index, from 1, in Get's order) or everything that fits into the looter's backpack.

Parameters

looter (Entity): The player.
corpse (Entity): The entity holding the loot.
index? (integer): The item (default all).

Returns boolean, string?

Example

lua

LootDrops.Take(player, wolf)

LootDrops.HasLoot#

lua

LootDrops.HasLoot(corpse: Entity): boolean

Whether anyone may still take something from the entity.

Parameters

corpse (Entity): The entity.

Returns boolean

Example

lua

if not LootDrops.HasLoot(wolf) then wolf:Destroy() end

LootDrops.PickUp#

lua

LootDrops.PickUp(player: Entity, groundItem: Entity): boolean, string?

Picks up a ground item in range that the player may see (its owner first, everyone later).

Parameters

player (Entity): The character.
groundItem (Entity): A GroundItem entity.

Returns boolean, string?

Example

lua

LootDrops.PickUp(player, drop)

LootDrops.CanSee#

lua

LootDrops.CanSee(groundItem: Entity, player: Entity): boolean

Whether the player may see and take the ground item now.

Parameters

groundItem (Entity): A GroundItem entity.
player (Entity): The character.

Returns boolean

Example

lua

UI.SetVisible(pickUpHint, LootDrops.CanSee(drop, player))

Mail#

Persistent character mail. Results arrive through OnServiceResult; new deliveries through OnMailReceived.

Member	Kind	Summary
`Mail.Inbox(page?: integer): integer?, string?`	Function	Lists Mails and Total.
`Mail.Read(mailId: integer): integer?, string?`	Function	Marks the caller's mail read and returns Mail with Body, Attachments and Currency alongside its summary.
`Mail.Delete(mailId: integer): integer?, string?`	Function	Deletes the caller's mail only after all attachments and currency have been collected.
`Mail.Return(mailId: integer): integer?, string?`	Function	Returns ordinary mail with its remaining attachments to its sender.
`Mail.Send(clientId: integer, data: table): integer?, string?`	Function	Zone scripts: authorize mail from this client.
`Mail.TakeAttachments(clientId: integer, mailId: integer): integer?, string?`	Function	Zone scripts: authorize collection from this client's mail.
`Mail.ConfirmTransfer(transferId: integer, committed: boolean): boolean`	Function	Zone scripts: tells the mail service the outcome of a Send or TakeAttachments authorization.
`Mail.SendSystem(characterId: integer, data: table): integer?, string?`	Function	Zone scripts: creates system mail containing Subject,Body,Attachments,Currency for a character, subject to the service item validator and inbox limits.

Mail.Inbox#

lua

Mail.Inbox(page?: integer): integer?, string?

Lists Mails and Total. Pages begin at zero; each summary includes MailId, FromName, Subject, Read, HasAttachments, expiry and System.

Parameters

page? (integer)

Returns integer?, string?

Mail.Read#

lua

Mail.Read(mailId: integer): integer?, string?

Marks the caller's mail read and returns Mail with Body, Attachments and Currency alongside its summary.

Parameters

mailId (integer)

Returns integer?, string?

Mail.Delete#

lua

Mail.Delete(mailId: integer): integer?, string?

Deletes the caller's mail only after all attachments and currency have been collected.

Parameters

mailId (integer)

Returns integer?, string?

Mail.Return#

lua

Mail.Return(mailId: integer): integer?, string?

Returns ordinary mail with its remaining attachments to its sender. System mail cannot be returned.

Parameters

mailId (integer)

Returns integer?, string?

Mail.Send#

lua

Mail.Send(clientId: integer, data: table): integer?, string?

Zone scripts: authorize mail from this client. data: To,Subject,Body,Attachments={{Item,Quantity},...},Currency. Result includes MailId,RequiresTransaction,Postage and the signed Ledger. When RequiresTransaction is true, TransferId and Operand are present: commit the matching character debit through Persistence.Transact(changes,{}, {result.Operand}). The operand already records its ledger centrally; the commit tells the service the outcome (Mail.ConfirmTransfer(TransferId, false) drops it). Free mail without attachments needs no transaction, and a zone without central persistence can send only that (when Mail.json charges no postage).

Parameters

clientId (integer)
data (table)

Returns integer?, string?

Mail.TakeAttachments#

lua

Mail.TakeAttachments(clientId: integer, mailId: integer): integer?, string?

Zone scripts: authorize collection from this client's mail. Result includes Attachments,Currency,TransferId,Operand. Credit the character with Persistence.Transact; attachments remain locked until the central outcome is known (Mail.ConfirmTransfer(TransferId, false) releases them when the script drops the authorization).

Parameters

clientId (integer)
mailId (integer)

Returns integer?, string?

Mail.ConfirmTransfer#

lua

Mail.ConfirmTransfer(transferId: integer, committed: boolean): boolean

Zone scripts: tells the mail service the outcome of a Send or TakeAttachments authorization. Persistence.Transact confirms the transfers it commits by itself; call ConfirmTransfer(transferId, false) when the script drops an authorization, which releases the mail's attachments (or removes the unsent mail) at once instead of when the authorization expires. Returns false when the scene awaits no such mail transfer.

Parameters

transferId (integer)
committed (boolean)

Returns boolean

Mail.SendSystem#

lua

Mail.SendSystem(characterId: integer, data: table): integer?, string?

Zone scripts: creates system mail containing Subject,Body,Attachments,Currency for a character, subject to the service item validator and inbox limits. Returns MailId asynchronously. There is no sender debit.

Parameters

characterId (integer)
data (table)

Returns integer?, string?

Market#

The game's auction houses and exchanges (Assets/Services/Market.json). Game clients search and read their listings, offers and price history; zone scripts move items and currency for their players: each such call answers an escrow authorization the script commits with the character's records (Persistence.Transact) and confirms with Market.ConfirmTransfer. Every call returns a request id; its result arrives once as OnMarketResult(requestId, ok, result) - "unavailable" when the market cannot be reached.

lua

function Shop:Browse()
    self.Search = Market.Search({ Market = "AuctionHouse", Filters = { { Attribute = "level", Min = 10, Max = 20 } }, Sort = "price" })
end

function Shop:OnMarketResult(id, ok, result)
    if id == self.Search and ok then self:Show(result.Listings, result.Next) end
end

Member	Kind	Summary
`Market.Search(query: table): integer`	Function	Searches a market: query = { Market, Filters = { { Attribute, Min, Max } (integer ranges), { Attribute, Text } (an enum value or a text prefix, compared ignoring ASCII case) } (at most 3), Sort ("price", "expires" or an attribute; default price), Descending, Limit (1-100, default 50), After (the Next of the previous page) }.
`Market.GetMyListings(market: string): integer`	Function	The player's auction listings that are open or hold something to collect, the listings it holds the bid on and those it can collect from (refunds, won items): OnMarketResult's Listings, each with CollectableItems and CollectableCurrency for this player.
`Market.GetMyOffers(market: string): integer`	Function	The player's exchange offers that are open or hold something to collect: OnMarketResult's Offers ({ OfferId, ItemKey, Buy, PricePerUnit, Quantity, Filled, CollectableItems, CollectableCurrency, CreatedAtUnixMs }).
`Market.GetPriceHistory(market: string, itemKey: string, days: integer): integer`	Function	The daily trades of an item type over the last days (at most the market's HistoryDays): OnMarketResult's History ({ DayUnix (seconds), Average (per unit), Volume (items) }), oldest first, days without trades left out.
`Market.CreateListing(client: integer, listing: table): integer`	Function	Zone scripts: lists an item of a connected player in an auction market: listing = { Market, Item (a table or JSON text: the game's item, with the market's ItemKey and searchable attributes), Quantity, StartBid, Buyout (0: none), Hours (one of the market's durations) }.
`Market.Bid(client: integer, listingId: integer, amount: integer): integer`	Function	Zone scripts: bids for a player (at least the starting bid, then the current bid plus MinBidIncrementPercent; below the buyout; never on a listing of the player's own account).
`Market.Buyout(client: integer, listingId: integer): integer`	Function	Zone scripts: buys a listing out for a player: the transfer takes the buyout price (Currency negative, no Items).
`Market.CancelListing(client: integer, listingId: integer): integer`	Function	Zone scripts: the seller cancels a listing without bids: the item returns in the transfer, the deposit is kept.
`Market.PlaceOffer(client: integer, offer: table): integer`	Function	Zone scripts: places a buy or sell offer in an exchange market for a player: offer = { Market, ItemKey, Item (the item type's JSON with that key), Buy, Price (per unit), Quantity }.
`Market.CancelOffer(client: integer, offerId: integer): integer`	Function	Zone scripts: cancels an exchange offer: the transfer returns what is unfilled and everything to collect.
`Market.Collect(client: integer, id: integer): integer`	Function	Zone scripts: collects what a player can take from an auction listing (proceeds, refunded bids, won or returned items) or an exchange offer (bought items, proceeds, the reserve above the trade price).
`Market.ConfirmTransfer(transferId: integer, committed: boolean): integer`	Function	Zone scripts: tells the market whether a transfer's Persistence.Transact committed (true) or not (false).

Market.Search#

lua

Market.Search(query: table): integer

Searches a market: query = { Market, Filters = { { Attribute, Min, Max } (integer ranges), { Attribute, Text } (an enum value or a text prefix, compared ignoring ASCII case) } (at most 3), Sort ("price", "expires" or an attribute; default price), Descending, Limit (1-100, default 50), After (the Next of the previous page) }. OnMarketResult's result has Listings ({ ListingId, SellerName, Item, ItemKey, Quantity, StartBid, CurrentBid, Buyout, ExpiresAtUnixMs, Bids, State, HighBidder }) and Next while more pages follow. Exchange markets list item types (ListingId 0, Quantity on sale, Buyout the lowest ask, CurrentBid the highest bid). At most 2 searches a second per character.

Parameters

query (table)

Returns integer

Example

lua

self.Page = Market.Search({ Market = "AuctionHouse", Filters = { { Attribute = "name", Text = "iron" } }, Limit = 20 })

Market.GetMyListings#

lua

Market.GetMyListings(market: string): integer

The player's auction listings that are open or hold something to collect, the listings it holds the bid on and those it can collect from (refunds, won items): OnMarketResult's Listings, each with CollectableItems and CollectableCurrency for this player.

Parameters

market (string)

Returns integer

Market.GetMyOffers#

lua

Market.GetMyOffers(market: string): integer

The player's exchange offers that are open or hold something to collect: OnMarketResult's Offers ({ OfferId, ItemKey, Buy, PricePerUnit, Quantity, Filled, CollectableItems, CollectableCurrency, CreatedAtUnixMs }).

Parameters

market (string)

Returns integer

Market.GetPriceHistory#

lua

Market.GetPriceHistory(market: string, itemKey: string, days: integer): integer

The daily trades of an item type over the last days (at most the market's HistoryDays): OnMarketResult's History ({ DayUnix (seconds), Average (per unit), Volume (items) }), oldest first, days without trades left out.

Parameters

market (string)
itemKey (string)
days (integer)

Returns integer

Market.CreateListing#

lua

Market.CreateListing(client: integer, listing: table): integer

Zone scripts: lists an item of a connected player in an auction market: listing = { Market, Item (a table or JSON text: the game's item, with the market's ItemKey and searchable attributes), Quantity, StartBid, Buyout (0: none), Hours (one of the market's durations) }. OnMarketResult's result has TransferId, ListingId, Operand (the escrow authorization to commit with Persistence.Transact), Currency and Items (what the character gives: the item and the deposit, as negative amounts) and the Ledger. The listing opens once Market.ConfirmTransfer(TransferId, true) arrives.

Parameters

client (integer)
listing (table)

Returns integer

Market.Bid#

lua

Market.Bid(client: integer, listingId: integer, amount: integer): integer

Zone scripts: bids for a player (at least the starting bid, then the current bid plus MinBidIncrementPercent; below the buyout; never on a listing of the player's own account). The previous bidder's bid becomes theirs to collect and they get OnMarketEvent Outbid. The result is an escrow transfer like CreateListing's (Currency: -amount).

Parameters

client (integer)
listingId (integer)
amount (integer)

Returns integer

Market.Buyout#

lua

Market.Buyout(client: integer, listingId: integer): integer

Zone scripts: buys a listing out for a player: the transfer takes the buyout price (Currency negative, no Items). The item waits for the buyer, who takes it with Collect(client, listingId) (OnMarketEvent Won); the seller gets OnMarketEvent Sold and collects the proceeds the same way.

Parameters

client (integer)
listingId (integer)

Returns integer

Market.CancelListing#

lua

Market.CancelListing(client: integer, listingId: integer): integer

Zone scripts: the seller cancels a listing without bids: the item returns in the transfer, the deposit is kept.

Parameters

client (integer)
listingId (integer)

Returns integer

Market.PlaceOffer#

lua

Market.PlaceOffer(client: integer, offer: table): integer

Zone scripts: places a buy or sell offer in an exchange market for a player: offer = { Market, ItemKey, Item (the item type's JSON with that key), Buy, Price (per unit), Quantity }. A buy offer reserves Price x Quantity, a sell offer the items. Once confirmed it matches at once against the book (the resting offer's price, oldest first, never the same account); fills are collected from the offer (Market.Collect) and announced with OnMarketEvent OfferFilled.

Parameters

client (integer)
offer (table)

Returns integer

Market.CancelOffer#

lua

Market.CancelOffer(client: integer, offerId: integer): integer

Zone scripts: cancels an exchange offer: the transfer returns what is unfilled and everything to collect.

Parameters

client (integer)
offerId (integer)

Returns integer

Market.Collect#

lua

Market.Collect(client: integer, id: integer): integer

Zone scripts: collects what a player can take from an auction listing (proceeds, refunded bids, won or returned items) or an exchange offer (bought items, proceeds, the reserve above the trade price).

Parameters

client (integer)
id (integer)

Returns integer

Market.ConfirmTransfer#

lua

Market.ConfirmTransfer(transferId: integer, committed: boolean): integer

Zone scripts: tells the market whether a transfer's Persistence.Transact committed (true) or not (false). Exactly once per transfer; a transfer never confirmed keeps its listing or offer locked and is listed by market.transfers.

Parameters

transferId (integer)
committed (boolean)

Returns integer

Matchmaking#

Queues for instances (Assets/Services/Matchmaking.json): a player (or a party, by its leader) joins with the roles it can fill; when a group forms everyone gets OnMatchFound and answers RespondReady; when all accepted the coordinator creates the instance, moves the group there and OnMatchReady follows. Results arrive as OnMatchmakingResult(requestId, ok, result).

lua

Matchmaking.Join("Dungeon", { "Tank", "Damage" })

function Lobby:OnMatchFound(matchId, queue, readySeconds, role)
    Matchmaking.RespondReady(matchId, true)
end

Member	Kind	Summary
`Matchmaking.Join(queue: string, roles?: table, asParty?: boolean): integer`	Function	Queues the player (asParty: its whole party; only the leader may) with the roles it can fill (names of the queue's Roles; none for queues without roles).
`Matchmaking.Leave(): integer`	Function	Leaves the queue (a party's ticket for every member); a match being formed for it is cancelled.
`Matchmaking.RespondReady(matchId: integer, ready: boolean): integer`	Function	Accepts (true) or declines (false) a found match within its ready check; a decline or silence cancels the match for everyone (OnMatchCancelled) and takes the player out of the queue, the others keep their place.

Matchmaking.Join#

lua

Matchmaking.Join(queue: string, roles?: table, asParty?: boolean): integer

Queues the player (asParty: its whole party; only the leader may) with the roles it can fill (names of the queue's Roles; none for queues without roles). OnMatchmakingResult's Ticket identifies the place in the queue.

Parameters

queue (string)
roles? (table)
asParty? (boolean)

Returns integer

Matchmaking.Leave#

lua

Matchmaking.Leave(): integer

Leaves the queue (a party's ticket for every member); a match being formed for it is cancelled.

Returns integer

Matchmaking.RespondReady#

lua

Matchmaking.RespondReady(matchId: integer, ready: boolean): integer

Accepts (true) or declines (false) a found match within its ready check; a decline or silence cancels the match for everyone (OnMatchCancelled) and takes the player out of the queue, the others keep their place.

Parameters

matchId (integer)
ready (boolean)

Returns integer

Math#

Scalar math helpers and the scene's deterministic random generator (PCG32, seeded per scene).

lua

local t = Math.Clamp01(elapsed / duration)
local x = Math.Lerp(startX, endX, Math.SmoothStep(0, 1, t))

Member	Kind	Summary
`Math.Lerp(a: number, b: number, t: number): number`	Function	Linear interpolation: a at t = 0, b at t = 1 (not clamped).
`Math.Clamp(value: number, min: number, max: number): number`	Function	value limited to [min, max] (integers stay integers).
`Math.Clamp01(value: number): number`	Function	value limited to [0, 1].
`Math.InverseLerp(a: number, b: number, value: number): number`	Function	The t for which Lerp(a, b, t) == value (not clamped); 0 when a == b.
`Math.Remap(value: number, inMin: number, inMax: number, outMin: number, outMax: number): number`	Function	Maps value from [inMin, inMax] to [outMin, outMax] (not clamped).
`Math.SmoothStep(edge0: number, edge1: number, x: number): number`	Function	Hermite interpolation: 0 at or below edge0, 1 at or above edge1, smooth in between.
`Math.MoveTowards(current: number\|Vec2, target: number\|Vec2, maxDelta: number): number\|Vec2`	Function	Moves current towards target by at most maxDelta without overshooting (numbers or Vec2 positions).
`Math.Sign(x: number): integer`	Function	-1, 0 or 1.
`Math.Round(x: number): integer`	Function	The nearest integer (halves away from zero).
`Math.DegToRad(degrees: number): number`	Function	Converts degrees to radians.
`Math.RadToDeg(radians: number): number`	Function	Converts radians to degrees.
`Math.PingPong(t: number, length: number): number`	Function	Bounces t back and forth between 0 and length (0 for a length <= 0).
`Math.WrapAngle(radians: number): number`	Function	The equivalent angle in [-pi, pi).
`Math.Approximately(a: number, b: number, tolerance?: number): boolean`	Function	True when \|a - b\| <= tolerance * max(1, \|a\|, \|b\|) (default tolerance 1e-5).
`Math.Random(): number`	Function	A uniform random number in [0, 1) from the scene's seeded generator (deterministic for a given seed).
`Math.RandomRange(min: number, max: number): number`	Function	A uniform random number in [min, max).
`Math.RandomInt(min: integer, max: integer): integer`	Function	A uniform random integer in [min, max], both inclusive (32-bit bounds).
`Math.RandomInsideUnitCircle(): Vec2`	Function	A uniform random point inside the unit circle.
`Math.RandomOnUnitCircle(): Vec2`	Function	A uniform random direction (length 1).
`Math.SetSeed(seed: integer)`	Function	Restarts the scene's random sequence from a seed (replays, tests).
`Math.Pi: number (read-only)`	Constant	pi (half a turn in radians).
`Math.TwoPi: number (read-only)`	Constant	2 pi (a full turn in radians).
`Math.HalfPi: number (read-only)`	Constant	pi / 2 (a quarter turn in radians).

Math.Lerp#

lua

Math.Lerp(a: number, b: number, t: number): number

Linear interpolation: a at t = 0, b at t = 1 (not clamped).

Parameters

a (number)
b (number)
t (number)

Returns number

Example

lua

Math.Lerp(0, 10, 0.25) -- 2.5

Math.Clamp#

lua

Math.Clamp(value: number, min: number, max: number): number

value limited to [min, max] (integers stay integers). Raises an error when min > max.

Parameters

value (number)
min (number)
max (number)

Returns number

Math.Clamp01#

lua

Math.Clamp01(value: number): number

value limited to [0, 1].

Parameters

value (number)

Returns number

Math.InverseLerp#

lua

Math.InverseLerp(a: number, b: number, value: number): number

The t for which Lerp(a, b, t) == value (not clamped); 0 when a == b.

Parameters

a (number)
b (number)
value (number)

Returns number

Math.Remap#

lua

Math.Remap(value: number, inMin: number, inMax: number, outMin: number, outMax: number): number

Maps value from [inMin, inMax] to [outMin, outMax] (not clamped).

Parameters

value (number)
inMin (number)
inMax (number)
outMin (number)
outMax (number)

Returns number

Math.SmoothStep#

lua

Math.SmoothStep(edge0: number, edge1: number, x: number): number

Hermite interpolation: 0 at or below edge0, 1 at or above edge1, smooth in between.

Parameters

edge0 (number)
edge1 (number)
x (number)

Returns number

Math.MoveTowards#

lua

Math.MoveTowards(current: number|Vec2, target: number|Vec2, maxDelta: number): number|Vec2

Moves current towards target by at most maxDelta without overshooting (numbers or Vec2 positions).

Parameters

current (number|Vec2)
target (number|Vec2)
maxDelta (number)

Returns number|Vec2

Example

lua

self.Entity.Position = Math.MoveTowards(self.Entity.Position, goal, speed * dt)

Math.Sign#

lua

Math.Sign(x: number): integer

-1, 0 or 1.

Parameters

x (number)

Returns integer

Math.Round#

lua

Math.Round(x: number): integer

The nearest integer (halves away from zero).

Parameters

x (number)

Returns integer

Math.DegToRad#

lua

Math.DegToRad(degrees: number): number

Converts degrees to radians.

Parameters

degrees (number)

Returns number

Math.RadToDeg#

lua

Math.RadToDeg(radians: number): number

Converts radians to degrees.

Parameters

radians (number)

Returns number

Math.PingPong#

lua

Math.PingPong(t: number, length: number): number

Bounces t back and forth between 0 and length (0 for a length <= 0).

Parameters

t (number)
length (number)

Returns number

Example

lua

local y = Math.PingPong(Time.Time, 2)

Math.WrapAngle#

lua

Math.WrapAngle(radians: number): number

The equivalent angle in [-pi, pi).

Parameters

radians (number)

Returns number

Math.Approximately#

lua

Math.Approximately(a: number, b: number, tolerance?: number): boolean

True when |a - b| <= tolerance * max(1, |a|, |b|) (default tolerance 1e-5).

Parameters

a (number)
b (number)
tolerance? (number)

Returns boolean

Math.Random#

lua

Math.Random(): number

A uniform random number in [0, 1) from the scene's seeded generator (deterministic for a given seed).

Returns number

Math.RandomRange#

lua

Math.RandomRange(min: number, max: number): number

A uniform random number in [min, max).

Parameters

min (number)
max (number)

Returns number

Math.RandomInt#

lua

Math.RandomInt(min: integer, max: integer): integer

A uniform random integer in [min, max], both inclusive (32-bit bounds).

Parameters

min (integer)
max (integer)

Returns integer

Math.RandomInsideUnitCircle#

lua

Math.RandomInsideUnitCircle(): Vec2

A uniform random point inside the unit circle.

Returns Vec2

Math.RandomOnUnitCircle#

lua

Math.RandomOnUnitCircle(): Vec2

A uniform random direction (length 1).

Returns Vec2

Math.SetSeed#

lua

Math.SetSeed(seed: integer)

Restarts the scene's random sequence from a seed (replays, tests).

Parameters

seed (integer)

Example

lua

Math.SetSeed(42)

Math.Pi#

lua

Math.Pi: number (read-only)

pi (half a turn in radians).

Math.TwoPi#

lua

Math.TwoPi: number (read-only)

2 pi (a full turn in radians).

Math.HalfPi#

lua

Math.HalfPi: number (read-only)

pi / 2 (a quarter turn in radians).

Metrics#

The game's own metrics beside the engine's (Docs/Operations.md, "Metrics"): counters, gauges and histograms named game_<name>_<unit> that the server's Prometheus endpoint (FrostRuntime --metrics-address) exposes. Labels are bounded (8 per metric, 1,024 value combinations); never use player or account ids as label values.

lua

Metrics.Define({ Name = "game_bosses_killed_total", Kind = "Counter", Help = "Bosses killed.", Labels = { "boss" } })
Metrics.Add("game_bosses_killed_total", 1, { boss = "Ragnaros" })

Member	Kind	Summary
`Metrics.Define(definition: table): boolean`	Function	Defines a metric { Name, Kind ("Counter", "Gauge" or "Histogram"; default Counter), Help, Labels (label names), Buckets (a histogram's ascending upper bounds) }.
`Metrics.Add(name: string, value?: number, labels?: table)`	Function	Adds `value` (default 1) to a counter (never negative) or a gauge, for the { label = "value" } series (labels not given are "").
`Metrics.Set(name: string, value: number, labels?: table)`	Function	Sets a gauge's series to `value`.
`Metrics.Observe(name: string, value: number, labels?: table)`	Function	Counts `value` into a histogram's buckets (its sum and count grow too).
`Metrics.Get(name: string, labels?: table): number\|table`	Function	A counter's or gauge's value for the series, or a histogram's { Count, Sum } (tests and debug screens).

Metrics.Define#

lua

Metrics.Define(definition: table): boolean

Defines a metric { Name, Kind ("Counter", "Gauge" or "Histogram"; default Counter), Help, Labels (label names), Buckets (a histogram's ascending upper bounds) }. Names start with "game_" and have 1-128 of a-z, 0-9 and '_'. Defining a metric again with the same kind, labels and buckets is fine (scripts reload); a process keeps at most 256 game metrics. Raises an error for an invalid definition.

Parameters

definition (table)

Returns boolean: true.

Example

lua

Metrics.Define({ Name = "game_queue_seconds", Kind = "Histogram", Buckets = { 1, 5, 30, 120 } })

Metrics.Add#

lua

Metrics.Add(name: string, value?: number, labels?: table)

Adds value (default 1) to a counter (never negative) or a gauge, for the { label = "value" } series (labels not given are "").

Parameters

name (string)
value? (number)
labels? (table)

Example

lua

Metrics.Add("game_gold_looted_total", gold, { zone = World.GetZoneName() })

Metrics.Set#

lua

Metrics.Set(name: string, value: number, labels?: table)

Sets a gauge's series to value.

Parameters

name (string)
value (number)
labels? (table)

Example

lua

Metrics.Set("game_open_auctions", #self.Auctions)

Metrics.Observe#

lua

Metrics.Observe(name: string, value: number, labels?: table)

Counts value into a histogram's buckets (its sum and count grow too).

Parameters

name (string)
value (number)
labels? (table)

Example

lua

Metrics.Observe("game_queue_seconds", waited)

Metrics.Get#

lua

Metrics.Get(name: string, labels?: table): number|table

A counter's or gauge's value for the series, or a histogram's { Count, Sum } (tests and debug screens).

Parameters

name (string)
labels? (table)

Returns number|table

Movement#

Character movement (CharacterMovement): AI input for Server-authority movers, Grid targets, and what the movers are doing. Movers move in the scene's Movement system with native models, on the server and in client prediction alike; game rules extend a step with OnMovementStep (ScriptExtension).

lua

Movement.SetInput(self.Entity, (target - self.Entity.Position):Normalized())

Member	Kind	Summary
`Movement.SetInput(entity: Entity, move: Vec2, run?: boolean)`	Function	The input of a mover whose CharacterMovement Authority is Server (NPCs, AI) from its next fixed step until the next call: move (clamped to length 1) scales MaxSpeed, run multiplies it by RunMultiplier (Grid movers: RunTilesPerGameTick).
`Movement.MoveTo(entity: Entity, cell: Vec2)`	Function	Grid movers: walk to the cell (whole-number coordinates) from the next game tick on, WalkTilesPerGameTick tiles per tick (diagonally first, then straight, stopping at unwalkable tiles).
`Movement.GetVelocity(entity: Entity): Vec2`	Function	The mover's velocity in world units per second (Grid movers: over the current game tick); zero without CharacterMovement.
`Movement.IsMoving(entity: Entity): boolean`	Function	Kinematic movers: the velocity is not zero.

Movement.SetInput#

lua

Movement.SetInput(entity: Entity, move: Vec2, run?: boolean)

The input of a mover whose CharacterMovement Authority is Server (NPCs, AI) from its next fixed step until the next call: move (clamped to length 1) scales MaxSpeed, run multiplies it by RunMultiplier (Grid movers: RunTilesPerGameTick). Server and offline; on a client a networked mover raises an error (the server moves it), as do other authorities.

Parameters

entity (Entity)
move (Vec2)
run? (boolean)

Example

lua

Movement.SetInput(self.Entity, Vec2(1, 0), true)

Movement.MoveTo#

lua

Movement.MoveTo(entity: Entity, cell: Vec2)

Grid movers: walk to the cell (whole-number coordinates) from the next game tick on, WalkTilesPerGameTick tiles per tick (diagonally first, then straight, stopping at unwalkable tiles). On the peer that walks the mover - the server (Server and ServerPredicted authority), its owner (Owner authority), any peer offline; elsewhere it raises an error (ask with an RPC).

Parameters

entity (Entity)
cell (Vec2)

Example

lua

Movement.MoveTo(self.Entity, Vec2(12, 7))

Movement.GetVelocity#

lua

Movement.GetVelocity(entity: Entity): Vec2

The mover's velocity in world units per second (Grid movers: over the current game tick); zero without CharacterMovement.

Parameters

entity (Entity)

Returns Vec2

Movement.IsMoving#

lua

Movement.IsMoving(entity: Entity): boolean

Kinematic movers: the velocity is not zero. Grid movers: the target is not reached yet (or the mover still glides into its cell). False without CharacterMovement.

Parameters

entity (Entity)

Returns boolean

Nameplates#

Nameplates (the Nameplate component): names with health and cast bars above entities, decluttered every frame - the target, party members and hostiles in combat before others - within Crowds.MaxNameplates.

lua

Nameplates.SetText(self.Entity, "Gate Guard")

Member	Kind	Summary
`Nameplates.SetText(entity: Entity, text: string): boolean`	Function	Shows `text` (at most 64 bytes of UTF-8) as the entity's name: the plate's Source becomes Custom.
`Nameplates.IsVisible(entity: Entity): boolean`	Function	Whether the last rendered frame drew the entity's nameplate (in a view, near enough and not hidden by a plate of higher priority).

Nameplates.SetText#

lua

Nameplates.SetText(entity: Entity, text: string): boolean

Shows text (at most 64 bytes of UTF-8) as the entity's name: the plate's Source becomes Custom. The text is not replicated: call it where the plate is drawn (on clients), or name networked characters in their prefab or through the nameplate data provider.

Parameters

entity (Entity)
text (string)

Returns boolean

Example

lua

Nameplates.SetText(self.Entity, "Gate Guard")

Nameplates.IsVisible#

lua

Nameplates.IsVisible(entity: Entity): boolean

Whether the last rendered frame drew the entity's nameplate (in a view, near enough and not hidden by a plate of higher priority). Always false where nothing renders (servers, headless runs).

Parameters

entity (Entity)

Returns boolean

Example

lua

UI.SetVisible(bossFrame, not Nameplates.IsVisible(boss))

Nav#

The scene's navigation (Docs/AI.md): path queries over the nav grid the project's Navigation settings describe, and what an agent class can stand on and see. Navigation runs where the scene has authority - servers, hosts, offline games and editor play - over the nav cells attached to the scene (baked cells of its world, or of the scene itself); every function but IsAvailable raises an error elsewhere. Agent classes are named as in the settings (default: the first class); positions are scene positions.

lua

Nav.FindPath(self.Entity.Position, target, function(path)
	if path.Status == "Found" then self.Route = path.Waypoints end
end)

Member	Kind	Summary
`Nav.IsAvailable(): boolean`	Function	True when the scene has navigation (not on clients of a server).
`Nav.FindPath(from: Vec2, to: Vec2, callback: function, agentClass?: string)`	Function	Searches a path in the background (the nav world's path queries: parallel jobs under the project's MaxExpansionsPerTick budget) and calls `callback(path)` once it is known - one or more fixed steps later, before the scripts' OnFixedUpdate.
`Nav.FindPathNow(from: Vec2, to: Vec2, agentClass?: string, maxExpandedNodes?: integer): { Status: string, Waypoints: Vec2[], Cost: number }`	Function	Searches a path at once, on the calling script's thread, expanding at most `maxExpandedNodes` search nodes (default 20000; a bound on work, never on time, so every machine answers the same): "Partial" when the bound ran out first.
`Nav.IsWalkable(position: Vec2, agentClass?: string): boolean`	Function	True when the agent class can stand at the position: an area it may use, with room for its radius.
`Nav.Raycast(from: Vec2, to: Vec2, agentClass?: string): boolean, Vec2`	Function	Grid line of sight for the agent class: false and `to` when every tile the segment touches is one the class can stand on; true and the first blocked point otherwise (`from` itself when the class cannot stand there).
`Nav.NearestWalkable(position: Vec2, maxDistance?: number, agentClass?: string): Vec2?`	Function	`position` when the agent class can stand there, otherwise the nearest point it can stand on within `maxDistance` world units (default: 64 tiles; never farther than 64 tiles); nil when there is none.

Nav.IsAvailable#

lua

Nav.IsAvailable(): boolean

True when the scene has navigation (not on clients of a server).

Returns boolean

Nav.FindPath#

lua

Nav.FindPath(from: Vec2, to: Vec2, callback: function, agentClass?: string)

Searches a path in the background (the nav world's path queries: parallel jobs under the project's MaxExpansionsPerTick budget) and calls callback(path) once it is known - one or more fixed steps later, before the scripts' OnFixedUpdate. path is { Status, Waypoints, Cost }: Status "Found", "Partial" (the goal is unreachable or too far: the path ends at the reachable point nearest to it), "NoPath", "Unloaded" (no nav cell under the start or the goal), "Cancelled" (the runtime stopped), "PathTooLong" (the way crosses more cells than the project's Navigation.MaxCorridorCells); Waypoints the smoothed points from the start to the end (empty without a path); Cost the length weighted by the areas' costs. A goal inside a wall snaps to the nearest walkable point within two tiles.

Parameters

from (Vec2)
to (Vec2)
callback (function): Called once with the path table; errors in it are reported like any script error.
agentClass? (string): The agent class whose size and areas count (default: the first class of the settings).

Example

lua

Nav.FindPath(self.Entity.Position, Vec2(40, 12), function(path)
	if path.Status == "Found" then
		self.Route = path.Waypoints
	end
end, "Medium")

Nav.FindPathNow#

lua

Nav.FindPathNow(from: Vec2, to: Vec2, agentClass?: string, maxExpandedNodes?: integer): { Status: string, Waypoints: Vec2[], Cost: number }

Searches a path at once, on the calling script's thread, expanding at most maxExpandedNodes search nodes (default 20000; a bound on work, never on time, so every machine answers the same): "Partial" when the bound ran out first. For tools and short paths; NPCs use FindPath or NavAgent:MoveTo, which run in parallel. The table is FindPath's.

Parameters

from (Vec2)
to (Vec2)
agentClass? (string)
maxExpandedNodes? (integer)

Returns { Status: string, Waypoints: Vec2[], Cost: number }

Example

lua

local path = Nav.FindPathNow(self.Entity.Position, door)
if path.Status == "Found" then print(#path.Waypoints) end

Nav.IsWalkable#

lua

Nav.IsWalkable(position: Vec2, agentClass?: string): boolean

True when the agent class can stand at the position: an area it may use, with room for its radius. False outside the attached nav cells.

Parameters

position (Vec2)
agentClass? (string)

Returns boolean

Nav.Raycast#

lua

Nav.Raycast(from: Vec2, to: Vec2, agentClass?: string): boolean, Vec2

Grid line of sight for the agent class: false and to when every tile the segment touches is one the class can stand on; true and the first blocked point otherwise (from itself when the class cannot stand there).

Parameters

from (Vec2)
to (Vec2)
agentClass? (string)

Returns boolean, Vec2

Example

lua

local blocked, point = Nav.Raycast(self.Entity.Position, target.Position)
if not blocked then self:Charge(target) end

Nav.NearestWalkable#

lua

Nav.NearestWalkable(position: Vec2, maxDistance?: number, agentClass?: string): Vec2?

position when the agent class can stand there, otherwise the nearest point it can stand on within maxDistance world units (default: 64 tiles; never farther than 64 tiles); nil when there is none.

Parameters

position (Vec2)
maxDistance? (number)
agentClass? (string)

Returns Vec2?

Example

lua

local spot = Nav.NearestWalkable(clickPosition, 3)
if spot then agent:MoveTo(spot) end

Net#

Multiplayer: sessions (host, dedicated server, client), the local peer's role, spawning networked entities (server) and RPCs (ScriptInstance:ServerRpc / ClientRpc run the receiving entity's script method of that name: methods named <Name>ServerRpc / <Name>ClientRpc; a call that arrives before the instance's OnCreate ran waits for it). ServerRpcs only run for the entity's owner unless the class declares MyClass.RpcOptions = { OpenServerRpc = { RequireOwnership = false } }. Scripts receive OnClientConnected(clientId) and OnClientDisconnected(clientId, reason, message) at the start of the next update phase (server: every client joining or leaving, the host's own player as client 0; client: its own connection, with a nil id when it failed before it was established), OnNetworkSpawn() when their networked entity joins the session (after OnCreate) and OnReplicatedChanged(propertyName) when a property declared with Replicated = true changed (clients: a value from the server arrived after OnCreate; host: the server sent a changed value). The server sends property values with its next network tick: values that arrive together with the spawn are set before OnCreate, later ones are announced by OnReplicatedChanged, so read them in OnCreate and react to changes there. Without the host's NetworkManager every peer is offline.

lua

function Player:OnNetworkSpawn()
	if self.Entity:IsOwner() then Camera.Main():SetParent(self.Entity, false) end
end

function Player:OnUpdate(dt)
	if self.Entity:IsOwner() and Input.IsKeyPressed(Key.Space) then
		self:ServerRpc("FireServerRpc", self.Entity.WorldPosition)
	end
end

function Player:FireServerRpc(position)
	Net.Spawn(self.BulletPrefab, position)
end

Member	Kind	Summary
`Net.IsServer(): boolean`	Function	True on a dedicated server and on a host (the server with a local player).
`Net.IsClient(): boolean`	Function	True on a client (connecting or connected) and on a host: the peer has a local player.
`Net.IsHost(): boolean`	Function	True on a host (listen server with a local player).
`Net.IsOffline(): boolean`	Function	True when no session runs (single player): the local game owns every entity.
`Net.GetLocalClientId(): integer?`	Function	The local player's client id: 0 on a host, the id the server assigned on a connected client, nil otherwise (offline, dedicated server, still connecting).
`Net.GetClients(): integer[]`	Function	Server: the ids of the connected remote clients in id order (the host's own player, 0, is not listed).
`Net.GetRpcSender(): integer?`	Function	Inside a ServerRpc method: the client that called it (0 for the host's own player).
`Net.StartHost(port: integer, options?: table)`	Function	Starts a listen server with a local player (client 0) on the port (1-65535; 0 = a free port the OS picks, see Net.GetPort).
`Net.StartServer(port: integer, options?: table)`	Function	Starts a dedicated server (no local player) on the port (1-65535; 0 = a free port the OS picks, see Net.GetPort).
`Net.GetPort(): integer?`	Function	Server/host: the port the session listens on (the port the OS picked after StartHost(0) or StartServer(0)).
`Net.Connect(address: string, options?: table)`	Function	Connects to a server at "host:port": an IPv4 literal, a bracketed IPv6 literal or a host name (resolved in the background, "localhost" included; every address of the name is tried).
`Net.Disconnect()`	Function	Ends the session (a server stops listening and disconnects its clients) and returns to offline.
`Net.Spawn(prefab: integer\|string, position?: Vec2, owner?: integer): Entity`	Function	Server: instantiates a prefab whose root has a NetworkIdentity (an asset handle such as a Prefab property, or a virtual path) at the world position (default: the prefab's) and spawns it on every client.
`Net.Despawn(entity: Entity)`	Function	Server: destroys a networked entity (and its children) at the end of the frame and despawns it on every client.
`Net.SetOwner(entity: Entity, client?: integer)`	Function	Server: gives a networked entity to a client (0 = the host's own player; it then sends the entity's movement itself) or, with nil, back to the server.
`Net.Kick(client: integer, reason?: string)`	Function	Server: disconnects a remote client.
`Net.GetPlayerName(client?: integer): string?`	Function	The name of a player of the session, on every peer (players choose it when they connect: Net.Connect's PlayerName, FrostRuntime --name; a connect token's name wins).
`Net.GetPlayers(): { Id: integer, Name: string }[]`	Function	Every player of the session on every peer: the host's own player (Id 0) first, then the remote clients in id order.
`Net.GetStats(client?: integer): { Ping: integer, PacketLoss: number?, BytesIn: integer, BytesOut: integer, BytesInPerSecond: number, BytesOutPerSecond: number, MessagesIn: integer, MessagesOut: integer }?`	Function	The statistics of a connection: on a server the client's (an id is required), on a client the server's.
`Net.GetReplicationStats(client?: integer): { Relevant: integer, BytesPerSecond: number, SnapshotBytesPerSecond: number, ReliableBytesPerSecond: number, BudgetBytesPerSecond: integer, SnapshotEntitiesPerTick: number, CompressionRatio: number, AckedPackets: integer, LostPackets: integer, MemoryBytes: integer }?`	Function	What replication sends to a client (server: the client's, an id is required) or receives from the server (client): Relevant - the networked entities the client receives (interest management); BytesPerSecond - snapshot and reliable bytes over the last second (SnapshotBytesPerSecond + ReliableBytesPerSecond); BudgetBytesPerSecond - the client's adaptive snapshot budget (server; 0 on clients); SnapshotEntitiesPerTick - snapshot records per network tick; CompressionRatio - reliable bytes on the wire over their size before compression (1: nothing saved); AckedPackets / LostPackets - snapshot packets the client acknowledged and those it never did (server), or received and skipped (client); MemoryBytes - the server's replication state for the client.
`Net.SetClientPhase(client: integer, phase: integer)`	Function	Server: the phase a remote client sees (0 to 65535).
`Net.SetClientTeams(client: integer, mask: integer)`	Function	Server: the teams of a remote client as a bit set (0 to 2^32 - 1).
`Net.SetClientChannels(client: integer, mask: integer)`	Function	Server: the channels a remote client subscribes to as a bit set (32 channels).
`Net.SetClientSeesAllPhases(client: integer, enabled: boolean)`	Function	Server: a remote client that sees the entities of every phase (game masters, spectators); false returns it to its own phase (Net.SetClientPhase).
`Net.AddObserver(client: integer, position: Vec2, radiusScale?: number): integer`	Function	Server: an extra point a remote client sees from, besides its own entities (a camera it controls, a scrying spell, spectating): entities around it become relevant to the client as around its avatar.
`Net.SetObserverPosition(client: integer, observer: integer, position: Vec2)`	Function	Server: moves an observer Net.AddObserver gave the client (a camera that follows something).
`Net.RemoveObserver(client: integer, observer: integer)`	Function	Server: removes an observer Net.AddObserver gave the client; what only it saw leaves the client (after the minimum relevant time of the project's Network.Interest settings).
`Net.SetRelevantTo(entity: Entity, client: integer, relevant: boolean): boolean`	Function	Server: gives a networked entity to a remote client (true) or takes it back (false).
`Net.IsRelevantTo(entity: Entity, client: integer): boolean`	Function	Server: whether the client receives the networked entity (it is in the client's relevant set; the host's own player, 0, receives every entity).
`Net.GetRelevantCount(client: integer): integer`	Function	Server: how many networked entities a remote client receives after the last network tick (its relevant set: its own entities, everything within its observers' ranges, AlwaysRelevant and granted ones).
`Net.GetInterestStats(): { Tick: integer, Clients: integer, Entities: integer, RelevantPairs: integer, CandidatesTested: integer, Entered: integer, Left: integer, Truncated: integer, FilterCalls: integer, FilterDeferred: integer, RangeClassEvaluations: integer, FullEvaluations: integer, NearestObserverUpdates: integer, NearestObserverGroup: integer, SpatialUpdateMs: number, QueryMs: number, FilterMs: number, NearestObserverMs: number, MemoryBytes: integer }?`	Function	Server: what interest management did in the last network tick.
`Net.SetRelevancyFilter(filter?: function)`	Function	Server: installs the relevancy filter, filter(client, entity) -> boolean, asked whether a remote client receives an entity whose NetworkRelevancy has ScriptFilter on, after every other rule let it through (line of sight, stealth).
`Net.RewindRaycast(origin: Vec2, direction: Vec2, distance: number, options?: table): { Entity: Entity, Point: Vec2, Normal: Vec2, Distance: number }[]`	Function	Server (and offline): the NetworkLagCompensation hitboxes the ray hits, nearest first, as they were when the client options.Client saw them (its view time, at most LagCompensation.MaxRewindMs ago; without Client: now).
`Net.RewindOverlapCircle(center: Vec2, radius: number, options?: table): { Entity: Entity, Point: Vec2, Normal: Vec2, Distance: number }[]`	Function	Server (and offline): the NetworkLagCompensation hitboxes a circle overlaps, nearest first, as the client options.Client saw them (as Net.RewindRaycast).
`Net.GetRewindTime(client: integer): number`	Function	Server (and offline): the server time in seconds the client's rewind queries test - the time it was rendering when it sampled its latest command, clamped to [now - LagCompensation.MaxRewindMs, now]; now for a client that sent no command yet.
`Net.GetPredictionStats(): { Corrections: integer, ReplayedTicks: integer, Snaps: integer, LastError: number, ClockDilation: number, Missed: integer, CommandsSent: integer, CommandsReceived: integer, CommandsRefused: integer, BufferedCommands: integer, ClockResyncs: integer }`	Function	Prediction counters of this peer since its session (or its scene) started.

Net.IsServer#

lua

Net.IsServer(): boolean

True on a dedicated server and on a host (the server with a local player).

Returns boolean

Net.IsClient#

lua

Net.IsClient(): boolean

True on a client (connecting or connected) and on a host: the peer has a local player.

Returns boolean

Net.IsHost#

lua

Net.IsHost(): boolean

True on a host (listen server with a local player).

Returns boolean

Net.IsOffline#

lua

Net.IsOffline(): boolean

True when no session runs (single player): the local game owns every entity.

Returns boolean

Net.GetLocalClientId#

lua

Net.GetLocalClientId(): integer?

The local player's client id: 0 on a host, the id the server assigned on a connected client, nil otherwise (offline, dedicated server, still connecting).

Returns integer?

Net.GetClients#

lua

Net.GetClients(): integer[]

Server: the ids of the connected remote clients in id order (the host's own player, 0, is not listed). Empty elsewhere.

Returns integer[]

Net.GetRpcSender#

lua

Net.GetRpcSender(): integer?

Inside a ServerRpc method: the client that called it (0 for the host's own player). nil elsewhere (ClientRpcs come from the server).

Returns integer?

Example

lua

Door.RpcOptions = { OpenServerRpc = { RequireOwnership = false } } -- any client may open the server's door

function Door:OpenServerRpc()
	Log.Info("opened by client " .. Net.GetRpcSender())
end

Net.StartHost#

lua

Net.StartHost(port: integer, options?: table)

Starts a listen server with a local player (client 0) on the port (1-65535; 0 = a free port the OS picks, see Net.GetPort). options (for this session): PlayerName (the host's own player's name, readable on every peer with Net.GetPlayerName), Password (clients must send it) and TokenKey (hexadecimal key: clients must send a connect token signed with it; FrostEditor network.create-token makes tokens). Clients that fail are refused with "AuthenticationFailed". Raises an error when a session already runs, an option is unknown or invalid, or the port cannot be opened.

Parameters

port (integer)
options? (table)

Example

lua

Net.StartHost(7777, { PlayerName = "Ann", Password = "hunter2" })

Net.StartServer#

lua

Net.StartServer(port: integer, options?: table)

Starts a dedicated server (no local player) on the port (1-65535; 0 = a free port the OS picks, see Net.GetPort). options (for this session): Password and TokenKey, as for Net.StartHost.

Parameters

port (integer)
options? (table)

Net.GetPort#

lua

Net.GetPort(): integer?

Server/host: the port the session listens on (the port the OS picked after StartHost(0) or StartServer(0)). nil elsewhere (offline, client).

Returns integer?

Example

lua

Net.StartHost(0)
Log.Info("hosting on port " .. Net.GetPort())

Net.Connect#

lua

Net.Connect(address: string, options?: table)

Connects to a server at "host:port": an IPv4 literal, a bracketed IPv6 literal or a host name (resolved in the background, "localhost" included; every address of the name is tried). options (for this session): PlayerName (the name every peer reads with Net.GetPlayerName; a connect token's name wins), Password and Token (a connect token) for servers that require them. The outcome arrives later: OnClientConnected(ownId) when the session is established, OnClientDisconnected(nil, reason, message) when it fails before that (e.g. "AuthenticationFailed", "Wrong password"; "ConnectFailed" for a name that does not resolve) and OnClientDisconnected(ownId, reason, message) when an established session ends.

Parameters

address (string)
options? (table)

Example

lua

Net.Connect("play.example.com:7777", { PlayerName = "Ann", Password = "hunter2" })

Net.Disconnect#

lua

Net.Disconnect()

Ends the session (a server stops listening and disconnects its clients) and returns to offline. Nothing happens offline. No disconnect callbacks are reported for it.

Net.Spawn#

lua

Net.Spawn(prefab: integer|string, position?: Vec2, owner?: integer): Entity

Server: instantiates a prefab whose root has a NetworkIdentity (an asset handle such as a Prefab property, or a virtual path) at the world position (default: the prefab's) and spawns it on every client. owner is the owning client id (0 = the host's player; owners move their entities themselves); nil keeps it server owned. Returns the root entity.

Parameters

prefab (integer|string)
position? (Vec2)
owner? (integer)

Returns Entity

Example

lua

local player = Net.Spawn(self.PlayerPrefab, Vec2(0, 2), clientId)

Net.Despawn#

lua

Net.Despawn(entity: Entity)

Server: destroys a networked entity (and its children) at the end of the frame and despawns it on every client.

Parameters

entity (Entity)

Net.SetOwner#

lua

Net.SetOwner(entity: Entity, client?: integer)

Server: gives a networked entity to a client (0 = the host's own player; it then sends the entity's movement itself) or, with nil, back to the server. Every peer sees the change through Entity:GetOwner and Entity:IsOwner; no script callback reports it, so a script that reacts compares GetOwner with the owner it saw last (in OnUpdate). The entity's descendants keep their owners.

Parameters

entity (Entity)
client? (integer)

Example

lua

Net.SetOwner(car, Net.GetRpcSender()) -- the client that asked drives the car

Net.Kick#

lua

Net.Kick(client: integer, reason?: string)

Server: disconnects a remote client. Its scripts receive OnClientDisconnected(id, "Kicked", reason); the server's scripts OnClientDisconnected(id, "Kicked") once the connection closed, and its entities follow their OwnerDisconnectPolicy. The host's own player (0) cannot be kicked.

Parameters

client (integer)
reason? (string)

Example

lua

Net.Kick(clientId, "Cheating is not allowed")

Net.GetPlayerName#

lua

Net.GetPlayerName(client?: integer): string?

The name of a player of the session, on every peer (players choose it when they connect: Net.Connect's PlayerName, FrostRuntime --name; a connect token's name wins). Without a client: the local player's own name. nil offline, for unknown clients, on a dedicated server for 0, on a client before the server sent the players, and for a client that left (also inside OnClientDisconnected).

Parameters

client? (integer)

Returns string?

Example

lua

function Scoreboard:OnClientConnected(id)
	Log.Info((Net.GetPlayerName(id) or "?") .. " joined")
end

Net.GetPlayers#

lua

Net.GetPlayers(): { Id: integer, Name: string }[]

Every player of the session on every peer: the host's own player (Id 0) first, then the remote clients in id order. Empty offline, on a dedicated server without clients and on a client before the server sent the list.

Returns { Id: integer, Name: string }[]

Net.GetStats#

lua

Net.GetStats(client?: integer): { Ping: integer, PacketLoss: number?, BytesIn: integer, BytesOut: integer, BytesInPerSecond: number, BytesOutPerSecond: number, MessagesIn: integer, MessagesOut: integer }?

The statistics of a connection: on a server the client's (an id is required), on a client the server's. Ping is the round trip in milliseconds; PacketLoss the share of packets lost or out of order, 0 to 1 (nil until measured); BytesIn / BytesOut and MessagesIn / MessagesOut count everything received and sent on the connection (message headers included); the per-second rates are the transport's recent averages. nil offline, for the host's own player (no connection) and for unknown clients.

Parameters

client? (integer)

Returns { Ping: integer, PacketLoss: number?, BytesIn: integer, BytesOut: integer, BytesInPerSecond: number, BytesOutPerSecond: number, MessagesIn: integer, MessagesOut: integer }?

Example

lua

local stats = Net.GetStats()
if stats then Log.Info("ping " .. stats.Ping .. " ms") end

Net.GetReplicationStats#

lua

Net.GetReplicationStats(client?: integer): { Relevant: integer, BytesPerSecond: number, SnapshotBytesPerSecond: number, ReliableBytesPerSecond: number, BudgetBytesPerSecond: integer, SnapshotEntitiesPerTick: number, CompressionRatio: number, AckedPackets: integer, LostPackets: integer, MemoryBytes: integer }?

What replication sends to a client (server: the client's, an id is required) or receives from the server (client): Relevant - the networked entities the client receives (interest management); BytesPerSecond - snapshot and reliable bytes over the last second (SnapshotBytesPerSecond + ReliableBytesPerSecond); BudgetBytesPerSecond - the client's adaptive snapshot budget (server; 0 on clients); SnapshotEntitiesPerTick - snapshot records per network tick; CompressionRatio - reliable bytes on the wire over their size before compression (1: nothing saved); AckedPackets / LostPackets - snapshot packets the client acknowledged and those it never did (server), or received and skipped (client); MemoryBytes - the server's replication state for the client. nil offline, for the host's own player and for clients that are not in the scene.

Parameters

client? (integer)

Returns { Relevant: integer, BytesPerSecond: number, SnapshotBytesPerSecond: number, ReliableBytesPerSecond: number, BudgetBytesPerSecond: integer, SnapshotEntitiesPerTick: number, CompressionRatio: number, AckedPackets: integer, LostPackets: integer, MemoryBytes: integer }?

Example

lua

for _, id in ipairs(Net.GetClients()) do
	local stats = Net.GetReplicationStats(id)
	if stats then Log.Info(id .. ": " .. stats.Relevant .. " entities, " .. math.floor(stats.BytesPerSecond) .. " B/s") end
end

Net.SetClientPhase#

lua

Net.SetClientPhase(client: integer, phase: integer)

Server: the phase a remote client sees (0 to 65535). It sees the entities of its phase and of phase 0 (every phase); NetworkRelevancy entities of other phases disappear from it at the next network tick, whatever their range (the hysteresis that keeps entities a moment longer does not apply). 0 = only entities without a phase. Errors for the host's own player (0), which sees everything, and for clients that are not connected.

Parameters

client (integer)
phase (integer)

Example

lua

-- the player entered the instanced dungeon: only its phase's monsters and doors show
Net.SetClientPhase(clientId, 7)

Net.SetClientTeams#

lua

Net.SetClientTeams(client: integer, mask: integer)

Server: the teams of a remote client as a bit set (0 to 2^32 - 1). It sees entities whose NetworkRelevancy TeamMask is 0 or shares a bit with it; 0 = sees every team. Applies at the next network tick.

Parameters

client (integer)
mask (integer)

Example

lua

Net.SetClientTeams(clientId, 1 << team) -- stealthed units of other teams stay hidden

Net.SetClientChannels#

lua

Net.SetClientChannels(client: integer, mask: integer)

Server: the channels a remote client subscribes to as a bit set (32 channels). Entities whose NetworkRelevancy Channels is not 0 reach only clients subscribed to one of their channels (a guild hall, a party's quest objects). Applies at the next network tick.

Parameters

client (integer)
mask (integer)

Example

lua

Net.SetClientChannels(clientId, 1 << guildChannel)

Net.SetClientSeesAllPhases#

lua

Net.SetClientSeesAllPhases(client: integer, enabled: boolean)

Server: a remote client that sees the entities of every phase (game masters, spectators); false returns it to its own phase (Net.SetClientPhase).

Parameters

client (integer)
enabled (boolean)

Example

lua

Net.SetClientSeesAllPhases(gameMasterId, true)

Net.AddObserver#

lua

Net.AddObserver(client: integer, position: Vec2, radiusScale?: number): integer

Server: an extra point a remote client sees from, besides its own entities (a camera it controls, a scrying spell, spectating): entities around it become relevant to the client as around its avatar. radiusScale (0 to 4, default 1) scales every range class's radius for this observer (a zoomed-out map). Returns the observer's id (Net.SetObserverPosition, Net.RemoveObserver). A client has at most 16 observers in all (its own entities count first).

Parameters

client (integer)
position (Vec2)
radiusScale? (number)

Returns integer: The observer's id (> 0).

Example

lua

self.Scry = Net.AddObserver(clientId, target.Position, 0.5)

Net.SetObserverPosition#

lua

Net.SetObserverPosition(client: integer, observer: integer, position: Vec2)

Server: moves an observer Net.AddObserver gave the client (a camera that follows something). Takes effect at the next network tick.

Parameters

client (integer)
observer (integer)
position (Vec2)

Example

lua

Net.SetObserverPosition(clientId, self.Scry, target.Position)

Net.RemoveObserver#

lua

Net.RemoveObserver(client: integer, observer: integer)

Server: removes an observer Net.AddObserver gave the client; what only it saw leaves the client (after the minimum relevant time of the project's Network.Interest settings).

Parameters

client (integer)
observer (integer)

Example

lua

Net.RemoveObserver(clientId, self.Scry)

Net.SetRelevantTo#

lua

Net.SetRelevantTo(entity: Entity, client: integer, relevant: boolean): boolean

Server: gives a networked entity to a remote client (true) or takes it back (false). Entities whose NetworkRelevancy Mode is Manual reach exactly the clients they were given to (still filtered by teams, channels and phases); other modes keep the grant for when their mode becomes Manual. A grant lasts until it is taken back, the client leaves or the entity despawns; taking it back hides the entity at the next network tick. Returns false (nothing recorded) when the entity is not one of the server's interest entities: networked descendants of a spawn follow their spawn root (give the root), and an entity created since the last network tick is not gathered yet.

Parameters

entity (Entity)
client (integer)
relevant (boolean)

Returns boolean: True when the grant was recorded.

Example

lua

Net.SetRelevantTo(questChest, clientId, true) -- only this player sees the chest

Net.IsRelevantTo#

lua

Net.IsRelevantTo(entity: Entity, client: integer): boolean

Server: whether the client receives the networked entity (it is in the client's relevant set; the host's own player, 0, receives every entity). Client: whether the server currently replicates the entity to this peer (pass Net.GetLocalClientId()). False offline and for entities that are not networked.

Parameters

entity (Entity)
client (integer)

Returns boolean

Example

lua

if not Net.IsRelevantTo(boss, clientId) then Net.SetRelevantTo(boss, clientId, true) end

Net.GetRelevantCount#

lua

Net.GetRelevantCount(client: integer): integer

Server: how many networked entities a remote client receives after the last network tick (its relevant set: its own entities, everything within its observers' ranges, AlwaysRelevant and granted ones). 0 before the first tick that evaluated it.

Parameters

client (integer)

Returns integer

Example

lua

Log.Info("client sees", Net.GetRelevantCount(clientId), "entities")

Net.GetInterestStats#

lua

Net.GetInterestStats(): { Tick: integer, Clients: integer, Entities: integer, RelevantPairs: integer, CandidatesTested: integer, Entered: integer, Left: integer, Truncated: integer, FilterCalls: integer, FilterDeferred: integer, RangeClassEvaluations: integer, FullEvaluations: integer, NearestObserverUpdates: integer, NearestObserverGroup: integer, SpatialUpdateMs: number, QueryMs: number, FilterMs: number, NearestObserverMs: number, MemoryBytes: integer }?

Server: what interest management did in the last network tick. RelevantPairs sums every client's relevant set; CandidatesTested counts the entities found around the clients' observers; Entered / Left / Truncated the set changes and the entities MaxRelevantPerClient dropped. Staggering: RangeClassEvaluations counts the (client, range class) pairs evaluated this tick - each client evaluates a class with UpdateIntervalTicks n on its own phase, so about 1/n of the clients per tick - and FullEvaluations the clients evaluated in every class at once (new, filters changed). NearestObserverUpdates are the nearest-observer distances refreshed by this tick's group (NearestObserverGroup, one of NearestObserverIntervalTicks). The times are the stage's parts in milliseconds; MemoryBytes is what the manager holds. nil on clients and offline.

Returns { Tick: integer, Clients: integer, Entities: integer, RelevantPairs: integer, CandidatesTested: integer, Entered: integer, Left: integer, Truncated: integer, FilterCalls: integer, FilterDeferred: integer, RangeClassEvaluations: integer, FullEvaluations: integer, NearestObserverUpdates: integer, NearestObserverGroup: integer, SpatialUpdateMs: number, QueryMs: number, FilterMs: number, NearestObserverMs: number, MemoryBytes: integer }?

Example

lua

local stats = Net.GetInterestStats()
if stats then Log.Info(stats.RangeClassEvaluations .. " evaluations, " .. stats.QueryMs .. " ms") end

Net.SetRelevancyFilter#

lua

Net.SetRelevancyFilter(filter?: function)

Server: installs the relevancy filter, filter(client, entity) -> boolean, asked whether a remote client receives an entity whose NetworkRelevancy has ScriptFilter on, after every other rule let it through (line of sight, stealth). It runs on the main thread during the network tick within the project's Network.Interest ScriptFilterBudgetUs per tick; its answer is kept ScriptFilterHoldTicks ticks. A pair it was not asked about yet is not relevant, and a pair the budget deferred keeps its previous answer. An error or a non-boolean answer counts as false (reported). The filter may read interest state but not change it. nil removes it (ScriptFilter entities then follow the other rules). One filter per server; installing another replaces it.

Parameters

filter? (function)

Example

lua

Net.SetRelevancyFilter(function(client, entity)
	return not entity:GetComponent("Script").Hidden
end)

Net.RewindRaycast#

lua

Net.RewindRaycast(origin: Vec2, direction: Vec2, distance: number, options?: table): { Entity: Entity, Point: Vec2, Normal: Vec2, Distance: number }[]

Server (and offline): the NetworkLagCompensation hitboxes the ray hits, nearest first, as they were when the client options.Client saw them (its view time, at most LagCompensation.MaxRewindMs ago; without Client: now). options: Client (integer), Layers (physics layer bit set; all by default), Ignore (an Entity left out: the shooter). A ray that starts inside a hitbox hits it at distance 0; entities destroyed since are left out. Raises an error on clients.

Parameters

origin (Vec2)
direction (Vec2)
distance (number)
options? (table)

Returns { Entity: Entity, Point: Vec2, Normal: Vec2, Distance: number }[]

Example

lua

function Gun:FireServerRpc(direction)
	local hits = Net.RewindRaycast(self.Entity.Position, direction, 20, { Client = Net.GetRpcSender(), Ignore = self.Entity })
	if hits[1] then hits[1].Entity:SendMessage("OnHit") end
end

Net.RewindOverlapCircle#

lua

Net.RewindOverlapCircle(center: Vec2, radius: number, options?: table): { Entity: Entity, Point: Vec2, Normal: Vec2, Distance: number }[]

Server (and offline): the NetworkLagCompensation hitboxes a circle overlaps, nearest first, as the client options.Client saw them (as Net.RewindRaycast). Point: the hitbox's point nearest the center; Normal: from there toward the center; Distance: 0.

Parameters

center (Vec2)
radius (number)
options? (table)

Returns { Entity: Entity, Point: Vec2, Normal: Vec2, Distance: number }[]

Example

lua

local hits = Net.RewindOverlapCircle(self.Entity.Position, 1.5, { Client = Net.GetRpcSender() })

Net.GetRewindTime#

lua

Net.GetRewindTime(client: integer): number

Server (and offline): the server time in seconds the client's rewind queries test - the time it was rendering when it sampled its latest command, clamped to [now - LagCompensation.MaxRewindMs, now]; now for a client that sent no command yet. Raises an error on clients.

Parameters

client (integer)

Returns number

Example

lua

Log.Info("rewinding " .. (Net.GetRewindTime(1) - Net.GetRewindTime(0)) .. " s")

Net.GetPredictionStats#

lua

Net.GetPredictionStats(): { Corrections: integer, ReplayedTicks: integer, Snaps: integer, LastError: number, ClockDilation: number, Missed: integer, CommandsSent: integer, CommandsReceived: integer, CommandsRefused: integer, BufferedCommands: integer, ClockResyncs: integer }

Prediction counters of this peer since its session (or its scene) started. Client: Corrections (server states that differed beyond the tolerance), ReplayedTicks, Snaps, LastError (world units), ClockDilation (-0.05 to 0.05), Missed (commands the server had to repeat), CommandsSent, BufferedCommands (the server's buffer depth), ClockResyncs. Server: CommandsReceived, CommandsRefused (too far ahead), Missed. All zero without prediction (offline, no session).

Returns { Corrections: integer, ReplayedTicks: integer, Snaps: integer, LastError: number, ClockDilation: number, Missed: integer, CommandsSent: integer, CommandsReceived: integer, CommandsRefused: integer, BufferedCommands: integer, ClockResyncs: integer }

Example

lua

local stats = Net.GetPredictionStats()
Log.Info("corrections: " .. stats.Corrections)

Npc#

NPC state: NpcState (replicated, so GetState and GetTarget work on clients too), homes, spawners and leashing. SetState, IsEvading and Leash need the scene's Npc system (servers and offline games).

lua

if Npc.GetState(self.Entity) == "Combat" then self.Nameplate.Color = Color.Red end

Member	Kind	Summary
`Npc.GetState(npc: Entity): string?`	Function	"Idle", "Patrolling", "Alert", "Combat", "Evading", "Dead" or "Custom"; nil for an entity without an NpcState.
`Npc.SetState(npc: Entity, state: string, target?: Entity)`	Function	Sets the NPC's NpcState (replicated) and, when given, its target.
`Npc.GetTarget(npc: Entity): Entity?`	Function	The NPC's target, or nil (on clients: the networked entity NpcState.Target names, nil while it is not replicated).
`Npc.GetHome(npc: Entity): Vec2?`	Function	Where the NPC returns: its Leash's Home, else its spawn point; nil for an NPC without either.
`Npc.GetSpawner(npc: Entity): Entity?`	Function	The spawner the NPC came from (nil for NPCs placed in the scene).
`Npc.IsEvading(npc: Entity): boolean`	Function	True while the NPC walks home on its leash (its tree paused, its perception ignored).
`Npc.Leash(npc: Entity)`	Function	Sends the NPC home now as if it had run past its leash: Evading, target cleared, perception ignored and tree paused until it is home (OnLeash, OnLeashEnd).

Npc.GetState#

lua

Npc.GetState(npc: Entity): string?

"Idle", "Patrolling", "Alert", "Combat", "Evading", "Dead" or "Custom"; nil for an entity without an NpcState.

Parameters

npc (Entity)

Returns string?

Example

lua

local state = Npc.GetState(target)

Npc.SetState#

lua

Npc.SetState(npc: Entity, state: string, target?: Entity)

Sets the NPC's NpcState (replicated) and, when given, its target. Evading here only shows the state: leashing (Npc.Leash) walks the NPC home.

Parameters

npc (Entity)
state (string)
target? (Entity)

Example

lua

Npc.SetState(self.Entity, "Combat", attacker)

Npc.GetTarget#

lua

Npc.GetTarget(npc: Entity): Entity?

The NPC's target, or nil (on clients: the networked entity NpcState.Target names, nil while it is not replicated).

Parameters

npc (Entity)

Returns Entity?

Example

lua

local target = Npc.GetTarget(boss)

Npc.GetHome#

lua

Npc.GetHome(npc: Entity): Vec2?

Where the NPC returns: its Leash's Home, else its spawn point; nil for an NPC without either.

Parameters

npc (Entity)

Returns Vec2?

Example

lua

local home = Npc.GetHome(self.Entity)

Npc.GetSpawner#

lua

Npc.GetSpawner(npc: Entity): Entity?

The spawner the NPC came from (nil for NPCs placed in the scene).

Parameters

npc (Entity)

Returns Entity?

Example

lua

local camp = Npc.GetSpawner(self.Entity)

Npc.IsEvading#

lua

Npc.IsEvading(npc: Entity): boolean

True while the NPC walks home on its leash (its tree paused, its perception ignored).

Parameters

npc (Entity)

Returns boolean

Example

lua

if Npc.IsEvading(self.Entity) then return end

Npc.Leash#

lua

Npc.Leash(npc: Entity)

Sends the NPC home now as if it had run past its leash: Evading, target cleared, perception ignored and tree paused until it is home (OnLeash, OnLeashEnd). Raises an error for an NPC without a Leash or one that already evades.

Parameters

npc (Entity)

Example

lua

Npc.Leash(boss) -- the pull reset

Party#

Parties and raids: invitations by name, ready checks, party chat (Chat.Send("Party", ...)). Results arrive as OnServiceResult; changes, invitations, ready checks and the end of a party as OnPartyChanged(event).

lua

Party.Invite("Merlin")
function Game:OnPartyChanged(event)
    if event.Kind == "Invite" then Party.Accept(event.PartyId) end
end

Member	Kind	Summary
`Party.Invite(name: string): integer?, string?`	Function	Invites an online character (the leader invites; a player without a party becomes its leader).
`Party.Accept(partyId: integer): integer?, string?`	Function	Accepts an invitation (the members get OnPartyChanged with the party).
`Party.Decline(partyId: integer): integer?, string?`	Function	Declines an invitation (the leader gets a notice).
`Party.Leave(): integer?, string?`	Function	Leaves the party (a leader's role passes to the longest member; a party of one ends: OnPartyChanged Disbanded).
`Party.Kick(characterId: integer): integer?, string?`	Function	The leader removes a member.
`Party.Promote(characterId: integer): integer?, string?`	Function	The leader makes another member the leader.
`Party.Disband(): integer?, string?`	Function	The leader ends the party: every member gets OnPartyChanged { Kind = "Disbanded" }.
`Party.ReadyCheck(): integer?, string?`	Function	The leader asks every member whether it is ready: members get OnPartyChanged { Kind = "ReadyCheck", ReadyCheck = { PartyId, InitiatorId, DeadlineUnixMs, Ready, NotReady, Finished } } as answers come in; who has not answered by the deadline (ReadyCheckSeconds) is not ready.
`Party.RespondReadyCheck(partyId: integer, ready: boolean): integer?, string?`	Function	Answers the party's ready check.
`Party.Get(): integer?, string?`	Function	The player's party: the result's Party is { PartyId, Raid, Members = { { CharacterId, Name, Online, Leader, Subgroup, Zone } } }; "notFound" without one.

Party.Invite#

lua

Party.Invite(name: string): integer?, string?

Invites an online character (the leader invites; a player without a party becomes its leader). The invitation waits PartyInviteSeconds (Social.json); the invitee gets OnPartyChanged { Kind = "Invite", PartyId, FromName }.

Parameters

name (string)

Returns integer?, string?

Party.Accept#

lua

Party.Accept(partyId: integer): integer?, string?

Accepts an invitation (the members get OnPartyChanged with the party).

Parameters

partyId (integer)

Returns integer?, string?

Party.Decline#

lua

Party.Decline(partyId: integer): integer?, string?

Declines an invitation (the leader gets a notice).

Parameters

partyId (integer)

Returns integer?, string?

Party.Leave#

lua

Party.Leave(): integer?, string?

Leaves the party (a leader's role passes to the longest member; a party of one ends: OnPartyChanged Disbanded).

Returns integer?, string?

Party.Kick#

lua

Party.Kick(characterId: integer): integer?, string?

The leader removes a member.

Parameters

characterId (integer)

Returns integer?, string?

Party.Promote#

lua

Party.Promote(characterId: integer): integer?, string?

The leader makes another member the leader.

Parameters

characterId (integer)

Returns integer?, string?

Party.Disband#

lua

Party.Disband(): integer?, string?

The leader ends the party: every member gets OnPartyChanged { Kind = "Disbanded" }.

Returns integer?, string?

Party.ReadyCheck#

lua

Party.ReadyCheck(): integer?, string?

The leader asks every member whether it is ready: members get OnPartyChanged { Kind = "ReadyCheck", ReadyCheck = { PartyId, InitiatorId, DeadlineUnixMs, Ready, NotReady, Finished } } as answers come in; who has not answered by the deadline (ReadyCheckSeconds) is not ready.

Returns integer?, string?

Party.RespondReadyCheck#

lua

Party.RespondReadyCheck(partyId: integer, ready: boolean): integer?, string?

Answers the party's ready check.

Parameters

partyId (integer)
ready (boolean)

Returns integer?, string?

Party.Get#

lua

Party.Get(): integer?, string?

The player's party: the result's Party is { PartyId, Raid, Members = { { CharacterId, Name, Online, Leader, Subgroup, Zone } } }; "notFound" without one.

Returns integer?, string?

Perception#

NPC perception (servers and offline games: the scene's Perception system): the targets an NPC with a Perception component senses - sorted by score, the nearest first - and noises it hears. Results also reach the NPC's behaviour tree (Target, TargetDistance, LastKnownPosition, NoisePosition and the TargetAcquired, TargetLost and NoiseHeard events) and its script (OnPerceived, OnTargetLost). Every function raises an error in a scene without perception (clients).

lua

function Guard:OnPerceived(target, sense)
	Log.Info(self.Entity.Name .. " noticed " .. target.Name .. " by " .. sense)
end

Member	Kind	Summary
`Perception.MakeNoise(position: Vec2, radius: number, tag?: string)`	Function	A noise at `position` that perceivers with hearing within `radius` hear at their next update (within 2 seconds): their NoisePosition key and NoiseHeard event, and Investigate.
`Perception.GetTargets(npc: Entity): { { Entity: Entity, Position: Vec2, Distance: number, Score: number, Sense: string, Visible: boolean, LastSensedTime: number } }`	Function	The targets the NPC tracks, highest score (nearest) first: where each was last sensed and how ("Sight" or "Hearing"), whether it was sensed at the last update (Visible) and when (scene seconds).
`Perception.GetBestTarget(npc: Entity): Entity?`	Function	The tracked target with the highest score (the nearest), or nil.
`Perception.Forget(npc: Entity, target: Entity): boolean`	Function	Drops a tracked target (OnTargetLost and the TargetLost event follow); false when the NPC does not track it.

Perception.MakeNoise#

lua

Perception.MakeNoise(position: Vec2, radius: number, tag?: string)

A noise at position that perceivers with hearing within radius hear at their next update (within 2 seconds): their NoisePosition key and NoiseHeard event, and Investigate. Raises an error for a radius outside (0, 1000], a tag longer than 64 characters or too many noises at once (256).

Parameters

position (Vec2)
radius (number)
tag? (string)

Example

lua

Perception.MakeNoise(self.Entity.Position, 12, "Explosion")

Perception.GetTargets#

lua

Perception.GetTargets(npc: Entity): { { Entity: Entity, Position: Vec2, Distance: number, Score: number, Sense: string, Visible: boolean, LastSensedTime: number } }

The targets the NPC tracks, highest score (nearest) first: where each was last sensed and how ("Sight" or "Hearing"), whether it was sensed at the last update (Visible) and when (scene seconds). Empty before the NPC's first perception update or when it is not a perceiver.

Parameters

npc (Entity)

Returns { { Entity: Entity, Position: Vec2, Distance: number, Score: number, Sense: string, Visible: boolean, LastSensedTime: number } }

Example

lua

for _, target in ipairs(Perception.GetTargets(self.Entity)) do Log.Info(target.Entity.Name) end

Perception.GetBestTarget#

lua

Perception.GetBestTarget(npc: Entity): Entity?

The tracked target with the highest score (the nearest), or nil.

Parameters

npc (Entity)

Returns Entity?

Example

lua

local target = Perception.GetBestTarget(self.Entity)

Perception.Forget#

lua

Perception.Forget(npc: Entity, target: Entity): boolean

Drops a tracked target (OnTargetLost and the TargetLost event follow); false when the NPC does not track it. It is sensed again at the next update if it is still in sight.

Parameters

npc (Entity)
target (Entity)

Returns boolean

Example

lua

Perception.Forget(self.Entity, decoy)

Persistence#

Server-side persistence of characters and world objects (Persistence component): the data fields the schema asset declares (Assets/Persistence/Schema.json) by entity, saves and atomic trades. Component fields flagged Persistent and script properties declared Persistent = true are saved automatically. Values are in document form: numbers, strings, booleans, Vec fields as { x, y } arrays (a Vec2 is accepted), Structs as tables, Lists as arrays. "Account.<Field>" addresses the account record of the entity's character (shared by the account's characters). Clients of a session have no persistence.

lua

function Player:OnPersistentLoaded()
	local gold = Persistence.Get(self.Entity, "Gold")
	Persistence.Set(self.Entity, "Gold", gold + 10)
end

Member	Kind	Summary
`Persistence.IsEnabled(): boolean`	Function	True when persistence runs in this scene: an entity has a Persistence component, the project declares something persistent, the zone's store is open and this peer is not a client of a session.
`Persistence.Get(entity: Entity, field: string): any`	Function	A data field of the entity's record (Character or World scope), or "Account.<Field>" of its character's account.
`Persistence.Set(entity: Entity, field: string, value: any)`	Function	Sets a data field (validated against the schema: types, bounds, enum names, struct members; nil sets the default; an empty table is an empty List).
`Persistence.SaveNow(entity: Entity): boolean`	Function	Captures and saves the entity's record (and its character's account) now, without waiting for the autosave.
`Persistence.Transact(changes: table[], ledger?: table[], serviceOperands?: string[]): boolean`	Function	Applies data-field changes { Entity, Field, Value } of one or more entities (two traders) atomically: every affected record is saved in one local transaction and is durable when it returns true; the central store applies it as one transaction too.
`Persistence.GetCharacterId(entity: Entity): integer?`	Function	The character whose record a Character-scope entity carries; nil before it is bound and for other entities.
`Persistence.GetAccountId(entity: Entity): integer?`	Function	The account of the entity's character; nil when it has none.
`Persistence.IsLoaded(entity: Entity): boolean`	Function	True once the entity's record was restored (and until its character logs out).

Persistence.IsEnabled#

lua

Persistence.IsEnabled(): boolean

True when persistence runs in this scene: an entity has a Persistence component, the project declares something persistent, the zone's store is open and this peer is not a client of a session.

Returns boolean

Persistence.Get#

lua

Persistence.Get(entity: Entity, field: string): any

A data field of the entity's record (Character or World scope), or "Account.<Field>" of its character's account. Raises an error for an entity without a Persistence component, a field the schema does not declare and a record that is not loaded yet (Persistence.IsLoaded).

Parameters

entity (Entity)
field (string)

Returns any

Example

lua

local quests = Persistence.Get(self.Entity, "QuestFlags")

Persistence.Set#

lua

Persistence.Set(entity: Entity, field: string, value: any)

Sets a data field (validated against the schema: types, bounds, enum names, struct members; nil sets the default; an empty table is an empty List). Saved with the next autosave of the entity.

Parameters

entity (Entity)
field (string)
value (any)

Example

lua

Persistence.Set(self.Entity, "Gold", 120)

Persistence.SaveNow#

lua

Persistence.SaveNow(entity: Entity): boolean

Captures and saves the entity's record (and its character's account) now, without waiting for the autosave. Returns false (with a warning) when it cannot be saved: persistence is off or the record is not loaded. OnPersistentSaved() follows once the save is durable.

Parameters

entity (Entity)

Returns boolean

Persistence.Transact#

lua

Persistence.Transact(changes: table[], ledger?: table[], serviceOperands?: string[]): boolean

Applies data-field changes { Entity, Field, Value } of one or more entities (two traders) atomically: every affected record is saved in one local transaction and is durable when it returns true; the central store applies it as one transaction too. The ledger's entries { Kind, From, To, Item, Amount } go to the economy log. Invalid changes raise an error and change nothing; false (with a warning) when the commit fails. With serviceOperands (the Operand strings returned by Guild, Mail or Market), true means the central transaction started; OnServiceTransferResult reports its durable result. The operands must share one transfer id.

Parameters

changes (table[])
ledger? (table[])
serviceOperands? (string[])

Returns boolean

Example

lua

local ok = Persistence.Transact({
	{ Entity = buyer, Field = "Gold", Value = buyerGold - 50 },
	{ Entity = seller, Field = "Gold", Value = sellerGold + 50 },
}, { { Kind = "trade", From = 1, To = 2, Item = "sword", Amount = 1 } })

Persistence.GetCharacterId#

lua

Persistence.GetCharacterId(entity: Entity): integer?

The character whose record a Character-scope entity carries; nil before it is bound and for other entities.

Parameters

entity (Entity)

Returns integer?

Persistence.GetAccountId#

lua

Persistence.GetAccountId(entity: Entity): integer?

The account of the entity's character; nil when it has none.

Parameters

entity (Entity)

Returns integer?

Persistence.IsLoaded#

lua

Persistence.IsLoaded(entity: Entity): boolean

True once the entity's record was restored (and until its character logs out).

Parameters

entity (Entity)

Returns boolean

Physics#

2D physics of the running scene (Box2D): queries, gravity and layer masks. Queries see the world as of the last fixed step (bodies created since then appear after the next one). Scripts of the colliding entities (and of their bodies, for child colliders) receive OnCollisionBegin(other, contact) / OnCollisionEnd(other) and, for sensor colliders, OnTriggerEnter(other) / OnTriggerExit(other) after each fixed step; other is the other collider's entity (an Entity whose IsValid() is false when it was destroyed meanwhile). Rigidbody2D calls on a body that does not exist yet (its component was added, or its entity spawned, this frame) are applied in call order right before the next physics step, all such bodies created together; reading such a body's state (velocities, mass, IsAwake) creates it at once, and SetTransform / Teleport move its entity at once. Needs the scene's Physics system (and the ScriptModules system for the callbacks and the batched creation of new bodies).

lua

local hit = Physics.Raycast(self.Entity.WorldPosition, Vec2.Down, 1.1, Physics.LayerMask("Ground"))
self.Grounded = hit ~= nil

Member	Kind	Summary
`Physics.Raycast(origin: Vec2, direction: Vec2, maxDistance: number, layerMask?: integer, includeSensors?: boolean): RaycastHit?`	Function	The closest collider hit by the ray from origin along direction (any non-zero length) within maxDistance (> 0), or nil.
`Physics.RaycastAll(origin: Vec2, direction: Vec2, maxDistance: number, layerMask?: integer, includeSensors?: boolean): RaycastHit[]`	Function	Every entity hit by the ray, closest first, with one hit per entity (its closest collider).
`Physics.OverlapCircle(center: Vec2, radius: number, layerMask?: integer, includeSensors?: boolean): Entity[]`	Function	Every entity with a collider overlapping the circle (touching counts), each once, ordered by ID.
`Physics.OverlapBox(center: Vec2, size: Vec2, angle?: number, layerMask?: integer, includeSensors?: boolean): Entity[]`	Function	Every entity with a collider overlapping the box of the given full size centred on center, rotated by angle radians (default 0); each once, ordered by ID.
`Physics.OverlapAABB(min: Vec2, max: Vec2, layerMask?: integer, includeSensors?: boolean): Entity[]`	Function	Every entity with a collider overlapping the axis-aligned box from min to max (the collider's geometry, not just its bounds; touching counts), each once, ordered by ID.
`Physics.OverlapPoint(point: Vec2, layerMask?: integer, includeSensors?: boolean): Entity[]`	Function	Every entity with a collider containing the point (on the outline counts), each once, ordered by ID.
`Physics.CircleCast(center: Vec2, radius: number, direction: Vec2, maxDistance: number, layerMask?: integer, includeSensors?: boolean): RaycastHit?`	Function	Sweeps a circle of radius (> 0) from center along direction (any non-zero length) up to maxDistance (> 0) and returns the first collider it hits, or nil: Point is the contact point, Distance how far the circle's center travelled.
`Physics.LayerMask(...: string): integer`	Function	The query mask of the named physics layers (names from the project's physics settings; unknown names raise an error).
`Physics.Gravity: Vec2`	Property	World gravity in units per second squared: the project's physics gravity, or the scene's own when its settings override it, unless a script assigned one.
`Physics.AllLayers: integer (read-only)`	Constant	The mask of every physics layer (the default of the query functions).

Physics.Raycast#

lua

Physics.Raycast(origin: Vec2, direction: Vec2, maxDistance: number, layerMask?: integer, includeSensors?: boolean): RaycastHit?

The closest collider hit by the ray from origin along direction (any non-zero length) within maxDistance (> 0), or nil. Colliders that contain the origin are not hit, nor is a collider whose outline the origin lies on; sensors only with includeSensors.

Parameters

origin (Vec2)
direction (Vec2)
maxDistance (number)
layerMask? (integer): Physics layers to test (Physics.LayerMask); all layers by default.
includeSensors? (boolean)

Returns RaycastHit?: The closest hit, or nil.

Example

lua

local hit = Physics.Raycast(self.Entity.WorldPosition, Vec2.Right, 10)
if hit then hit.Entity:SendMessage("OnShot") end

Physics.RaycastAll#

lua

Physics.RaycastAll(origin: Vec2, direction: Vec2, maxDistance: number, layerMask?: integer, includeSensors?: boolean): RaycastHit[]

Every entity hit by the ray, closest first, with one hit per entity (its closest collider). A new table, empty when nothing is hit.

Parameters

origin (Vec2)
direction (Vec2)
maxDistance (number)
layerMask? (integer)
includeSensors? (boolean)

Returns RaycastHit[]

Example

lua

for _, hit in ipairs(Physics.RaycastAll(origin, Vec2.Right, 20)) do print(hit.Entity.Name) end

Physics.OverlapCircle#

lua

Physics.OverlapCircle(center: Vec2, radius: number, layerMask?: integer, includeSensors?: boolean): Entity[]

Every entity with a collider overlapping the circle (touching counts), each once, ordered by ID. A new table.

Parameters

center (Vec2)
radius (number)
layerMask? (integer)
includeSensors? (boolean)

Returns Entity[]

Example

lua

for _, entity in ipairs(Physics.OverlapCircle(self.Entity.WorldPosition, 3)) do entity:SendMessage("OnExplosion") end

Physics.OverlapBox#

lua

Physics.OverlapBox(center: Vec2, size: Vec2, angle?: number, layerMask?: integer, includeSensors?: boolean): Entity[]

Every entity with a collider overlapping the box of the given full size centred on center, rotated by angle radians (default 0); each once, ordered by ID. A new table.

Parameters

center (Vec2)
size (Vec2)
angle? (number)
layerMask? (integer)
includeSensors? (boolean)

Returns Entity[]

Example

lua

local inside = Physics.OverlapBox(Vec2(0, 0), Vec2(4, 2))

Physics.OverlapAABB#

lua

Physics.OverlapAABB(min: Vec2, max: Vec2, layerMask?: integer, includeSensors?: boolean): Entity[]

Every entity with a collider overlapping the axis-aligned box from min to max (the collider's geometry, not just its bounds; touching counts), each once, ordered by ID. A new table. min greater than max on an axis raises an error; a box of zero size is a line or a point.

Parameters

min (Vec2)
max (Vec2)
layerMask? (integer)
includeSensors? (boolean)

Returns Entity[]

Example

lua

local inRoom = Physics.OverlapAABB(Vec2(-5, -3), Vec2(5, 3))

Physics.OverlapPoint#

lua

Physics.OverlapPoint(point: Vec2, layerMask?: integer, includeSensors?: boolean): Entity[]

Every entity with a collider containing the point (on the outline counts), each once, ordered by ID. A new table.

Parameters

point (Vec2)
layerMask? (integer)
includeSensors? (boolean)

Returns Entity[]

Example

lua

local clicked = Physics.OverlapPoint(Camera.ScreenToWorld(Input.GetMousePosition()))
if clicked[1] then clicked[1]:SendMessage("OnClicked") end

Physics.CircleCast#

lua

Physics.CircleCast(center: Vec2, radius: number, direction: Vec2, maxDistance: number, layerMask?: integer, includeSensors?: boolean): RaycastHit?

Sweeps a circle of radius (> 0) from center along direction (any non-zero length) up to maxDistance (> 0) and returns the first collider it hits, or nil: Point is the contact point, Distance how far the circle's center travelled. The circle stops 0.005 world units (the physics' contact margin) inside the collider, so Point lies that much inside its outline. A collider the circle already overlaps at the start is hit at distance 0 with a zero normal.

Parameters

center (Vec2)
radius (number): The circle's radius in world units.
direction (Vec2)
maxDistance (number)
layerMask? (integer)
includeSensors? (boolean)

Returns RaycastHit?: The first hit, or nil.

Example

lua

local hit = Physics.CircleCast(self.Entity.WorldPosition, 0.5, self.Velocity, 2)
if hit then self:Bounce(hit.Normal) end

Physics.LayerMask#

lua

Physics.LayerMask(...: string): integer

The query mask of the named physics layers (names from the project's physics settings; unknown names raise an error). No names: 0, a mask that matches nothing.

Parameters

...? (string)

Returns integer

Example

lua

local mask = Physics.LayerMask("Default", "Enemies")

Physics.Gravity#

lua

Physics.Gravity: Vec2

World gravity in units per second squared: the project's physics gravity, or the scene's own when its settings override it, unless a script assigned one. Assigning overrides it for the rest of the run from the next fixed step on. Non-finite values raise an error.

Example

lua

Physics.Gravity = Vec2(0, -20)

Physics.AllLayers#

lua

Physics.AllLayers: integer (read-only)

The mask of every physics layer (the default of the query functions).

Progression#

Character XP and levels (Progression settings: CharacterCurve, MaxLevel) and the timed actions of crafting and gathering. Where the scene has authority (servers, hosts, offline games) the functions read and change the authoritative state; on a client they read the local character's mirrored Skills section and the replicated level, and a cancel is a request of the RPG lane. A player character is an RpgActor with a Class and no Template.

lua

local ok, why = Progression.AddXp(player, 250)
if not ok then Log.Warn(why) end
Log.Info("level " .. Progression.GetLevel(player))

Member	Kind	Summary
`Progression.AddXp(player: Entity, xp: integer): boolean, string?`	Function	Grants character XP (source "Script"): level-ups up to Progression.MaxLevel raise RpgActor.Level, teach the class abilities of each level reached and call OnLevelUp per level; XP stops at the max level's.
`Progression.SetLevel(player: Entity, level: integer): boolean, string?`	Function	Sets the character's level (a tutorial, a scripted boost): with a character curve its XP becomes the level's; raising it applies every level-up in between (abilities, OnLevelUp), lowering it keeps what was learned.
`Progression.GetLevel(entity: Entity): integer`	Function	An RPG actor's level (players and NPCs; any entity on a client: the replicated public state, the local character's mirrored section); 0 for entities that are no RPG actor.
`Progression.GetXp(player: Entity): integer?`	Function	The character's XP (0 before any).
`Progression.GetXpForNextLevel(player: Entity): integer?`	Function	The XP the character's next level needs (cumulative, on Progression.CharacterCurve); nil at the max level, without a character curve, and on a client before the RPG database was built.
`Progression.GetAction(player: Entity): table?`	Function	The character's craft or gather in progress: { Kind = "Craft" or "Gather", Key (the recipe or gathering node), Remaining (crafts of the batch left, the current one included), Progress (0 to 1 of the current one) }; nil when idle.
`Progression.CancelAction(player: Entity): boolean, string\|integer?`	Function	Ends the character's craft batch or gather without completing the current step (OnActionEnded with "Cancelled").

Progression.AddXp#

lua

Progression.AddXp(player: Entity, xp: integer): boolean, string?

Grants character XP (source "Script"): level-ups up to Progression.MaxLevel raise RpgActor.Level, teach the class abilities of each level reached and call OnLevelUp per level; XP stops at the max level's. False and why for an entity that is no player character or a scene without an RPG database. Authority only.

Parameters

player (Entity): The player character.
xp (integer): The XP, in [1, 1,000,000,000].

Returns boolean, string?

Example

lua

Progression.AddXp(player, 500)

Progression.SetLevel#

lua

Progression.SetLevel(player: Entity, level: integer): boolean, string?

Sets the character's level (a tutorial, a scripted boost): with a character curve its XP becomes the level's; raising it applies every level-up in between (abilities, OnLevelUp), lowering it keeps what was learned. False and why above Progression.MaxLevel. Authority only.

Parameters

player (Entity): The player character.
level (integer): The level, in [1, Progression.MaxLevel].

Returns boolean, string?

Example

lua

Progression.SetLevel(player, 10)

Progression.GetLevel#

lua

Progression.GetLevel(entity: Entity): integer

An RPG actor's level (players and NPCs; any entity on a client: the replicated public state, the local character's mirrored section); 0 for entities that are no RPG actor.

Parameters

entity (Entity): The actor.

Returns integer

Example

lua

levelLabel:GetComponent("UIText"):SetText("Level " .. Progression.GetLevel(player))

Progression.GetXp#

lua

Progression.GetXp(player: Entity): integer?

The character's XP (0 before any). On a client only the local character's, from its Skills section: nil for other entities and before the section arrived.

Parameters

player (Entity): The player character.

Returns integer?

Example

lua

local xp = Progression.GetXp(player) or 0

Progression.GetXpForNextLevel#

lua

Progression.GetXpForNextLevel(player: Entity): integer?

The XP the character's next level needs (cumulative, on Progression.CharacterCurve); nil at the max level, without a character curve, and on a client before the RPG database was built.

Parameters

player (Entity): The player character.

Returns integer?

Example

lua

local next = Progression.GetXpForNextLevel(player)
if next then UI.SetFill(bar, Progression.GetXp(player) / next) end

Progression.GetAction#

lua

Progression.GetAction(player: Entity): table?

The character's craft or gather in progress: { Kind = "Craft" or "Gather", Key (the recipe or gathering node), Remaining (crafts of the batch left, the current one included), Progress (0 to 1 of the current one) }; nil when idle. Authority only (a client's cast bar comes from its request's answer).

Parameters

player (Entity): The player character.

Returns table?

Example

lua

local action = Progression.GetAction(player)
if action then Log.Info(action.Kind .. " " .. action.Key) end

Progression.CancelAction#

lua

Progression.CancelAction(player: Entity): boolean, string|integer?

Ends the character's craft batch or gather without completing the current step (OnActionEnded with "Cancelled"). Where the scene has authority: false and why when it was idle. On a client: a CancelCraft request; true and its request id when sent.

Parameters

player (Entity): The player character (on a client: one it controls).

Returns boolean, string|integer?

Example

lua

Progression.CancelAction(player)

Quests#

The quest logs of player characters (servers, hosts and offline games: the scene's Quests system; on a client GetLog answers for the local character from the RPG lane and changes are refused). Quests are .fquest assets named by their Id. Changes return true, or false and "<Refusal>: <why>" (UnknownQuest, AlreadyActive, Prerequisites, LogFull, NotReady, NoRoom, ...) and change nothing; wrong arguments raise errors.

lua

local ok, why = Quests.Accept(player, "Q_WolvesAtTheGate")
if not ok then Log.Warn(why) end

Member	Kind	Summary
`Quests.Accept(player: Entity, quest: string): boolean, string?`	Function	Adds a quest to the player's log as a script decides it (no giver check): its prerequisites, repeat rules and Quests.MaxActive hold.
`Quests.CanAccept(player: Entity, quest: string): boolean, string?`	Function	Whether Accept would add the quest now (the giver aside), and why not.
`Quests.Abandon(player: Entity, quest: string): boolean, string?`	Function	Drops an active quest: its step's spawns go, its phase ends, OnQuestFailed(quest, "Abandoned") follows.
`Quests.TurnIn(player: Entity, quest: string, choice?: integer): boolean, string?`	Function	Completes a quest that reached its end (no NPC check): the consumed items leave, the rewards arrive in one transaction (what does not fit goes by system mail on a zone with a Social host, else the turn-in is refused), XP and reputation through progression, then OnQuestCompleted.
`Quests.IsActive(player: Entity, quest: string): boolean`	Function	Whether the quest is in the player's log.
`Quests.IsCompleted(player: Entity, quest: string): boolean`	Function	Whether the player completed the quest (a repeatable one: at least once).
`Quests.GetStep(player: Entity, quest: string): string?`	Function	The id of the quest's active step ("end" once it waits to be turned in); nil when it is not active.
`Quests.GetLog(player: Entity): table`	Function	The player's active quests in log order: a list of { Quest, Title, Step, StepTitle, Ready, AcceptedAt, Deadline?, Counters, Required } (counters and their targets in the step's objective order; times in UTC milliseconds).
`Quests.Raise(player: Entity, event: string, value?: integer)`	Function	Counts a Custom objective event: every Custom objective of the player's active steps with this Event name gains value (default 1).
`Quests.RecordItemUse(player: Entity, item: string, count?: integer)`	Function	Counts item uses the item system does not see, for UseItem objectives (a script that spends the item itself); Inventory.Use and the UseItem request count on their own (the ItemUsed event), so an item's Use hook must not call it.
`Quests.GetMarker(player: Entity, npc: Entity): string`	Function	What the NPC shows the player: "ReadyToTurnIn", "Available", "InProgress" or "None".
`Quests.GetMarkers(player: Entity): table`	Function	The quest NPCs with a marker for the player, by entity id: a list of { Npc, Marker } (a zone server: the NPCs relevant to the player's client).
`Quests.GetPhase(player: Entity): integer`	Function	The phase the player's quest log puts it in (the active step's Phase, Quests.PhasePriority between quests; 0: the shared world).
`Quests.Reset(player: Entity, quest: string): boolean, string?`	Function	Forgets the quest for the player (active, completed, its repeat time) so it can be taken again.

Quests.Accept#

lua

Quests.Accept(player: Entity, quest: string): boolean, string?

Adds a quest to the player's log as a script decides it (no giver check): its prerequisites, repeat rules and Quests.MaxActive hold. Its start step begins (spawns, phase, OnEnter hook) and OnQuestAccepted follows.

Parameters

player (Entity): A player character (an RpgActor with a Class).
quest (string): The quest's Id.

Returns boolean, string?

Example

lua

Quests.Accept(player, "Q_WolvesAtTheGate")

Quests.CanAccept#

lua

Quests.CanAccept(player: Entity, quest: string): boolean, string?

Whether Accept would add the quest now (the giver aside), and why not.

Parameters

player (Entity): The player character.
quest (string): The quest's Id.

Returns boolean, string?

Example

lua

UI.SetVisible(questMarker, Quests.CanAccept(player, "Q_Daily"))

Quests.Abandon#

lua

Quests.Abandon(player: Entity, quest: string): boolean, string?

Drops an active quest: its step's spawns go, its phase ends, OnQuestFailed(quest, "Abandoned") follows.

Parameters

player (Entity): The player character.
quest (string): The quest's Id.

Returns boolean, string?

Example

lua

Quests.Abandon(player, "Q_WolvesAtTheGate")

Quests.TurnIn#

lua

Quests.TurnIn(player: Entity, quest: string, choice?: integer): boolean, string?

Completes a quest that reached its end (no NPC check): the consumed items leave, the rewards arrive in one transaction (what does not fit goes by system mail on a zone with a Social host, else the turn-in is refused), XP and reputation through progression, then OnQuestCompleted.

Parameters

player (Entity): The player character.
quest (string): The quest's Id.
choice? (integer): Which Choice reward, from 1 (default 1; ignored without choices).

Returns boolean, string?

Example

lua

Quests.TurnIn(player, "Q_WolvesAtTheGate", 2)

Quests.IsActive#

lua

Quests.IsActive(player: Entity, quest: string): boolean

Whether the quest is in the player's log.

Parameters

player (Entity): The player character.
quest (string): The quest's Id.

Returns boolean

Example

lua

if Quests.IsActive(player, "Q_Arrival") then ... end

Quests.IsCompleted#

lua

Quests.IsCompleted(player: Entity, quest: string): boolean

Whether the player completed the quest (a repeatable one: at least once).

Parameters

player (Entity): The player character.
quest (string): The quest's Id.

Returns boolean

Example

lua

if Quests.IsCompleted(player, "Q_Arrival") then Door.Open() end

Quests.GetStep#

lua

Quests.GetStep(player: Entity, quest: string): string?

The id of the quest's active step ("end" once it waits to be turned in); nil when it is not active.

Parameters

player (Entity): The player character.
quest (string): The quest's Id.

Returns string?

Example

lua

if Quests.GetStep(player, "Q_WolvesAtTheGate") == "s2" then Captain:Wave() end

Quests.GetLog#

lua

Quests.GetLog(player: Entity): table

The player's active quests in log order: a list of { Quest, Title, Step, StepTitle, Ready, AcceptedAt, Deadline?, Counters, Required } (counters and their targets in the step's objective order; times in UTC milliseconds). On a client: the local character's log from the RPG lane, ordered by the quests' key hashes and without AcceptedAt; empty for anyone else.

Parameters

player (Entity): The player character.

Returns table

Example

lua

for _, quest in ipairs(Quests.GetLog(player)) do Log.Info(quest.Title .. ": " .. quest.Step) end

Quests.Raise#

lua

Quests.Raise(player: Entity, event: string, value?: integer)

Counts a Custom objective event: every Custom objective of the player's active steps with this Event name gains value (default 1).

Parameters

player (Entity): The player character.
event (string): The Custom objective's Event name.
value? (integer): How much (default 1).

Example

lua

Quests.Raise(player, "LitBeacon")

Quests.RecordItemUse#

lua

Quests.RecordItemUse(player: Entity, item: string, count?: integer)

Counts item uses the item system does not see, for UseItem objectives (a script that spends the item itself); Inventory.Use and the UseItem request count on their own (the ItemUsed event), so an item's Use hook must not call it.

Parameters

player (Entity): The player character.
item (string): The item key.
count? (integer): How many uses (default 1).

Example

lua

Inventory.Take(player, "war_horn", 1) Quests.RecordItemUse(player, "war_horn")

Quests.GetMarker#

lua

Quests.GetMarker(player: Entity, npc: Entity): string

What the NPC shows the player: "ReadyToTurnIn", "Available", "InProgress" or "None".

Parameters

player (Entity): The player character.
npc (Entity): A quest giver or turn-in NPC.

Returns string

Example

lua

Nameplate.SetIcon(npc, Quests.GetMarker(player, npc))

Quests.GetMarkers#

lua

Quests.GetMarkers(player: Entity): table

The quest NPCs with a marker for the player, by entity id: a list of { Npc, Marker } (a zone server: the NPCs relevant to the player's client).

Parameters

player (Entity): The player character.

Returns table

Example

lua

for _, giver in ipairs(Quests.GetMarkers(player)) do Log.Info(giver.Marker) end

Quests.GetPhase#

lua

Quests.GetPhase(player: Entity): integer

The phase the player's quest log puts it in (the active step's Phase, Quests.PhasePriority between quests; 0: the shared world).

Parameters

player (Entity): The player character.

Returns integer

Example

lua

UI.SetVisible(phasedBadge, Quests.GetPhase(player) ~= 0)

Quests.Reset#

lua

Quests.Reset(player: Entity, quest: string): boolean, string?

Forgets the quest for the player (active, completed, its repeat time) so it can be taken again.

Parameters

player (Entity): The player character.
quest (string): The quest's Id.

Returns boolean, string?

Example

lua

Quests.Reset(player, "Q_Tutorial")

Realm#

The realm a zone server belongs to: its process key - zone, shard, layer or instance - on realm zones (FrostRuntime --server --services <realm cluster> --zone Lumbridge@1.2), nil everywhere else (clients, the editor, standalone servers). Backend service scripts (Assets/Services/*.lua on FrostServices) install the coordinator's layer policy here.

lua

if Realm.GetZone() == "Lumbridge" and Realm.GetLayer() > 1 then
	print("an overflow layer of Lumbridge")
end

Member	Kind	Summary
`Realm.GetZone(): string?`	Function	The topology zone (or instance template) this zone server runs; nil when the scene does not run on a realm zone.
`Realm.GetShard(): integer?`	Function	The shard (1-based copy of the realm's zones that players pick at login); nil off realm zones.
`Realm.GetLayer(): integer?`	Function	The layer (1-based automatic copy of a full zone within its shard; 0 on an instance); nil off realm zones.
`Realm.GetInstanceId(): integer?`	Function	The instance id on an instance's process (0 on a zone's layer); nil off realm zones.
`Realm.Travel(player: integer, zone: string, position: Vec2): boolean`	Function	Server: begins moving the player's character to a zone in this shard.
`Realm.EnterInstance(player: integer, instanceId: integer): boolean`	Function	Server: begins moving a player's character into an existing reserved instance; the coordinator validates membership and capacity.
`Realm.ChangeLayer(player: integer, layer: integer): boolean`	Function	Server: requests another layer of this zone for the player's character, preserving its world position.
`Realm.HopShard(player: integer, shard: integer): boolean`	Function	Server: requests the same zone on another shard.
`Realm.SetLayerPolicy(fn?: function): function?`	Function	Backend service scripts (Assets/Services/*.lua on FrostServices): orders the layers the coordinator may place a character on with fn(character, layers) -> layers.

Realm.GetZone#

lua

Realm.GetZone(): string?

The topology zone (or instance template) this zone server runs; nil when the scene does not run on a realm zone.

Returns string?

Realm.GetShard#

lua

Realm.GetShard(): integer?

The shard (1-based copy of the realm's zones that players pick at login); nil off realm zones.

Returns integer?

Realm.GetLayer#

lua

Realm.GetLayer(): integer?

The layer (1-based automatic copy of a full zone within its shard; 0 on an instance); nil off realm zones.

Returns integer?

Realm.GetInstanceId#

lua

Realm.GetInstanceId(): integer?

The instance id on an instance's process (0 on a zone's layer); nil off realm zones.

Returns integer?

Realm.Travel#

lua

Realm.Travel(player: integer, zone: string, position: Vec2): boolean

Server: begins moving the player's character to a zone in this shard. Position is absolute world space. Returns true when the request starts; completion is asynchronous. Invalid players, unavailable destinations and an in-flight handoff raise an error.

Parameters

player (integer)
zone (string)
position (Vec2)

Returns boolean

Realm.EnterInstance#

lua

Realm.EnterInstance(player: integer, instanceId: integer): boolean

Server: begins moving a player's character into an existing reserved instance; the coordinator validates membership and capacity.

Parameters

player (integer)
instanceId (integer)

Returns boolean

Realm.ChangeLayer#

lua

Realm.ChangeLayer(player: integer, layer: integer): boolean

Server: requests another layer of this zone for the player's character, preserving its world position.

Parameters

player (integer)
layer (integer)

Returns boolean

Realm.HopShard#

lua

Realm.HopShard(player: integer, shard: integer): boolean

Server: requests the same zone on another shard. The coordinator applies the shard's placement policy and access rules.

Parameters

player (integer)
shard (integer)

Returns boolean

Realm.SetLayerPolicy#

lua

Realm.SetLayerPolicy(fn?: function): function?

Backend service scripts (Assets/Services/*.lua on FrostServices): orders the layers the coordinator may place a character on with fn(character, layers) -> layers. layers lists the candidates' numbers in the default order (layers holding party members, then guild members, then friends, then the fullest below the soft capacity); return the ones to use, best first (a subset), or nil for the default. An error or anything else keeps the default order (the policy fails closed). nil removes the hook. Returns the previous hook. In game scripts it only records the function.

Parameters

fn? (function)

Returns function?

Example

lua

Realm.SetLayerPolicy(function(character, layers)
    if Veterans[character] then return { layers[#layers] } end
end)

Reputation#

Characters' standings with the factions that track reputation (Faction rows with Reputation): changed by kills (NpcTemplate.Reputation), quests and scripts; the ReputationTier a standing falls in sets the faction's relation to the player (hostile guards, a vendor's Faction.Min entries). On a client the functions read the local character's mirrored Reputation section.

lua

Reputation.Add(player, "city_guard", 250)
Log.Info(Reputation.GetTier(player, "city_guard").Name)

Member	Kind	Summary
`Reputation.Add(player: Entity, faction: string, amount: integer): boolean, string?`	Function	Changes the standing with a tracked faction (clamped to +-1,000,000,000; OnReputationChanged when it changed).
`Reputation.Get(player: Entity, faction: string): integer?`	Function	The character's standing with a faction (its StartingReputation until it changed).
`Reputation.GetTier(player: Entity, faction: string): table?`	Function	The ReputationTier the character's standing with a faction falls in: { Key, Name, Min, Relation } (Relation: "Hostile", "Unfriendly", "Neutral", "Friendly" or "Allied"); nil without tiers (and on a client as Reputation.Get).
`Reputation.GetAll(player: Entity): table`	Function	The character's standings that changed from their start: a list of { Faction, Standing, Tier?, Relation? } (on a client the local character's).

Reputation.Add#

lua

Reputation.Add(player: Entity, faction: string, amount: integer): boolean, string?

Changes the standing with a tracked faction (clamped to +-1,000,000,000; OnReputationChanged when it changed). False and why for an unknown or untracked faction or an entity that is no player character. Authority only.

Parameters

player (Entity): The player character.
faction (string): The Faction row key.
amount (integer): The change, in [-100,000,000, 100,000,000].

Returns boolean, string?

Example

lua

Reputation.Add(player, "bandits", -50)

Reputation.Get#

lua

Reputation.Get(player: Entity, faction: string): integer?

The character's standing with a faction (its StartingReputation until it changed). On a client nil for anyone but the local character and before its Reputation section arrived. Unknown factions raise an error.

Parameters

player (Entity): The player character.
faction (string): The Faction row key.

Returns integer?

Example

lua

local standing = Reputation.Get(player, "city_guard")

Reputation.GetTier#

lua

Reputation.GetTier(player: Entity, faction: string): table?

The ReputationTier the character's standing with a faction falls in: { Key, Name, Min, Relation } (Relation: "Hostile", "Unfriendly", "Neutral", "Friendly" or "Allied"); nil without tiers (and on a client as Reputation.Get).

Parameters

player (Entity): The player character.
faction (string): The Faction row key.

Returns table?

Example

lua

local tier = Reputation.GetTier(player, "city_guard")
if tier then Log.Info(tier.Name) end

Reputation.GetAll#

lua

Reputation.GetAll(player: Entity): table

The character's standings that changed from their start: a list of { Faction, Standing, Tier?, Relation? } (on a client the local character's). Empty for others.

Parameters

player (Entity): The player character.

Returns table

Example

lua

for _, entry in ipairs(Reputation.GetAll(player)) do Log.Info(entry.Faction .. " " .. entry.Standing) end

Rpg#

RPG actors (entities with an RpgActor): their public state, visible status effects, relations, death and respawn, targets, interactions, custom events and Lua conditions. On a scene with an RPG store (servers, hosts, offline games) it reads and changes the store; on a client's scene it reads what the server replicated and turns SetTarget, Interact and Respawn into requests whose answers arrive as OnRpgRequestResult. Functions that only the server may perform raise an error on clients. A client's local character - the actor the client read functions of Stats, Abilities, Inventory, Quests and the other RPG namespaces answer for - is the first networked entity with an RpgActor whose Class is set that the client owns when it spawns there (the player's character, spawned by the server with the client as its owner); until the server replaces it, no other actor is: one handed to the client later with Net.SetOwner reads as anyone else's (nil, 0 or empty).

lua

local public = Rpg.GetPublic(self.Entity)
if public and public.Health < public.HealthMax * 0.2 then Log.Warn("low health") end

Member	Kind	Summary
`Rpg.IsActor(entity: Entity): boolean`	Function	Whether the entity is an RPG actor (it has an RpgActor component).
`Rpg.IsPlayer(entity: Entity): boolean`	Function	Whether the actor is a player character (RpgActor.Class set, no Template).
`Rpg.IsInitialized(entity: Entity): boolean?`	Function	Servers: whether the character's RPG state was created from its class (Rpg.Initialized, character creation: level 1, the class's stats and resources, starting abilities and items).
`Rpg.GetPublic(entity: Entity): { Health: number, HealthMax: number, Resource: number, ResourceMax: number, ResourceStat: string?, Level: integer, Faction: string?, States: { string }, Dead: boolean, InCombat: boolean, Casting: boolean, CastAbilityHash: integer, CastStartTick: integer, CastEndTick: integer, Target: Entity?, Classification: string }?`	Function	The actor's public state - what every peer sees: health, its primary resource, level, faction, its states (Dead, InCombat, Casting, Channeling, Stunned, Rooted, Silenced, Invisible, PvP), the cast in progress (the ability's key hash and its ticks), its target and its classification (Normal, Elite, Rare, Boss).
`Rpg.GetEffects(entity: Entity): { { Effect: string?, EffectHash: integer, Stacks: integer, Remaining: number, Duration: number, Caster: Entity?, Instance: integer } }`	Function	The entity's visible status effects (StatusEffect.Visible) in application order: the effect's key (nil on a client without the definition), stacks, seconds left (-1: until removed), its duration, the caster when the scene has it, and the instance id.
`Rpg.GetRelation(entity: Entity, from?: Entity): string?`	Function	How `from` stands towards the entity: "Hostile", "Unfriendly", "Neutral", "Friendly" or "Allied".
`Rpg.GetLevel(entity: Entity): integer?`	Function	The actor's level; nil for non-actors.
`Rpg.SetLevel(entity: Entity, level: integer)`	Function	Sets the actor's level (1-1000): its stat profile's base values follow.
`Rpg.IsDead(entity: Entity): boolean`	Function	Whether the actor is dead (false for non-actors).
`Rpg.IsInCombat(entity: Entity): boolean`	Function	Whether the actor is in combat: it dealt or took damage or was threatened less than Combat.CombatTimeoutSeconds ago.
`Rpg.HasState(entity: Entity, state: string): boolean`	Function	Whether one of the actor's status effects gives it the state (StatusEffect.States: Stunned, Rooted, Silenced, Disarmed, Pacified, Immune, Invisible, Stealthed, Sleeping or a game's own name; case-insensitive).
`Rpg.Kill(entity: Entity, killer?: Entity)`	Function	Kills the actor now: the Death event (OnDeath on its script), the Kill event for the credited players, NPC corpses, player respawn timers.
`Rpg.Respawn(entity: Entity): integer?`	Function	Brings a dead player back by Rpg.Respawn (its bind point, the nearest graveyard, or where it died for Script: OnRespawn moves it) with full resources.
`Rpg.SetBindPoint(entity: Entity, position: Vec2)`	Function	Where the player comes back with Rpg.Respawn = AtBindPoint (saved with the character).
`Rpg.SetTarget(entity: Entity, target?: Entity): integer?`	Function	The actor's target (nil clears it): it replicates as the public state's Target.
`Rpg.GetTarget(entity: Entity): Entity?`	Function	The actor's target, or nil.
`Rpg.Interact(entity: Entity, target: Entity): integer?`	Function	The actor interacts with an Interactable within its Range (plus Combat.RangeTolerance): the Interact event (and Talk for Talk interactables) that quests and scripts react to.
`Rpg.SetPvP(entity: Entity, enabled: boolean)`	Function	The player's PvP flag: two flagged players may attack each other in Contested areas (PvPVolume).
`Rpg.Emit(entity: Entity, name: string, value?: integer, amount?: number)`	Function	Records a Custom event about the entity on the RPG event bus (quests' Custom objectives, OnRpgEvent, analytics): its KeyHash is Rpg.Hash(name).
`Rpg.Hash(key: string): integer`	Function	The 32-bit key hash the RPG framework names keys by on the wire and in events (FNV-1a of the key with ASCII upper case folded): compare it with KeyHash, CastAbilityHash and EffectHash values.
`Rpg.RegisterCondition(name: string, predicate: function \| string)`	Function	Registers a Lua predicate that conditions in data name (loot entries, vendors, requirements, dialogue branches, NPC ability choices: "IsNight & Level.Min(10)"): predicate(ctx, ...) gets ctx.Player and ctx.Npc (Entities or nil) and the condition's arguments (numbers or strings), and returns a boolean (anything else, or an error, is false).
`Rpg.CheckCondition(entity: Entity, condition: string, npc?: Entity): boolean`	Function	Evaluates condition text for the actor as the data's conditions are (Level.Min(10) & !Effect.Has(burning), Lua predicates of Rpg.RegisterCondition); Random(p) draws from the actor's own stream.
`Rpg.GetRequestResult(id: integer): { Status: string, Code: integer, Message: string, StartTick: integer, EndTick: integer }?`	Function	Clients: the server's answer to a request (the newest 64 are kept) - Status "Ok", "Refused", "RateLimited", "OutOfRange", ...; nil while none arrived, for unknown ids and on servers (which act at once).
`Rpg.GetScriptStats(): { Calls: integer, Errors: integer, Milliseconds: number, OverBudgetTicks: integer, Skipped: integer }`	Function	The RPG Lua hooks, formulas and conditions of this scene since its scripts started: calls, errors, their time, the ticks over Rpg.LuaBudgetMs (report-only: nothing is skipped for it) and the calls skipped because their function did not resolve or the scripts did not run.

Rpg.IsActor#

lua

Rpg.IsActor(entity: Entity): boolean

Whether the entity is an RPG actor (it has an RpgActor component).

Parameters

entity (Entity)

Returns boolean

Example

lua

if Rpg.IsActor(other) then Rpg.SetTarget(self.Entity, other) end

Rpg.IsPlayer#

lua

Rpg.IsPlayer(entity: Entity): boolean

Whether the actor is a player character (RpgActor.Class set, no Template).

Parameters

entity (Entity)

Returns boolean

Example

lua

if Rpg.IsPlayer(killer) then self:Gloat() end

Rpg.IsInitialized#

lua

Rpg.IsInitialized(entity: Entity): boolean?

Servers: whether the character's RPG state was created from its class (Rpg.Initialized, character creation: level 1, the class's stats and resources, starting abilities and items). nil for non-actors and on clients.

Parameters

entity (Entity)

Returns boolean?

Example

lua

Log.Info(tostring(Rpg.IsInitialized(self.Entity)))

Rpg.GetPublic#

lua

Rpg.GetPublic(entity: Entity): { Health: number, HealthMax: number, Resource: number, ResourceMax: number, ResourceStat: string?, Level: integer, Faction: string?, States: { string }, Dead: boolean, InCombat: boolean, Casting: boolean, CastAbilityHash: integer, CastStartTick: integer, CastEndTick: integer, Target: Entity?, Classification: string }?

The actor's public state - what every peer sees: health, its primary resource, level, faction, its states (Dead, InCombat, Casting, Channeling, Stunned, Rooted, Silenced, Invisible, PvP), the cast in progress (the ability's key hash and its ticks), its target and its classification (Normal, Elite, Rare, Boss). nil for non-actors (and on a client before the server sent it).

Parameters

entity (Entity)

Returns { Health: number, HealthMax: number, Resource: number, ResourceMax: number, ResourceStat: string?, Level: integer, Faction: string?, States: { string }, Dead: boolean, InCombat: boolean, Casting: boolean, CastAbilityHash: integer, CastStartTick: integer, CastEndTick: integer, Target: Entity?, Classification: string }?

Example

lua

local public = Rpg.GetPublic(target)
self.Bar.Fill = public.Health / math.max(public.HealthMax, 1)

Rpg.GetEffects#

lua

Rpg.GetEffects(entity: Entity): { { Effect: string?, EffectHash: integer, Stacks: integer, Remaining: number, Duration: number, Caster: Entity?, Instance: integer } }

The entity's visible status effects (StatusEffect.Visible) in application order: the effect's key (nil on a client without the definition), stacks, seconds left (-1: until removed), its duration, the caster when the scene has it, and the instance id. Servers list the store's (with Kind, Absorb and FromAura too); clients what the server sent of the entity.

Parameters

entity (Entity)

Returns { { Effect: string?, EffectHash: integer, Stacks: integer, Remaining: number, Duration: number, Caster: Entity?, Instance: integer } }

Example

lua

for _, effect in ipairs(Rpg.GetEffects(target)) do self:ShowIcon(effect.Effect, effect.Remaining) end

Rpg.GetRelation#

lua

Rpg.GetRelation(entity: Entity, from?: Entity): string?

How from stands towards the entity: "Hostile", "Unfriendly", "Neutral", "Friendly" or "Allied". Servers decide it from the factions, the players' reputation and PvP flags (from is required); a client tells it from the two factions the server replicated and both PvP flags (from defaults to the local character) - for nameplate colours; the server decides attacks (Factions.CanAttack). nil for non-actors.

Parameters

entity (Entity)
from? (Entity): The observer (servers: required; clients: default the local character).

Returns string?

Example

lua

if Rpg.GetRelation(other) == "Hostile" then self.Plate.Color = Color.Red end

Rpg.GetLevel#

lua

Rpg.GetLevel(entity: Entity): integer?

The actor's level; nil for non-actors.

Parameters

entity (Entity)

Returns integer?

Example

lua

local level = Rpg.GetLevel(target)

Rpg.SetLevel#

lua

Rpg.SetLevel(entity: Entity, level: integer)

Sets the actor's level (1-1000): its stat profile's base values follow. Servers only.

Parameters

entity (Entity)
level (integer)

Example

lua

Rpg.SetLevel(self.Entity, 10)

Rpg.IsDead#

lua

Rpg.IsDead(entity: Entity): boolean

Whether the actor is dead (false for non-actors).

Parameters

entity (Entity)

Returns boolean

Example

lua

if Rpg.IsDead(target) then Rpg.SetTarget(self.Entity, nil) end

Rpg.IsInCombat#

lua

Rpg.IsInCombat(entity: Entity): boolean

Whether the actor is in combat: it dealt or took damage or was threatened less than Combat.CombatTimeoutSeconds ago.

Parameters

entity (Entity)

Returns boolean

Example

lua

if not Rpg.IsInCombat(self.Entity) then self:Sit() end

Rpg.HasState#

lua

Rpg.HasState(entity: Entity, state: string): boolean

Whether one of the actor's status effects gives it the state (StatusEffect.States: Stunned, Rooted, Silenced, Disarmed, Pacified, Immune, Invisible, Stealthed, Sleeping or a game's own name; case-insensitive). Clients know the replicated ones: Stunned, Rooted, Silenced, Invisible (and Dead, InCombat, Casting, Channeling, PvP).

Parameters

entity (Entity)
state (string)

Returns boolean

Example

lua

if Rpg.HasState(self.Entity, "Stunned") then return end

Rpg.Kill#

lua

Rpg.Kill(entity: Entity, killer?: Entity)

Kills the actor now: the Death event (OnDeath on its script), the Kill event for the credited players, NPC corpses, player respawn timers. Servers only.

Parameters

entity (Entity)
killer? (Entity)

Example

lua

Rpg.Kill(trapVictim)

Rpg.Respawn#

lua

Rpg.Respawn(entity: Entity): integer?

Brings a dead player back by Rpg.Respawn (its bind point, the nearest graveyard, or where it died for Script: OnRespawn moves it) with full resources. Servers do it at once (nil); a client asks the server and gets the request's id (the answer: OnRpgRequestResult). Raises an error for a living actor or an NPC on a server.

Parameters

entity (Entity)

Returns integer?

Example

lua

function Hud:OnRespawnClicked()
	Rpg.Respawn(self.Player)
end

Rpg.SetBindPoint#

lua

Rpg.SetBindPoint(entity: Entity, position: Vec2)

Where the player comes back with Rpg.Respawn = AtBindPoint (saved with the character). Servers only.

Parameters

entity (Entity)
position (Vec2)

Example

lua

Rpg.SetBindPoint(player, innkeeper.Position)

Rpg.SetTarget#

lua

Rpg.SetTarget(entity: Entity, target?: Entity): integer?

The actor's target (nil clears it): it replicates as the public state's Target. Servers set it at once (nil); a client asks the server for its own character and gets the request's id.

Parameters

entity (Entity)
target? (Entity)

Returns integer?

Example

lua

Rpg.SetTarget(self.Entity, clicked)

Rpg.GetTarget#

lua

Rpg.GetTarget(entity: Entity): Entity?

The actor's target, or nil.

Parameters

entity (Entity)

Returns Entity?

Example

lua

local target = Rpg.GetTarget(self.Entity)

Rpg.Interact#

lua

Rpg.Interact(entity: Entity, target: Entity): integer?

The actor interacts with an Interactable within its Range (plus Combat.RangeTolerance): the Interact event (and Talk for Talk interactables) that quests and scripts react to. Servers act at once (nil; an error out of range or for a target without Interactable); a client asks the server and gets the request's id.

Parameters

entity (Entity)
target (Entity)

Returns integer?

Example

lua

Rpg.Interact(self.Entity, chest)

Rpg.SetPvP#

lua

Rpg.SetPvP(entity: Entity, enabled: boolean)

The player's PvP flag: two flagged players may attack each other in Contested areas (PvPVolume). Servers only.

Parameters

entity (Entity)
enabled (boolean)

Example

lua

Rpg.SetPvP(player, true)

Rpg.Emit#

lua

Rpg.Emit(entity: Entity, name: string, value?: integer, amount?: number)

Records a Custom event about the entity on the RPG event bus (quests' Custom objectives, OnRpgEvent, analytics): its KeyHash is Rpg.Hash(name). Dispatched at the tick's RpgEvents stage. Servers only.

Parameters

entity (Entity)
name (string)
value? (integer)
amount? (number)

Example

lua

Rpg.Emit(player, "LeverPulled", 1)

Rpg.Hash#

lua

Rpg.Hash(key: string): integer

The 32-bit key hash the RPG framework names keys by on the wire and in events (FNV-1a of the key with ASCII upper case folded): compare it with KeyHash, CastAbilityHash and EffectHash values.

Parameters

key (string)

Returns integer

Example

lua

if event.KeyHash == Rpg.Hash("LeverPulled") then self:Open() end

Rpg.RegisterCondition#

lua

Rpg.RegisterCondition(name: string, predicate: function | string)

Registers a Lua predicate that conditions in data name (loot entries, vendors, requirements, dialogue branches, NPC ability choices: "IsNight & Level.Min(10)"): predicate(ctx, ...) gets ctx.Player and ctx.Npc (Entities or nil) and the condition's arguments (numbers or strings), and returns a boolean (anything else, or an error, is false). A string names a "Module.Function" instead. Kept until the scripts stop; a name of a native predicate (Level.Min, ...) is refused.

Parameters

name (string)
predicate (function | string)

Example

lua

Rpg.RegisterCondition("IsNight", function(ctx) return World.GetTimeOfDay() > 20 end)

Rpg.CheckCondition#

lua

Rpg.CheckCondition(entity: Entity, condition: string, npc?: Entity): boolean

Evaluates condition text for the actor as the data's conditions are (Level.Min(10) & !Effect.Has(burning), Lua predicates of Rpg.RegisterCondition); Random(p) draws from the actor's own stream. Raises an error for malformed text (with its position). Servers only.

Parameters

entity (Entity)
condition (string)
npc? (Entity)

Returns boolean

Example

lua

if Rpg.CheckCondition(player, "Level.Min(5) | Class.Is(mage)") then self:OpenDoor() end

Rpg.GetRequestResult#

lua

Rpg.GetRequestResult(id: integer): { Status: string, Code: integer, Message: string, StartTick: integer, EndTick: integer }?

Clients: the server's answer to a request (the newest 64 are kept) - Status "Ok", "Refused", "RateLimited", "OutOfRange", ...; nil while none arrived, for unknown ids and on servers (which act at once).

Parameters

id (integer)

Returns { Status: string, Code: integer, Message: string, StartTick: integer, EndTick: integer }?

Example

lua

local result = Rpg.GetRequestResult(self.PendingTarget)

Rpg.GetScriptStats#

lua

Rpg.GetScriptStats(): { Calls: integer, Errors: integer, Milliseconds: number, OverBudgetTicks: integer, Skipped: integer }

The RPG Lua hooks, formulas and conditions of this scene since its scripts started: calls, errors, their time, the ticks over Rpg.LuaBudgetMs (report-only: nothing is skipped for it) and the calls skipped because their function did not resolve or the scripts did not run.

Returns { Calls: integer, Errors: integer, Milliseconds: number, OverBudgetTicks: integer, Skipped: integer }

Example

lua

Log.Info("RPG Lua: " .. Rpg.GetScriptStats().Milliseconds .. " ms")

Scene#

The running scene: create, find and destroy entities, spawn prefabs and switch scenes.

lua

local bullet = Scene.Instantiate(self.BulletPrefab, self.Entity.WorldPosition)
local player = Scene.FindEntityByName("Player")

Member	Kind	Summary
`Scene.Name: string (read-only)`	Property	The scene's name.
`Scene.CreateEntity(name?: string): Entity`	Function	Creates an entity (with ID, Tag, Transform and Relationship) at the origin; it is a root and takes part in the frame at once.
`Scene.FindEntityByName(name: string): Entity?`	Function	The first entity (in scene order) with this exact name, or nil.
`Scene.FindEntityByID(id: integer): Entity?`	Function	The entity with this UUID (Entity.ID), or nil.
`Scene.GetEntities(componentName?: string): Entity[]`	Function	Every entity in scene order, or only those with the named component (a new table).
`Scene.Destroy(entity: Entity)`	Function	Destroys the entity and its children at the end of the frame (scripts get OnDestroy then).
`Scene.Instantiate(prefab: integer\|string, position?: Vec2, parent?: Entity): Entity`	Function	Spawns a prefab (asset handle, e.g.
`Scene.LoadScene(scene: integer\|string)`	Function	Requests a switch to another scene (asset handle or virtual path); it happens after the current frame, when this scene stops (scripts get OnDestroy).
`Scene.OriginShiftDistance: number`	Property	The scene's origin-shift policy (the scene setting OriginShiftDistance): once the primary camera is farther than this many world units (on either axis) from the origin, the frame's end shifts the origin to it.
`Scene.GetWorldOrigin(): number, number`	Function	The scene origin's absolute position (x, y in double precision).
`Scene.ShiftOrigin(offset: Vec2\|number, y?: number)`	Function	Moves the scene origin by offset now: every root entity moves by -offset, so absolute positions stay where they were while positions relative to the origin get small again.

Scene.Name#

lua

Scene.Name: string (read-only)

The scene's name.

Scene.CreateEntity#

lua

Scene.CreateEntity(name?: string): Entity

Creates an entity (with ID, Tag, Transform and Relationship) at the origin; it is a root and takes part in the frame at once.

Parameters

name? (string)

Returns Entity

Example

lua

local marker = Scene.CreateEntity("Marker")
marker.Position = Vec2(3, 1)

Scene.FindEntityByName#

lua

Scene.FindEntityByName(name: string): Entity?

The first entity (in scene order) with this exact name, or nil.

Parameters

name (string)

Returns Entity?

Scene.FindEntityByID#

lua

Scene.FindEntityByID(id: integer): Entity?

The entity with this UUID (Entity.ID), or nil.

Parameters

id (integer)

Returns Entity?

Scene.GetEntities#

lua

Scene.GetEntities(componentName?: string): Entity[]

Every entity in scene order, or only those with the named component (a new table).

Parameters

componentName? (string)

Returns Entity[]

Example

lua

for _, enemy in ipairs(Scene.GetEntities("Script")) do print(enemy.Name) end

Scene.Destroy#

lua

Scene.Destroy(entity: Entity)

Destroys the entity and its children at the end of the frame (scripts get OnDestroy then). Same as entity:Destroy().

Parameters

entity (Entity)

Scene.Instantiate#

lua

Scene.Instantiate(prefab: integer|string, position?: Vec2, parent?: Entity): Entity

Spawns a prefab (asset handle, e.g. a Prefab property, or a virtual path) and returns its root entity. position is the root's world position (default: the position stored in the prefab, relative to parent); parent makes the root its child. Scripts of the new entities get OnCreate at the start of the next update phase; GetScript works at once.

Parameters

prefab (integer|string)
position? (Vec2)
parent? (Entity)

Returns Entity

Example

lua

local bullet = Scene.Instantiate("Assets/Prefabs/Bullet.fprefab", self.Entity.WorldPosition)
bullet:GetScript("Bullet").Direction = Vec2.Right

Scene.LoadScene#

lua

Scene.LoadScene(scene: integer|string)

Requests a switch to another scene (asset handle or virtual path); it happens after the current frame, when this scene stops (scripts get OnDestroy).

Parameters

scene (integer|string)

Example

lua

Scene.LoadScene("Assets/Scenes/Level2.fscene")

Scene.OriginShiftDistance#

lua

Scene.OriginShiftDistance: number

The scene's origin-shift policy (the scene setting OriginShiftDistance): once the primary camera is farther than this many world units (on either axis) from the origin, the frame's end shifts the origin to it. 0 (the default) never shifts. Negative or non-finite values, and values beyond the float range, raise an error.

Scene.GetWorldOrigin#

lua

Scene.GetWorldOrigin(): number, number

The scene origin's absolute position (x, y in double precision). Positions (Entity.Position, WorldPosition, physics, audio) are relative to it; an entity's absolute position is the origin plus its WorldPosition. Large worlds shift the origin (Scene.ShiftOrigin, the scene setting OriginShiftDistance), so compare it with an earlier value to find out whether positions a script kept must be moved.

Returns number, number

Example

lua

local ox, oy = Scene.GetWorldOrigin()
local absoluteX = ox + self.Entity.WorldPosition.x

Scene.ShiftOrigin#

lua

Scene.ShiftOrigin(offset: Vec2|number, y?: number)

Moves the scene origin by offset now: every root entity moves by -offset, so absolute positions stay where they were while positions relative to the origin get small again. Physics bodies, audio, particles, debug shapes and the network follow. Two numbers (x, y) give the offset in double precision. Positions a script kept (targets, waypoints) are relative to the old origin: subtract the offset from them. Non-finite offsets, and offsets that would move the origin or an entity out of the representable range, raise an error (nothing moves).

Parameters

offset (Vec2|number)
y? (number)

Example

lua

-- recenter the world on the player
Scene.ShiftOrigin(self.Entity.WorldPosition)

Server#

The server runtime: the tick profiler's distribution of frame costs, the script classes' costs and budgets, the zone's memory per player and per NPC, and the scene's game ticks. Works on servers and in single-player and editor play alike (every engine profiles its frames).

lua

local stats = Server.GetTickStats()
if stats.P99Ms > stats.BudgetMs then Log.Warn("the zone runs over budget") end

Member	Kind	Summary
`Server.GetTickStats(): { LastMs: number, AverageMs: number, P50Ms: number, P99Ms: number, MaxMs: number, BudgetMs: number, OverBudgetTicks: integer, WindowTicks: integer, Tick: integer }`	Function	The whole frame's (tick's) cost over the profiler's window (Server.ProfilerWindowTicks ticks): the last tick, the average, p50 and p99 (read from a log histogram: at most one bucket, 26 %, off) and the maximum in milliseconds; the tick budget (Server.TickBudgetMs) and how many ticks went over it since the start.
`Server.GetScriptStats(): { Class: string, Path: string, Instances: integer, UpdateMode: string, BudgetMs: number, LastTickMs: number, AverageMs: number, MaxCallMs: number, Calls: integer, Instructions: integer, AllocatedBytes: integer, OverBudgetTicks: integer, DeferredUpdates: integer }[]`	Function	The cost of every script class this runtime loaded, most expensive first: its instances' callbacks, coroutines and timers together.
`Server.GetMemoryStats(): { ResidentBytes: integer, PrivateBytes: integer, AccountedBytes: integer, Players: integer, Npcs: integer, BytesPerPlayer: number, BytesPerNpc: number, Categories: table<string, integer> }?`	Function	The process's memory (resident and private bytes from the OS) and what the engine's gauges account for: Categories by subsystem (Scene, Scripts, Replication, Interest, Prediction, Physics, Persistence, Services, Assets, Other), and the bytes per connected player and per AI agent of the gauges attributed to players and NPCs.
`Server.GetJobStats(): { Workers: integer, Wakeups: integer, Sleeps: integer, SpinMicroseconds: integer, Spins: integer, JobsExecuted: integer, InlineJobs: integer, Submissions: integer, WakeLimit: integer, MultiBatchSubmissions: integer }`	Function	The job system of this process: its worker threads (FrostRuntime --workers, a realm zone's share of its machine's CoreBudget) and its scheduling counters since the process started - sleeping workers woken, times a worker went to sleep, the time and number of idle spins, jobs run from the queues and inline, the submissions that queued work and the most wake-ups the wake policy allowed them (Wakeups never exceeds WakeLimit), and the parallel submissions that kept workers spinning.
`Server.GetGameTick(): integer`	Function	The scene's game ticks since it started (the first game tick is 1); 0 while the scene has no game ticks (Server.GameTickMs and the scene's GameTickMs are 0) or before the first one.
`Server.GetGameTickAlpha(): number`	Function	How far the scene is towards its next game tick, from 0 (a game tick just happened) to just below 1: draw grid movement between its game-tick positions with it.
`Server.SetScriptBudget(className: string, msPerTick: number)`	Function	Sets the per-frame budget of every script class named className (also classes loaded later) until the scene stops, over the class's own Budget field and the project's Server.Scripts.ClassBudgetMs.

Server.GetTickStats#

lua

Server.GetTickStats(): { LastMs: number, AverageMs: number, P50Ms: number, P99Ms: number, MaxMs: number, BudgetMs: number, OverBudgetTicks: integer, WindowTicks: integer, Tick: integer }

The whole frame's (tick's) cost over the profiler's window (Server.ProfilerWindowTicks ticks): the last tick, the average, p50 and p99 (read from a log histogram: at most one bucket, 26 %, off) and the maximum in milliseconds; the tick budget (Server.TickBudgetMs) and how many ticks went over it since the start. Outside an engine (tests) the numbers are the scripts' own ticks.

Returns { LastMs: number, AverageMs: number, P50Ms: number, P99Ms: number, MaxMs: number, BudgetMs: number, OverBudgetTicks: integer, WindowTicks: integer, Tick: integer }

Example

lua

local tick = Server.GetTickStats()
Debug.DrawText(string.format("p99 %.1f ms", tick.P99Ms), Vec2(0, 5))

Server.GetScriptStats#

lua

Server.GetScriptStats(): { Class: string, Path: string, Instances: integer, UpdateMode: string, BudgetMs: number, LastTickMs: number, AverageMs: number, MaxCallMs: number, Calls: integer, Instructions: integer, AllocatedBytes: integer, OverBudgetTicks: integer, DeferredUpdates: integer }[]

The cost of every script class this runtime loaded, most expensive first: its instances' callbacks, coroutines and timers together. LastTickMs, Calls, Instructions (sampled every 10,000 instructions by the watchdog's hook), AllocatedBytes and DeferredUpdates (Sliced OnUpdates moved to a later frame) are the last frame's; AverageMs is over the profiler's window, MaxCallMs the longest single call so far, OverBudgetTicks the frames over the class's BudgetMs. Time is exclusive: a method another script calls is charged to its own class. Calls that belong to no instance appear as "(no instance)".

Returns { Class: string, Path: string, Instances: integer, UpdateMode: string, BudgetMs: number, LastTickMs: number, AverageMs: number, MaxCallMs: number, Calls: integer, Instructions: integer, AllocatedBytes: integer, OverBudgetTicks: integer, DeferredUpdates: integer }[]

Example

lua

for _, class in ipairs(Server.GetScriptStats()) do
	print(class.Class, class.AverageMs, class.OverBudgetTicks)
end

Server.GetMemoryStats#

lua

Server.GetMemoryStats(): { ResidentBytes: integer, PrivateBytes: integer, AccountedBytes: integer, Players: integer, Npcs: integer, BytesPerPlayer: number, BytesPerNpc: number, Categories: table<string, integer> }?

The process's memory (resident and private bytes from the OS) and what the engine's gauges account for: Categories by subsystem (Scene, Scripts, Replication, Interest, Prediction, Physics, Persistence, Services, Assets, Other), and the bytes per connected player and per AI agent of the gauges attributed to players and NPCs. The scene's storage is measured once per second. nil when the scene runs outside an engine.

Returns { ResidentBytes: integer, PrivateBytes: integer, AccountedBytes: integer, Players: integer, Npcs: integer, BytesPerPlayer: number, BytesPerNpc: number, Categories: table<string, integer> }?

Example

lua

local memory = Server.GetMemoryStats()
if memory then print(memory.BytesPerNpc) end

Server.GetJobStats#

lua

Server.GetJobStats(): { Workers: integer, Wakeups: integer, Sleeps: integer, SpinMicroseconds: integer, Spins: integer, JobsExecuted: integer, InlineJobs: integer, Submissions: integer, WakeLimit: integer, MultiBatchSubmissions: integer }

The job system of this process: its worker threads (FrostRuntime --workers, a realm zone's share of its machine's CoreBudget) and its scheduling counters since the process started - sleeping workers woken, times a worker went to sleep, the time and number of idle spins, jobs run from the queues and inline, the submissions that queued work and the most wake-ups the wake policy allowed them (Wakeups never exceeds WakeLimit), and the parallel submissions that kept workers spinning. Take the difference of two calls for an interval: an idle zone wakes nobody and spins never.

Returns { Workers: integer, Wakeups: integer, Sleeps: integer, SpinMicroseconds: integer, Spins: integer, JobsExecuted: integer, InlineJobs: integer, Submissions: integer, WakeLimit: integer, MultiBatchSubmissions: integer }

Example

lua

local before = Server.GetJobStats()
WaitFrames(60)
local now = Server.GetJobStats()
print("wake-ups per second:", now.Wakeups - before.Wakeups)

Server.GetGameTick#

lua

Server.GetGameTick(): integer

The scene's game ticks since it started (the first game tick is 1); 0 while the scene has no game ticks (Server.GameTickMs and the scene's GameTickMs are 0) or before the first one.

Returns integer

Example

lua

if Server.GetGameTick() % 10 == 0 then self:Regenerate() end

Server.GetGameTickAlpha#

lua

Server.GetGameTickAlpha(): number

How far the scene is towards its next game tick, from 0 (a game tick just happened) to just below 1: draw grid movement between its game-tick positions with it. 0 without game ticks.

Returns number

Example

lua

local alpha = Server.GetGameTickAlpha()
self.Entity.Position = self.From + (self.To - self.From) * alpha

Server.SetScriptBudget#

lua

Server.SetScriptBudget(className: string, msPerTick: number)

Sets the per-frame budget of every script class named className (also classes loaded later) until the scene stops, over the class's own Budget field and the project's Server.Scripts.ClassBudgetMs. A negative value removes the override. Budgets report and count overruns; they never stop a call.

Parameters

className (string): The class name: the script's file name without extension.
msPerTick (number): Milliseconds per frame, at most 1000 (0: no budget; negative: remove the override).

Example

lua

Server.SetScriptBudget("Wolf", 0.25)

Skills#

Skills (Skill rows: each with its own XP curve) and their XP per character. Skill.Min conditions, recipes, gathering nodes and equipment requirements read the levels. On a client the functions read the local character's mirrored Skills section.

lua

Skills.AddXp(player, "mining", 35)
Log.Info("mining " .. Skills.GetLevel(player, "mining"))

Member	Kind	Summary
`Skills.AddXp(player: Entity, skill: string, xp: integer): boolean, string?`	Function	Grants skill XP: level-ups on the skill's curve call OnSkillLevelUp per level.
`Skills.GetLevel(player: Entity, skill: string): integer`	Function	The character's level in a skill: 1 before any XP; 0 for unknown skills and entities that are no player character (on a client: anyone but the local character, or before its Skills section arrived).
`Skills.GetXp(player: Entity, skill: string): integer`	Function	The character's XP in a skill (0 before any, for unknown skills and for entities that are no player character).
`Skills.GetXpForLevel(skill: string, level: integer): integer?`	Function	The XP a level of a skill needs (cumulative, on the skill's curve); nil past the curve's last level.
`Skills.GetAll(player: Entity): table`	Function	The skills the character has XP in: a list of { Key, Name, Kind, Level, Xp } (where the scene has authority in the order they were first trained; on a client the local character's, by key hash).

Skills.AddXp#

lua

Skills.AddXp(player: Entity, skill: string, xp: integer): boolean, string?

Grants skill XP: level-ups on the skill's curve call OnSkillLevelUp per level. False and why for an unknown skill, an entity that is no player character, or a character already training 64 skills. Authority only.

Parameters

player (Entity): The player character.
skill (string): The Skill row key.
xp (integer): The XP, in [1, 1,000,000,000].

Returns boolean, string?

Example

lua

Skills.AddXp(player, "fishing", 40)

Skills.GetLevel#

lua

Skills.GetLevel(player: Entity, skill: string): integer

The character's level in a skill: 1 before any XP; 0 for unknown skills and entities that are no player character (on a client: anyone but the local character, or before its Skills section arrived).

Parameters

player (Entity): The player character.
skill (string): The Skill row key.

Returns integer

Example

lua

if Skills.GetLevel(player, "mining") >= 15 then Log.Info("iron!") end

Skills.GetXp#

lua

Skills.GetXp(player: Entity, skill: string): integer

The character's XP in a skill (0 before any, for unknown skills and for entities that are no player character).

Parameters

player (Entity): The player character.
skill (string): The Skill row key.

Returns integer

Example

lua

local xp = Skills.GetXp(player, "cooking")

Skills.GetXpForLevel#

lua

Skills.GetXpForLevel(skill: string, level: integer): integer?

The XP a level of a skill needs (cumulative, on the skill's curve); nil past the curve's last level.

Parameters

skill (string): The Skill row key.
level (integer): The level, from 1.

Returns integer?

Example

lua

local need = Skills.GetXpForLevel("mining", Skills.GetLevel(player, "mining") + 1)

Skills.GetAll#

lua

Skills.GetAll(player: Entity): table

The skills the character has XP in: a list of { Key, Name, Kind, Level, Xp } (where the scene has authority in the order they were first trained; on a client the local character's, by key hash). Empty for others.

Parameters

player (Entity): The player character.

Returns table

Example

lua

for _, skill in ipairs(Skills.GetAll(player)) do Log.Info(skill.Name .. " " .. skill.Level) end

The player's presence and the state of the player services.

lua

Social.SetStatus("Away")

Member	Kind	Summary
`Social.SetStatus(status: string, showZone?: boolean): integer?, string?`	Function	Sets what friends see: "Online", "Away", "Busy", or "Offline" to appear offline (whispers, invitations and lookups then treat you as offline); showZone (default true) shows your zone to friends.
`Social.IsAvailable(): boolean`	Function	Whether the player services can be used now: the scene's network is a client connected to a zone.
`Social.GetStats(): table?`	Function	The client's counters ({ Requests, Results, Unavailable, LateResults, Events, EventsHeld, EventsDuplicate, Malformed, InFlight }); nil without a zone session.

Social.SetStatus#

lua

Social.SetStatus(status: string, showZone?: boolean): integer?, string?

Sets what friends see: "Online", "Away", "Busy", or "Offline" to appear offline (whispers, invitations and lookups then treat you as offline); showZone (default true) shows your zone to friends.

Parameters

status (string)
showZone? (boolean)

Returns integer?, string?

Social.IsAvailable#

lua

Social.IsAvailable(): boolean

Whether the player services can be used now: the scene's network is a client connected to a zone. Results still say whether the zone's Social hosts answered.

Returns boolean

Social.GetStats#

lua

Social.GetStats(): table?

The client's counters ({ Requests, Results, Unavailable, LateResults, Events, EventsHeld, EventsDuplicate, Malformed, InFlight }); nil without a zone session.

Returns table?

Spawner#

NPC spawners (servers and offline games: the scene's Npc system). Slots are numbered from 0; a dead slot respawns after its delay (RespawnRule), its time kept in the spawner's persistent record. The spawner's script hears OnSpawnerSpawned, OnSpawnerDepleted and OnSpawnerRespawnDue (rule Scripted); each NPC hears OnSpawned. Every function raises an error in a scene without NPCs (clients).

lua

function Camp:OnSpawnerDepleted()
	Log.Info("the camp is cleared")
end

Member	Kind	Summary
`Spawner.Respawn(spawner: Entity, slot?: integer)`	Function	Respawns the spawner's dead slots now - or only `slot` - through the spawn queue (also slots a Scripted rule held back).
`Spawner.Despawn(spawner: Entity)`	Function	Removes every NPC of the spawner and disables it (no death, no respawn timers); Spawner.SetEnabled(spawner, true) spawns them again.
`Spawner.GetAlive(spawner: Entity): { Entity }`	Function	The spawner's living NPCs in slot order.
`Spawner.SetEnabled(spawner: Entity, enabled: boolean)`	Function	A disabled spawner spawns and respawns nothing (its NPCs stay); enabling it spawns its empty slots.
`Spawner.NotifyDeath(npc: Entity)`	Function	A game rule killed the NPC (its corpse may stay): its slot is dead from now on and its respawn delay starts.

Spawner.Respawn#

lua

Spawner.Respawn(spawner: Entity, slot?: integer)

Respawns the spawner's dead slots now - or only slot - through the spawn queue (also slots a Scripted rule held back). Raises an error for an entity that is not an active spawner or a slot out of range.

Parameters

spawner (Entity)
slot? (integer)

Example

lua

Spawner.Respawn(camp)

Spawner.Despawn#

lua

Spawner.Despawn(spawner: Entity)

Removes every NPC of the spawner and disables it (no death, no respawn timers); Spawner.SetEnabled(spawner, true) spawns them again.

Parameters

spawner (Entity)

Example

lua

Spawner.Despawn(eventCamp)

Spawner.GetAlive#

lua

Spawner.GetAlive(spawner: Entity): { Entity }

The spawner's living NPCs in slot order.

Parameters

spawner (Entity)

Returns { Entity }

Example

lua

Log.Info(#Spawner.GetAlive(camp) .. " wolves left")

Spawner.SetEnabled#

lua

Spawner.SetEnabled(spawner: Entity, enabled: boolean)

A disabled spawner spawns and respawns nothing (its NPCs stay); enabling it spawns its empty slots.

Parameters

spawner (Entity)
enabled (boolean)

Example

lua

Spawner.SetEnabled(nightCamp, World.IsNight)

Spawner.NotifyDeath#

lua

Spawner.NotifyDeath(npc: Entity)

A game rule killed the NPC (its corpse may stay): its slot is dead from now on and its respawn delay starts. Destroying a spawned NPC does the same. Raises an error for an entity no spawner spawned or one already reported dead.

Parameters

npc (Entity)

Example

lua

function Wolf:OnKilled()
	Spawner.NotifyDeath(self.Entity)
end

Stats#

Actors' stats (the Stat table's rows: attributes, resources, derived stats, ratings) and their modifiers. Servers read and change the store; a client reads its local character's stats (its owner section; the Rpg namespace says which actor that is; other actors' public values are Rpg.GetPublic's).

lua

local strength = Stats.Get(self.Entity, "Strength")

Member	Kind	Summary
`Stats.Get(entity: Entity, stat: string): number?`	Function	The stat's final value (a Resource stat's maximum); nil for non-actors and unknown stats - and on clients for any entity but the local character.
`Stats.GetResource(entity: Entity, stat: string): number?`	Function	The current value of a Resource stat (health, mana, ...); its maximum is Stats.Get.
`Stats.GetBreakdown(entity: Entity, stat: string): { Base: number, Add: number, Percent: number, Multiply: number, Override: number?, Final: number, Modifiers: integer }?`	Function	How the stat's value came about: final = clamp(Override or (Base + Add) x (1 + Percent) x Multiply, Min, Max), rounded for Integer stats.
`Stats.GetAll(entity: Entity): { { Key: string?, Hash: integer, Value: number, Current: number? } }`	Function	Every stat of the actor in the database's order (Current for Resource stats).
`Stats.SetResource(entity: Entity, stat: string, value: number)`	Function	Sets a Resource stat's current value, clamped to [0, maximum]; the health stat at 0 kills the actor.
`Stats.SetBase(entity: Entity, stat: string, value: number)`	Function	Overrides the stat's base value (its profile and level give it otherwise); saved with players (Rpg.Stats).
`Stats.ClearBase(entity: Entity, stat: string): boolean`	Function	Removes a base override (the profile's value applies again); false when there was none.
`Stats.AddModifier(entity: Entity, stat: string, op: string, value: number, source: string, priority?: integer)`	Function	Adds a script-owned modifier: op "Add", "Percent" (0.1 = +10 %), "Multiply", "Override" (the highest priority wins), "Min" or "Max" (clamps).
`Stats.RemoveModifiers(entity: Entity, source: string): integer`	Function	Removes every modifier Stats.AddModifier added with `source`; returns how many.
`Stats.Subscribe(entity: Entity, stat: string)`	Function	The actor's script hears OnStatChanged(stat, value, previous) when the stat changes - its final value, a Resource stat's current value - at the tick's RpgEvents stage.
`Stats.Unsubscribe(entity: Entity, stat: string): boolean`	Function	Ends a Stats.Subscribe; false when there was none.

Stats.Get#

lua

Stats.Get(entity: Entity, stat: string): number?

The stat's final value (a Resource stat's maximum); nil for non-actors and unknown stats - and on clients for any entity but the local character. Stat keys are case-insensitive.

Parameters

entity (Entity)
stat (string)

Returns number?

Example

lua

local maxHealth = Stats.Get(self.Entity, "Health")

Stats.GetResource#

lua

Stats.GetResource(entity: Entity, stat: string): number?

The current value of a Resource stat (health, mana, ...); its maximum is Stats.Get. nil like Stats.Get.

Parameters

entity (Entity)
stat (string)

Returns number?

Example

lua

local mana = Stats.GetResource(self.Entity, "Mana")

Stats.GetBreakdown#

lua

Stats.GetBreakdown(entity: Entity, stat: string): { Base: number, Add: number, Percent: number, Multiply: number, Override: number?, Final: number, Modifiers: integer }?

How the stat's value came about: final = clamp(Override or (Base + Add) x (1 + Percent) x Multiply, Min, Max), rounded for Integer stats. Servers only (a client's owner section carries values, not their parts): nil on clients, for non-actors and unknown stats.

Parameters

entity (Entity)
stat (string)

Returns { Base: number, Add: number, Percent: number, Multiply: number, Override: number?, Final: number, Modifiers: integer }?

Example

lua

local parts = Stats.GetBreakdown(self.Entity, "Armor")

Stats.GetAll#

lua

Stats.GetAll(entity: Entity): { { Key: string?, Hash: integer, Value: number, Current: number? } }

Every stat of the actor in the database's order (Current for Resource stats). Clients: the local character's stats section (empty for other entities).

Parameters

entity (Entity)

Returns { { Key: string?, Hash: integer, Value: number, Current: number? } }

Example

lua

for _, stat in ipairs(Stats.GetAll(self.Entity)) do Log.Info(stat.Key .. " = " .. stat.Value) end

Stats.SetResource#

lua

Stats.SetResource(entity: Entity, stat: string, value: number)

Sets a Resource stat's current value, clamped to [0, maximum]; the health stat at 0 kills the actor. Servers only.

Parameters

entity (Entity)
stat (string)
value (number)

Example

lua

Stats.SetResource(self.Entity, "Mana", 0)

Stats.SetBase#

lua

Stats.SetBase(entity: Entity, stat: string, value: number)

Overrides the stat's base value (its profile and level give it otherwise); saved with players (Rpg.Stats). Servers only.

Parameters

entity (Entity)
stat (string)
value (number)

Example

lua

Stats.SetBase(self.Entity, "Strength", 25)

Stats.ClearBase#

lua

Stats.ClearBase(entity: Entity, stat: string): boolean

Removes a base override (the profile's value applies again); false when there was none. Servers only.

Parameters

entity (Entity)
stat (string)

Returns boolean

Example

lua

Stats.ClearBase(self.Entity, "Strength")

Stats.AddModifier#

lua

Stats.AddModifier(entity: Entity, stat: string, op: string, value: number, source: string, priority?: integer)

Adds a script-owned modifier: op "Add", "Percent" (0.1 = +10 %), "Multiply", "Override" (the highest priority wins), "Min" or "Max" (clamps). Every modifier of source goes with Stats.RemoveModifiers(entity, source). Recomputed at the next RPG stage (Stats.Get sees it then). Servers only.

Parameters

entity (Entity)
stat (string)
op (string)
value (number)
source (string)
priority? (integer)

Example

lua

Stats.AddModifier(self.Entity, "Strength", "Add", 5, "Shrine")

Stats.RemoveModifiers#

lua

Stats.RemoveModifiers(entity: Entity, source: string): integer

Removes every modifier Stats.AddModifier added with source; returns how many. Servers only.

Parameters

entity (Entity)
source (string)

Returns integer

Example

lua

Stats.RemoveModifiers(self.Entity, "Shrine")

Stats.Subscribe#

lua

Stats.Subscribe(entity: Entity, stat: string)

The actor's script hears OnStatChanged(stat, value, previous) when the stat changes - its final value, a Resource stat's current value - at the tick's RpgEvents stage. At most 4096 subscriptions per scene. Servers only.

Parameters

entity (Entity)
stat (string)

Example

lua

Stats.Subscribe(self.Entity, "Health")

Stats.Unsubscribe#

lua

Stats.Unsubscribe(entity: Entity, stat: string): boolean

Ends a Stats.Subscribe; false when there was none. Servers only.

Parameters

entity (Entity)
stat (string)

Returns boolean

Example

lua

Stats.Unsubscribe(self.Entity, "Health")

Storage#

Persistent save data: booleans, numbers, strings and tables of them by key, stored as JSON in the file SaveData/SaveData.json: <project>/Cache/SaveData/SaveData.json while the game runs from its project (the editor's play mode, run, FrostRuntime --project), <game folder>/SaveData/SaveData.json in an exported game (a dedicated server's in SaveData/Server). Changes are written by Storage.Save() and when the scene stops playing; writes are atomic.

lua

local best = Storage.Get("BestScore", 0)
if score > best then
	Storage.Set("BestScore", score)
	Storage.Save()
end

Member	Kind	Summary
`Storage.Get(key: string, default?: any): any`	Function	The stored value (tables are returned as new tables), or default (nil) when the key does not exist.
`Storage.Set(key: string, value: any)`	Function	Stores a boolean, number, string or table (sequences and string-keyed tables, nested up to 32 levels, at most 1000000 values; a table referenced twice is stored twice); nil deletes the key.
`Storage.Has(key: string): boolean`	Function	True when the key exists.
`Storage.Delete(key: string): boolean`	Function	Removes the key; false when it did not exist.
`Storage.GetKeys(): string[]`	Function	Every stored key, sorted.
`Storage.Clear()`	Function	Removes every key (saved by the next Save).
`Storage.Save(): boolean, string?`	Function	Writes the save data now (atomically).

Storage.Get#

lua

Storage.Get(key: string, default?: any): any

The stored value (tables are returned as new tables), or default (nil) when the key does not exist.

Parameters

key (string)
default? (any)

Returns any

Example

lua

local volume = Storage.Get("Volume", 1.0)

Storage.Set#

lua

Storage.Set(key: string, value: any)

Stores a boolean, number, string or table (sequences and string-keyed tables, nested up to 32 levels, at most 1000000 values; a table referenced twice is stored twice); nil deletes the key. Functions, userdata (vectors, entities), tables that contain themselves and non-finite numbers raise an error.

Parameters

key (string)
value (any)

Example

lua

Storage.Set("Settings", { Volume = 0.8, Fullscreen = true })

Storage.Has#

lua

Storage.Has(key: string): boolean

True when the key exists.

Parameters

key (string)

Returns boolean

Storage.Delete#

lua

Storage.Delete(key: string): boolean

Removes the key; false when it did not exist.

Parameters

key (string)

Returns boolean

Storage.GetKeys#

lua

Storage.GetKeys(): string[]

Every stored key, sorted.

Returns string[]

Storage.Clear#

lua

Storage.Clear()

Removes every key (saved by the next Save).

Storage.Save#

lua

Storage.Save(): boolean, string?

Writes the save data now (atomically). Returns true, or false and the reason (also logged) when the file cannot be written.

Returns boolean, string?: Whether the data was written, and the error message when it was not.

Example

lua

local ok, message = Storage.Save()

Test#

Available in test mode only.

Assertions and test cases for automated tests (available in test mode only). Results are collected by the engine (passed/failed assertions, failures with script locations) and reported by the test runner; failed assertions do not stop the script.

lua

Test.Case("Vec2 addition", function()
	Test.Equal(Vec2(1, 2) + Vec2(3, 4), Vec2(4, 6))
	Test.Near(Vec2(3, 4):Length(), 5)
end)

Member	Kind	Summary
`Test.Assert(condition: any, message?: string): boolean`	Function	Passes when condition is neither false nor nil.
`Test.Equal(actual: any, expected: any, message?: string): boolean`	Function	Passes when the values are equal: numbers by value, engine values (vectors, colors, entities) with ==, tables recursively by contents (shared and cyclic tables included; at most 1000000 entries are compared).
`Test.Near(actual: number\|Vec2\|Vec3\|Vec4\|Color, expected: number\|Vec2\|Vec3\|Vec4\|Color, epsilon?: number, message?: string): boolean`	Function	Passes when every component differs by at most epsilon (default 1e-5).
`Test.Fail(message?: string)`	Function	Records a failure (the script continues).
`Test.Pass(message?: string)`	Function	Records a passed assertion (e.g.
`Test.Skip(reason?: string)`	Function	Marks the running test case skipped and stops it; outside a test case it only counts a skip.
`Test.ExpectFailure(fn: function, expected?: string): boolean`	Function	Calls fn at once (it cannot wait) and passes when fn failed: a failed assertion, Test.Fail or an error raised in fn (with expected: one whose message contains that text).
`Test.CaptureLog(fn: function): table[]`	Function	Calls fn at once and returns the log messages written while it ran - until it returns, also when it waits (Wait, WaitFrames) - from the App and Core loggers and every thread, oldest first, as tables { Level = "Trace"\|"Info"\|"Warn"\|"Error"\|"Critical", Logger = "App"\|"Core", Message = string }; messages of scripts start with their script location.
`Test.Case(name: string, fn: function)`	Function	Registers a test case; the test runner calls fn later (in registration order), collecting its assertions under the case's name.

Test.Assert#

lua

Test.Assert(condition: any, message?: string): boolean

Available in test mode only.

Passes when condition is neither false nor nil. Returns whether it passed.

Parameters

condition (any)
message? (string)

Returns boolean

Test.Equal#

lua

Test.Equal(actual: any, expected: any, message?: string): boolean

Available in test mode only.

Passes when the values are equal: numbers by value, engine values (vectors, colors, entities) with ==, tables recursively by contents (shared and cyclic tables included; at most 1000000 entries are compared).

Parameters

actual (any)
expected (any)
message? (string)

Returns boolean

Test.Near#

lua

Test.Near(actual: number|Vec2|Vec3|Vec4|Color, expected: number|Vec2|Vec3|Vec4|Color, epsilon?: number, message?: string): boolean

Available in test mode only.

Passes when every component differs by at most epsilon (default 1e-5).

Parameters

actual (number|Vec2|Vec3|Vec4|Color)
expected (number|Vec2|Vec3|Vec4|Color)
epsilon? (number)
message? (string)

Returns boolean

Test.Fail#

lua

Test.Fail(message?: string)

Available in test mode only.

Records a failure (the script continues).

Parameters

message? (string)

Test.Pass#

lua

Test.Pass(message?: string)

Available in test mode only.

Records a passed assertion (e.g. that a callback was reached).

Parameters

message? (string)

Test.Skip#

lua

Test.Skip(reason?: string)

Available in test mode only.

Marks the running test case skipped and stops it; outside a test case it only counts a skip.

Parameters

reason? (string)

Test.ExpectFailure#

lua

Test.ExpectFailure(fn: function, expected?: string): boolean

Available in test mode only.

Calls fn at once (it cannot wait) and passes when fn failed: a failed assertion, Test.Fail or an error raised in fn (with expected: one whose message contains that text). The failures inside fn are expected, so they do not fail the test; only the outcome of ExpectFailure is recorded. Returns whether it passed. For testing test helpers and the assertions themselves.

Parameters

fn (function)
expected? (string)

Returns boolean

Example

lua

Test.ExpectFailure(function() Test.Equal(1, 2) end, "expected 2, got 1")

Test.CaptureLog#

lua

Test.CaptureLog(fn: function): table[]

Available in test mode only.

Calls fn at once and returns the log messages written while it ran - until it returns, also when it waits (Wait, WaitFrames) - from the App and Core loggers and every thread, oldest first, as tables { Level = "Trace"|"Info"|"Warn"|"Error"|"Critical", Logger = "App"|"Core", Message = string }; messages of scripts start with their script location. Errors raised in fn propagate. Dist builds compile informational logging out: they capture no Trace or Info messages. The log keeps the last 4096 messages.

Parameters

fn (function)

Returns table[]

Example

lua

local log = Test.CaptureLog(function() Log.Warn("low health") end)
Test.Equal(log[1].Level, "Warn")

Test.Case#

lua

Test.Case(name: string, fn: function)

Available in test mode only.

Registers a test case; the test runner calls fn later (in registration order), collecting its assertions under the case's name. An error in fn fails the case.

Parameters

name (string)
fn (function)

Example

lua

Test.Case("Clamp", function() Test.Equal(Math.Clamp(5, 0, 3), 3) end)

Text#

Text layout queries with the fonts the engine draws text with (TextRenderer components, Debug.DrawText).

lua

local size = Text.Measure("Game Over", nil, 0.8)
if size then panel.Size = size + Vec2(0.4, 0.2) end

Member	Kind	Summary
`Text.Measure(text: string, font?: integer\|string, size?: number, maxWidth?: number): Vec2?`	Function	The width and height of the box text takes when it is laid out like a TextRenderer draws it: font (a Font asset handle or path; nil = the default font, characters it lacks come from the default and icon fonts), size (the em size in the units of the result, default 1: TextRenderer.FontSize in world units, for example), maxWidth (wrapping width in the same units; 0 = no wrapping, the default).

Text.Measure#

lua

Text.Measure(text: string, font?: integer|string, size?: number, maxWidth?: number): Vec2?

The width and height of the box text takes when it is laid out like a TextRenderer draws it: font (a Font asset handle or path; nil = the default font, characters it lacks come from the default and icon fonts), size (the em size in the units of the result, default 1: TextRenderer.FontSize in world units, for example), maxWidth (wrapping width in the same units; 0 = no wrapping, the default). The height spans every line from the first line's ascender to the last line's descender. An empty text measures Vec2(0, 0) (its font is checked all the same). Returns nil when the engine draws no text (dedicated servers, headless runs). A font that is not loaded yet is loaded first; fonts that cannot be loaded raise an error.

Parameters

text (string)
font? (integer|string): A Font asset handle or path, or nil for the default font.
size? (number)
maxWidth? (number)

Returns Vec2?

Example

lua

local size = Text.Measure(label.Text, label.Font, label.FontSize)

Threat#

NPC threat tables (the scene's Combat system: servers, hosts and offline games). An NPC in combat keeps the 16 actors with the most threat - from damage times the ability's ThreatScale and Combat.ThreatPerDamage, healing of the actors it fights, Threat and Taunt effects and this namespace - and targets the top one (a taunter while taunted); perception ranks its targets by threat, so behaviour trees follow it. Tables decay out of combat and empty when the NPC leashes or dies. Every function raises an error in a scene without the Combat system (clients).

lua

local top = Threat.GetTarget(boss)
if top then Log.Info("the boss attacks " .. top.Name) end

Member	Kind	Summary
`Threat.Get(npc: Entity): { { Entity: Entity, Threat: number } }`	Function	The NPC's threat table, the highest threat first (ties by entity id); empty when it is not in combat or not an NPC actor.
`Threat.Add(npc: Entity, target: Entity, amount: number): boolean, string?`	Function	Adds threat (negative amounts lower it, not below 0) for `target` to the NPC's table; both enter combat.
`Threat.Taunt(npc: Entity, target: Entity, seconds: number): boolean, string?`	Function	Forces the NPC to target `target` for `seconds` and raises its threat to the table's top.
`Threat.Clear(npc: Entity)`	Function	Empties the NPC's threat table (as a leash does); nothing happens for entities without one.
`Threat.GetTarget(npc: Entity): Entity?`	Function	The NPC's target by threat: its taunter while taunted, else the top entry; nil with an empty table.

Threat.Get#

lua

Threat.Get(npc: Entity): { { Entity: Entity, Threat: number } }

The NPC's threat table, the highest threat first (ties by entity id); empty when it is not in combat or not an NPC actor.

Parameters

npc (Entity)

Returns { { Entity: Entity, Threat: number } }

Example

lua

for _, entry in ipairs(Threat.Get(boss)) do Log.Info(entry.Entity.Name .. ": " .. entry.Threat) end

Threat.Add#

lua

Threat.Add(npc: Entity, target: Entity, amount: number): boolean, string?

Adds threat (negative amounts lower it, not below 0) for target to the NPC's table; both enter combat. False and the reason when the first entity is not an NPC actor (an RpgActor with a Template), the target is not another RPG actor or either is dead. Raises an error for an amount that is not finite or beyond +-1e9.

Parameters

npc (Entity)
target (Entity)
amount (number)

Returns boolean, string?

Example

lua

Threat.Add(boss, tank, 500)

Threat.Taunt#

lua

Threat.Taunt(npc: Entity, target: Entity, seconds: number): boolean, string?

Forces the NPC to target target for seconds and raises its threat to the table's top. False and the reason as Add's. Raises an error for a duration outside (0, 3600] seconds.

Parameters

npc (Entity)
target (Entity)
seconds (number)

Returns boolean, string?

Example

lua

Threat.Taunt(boss, self.Entity, 3)

Threat.Clear#

lua

Threat.Clear(npc: Entity)

Empties the NPC's threat table (as a leash does); nothing happens for entities without one.

Parameters

npc (Entity)

Example

lua

Threat.Clear(boss)

Threat.GetTarget#

lua

Threat.GetTarget(npc: Entity): Entity?

The NPC's target by threat: its taunter while taunted, else the top entry; nil with an empty table.

Parameters

npc (Entity)

Returns Entity?

Example

lua

local victim = Threat.GetTarget(boss)

Time#

The scene clock. Times are in seconds and scaled by TimeScale unless named Unscaled.

lua

self.Entity.Position = self.Entity.Position + self.Velocity * Time.DeltaTime

Member	Kind	Summary
`Time.DeltaTime: number (read-only)`	Property	Seconds since the previous update (scaled); the fixed timestep inside OnFixedUpdate.
`Time.FixedDeltaTime: number (read-only)`	Property	The fixed timestep of OnFixedUpdate (the scene's FixedTimestep setting).
`Time.Time: number (read-only)`	Property	Scaled seconds since the scene started playing.
`Time.UnscaledTime: number (read-only)`	Property	Real seconds since the scene started playing, ignoring TimeScale.
`Time.UnscaledDeltaTime: number (read-only)`	Property	Real seconds of the current frame, ignoring TimeScale (pause menus).
`Time.FrameCount: integer (read-only)`	Property	Frames the scene has completed since it started playing.
`Time.TimeScale: number`	Property	Multiplier of the scene clock: 0 pauses gameplay time, 0.5 is slow motion.

Time.DeltaTime#

lua

Time.DeltaTime: number (read-only)

Seconds since the previous update (scaled); the fixed timestep inside OnFixedUpdate.

Time.FixedDeltaTime#

lua

Time.FixedDeltaTime: number (read-only)

The fixed timestep of OnFixedUpdate (the scene's FixedTimestep setting).

Time.Time#

lua

Time.Time: number (read-only)

Scaled seconds since the scene started playing.

Time.UnscaledTime#

lua

Time.UnscaledTime: number (read-only)

Real seconds since the scene started playing, ignoring TimeScale.

Time.UnscaledDeltaTime#

lua

Time.UnscaledDeltaTime: number (read-only)

Real seconds of the current frame, ignoring TimeScale (pause menus).

Time.FrameCount#

lua

Time.FrameCount: integer (read-only)

Frames the scene has completed since it started playing.

Time.TimeScale#

lua

Time.TimeScale: number

Multiplier of the scene clock: 0 pauses gameplay time, 0.5 is slow motion. Values above 100 are clamped; negative or non-finite values raise an error.

Example

lua

Time.TimeScale = 0 -- pause

Timer#

Delayed and repeating calls on the scene clock (scaled time), run after the coroutines in each update. Timers created while a script's callback runs belong to that script: they are cancelled when it is destroyed or disabled, and those of a freshly spawned script fire once its OnCreate ran.

lua

Timer.After(2, function() self.Entity:Destroy() end)
self.Spawner = Timer.Every(0.5, function() self:Spawn() end)

Member	Kind	Summary
`Timer.After(seconds: number, callback: function): TimerHandle`	Function	Calls callback once after the delay (never in the frame it was created, so After(0, f) runs next frame).
`Timer.Every(seconds: number, callback: function): TimerHandle`	Function	Calls callback every interval (> 0) until cancelled; at most once per frame (missed intervals are skipped, the phase is kept).

Timer.After#

lua

Timer.After(seconds: number, callback: function): TimerHandle

Calls callback once after the delay (never in the frame it was created, so After(0, f) runs next frame).

Parameters

seconds (number)
callback (function)

Returns TimerHandle

Example

lua

Timer.After(1.5, function() Log.Info("later") end)

Timer.Every#

lua

Timer.Every(seconds: number, callback: function): TimerHandle

Calls callback every interval (> 0) until cancelled; at most once per frame (missed intervals are skipped, the phase is kept).

Parameters

seconds (number)
callback (function)

Returns TimerHandle

Example

lua

local handle = Timer.Every(1, function() self.Seconds = self.Seconds + 1 end)

Trade#

Trades between two characters of the zone within Items.TradeRange: both offer items and currencies, both accept, and the exchange commits at once for both; any change resets the acceptances. Bound items cannot be offered.

lua

local trade = Trade.Begin(a, b)
Trade.OfferItem(trade, a, 1, 5)
Trade.Accept(trade, a)
Trade.Accept(trade, b)

Member	Kind	Summary
`Trade.Begin(first: Entity, second: Entity): integer?, string?`	Function	Opens a trade between two characters; nil and the reason when one is trading, out of range or dead.
`Trade.OfferItem(trade: integer, side: Entity, slot: integer, quantity: integer): boolean, string?`	Function	Offers items of a backpack slot (0 takes the slot out of the offer).
`Trade.OfferCurrency(trade: integer, side: Entity, currency: string, amount: integer): boolean, string?`	Function	Sets the side's offer of a tradable currency (0 removes it).
`Trade.Accept(trade: integer, side: Entity): boolean, string?`	Function	Accepts the current offers for one side; when both accepted the exchange commits (false and the reason when it cannot: nothing moves and both accept again).
`Trade.Cancel(trade: integer)`	Function	Ends a trade without an exchange (unknown trades are ignored).
`Trade.Get(actor: Entity): integer?`	Function	The character's open trade, nil when it trades with nobody.
`Trade.GetState(actor: Entity): table?`	Function	The character's open trade as its window shows it: { Trade, Partner, Mine, Theirs }, each side { Items = { { Slot (the offering side's backpack slot, from 1), Key, Qty } }, Currencies = { { Currency, Amount } }, Accepted }; nil when it trades with nobody.

Trade.Begin#

lua

Trade.Begin(first: Entity, second: Entity): integer?, string?

Opens a trade between two characters; nil and the reason when one is trading, out of range or dead.

Parameters

first (Entity): A character.
second (Entity): The other character.

Returns integer?, string?

Example

lua

local trade = Trade.Begin(player, other)

Trade.OfferItem#

lua

Trade.OfferItem(trade: integer, side: Entity, slot: integer, quantity: integer): boolean, string?

Offers items of a backpack slot (0 takes the slot out of the offer).

Parameters

trade (integer): The trade.
side (Entity): The offering character.
slot (integer): The backpack slot, from 1.
quantity (integer): How many.

Returns boolean, string?

Example

lua

Trade.OfferItem(trade, player, 1, 5)

Trade.OfferCurrency#

lua

Trade.OfferCurrency(trade: integer, side: Entity, currency: string, amount: integer): boolean, string?

Sets the side's offer of a tradable currency (0 removes it).

Parameters

trade (integer): The trade.
side (Entity): The offering character.
currency (string): The Currency key.
amount (integer): How much.

Returns boolean, string?

Example

lua

Trade.OfferCurrency(trade, player, "gold", 100)

Trade.Accept#

lua

Trade.Accept(trade: integer, side: Entity): boolean, string?

Accepts the current offers for one side; when both accepted the exchange commits (false and the reason when it cannot: nothing moves and both accept again).

Parameters

trade (integer): The trade.
side (Entity): The accepting character.

Returns boolean, string?

Example

lua

Trade.Accept(trade, player)

Trade.Cancel#

lua

Trade.Cancel(trade: integer)

Ends a trade without an exchange (unknown trades are ignored).

Parameters

trade (integer): The trade.

Example

lua

Trade.Cancel(trade)

Trade.Get#

lua

Trade.Get(actor: Entity): integer?

The character's open trade, nil when it trades with nobody. On a client: 0 while the local character trades (the id is the server's); nil for anyone else.

Parameters

actor (Entity): The character.

Returns integer?

Example

lua

if Trade.Get(player) then UI.Toast("Finish your trade first") end

Trade.GetState#

lua

Trade.GetState(actor: Entity): table?

The character's open trade as its window shows it: { Trade, Partner, Mine, Theirs }, each side { Items = { { Slot (the offering side's backpack slot, from 1), Key, Qty } }, Currencies = { { Currency, Amount } }, Accepted }; nil when it trades with nobody. Any change of an offer clears both acceptances. On a client: the local character's trade from the RPG lane, with Trade 0 and without the partner's slots; nil for anyone else.

Parameters

actor (Entity): The character.

Returns table?

Example

lua

local trade = Trade.GetState(player)
if trade and trade.Theirs.Accepted then Log.Info("waiting for you") end

UI#

The in-game UI: element lookup, pointer and focus state, visibility (the scene's UI system). Two pointers act on the UI the same way: the mouse and the primary touch contact of a touch screen (the first finger of a gesture; further fingers are left to scripts through Input.GetTouch). Scripts of UI elements receive these methods when they define them: OnUIPointerEnter(position, pointerId) / OnUIPointerExit(position, pointerId) when a pointer's target (the nearest button or slider at or above the front-most element that blocks the pointer) changes - a finger hovers only while it touches -, OnUIPointerDown(position, pointerId) / OnUIPointerUp(position, pointerId) for the left button or the finger (position: Vec2 in framebuffer pixels; pointerId: 0 for the mouse, else the touch contact's id), OnUIValueChanged(value) on a UISlider's script when a pointer moves it, OnUIScroll(offset) on a UIScrollView's script when it scrolls (offset: the new ScrollOffset), OnUIFocusGained() / OnUIFocusLost() for the keyboard/gamepad focus, and OnUICancel(focused) for the Cancel input (Escape, gamepad B) while a button has the focus: the focused button's script gets it first, else the nearest element or canvas above it whose script defines it. A button's UIButton.OnClick names its click method. A press inside a UIScrollView that moves past a few pixels scrolls it instead of clicking the button it began on. Navigation: the arrow keys, WASD, the D-pad and the left stick move the focus between interactable buttons, input fields and draggables, Submit (Enter, gamepad A) clicks the focused button; they only act while something has the focus, which UI.SetFocus or a UICanvas with AutoFocus gives (the pointers never do, except on input fields), so a HUD's buttons never take the movement keys. A UIInputField takes the keyboard when it is clicked or focused (OnUITextChanged(text, field), OnUISubmit(text, field)); UIDraggable elements are dragged onto UIDropTargets with the pointer or picked up with the gamepad (OnUIDragBegin(source, pointerId), OnUIDrop(payload, source, target, payloadType), OnUIDragEnd(source, target)); UIToggles switch on clicks (OnUIToggleChanged(isOn, toggle)), UIDropdowns open a popup to choose an option (OnUIDropdownChanged(index, option, dropdown)), UITooltips show after the pointer rests on their element (OnUITooltipShown(owner, content), OnUITooltipHidden(owner)); these bubble like OnUICancel.

lua

local play = UI.FindElement("MainMenu/Buttons/Play")
UI.SetFocus(play)

function Menu:OnUICancel(focused)
	self:Close()
end

Member	Kind	Summary
`UI.FindElement(nameOrPath: string): Entity?`	Function	The UI element (an entity with a UI component) named `nameOrPath`, searched below every root canvas (canvases in draw order, then depth first; hidden elements included), or the entity at a path of names "Canvas/Panel/Button" (the first segment names a root canvas, each further one a child of the previous entity).
`UI.GetHovered(): Entity?`	Function	The element under the pointer (the primary touch contact while a finger touches, else the mouse): the nearest button or slider at or above the front-most element that blocks the pointer (RaycastTarget), or that element; nil when the pointer is over no UI.
`UI.GetFocused(): Entity?`	Function	The button with the keyboard/gamepad focus (Submit clicks it), or nil.
`UI.SetFocus(element?: Entity): boolean`	Function	Gives an interactable button, input field or draggable the keyboard/gamepad focus and shows it (arrow keys, the D-pad and the left stick move it from there; Submit clicks a button; Cancel keeps it; an input field takes the keyboard with the caret at the end of its text); nil clears the focus and forgets the last one, so navigation input reaches the UI again only through a UICanvas with AutoFocus or another SetFocus.
`UI.IsPointerOverUI(): boolean`	Function	True while the mouse, or the primary touch contact while it touches, is over a UI element that blocks pointer input (raycast targets, buttons, sliders, scroll views): gameplay should ignore those clicks and taps then (the UI consumed them).
`UI.IsPointerCaptured(): boolean`	Function	True while a left-button press or a primary touch contact that began over the UI is held (a drag that started on a button, slider, scroll view or panel).
`UI.IsKeyboardCaptured(): boolean`	Function	True while a UIInputField has the keyboard (the player is typing).
`UI.IsDragging(): boolean`	Function	True while a UIDraggable element is dragged (by a pointer, or carried with the gamepad).
`UI.GetDragPayload(): string?, string?`	Function	The payload and the payload type of the drag in progress; nil, nil without one.
`UI.SetDragPayload(payload: string, payloadType?: string): boolean`	Function	Replaces what the drag in progress carries (usually in OnUIDragBegin: the item in the dragged slot) and, when given, its type (drop targets accept drags by type).
`UI.CancelDrag(): boolean`	Function	Ends the drag in progress without a drop (OnUIDragEnd gets nil).
`UI.GetTooltip(): Entity?`	Function	The element (with UITooltip) whose tooltip shows, or nil.
`UI.HideTooltip(): boolean`	Function	Hides the tooltip being shown (OnUITooltipHidden follows); it shows again once the pointer rests on an element anew.
`UI.GetOpenDropdown(): Entity?`	Function	The UIDropdown whose popup is open (one at a time), or nil.
`UI.SetVisible(element: Entity, visible: boolean)`	Function	Shows or hides an element and everything below it (UIRect.Visible, and UICanvas.Visible for canvases): hidden elements are neither drawn nor receive input.
`UI.IsVisible(element: Entity): boolean`	Function	True when the element lies below a canvas (or is one), it and every element and canvas above it are Visible and it is not (or lies below) the Checkmark of a UIToggle above it that is off (it may still be outside the screen or clipped).
`UI.NavigationEnabled: boolean`	Property	Whether keyboard/gamepad navigation runs (Submit, Cancel and the Horizontal/Vertical axes move and use the focus).

UI.FindElement#

lua

UI.FindElement(nameOrPath: string): Entity?

The UI element (an entity with a UI component) named nameOrPath, searched below every root canvas (canvases in draw order, then depth first; hidden elements included), or the entity at a path of names "Canvas/Panel/Button" (the first segment names a root canvas, each further one a child of the previous entity). nil when there is none.

Parameters

nameOrPath (string): An entity name, or names separated by '/'.

Returns Entity?

Example

lua

local score = UI.FindElement("HUD/Score")

UI.GetHovered#

lua

UI.GetHovered(): Entity?

The element under the pointer (the primary touch contact while a finger touches, else the mouse): the nearest button or slider at or above the front-most element that blocks the pointer (RaycastTarget), or that element; nil when the pointer is over no UI. Updated before the scripts' OnUpdate.

Returns Entity?

UI.GetFocused#

lua

UI.GetFocused(): Entity?

The button with the keyboard/gamepad focus (Submit clicks it), or nil. While a button has the focus the UI uses Submit, Cancel and the navigation directions: gameplay that shares those inputs checks for nil first.

Returns Entity?

Example

lua

if UI.GetFocused() == nil and Input.IsActionPressed("Jump") then self:Jump() end

UI.SetFocus#

lua

UI.SetFocus(element?: Entity): boolean

Gives an interactable button, input field or draggable the keyboard/gamepad focus and shows it (arrow keys, the D-pad and the left stick move it from there; Submit clicks a button; Cancel keeps it; an input field takes the keyboard with the caret at the end of its text); nil clears the focus and forgets the last one, so navigation input reaches the UI again only through a UICanvas with AutoFocus or another SetFocus. Returns false (nothing changes) for other entities and for elements that are not interactable. Menus set their first button this way when they open.

Parameters

element? (Entity): A button, input field or draggable entity, or nil.

Returns boolean

Example

lua

UI.SetFocus(UI.FindElement("Play"))

UI.IsPointerOverUI#

lua

UI.IsPointerOverUI(): boolean

True while the mouse, or the primary touch contact while it touches, is over a UI element that blocks pointer input (raycast targets, buttons, sliders, scroll views): gameplay should ignore those clicks and taps then (the UI consumed them).

Returns boolean

Example

lua

if Input.IsMouseButtonPressed(MouseButton.Left) and not UI.IsPointerOverUI() then self:Fire() end

UI.IsPointerCaptured#

lua

UI.IsPointerCaptured(): boolean

True while a left-button press or a primary touch contact that began over the UI is held (a drag that started on a button, slider, scroll view or panel).

Returns boolean

UI.IsKeyboardCaptured#

lua

UI.IsKeyboardCaptured(): boolean

True while a UIInputField has the keyboard (the player is typing). Actions and axes ignore their keyboard bindings meanwhile (gamepad and mouse bindings still work), so typing does not move the player; gameplay that reads keys directly (Input.IsKeyDown) checks this first. Updated by the UI system before the scripts' OnUpdate.

Returns boolean

Example

lua

if not UI.IsKeyboardCaptured() and Input.IsKeyPressed("I") then self:ToggleInventory() end

UI.IsDragging#

lua

UI.IsDragging(): boolean

True while a UIDraggable element is dragged (by a pointer, or carried with the gamepad).

Returns boolean

UI.GetDragPayload#

lua

UI.GetDragPayload(): string?, string?

The payload and the payload type of the drag in progress; nil, nil without one.

Returns string?, string?: The payload and its type.

UI.SetDragPayload#

lua

UI.SetDragPayload(payload: string, payloadType?: string): boolean

Replaces what the drag in progress carries (usually in OnUIDragBegin: the item in the dragged slot) and, when given, its type (drop targets accept drags by type). Returns false without a drag. At most 4 KiB each.

Parameters

payload (string): The new payload.
payloadType? (string): The new payload type (optional).

Returns boolean

Example

lua

function Slot:OnUIDragBegin(source)
	UI.SetDragPayload(tostring(self.ItemId), "item")
end

UI.CancelDrag#

lua

UI.CancelDrag(): boolean

Ends the drag in progress without a drop (OnUIDragEnd gets nil). Returns false without a drag.

Returns boolean

UI.GetTooltip#

lua

UI.GetTooltip(): Entity?

The element (with UITooltip) whose tooltip shows, or nil.

Returns Entity?

UI.HideTooltip#

lua

UI.HideTooltip(): boolean

Hides the tooltip being shown (OnUITooltipHidden follows); it shows again once the pointer rests on an element anew. Returns false when none shows.

Returns boolean

UI.GetOpenDropdown#

lua

UI.GetOpenDropdown(): Entity?

The UIDropdown whose popup is open (one at a time), or nil.

Returns Entity?

UI.SetVisible#

lua

UI.SetVisible(element: Entity, visible: boolean)

Shows or hides an element and everything below it (UIRect.Visible, and UICanvas.Visible for canvases): hidden elements are neither drawn nor receive input. Raises an error for entities without UIRect or UICanvas.

Parameters

element (Entity)
visible (boolean)

Example

lua

UI.SetVisible(UI.FindElement("PauseMenu"), true)

UI.IsVisible#

lua

UI.IsVisible(element: Entity): boolean

True when the element lies below a canvas (or is one), it and every element and canvas above it are Visible and it is not (or lies below) the Checkmark of a UIToggle above it that is off (it may still be outside the screen or clipped).

Parameters

element (Entity)

Returns boolean

UI.NavigationEnabled#

lua

UI.NavigationEnabled: boolean

Whether keyboard/gamepad navigation runs (Submit, Cancel and the Horizontal/Vertical axes move and use the focus). Off, the focus is kept but not shown and those inputs are left to gameplay even while a menu has the focus.

Example

lua

UI.NavigationEnabled = false

Vendor#

Vendors (an Interactable of kind Vendor naming a Vendor row, within its Range): buying within stock (restocked over time and kept across restarts), selling at the row's SellRate times the item's Value, buying back what the player sold this session, and repairs. Changes return true, or false and "<Refusal>: <why>".

lua

Vendor.Open(player, smith)
Vendor.Buy(player, smith, "iron_ore", 5)

Member	Kind	Summary
`Vendor.Open(player: Entity, vendor: Entity): boolean, string?`	Function	Opens the vendor's window for the player (its stock and buy-back list reach the player's client).
`Vendor.Buy(player: Entity, vendor: Entity, item: string\|integer, quantity?: integer): boolean, string?`	Function	Buys an item (its key, or its entry from 1 in GetEntries' order) at the entry's price and currency, within its stock and condition.
`Vendor.Sell(player: Entity, vendor: Entity, slot: integer, quantity?: integer): boolean, string?`	Function	Sells a backpack stack (or quantity of it) for the vendor's SellRate times the item's Value; it joins the buy-back list (Items.BuyBackSlots).
`Vendor.BuyBack(player: Entity, vendor: Entity, index: integer): boolean, string?`	Function	Buys back an item the player sold (from 1, newest first, GetBuyBack's order) for what it sold for.
`Vendor.Repair(player: Entity, vendor: Entity, container?: string, slot?: integer): boolean, string?`	Function	Repairs one item (a container and slot) or everything worn and carried, for Items.RepairCostRate times the item's Value per missing durability; vendors without Repair refuse.
`Vendor.GetEntries(vendor: Entity): table?`	Function	What the vendor sells: a list of { Entry, Item, Price, Currency, Stock? } (Stock: what is left of a limited entry); nil for an entity that is not a vendor.
`Vendor.GetBuyBack(player: Entity): table`	Function	What the player sold this session and may buy back, newest first: a list of { Item, Price, Currency }.
`Vendor.GetOpen(player: Entity): Entity?`	Function	The vendor whose window the player has open; nil when none.

Vendor.Open#

lua

Vendor.Open(player: Entity, vendor: Entity): boolean, string?

Opens the vendor's window for the player (its stock and buy-back list reach the player's client).

Parameters

player (Entity): The character.
vendor (Entity): The vendor entity.

Returns boolean, string?

Example

lua

Vendor.Open(player, smith)

Vendor.Buy#

lua

Vendor.Buy(player: Entity, vendor: Entity, item: string|integer, quantity?: integer): boolean, string?

Buys an item (its key, or its entry from 1 in GetEntries' order) at the entry's price and currency, within its stock and condition.

Parameters

player (Entity): The character.
vendor (Entity): The vendor entity.
item (string|integer): The item key or entry.
quantity? (integer): How many (default 1).

Returns boolean, string?

Example

lua

Vendor.Buy(player, smith, "iron_ore", 5)

Vendor.Sell#

lua

Vendor.Sell(player: Entity, vendor: Entity, slot: integer, quantity?: integer): boolean, string?

Sells a backpack stack (or quantity of it) for the vendor's SellRate times the item's Value; it joins the buy-back list (Items.BuyBackSlots).

Parameters

player (Entity): The character.
vendor (Entity): The vendor entity.
slot (integer): The backpack slot, from 1.
quantity? (integer): How many (default all).

Returns boolean, string?

Example

lua

Vendor.Sell(player, smith, 3)

Vendor.BuyBack#

lua

Vendor.BuyBack(player: Entity, vendor: Entity, index: integer): boolean, string?

Buys back an item the player sold (from 1, newest first, GetBuyBack's order) for what it sold for.

Parameters

player (Entity): The character.
vendor (Entity): The vendor entity.
index (integer): The buy-back entry, from 1.

Returns boolean, string?

Example

lua

Vendor.BuyBack(player, smith, 1)

Vendor.Repair#

lua

Vendor.Repair(player: Entity, vendor: Entity, container?: string, slot?: integer): boolean, string?

Repairs one item (a container and slot) or everything worn and carried, for Items.RepairCostRate times the item's Value per missing durability; vendors without Repair refuse.

Parameters

player (Entity): The character.
vendor (Entity): The vendor entity.
container? (string): Equipment or Backpack (default all).
slot? (integer): The slot, from 1.

Returns boolean, string?

Example

lua

Vendor.Repair(player, smith)

Vendor.GetEntries#

lua

Vendor.GetEntries(vendor: Entity): table?

What the vendor sells: a list of { Entry, Item, Price, Currency, Stock? } (Stock: what is left of a limited entry); nil for an entity that is not a vendor. On a client: the entries of the vendor whose window the local character has open, from the RPG lane; nil for every other vendor.

Parameters

vendor (Entity): The vendor entity.

Returns table?

Example

lua

for _, entry in ipairs(Vendor.GetEntries(smith)) do Log.Info(entry.Item .. ": " .. entry.Price) end

Vendor.GetBuyBack#

lua

Vendor.GetBuyBack(player: Entity): table

What the player sold this session and may buy back, newest first: a list of { Item, Price, Currency }.

Parameters

player (Entity): The character.

Returns table

Example

lua

local sold = #Vendor.GetBuyBack(player)

Vendor.GetOpen#

lua

Vendor.GetOpen(player: Entity): Entity?

The vendor whose window the player has open; nil when none.

Parameters

player (Entity): The character.

Returns Entity?

Example

lua

local vendor = Vendor.GetOpen(player)

Volumes#

Areas of the scene (Docs/WorldBuilding.md, Volumes): entities with a VolumeShape and kind components - regions, music, ambient sound, PvP rules, phases, triggers, nav areas. Positions are scene positions (like Entity.Position). Every function but IsInside and SamplePoint needs the scene's volume system (the Volumes engine module adds it to running scenes) and raises an error without it. Tracked entities - players and VolumeTracker entities - also get the callbacks OnRegionChanged, OnVolumeEnter, OnVolumeExit and OnPhaseVolumeEntered.

lua

local region, banner = Volumes.GetRegion(self.Entity.Position)
if Volumes.GetPvPMode(self.Entity) == "Sanctuary" then return end

Member	Kind	Summary
`Volumes.GetRegion(position: Vec2): string?, string?`	Function	The region at a position: the Name (id) and the display name (DisplayName, else the Name) of the highest-priority RegionVolume containing it; nil, nil outside every region.
`Volumes.GetPvPMode(entityOrPosition: Entity \| Vec2): string?`	Function	The player-versus-player rules where an entity (its world position) or a position is: the Mode of the highest-priority PvPVolume containing it - "Sanctuary", "Contested", "FreeForAll" or "Arena" - or nil outside every PvP volume (the game's default applies).
`Volumes.Query(position: Vec2, kind?: string): Entity[]`	Function	The volumes containing a position, highest priority first (the highest Priority among their kind components; ties by ID), at most 64; with a kind ("Region", "Music", "Ambient", "PvP", "Phase", "Trigger" or "NavArea") only the volumes of that kind, ordered by its Priority.
`Volumes.IsInside(volume: Entity, position: Vec2): boolean`	Function	Whether a position lies inside a volume's shape (on the edge counts), placed by the volume's world transform.
`Volumes.SamplePoint(volume: Entity, seed: integer): Vec2?`	Function	A point uniformly distributed over a volume's area (scene position), the same for the same seed and shape: deterministic spawn and loot points.

Volumes.GetRegion#

lua

Volumes.GetRegion(position: Vec2): string?, string?

The region at a position: the Name (id) and the display name (DisplayName, else the Name) of the highest-priority RegionVolume containing it; nil, nil outside every region.

Parameters

position (Vec2)

Returns string?, string?

Example

lua

local id, name = Volumes.GetRegion(self.Entity.Position)
if id then self.Banner:GetComponent("UIText"):SetText(name) end

Volumes.GetPvPMode#

lua

Volumes.GetPvPMode(entityOrPosition: Entity | Vec2): string?

The player-versus-player rules where an entity (its world position) or a position is: the Mode of the highest-priority PvPVolume containing it - "Sanctuary", "Contested", "FreeForAll" or "Arena" - or nil outside every PvP volume (the game's default applies). Servers and clients give the same answer.

Parameters

entityOrPosition (Entity | Vec2)

Returns string?

Example

lua

if Volumes.GetPvPMode(target) == "Sanctuary" then return false end

Volumes.Query#

lua

Volumes.Query(position: Vec2, kind?: string): Entity[]

The volumes containing a position, highest priority first (the highest Priority among their kind components; ties by ID), at most 64; with a kind ("Region", "Music", "Ambient", "PvP", "Phase", "Trigger" or "NavArea") only the volumes of that kind, ordered by its Priority. A new table.

Parameters

position (Vec2)
kind? (string)

Returns Entity[]

Example

lua

for _, volume in ipairs(Volumes.Query(self.Entity.Position, "Trigger")) do
	Log.Info(volume.Name)
end

Volumes.IsInside#

lua

Volumes.IsInside(volume: Entity, position: Vec2): boolean

Whether a position lies inside a volume's shape (on the edge counts), placed by the volume's world transform. Raises an error for an entity without a VolumeShape.

Parameters

volume (Entity)
position (Vec2)

Returns boolean

Example

lua

if Volumes.IsInside(self.Arena, player.Position) then self:StartRound() end

Volumes.SamplePoint#

lua

Volumes.SamplePoint(volume: Entity, seed: integer): Vec2?

A point uniformly distributed over a volume's area (scene position), the same for the same seed and shape: deterministic spawn and loot points. nil for a shape that is not valid (a polygon crossing itself, a zero scale). Raises an error for an entity without a VolumeShape.

Parameters

volume (Entity)
seed (integer)

Returns Vec2?

Example

lua

local spot = Volumes.SamplePoint(self.Area, self.Wave * 100 + i)

Wallet#

Currencies characters hold (Currency rows), within each currency's Cap.

lua

Wallet.Add(player, "gold", 25)

Member	Kind	Summary
`Wallet.Get(actor: Entity, currency: string): integer`	Function	The actor's amount of a currency (0 when it has none).
`Wallet.Add(actor: Entity, currency: string, amount: integer): boolean, string?`	Function	Adds (or with a negative amount spends) currency; false when the wallet would go below 0 or above the cap.

Wallet.Get#

lua

Wallet.Get(actor: Entity, currency: string): integer

The actor's amount of a currency (0 when it has none). On a client: the local character's, from the RPG lane; 0 for anyone else.

Parameters

actor (Entity): The character.
currency (string): The Currency key.

Returns integer

Example

lua

local gold = Wallet.Get(player, "gold")

Wallet.Add#

lua

Wallet.Add(actor: Entity, currency: string, amount: integer): boolean, string?

Adds (or with a negative amount spends) currency; false when the wallet would go below 0 or above the cap.

Parameters

actor (Entity): The character.
currency (string): The Currency key.
amount (integer): The change.

Returns boolean, string?

Example

lua

if not Wallet.Add(player, "gold", -price) then UI.Toast("Not enough gold") end

World#

The scene's streamed world (SceneSettings.World): a grid of square cells with int64 coordinates, each holding a position inside it (local, in [0, CellSize)). Cells stream in around the streaming sources - players, the camera and WorldStreamingSource components - and out again when nobody is near; scripts hear it through OnCellLoaded and OnCellUnloaded. Positions are scene positions (relative to the scene origin, like Entity.Position); the scene origin may move on clients (OnWorldOriginShifted). Every function but IsBound raises an error in a scene that streams no world.

lua

function Guide:OnCellLoaded(x, y, layer)
	if layer == "Props" then Log.Info("cell " .. x .. "," .. y .. " is here") end
end

Member	Kind	Summary
`World.IsBound(): boolean`	Function	True when the scene streams a world (its cooked pack is open).
`World.GetCell(position: Vec2): integer, integer`	Function	The cell (x, y) a scene position lies in.
`World.ToWorld(position: Vec2): integer, integer, number, number`	Function	The world position of a scene position: its cell (x, y) and the position inside the cell (localX, localY in [0, CellSize)).
`World.ToScene(cellX: integer, cellY: integer, localX: number, localY: number): Vec2`	Function	The scene position of a world position (a cell and a position inside it; local values beyond the cell are allowed and measured from its corner).
`World.IsCellLoaded(x: integer, y: integer, layer?: string \| integer): boolean`	Function	True when the cell of the layer (a name, or an index from 0; default: the world's first layer) is loaded: every entity of it exists.
`World.GetCellState(x: integer, y: integer, layer?: string \| integer): string`	Function	Where the cell is in its life: "Unloaded", "Requested", "Loading", "Prepared", "Applying", "Loaded" or "Unloading".
`World.PinCell(x: integer, y: integer, layer: string \| integer, seconds: number)`	Function	Keeps a cell loaded for `seconds` of scene time whether or not a source is near, e.g.
`World.GetStats(): { World: string, CellSize: number, LoadedCells: integer, LoadingCells: integer, PendingCells: integer, UnloadingCells: integer, FailedCells: integer, CellsLoaded: integer, CellsUnloaded: integer, Sources: integer, EntitiesInstantiated: integer, EntitiesDestroyed: integer, ApplyMs: number, MappedBytes: integer }`	Function	The streaming state: cells loaded, in flight, waiting and unloading now; refused cells (a damaged pack, logged); totals since the world was bound; the sources of the last frame; the main-thread time the last frame spent instantiating and destroying (MaxApplyMsPerFrame bounds it); the bytes of the mapped pack.

World.IsBound#

lua

World.IsBound(): boolean

True when the scene streams a world (its cooked pack is open).

Returns boolean

World.GetCell#

lua

World.GetCell(position: Vec2): integer, integer

The cell (x, y) a scene position lies in.

Parameters

position (Vec2)

Returns integer, integer

Example

lua

local x, y = World.GetCell(self.Entity.Position)

World.ToWorld#

lua

World.ToWorld(position: Vec2): integer, integer, number, number

The world position of a scene position: its cell (x, y) and the position inside the cell (localX, localY in [0, CellSize)). Store world positions (save games, waypoints) this way: they stay exact anywhere in the world while scene positions depend on the origin.

Parameters

position (Vec2)

Returns integer, integer, number, number

Example

lua

local cx, cy, lx, ly = World.ToWorld(self.Entity.Position)

World.ToScene#

lua

World.ToScene(cellX: integer, cellY: integer, localX: number, localY: number): Vec2

The scene position of a world position (a cell and a position inside it; local values beyond the cell are allowed and measured from its corner).

Parameters

cellX (integer)
cellY (integer)
localX (number)
localY (number)

Returns Vec2

Example

lua

self.Entity.Position = World.ToScene(cx, cy, lx, ly)

World.IsCellLoaded#

lua

World.IsCellLoaded(x: integer, y: integer, layer?: string | integer): boolean

True when the cell of the layer (a name, or an index from 0; default: the world's first layer) is loaded: every entity of it exists. A cell the world has no file for is never loaded.

Parameters

x (integer)
y (integer)
layer? (string | integer)

Returns boolean

World.GetCellState#

lua

World.GetCellState(x: integer, y: integer, layer?: string | integer): string

Where the cell is in its life: "Unloaded", "Requested", "Loading", "Prepared", "Applying", "Loaded" or "Unloading".

Parameters

x (integer)
y (integer)
layer? (string | integer)

Returns string

World.PinCell#

lua

World.PinCell(x: integer, y: integer, layer: string | integer, seconds: number)

Keeps a cell loaded for seconds of scene time whether or not a source is near, e.g. the destination of a scripted teleport before the player arrives; it starts loading at once. 0 releases the pin (the cell unloads when nobody is near). A cell without a file is ignored.

Parameters

x (integer)
y (integer)
layer (string | integer)
seconds (number)

Example

lua

World.PinCell(40, -3, "Terrain", 5)
-- later, once World.IsCellLoaded(40, -3, "Terrain"):
self.Entity.Position = World.ToScene(40, -3, 32, 32)

World.GetStats#

lua

World.GetStats(): { World: string, CellSize: number, LoadedCells: integer, LoadingCells: integer, PendingCells: integer, UnloadingCells: integer, FailedCells: integer, CellsLoaded: integer, CellsUnloaded: integer, Sources: integer, EntitiesInstantiated: integer, EntitiesDestroyed: integer, ApplyMs: number, MappedBytes: integer }

The streaming state: cells loaded, in flight, waiting and unloading now; refused cells (a damaged pack, logged); totals since the world was bound; the sources of the last frame; the main-thread time the last frame spent instantiating and destroying (MaxApplyMsPerFrame bounds it); the bytes of the mapped pack.

Returns { World: string, CellSize: number, LoadedCells: integer, LoadingCells: integer, PendingCells: integer, UnloadingCells: integer, FailedCells: integer, CellsLoaded: integer, CellsUnloaded: integer, Sources: integer, EntitiesInstantiated: integer, EntitiesDestroyed: integer, ApplyMs: number, MappedBytes: integer }

Types#

Value types. Calling the type's global table constructs a value; static members live on that table, instance members are used on values (v.X, v:Length()).

CellRect#

An inclusive rectangle of tilemap cells: both corner cells belong to it (a read-only value).

lua

local room = CellRect(0, 0, 9, 5)
tilemap:Fill(room, 3)
print(room.Width, room.Height) -- 10 6

Member	Kind	Summary
`CellRect(x1: integer, y1: integer, x2: integer, y2: integer): CellRect`	Constructor	The rectangle spanned by two opposite corner cells, given in any order.
`CellRect.MinX: integer (read-only)`	Property	Leftmost cell column.
`CellRect.MinY: integer (read-only)`	Property	Bottom cell row.
`CellRect.MaxX: integer (read-only)`	Property	Rightmost cell column (inclusive).
`CellRect.MaxY: integer (read-only)`	Property	Top cell row (inclusive).
`CellRect.Width: integer (read-only)`	Property	Number of columns (MaxX - MinX + 1).
`CellRect.Height: integer (read-only)`	Property	Number of rows (MaxY - MinY + 1).
`CellRect:Contains(x: integer, y: integer): boolean`	Method	True when the cell lies inside the rectangle (edges included).
`CellRect.__eq(a: CellRect, b: CellRect): boolean`	Operator	True when both rectangles have the same corners.
`CellRect.__tostring(rect: CellRect): string`	Operator	"CellRect(minX, minY, maxX, maxY)".

CellRect()#

lua

CellRect(x1: integer, y1: integer, x2: integer, y2: integer): CellRect

The rectangle spanned by two opposite corner cells, given in any order.

Parameters

x1 (integer)
y1 (integer)
x2 (integer)
y2 (integer)

Returns CellRect

Example

lua

local area = CellRect(-5, -5, 5, 5)

CellRect.MinX#

lua

CellRect.MinX: integer (read-only)

Leftmost cell column.

CellRect.MinY#

lua

CellRect.MinY: integer (read-only)

Bottom cell row.

CellRect.MaxX#

lua

CellRect.MaxX: integer (read-only)

Rightmost cell column (inclusive).

CellRect.MaxY#

lua

CellRect.MaxY: integer (read-only)

Top cell row (inclusive).

CellRect.Width#

lua

CellRect.Width: integer (read-only)

Number of columns (MaxX - MinX + 1).

CellRect.Height#

lua

CellRect.Height: integer (read-only)

Number of rows (MaxY - MinY + 1).

CellRect:Contains#

lua

CellRect:Contains(x: integer, y: integer): boolean

True when the cell lies inside the rectangle (edges included).

Parameters

x (integer)
y (integer)

Returns boolean

CellRect.__eq#

lua

CellRect.__eq(a: CellRect, b: CellRect): boolean

Lua syntax: a == b

True when both rectangles have the same corners.

Parameters

a (CellRect)
b (CellRect)

Returns boolean

CellRect.__tostring#

lua

CellRect.__tostring(rect: CellRect): string

Lua syntax: tostring(a)

"CellRect(minX, minY, maxX, maxY)".

Parameters

rect (CellRect)

Returns string

Color#

RGBA color with components in [0, 1] (straight alpha, as in the editor's color pickers). Shared by reference like Vec2.

lua

sprite.Color = Color(1, 0.5, 0)
sprite.Color = Color.FromHex("#FF8800")

Member	Kind	Summary
`Color(r?: number\|Color\|Vec4, g?: number, b?: number, a?: number): Color`	Constructor	Color() is opaque white, Color(r, g, b) is opaque, Color(r, g, b, a) sets alpha, Color(c) copies a Color or converts a Vec4.
`Color.R: number`	Property	Red component.
`Color.G: number`	Property	Green component.
`Color.B: number`	Property	Blue component.
`Color.A: number`	Property	Alpha (opacity) component.
`Color:WithAlpha(alpha: number): Color`	Method	A copy with another alpha.
`Color:Lerp(other: Color, t: number): Color`	Method	Component-wise linear interpolation towards other (not clamped).
`Color:ToHex(includeAlpha?: boolean): string`	Method	"#RRGGBBAA" ("#RRGGBB" when includeAlpha is false) with the components clamped to [0, 1].
`Color:Unpack(): number, number, number, number`	Method	The r, g, b and a components.
`Color.FromHex(hex: string): Color?`	Function	Parses "#RRGGBB" or "#RRGGBBAA" (the '#' is optional); nil when the text is not a color.
`Color.FromHSV(hue: number, saturation: number, value: number, alpha?: number): Color`	Function	A color from hue, saturation and value in [0, 1] (hue as a fraction of a turn: 0 red, 1/3 green, 2/3 blue).
`Color.Lerp(a: Color, b: Color, t: number): Color`	Function	Component-wise linear interpolation from a to b (not clamped).
`Color.White: Color (read-only)`	StaticProperty	A new opaque white.
`Color.Black: Color (read-only)`	StaticProperty	A new opaque black.
`Color.Red: Color (read-only)`	StaticProperty	A new opaque red.
`Color.Green: Color (read-only)`	StaticProperty	A new opaque green.
`Color.Blue: Color (read-only)`	StaticProperty	A new opaque blue.
`Color.Yellow: Color (read-only)`	StaticProperty	A new opaque yellow.
`Color.Cyan: Color (read-only)`	StaticProperty	A new opaque cyan.
`Color.Magenta: Color (read-only)`	StaticProperty	A new opaque magenta.
`Color.Gray: Color (read-only)`	StaticProperty	A new opaque mid gray (128/255).
`Color.Clear: Color (read-only)`	StaticProperty	A new fully transparent black.
`Color.__add(a: Color, b: Color): Color`	Operator	Component-wise sum (not clamped).
`Color.__sub(a: Color, b: Color): Color`	Operator	Component-wise difference (not clamped).
`Color.__mul(a: Color\|number, b: Color\|number): Color`	Operator	Component-wise product (tinting), or scaling by a number.
`Color.__eq(a: Color, b: Color): boolean`	Operator	True when every component is exactly equal.
`Color.__tostring(a: Color): string`	Operator	"Color(r, g, b, a)".

Color()#

lua

Color(r?: number|Color|Vec4, g?: number, b?: number, a?: number): Color

Color() is opaque white, Color(r, g, b) is opaque, Color(r, g, b, a) sets alpha, Color(c) copies a Color or converts a Vec4.

Parameters

r? (number|Color|Vec4)
g? (number)
b? (number)
a? (number)

Returns Color

Example

lua

local orange = Color(1, 0.5, 0)

Color.R#

lua

Color.R: number

Red component.

Color.G#

lua

Color.G: number

Green component.

Color.B#

lua

Color.B: number

Blue component.

Color.A#

lua

Color.A: number

Alpha (opacity) component.

Color:WithAlpha#

lua

Color:WithAlpha(alpha: number): Color

A copy with another alpha.

Parameters

alpha (number)

Returns Color

Example

lua

sprite.Color = sprite.Color:WithAlpha(0.5)

Color:Lerp#

lua

Color:Lerp(other: Color, t: number): Color

Component-wise linear interpolation towards other (not clamped).

Parameters

other (Color)
t (number)

Returns Color

Color:ToHex#

lua

Color:ToHex(includeAlpha?: boolean): string

"#RRGGBBAA" ("#RRGGBB" when includeAlpha is false) with the components clamped to [0, 1].

Parameters

includeAlpha? (boolean)

Returns string

Color:Unpack#

lua

Color:Unpack(): number, number, number, number

The r, g, b and a components.

Returns number, number, number, number

Color.FromHex#

lua

Color.FromHex(hex: string): Color?

Parses "#RRGGBB" or "#RRGGBBAA" (the '#' is optional); nil when the text is not a color.

Parameters

hex (string)

Returns Color?

Example

lua

local red = Color.FromHex("#FF0000")

Color.FromHSV#

lua

Color.FromHSV(hue: number, saturation: number, value: number, alpha?: number): Color

A color from hue, saturation and value in [0, 1] (hue as a fraction of a turn: 0 red, 1/3 green, 2/3 blue).

Parameters

hue (number)
saturation (number)
value (number)
alpha? (number)

Returns Color

Color.Lerp#

lua

Color.Lerp(a: Color, b: Color, t: number): Color

Component-wise linear interpolation from a to b (not clamped).

Parameters

a (Color)
b (Color)
t (number)

Returns Color

Color.White#

lua

Color.White: Color (read-only)

A new opaque white.

Color.Black#

lua

Color.Black: Color (read-only)

A new opaque black.

Color.Red#

lua

Color.Red: Color (read-only)

A new opaque red.

Color.Green#

lua

Color.Green: Color (read-only)

A new opaque green.

Color.Blue#

lua

Color.Blue: Color (read-only)

A new opaque blue.

Color.Yellow#

lua

Color.Yellow: Color (read-only)

A new opaque yellow.

Color.Cyan#

lua

Color.Cyan: Color (read-only)

A new opaque cyan.

Color.Magenta#

lua

Color.Magenta: Color (read-only)

A new opaque magenta.

Color.Gray#

lua

Color.Gray: Color (read-only)

A new opaque mid gray (128/255).

Color.Clear#

lua

Color.Clear: Color (read-only)

A new fully transparent black.

Color.__add#

lua

Color.__add(a: Color, b: Color): Color

Lua syntax: a + b

Component-wise sum (not clamped).

Parameters

a (Color)
b (Color)

Returns Color

Color.__sub#

lua

Color.__sub(a: Color, b: Color): Color

Lua syntax: a - b

Component-wise difference (not clamped).

Parameters

a (Color)
b (Color)

Returns Color

Color.__mul#

lua

Color.__mul(a: Color|number, b: Color|number): Color

Lua syntax: a * b

Component-wise product (tinting), or scaling by a number.

Parameters

a (Color|number)
b (Color|number)

Returns Color

Color.__eq#

lua

Color.__eq(a: Color, b: Color): boolean

Lua syntax: a == b

True when every component is exactly equal.

Parameters

a (Color)
b (Color)

Returns boolean

Color.__tostring#

lua

Color.__tostring(a: Color): string

Lua syntax: tostring(a)

"Color(r, g, b, a)".

Parameters

a (Color)

Returns string

Component#

A proxy of one component of an entity (Entity:GetComponent). Its fields are the component's registered fields (see Components): reading converts them to Lua values, writing validates the type, clamps to the registered range (with a warning) and raises an error for invalid values or read-only fields. The proxy looks the component up on every access, so it stays usable while the entity lives and raises errors once the component or entity is gone.

lua

local sprite = self.Entity:GetComponent("SpriteRenderer")
sprite.Color = Color(1, 0, 0)
sprite.FlipX = true
print(sprite.DrawMode) -- "Simple"

Member	Kind	Summary
`Component:GetEntity(): Entity`	Method	The entity the component belongs to.
`Component:IsValid(): boolean`	Method	True while the entity exists and still has the component.
`Component:GetTypeName(): string`	Method	The registered component name ("SpriteRenderer").
`Component.__eq(a: Component, b: Component): boolean`	Operator	True when both refer to the same component of the same entity.
`Component.__tostring(a: Component): string`	Operator	"<Component>(<entity id>)".

Component:GetEntity#

lua

Component:GetEntity(): Entity

The entity the component belongs to.

Returns Entity

Component:IsValid#

lua

Component:IsValid(): boolean

True while the entity exists and still has the component.

Returns boolean

Component:GetTypeName#

lua

Component:GetTypeName(): string

The registered component name ("SpriteRenderer").

Returns string

Component.__eq#

lua

Component.__eq(a: Component, b: Component): boolean

Lua syntax: a == b

True when both refer to the same component of the same entity.

Parameters

a (Component)
b (Component)

Returns boolean

Component.__tostring#

lua

Component.__tostring(a: Component): string

Lua syntax: tostring(a)

"<Component>(<entity id>)".

Parameters

a (Component)

Returns string

Contact#

The contact passed to OnCollisionBegin(other, contact), seen from the receiving entity (a read-only value).

lua

function Ball:OnCollisionBegin(other, contact)
	if contact.Normal.Y < -0.5 then
		self.Grounded = true
	end
end

Member	Kind	Summary
`Contact.Point: Vec2 (read-only)`	Property	World-space contact point (the mean of the 1 or 2 manifold points).
`Contact.Normal: Vec2 (read-only)`	Property	Unit contact normal pointing from the receiving entity towards the other one.
`Contact.PointCount: integer (read-only)`	Property	Number of manifold points (1 or 2).
`Contact.Collider: Entity (read-only)`	Property	The receiving side's collider entity: the receiving entity itself, or one of its children for a body's child collider.
`Contact.OtherBody: Entity (read-only)`	Property	The entity owning the other collider's body (the other entity, or its ancestor with the Rigidbody2D).
`Contact.__tostring(contact: Contact): string`	Operator	"Contact(point: (x, y), normal: (x, y))".

Contact.Point#

lua

Contact.Point: Vec2 (read-only)

World-space contact point (the mean of the 1 or 2 manifold points).

Contact.Normal#

lua

Contact.Normal: Vec2 (read-only)

Unit contact normal pointing from the receiving entity towards the other one.

Contact.PointCount#

lua

Contact.PointCount: integer (read-only)

Number of manifold points (1 or 2).

Contact.Collider#

lua

Contact.Collider: Entity (read-only)

The receiving side's collider entity: the receiving entity itself, or one of its children for a body's child collider.

Contact.OtherBody#

lua

Contact.OtherBody: Entity (read-only)

The entity owning the other collider's body (the other entity, or its ancestor with the Rigidbody2D).

Contact.__tostring#

lua

Contact.__tostring(contact: Contact): string

Lua syntax: tostring(a)

"Contact(point: (x, y), normal: (x, y))".

Parameters

contact (Contact)

Returns string

CoroutineHandle#

A coroutine started by self:StartCoroutine.

lua

local handle = self:StartCoroutine(Blink)
handle:Stop()

Member	Kind	Summary
`CoroutineHandle:Stop(): boolean`	Method	Stops the coroutine (its to-be-closed variables are closed at the end of the update); false when it had already finished.
`CoroutineHandle.IsRunning: boolean (read-only)`	Property	True until the coroutine finishes, fails or is stopped.
`CoroutineHandle.__eq(a: CoroutineHandle, b: CoroutineHandle): boolean`	Operator	True for the same coroutine.
`CoroutineHandle.__tostring(a: CoroutineHandle): string`	Operator	"CoroutineHandle(<id>)".

CoroutineHandle:Stop#

lua

CoroutineHandle:Stop(): boolean

Stops the coroutine (its to-be-closed variables are closed at the end of the update); false when it had already finished.

Returns boolean

CoroutineHandle.IsRunning#

lua

CoroutineHandle.IsRunning: boolean (read-only)

True until the coroutine finishes, fails or is stopped.

CoroutineHandle.__eq#

lua

CoroutineHandle.__eq(a: CoroutineHandle, b: CoroutineHandle): boolean

Lua syntax: a == b

True for the same coroutine.

Parameters

a (CoroutineHandle)
b (CoroutineHandle)

Returns boolean

CoroutineHandle.__tostring#

lua

CoroutineHandle.__tostring(a: CoroutineHandle): string

Lua syntax: tostring(a)

"CoroutineHandle(<id>)".

Parameters

a (CoroutineHandle)

Returns string

DataList#

A List column's value: read-only, its elements by number from 1 (nil past the end; lists of structs give DataStruct elements), # its length, so ipairs works.

lua

for _, tag in ipairs(Data.Get("Item", "iron_sword").Tags) do
	Log.Info(tag)
end

Member	Kind	Summary
`DataList.__len(a: DataList): integer`	Operator	The number of elements (#list).

DataList.__len#

lua

DataList.__len(a: DataList): integer

Lua syntax: #a

The number of elements (#list).

Parameters

a (DataList)

Returns integer

Example

lua

local count = #row.Tags

DataRow#

A row of a data table (Data.Get, Data.Rows, Items.Get, Ref columns): read-only, its columns as fields (row.Damage, row.Rolls.Min). Int columns read as integers, Float as numbers, String, Name and Enum as strings, Asset as handles, Ref as DataRow (nil when empty), Color and Vec2 as values, Struct as DataStruct and List as DataList; a value the row does not set reads its column's default. A row survives hot reloads: after a new version of its table was swapped in, it reads the row with its key in the new version (an error once no row has that key; IsValid tells).

lua

local sword = Data.Get("Weapon", "iron_sword")
Log.Info(sword.Name .. " hits for " .. sword.Damage)

Member	Kind	Summary
`DataRow:GetKey(): string`	Method	The row's key (unique in its table's family).
`DataRow:GetTable(): string`	Method	The path of the table that holds the row, below Assets/ ("Data/Weapons.ftable").
`DataRow:IsValid(): boolean`	Method	Whether a row with the key still exists (false once a hot reload removed it; reading it then raises an error).
`DataRow.__tostring(a: DataRow): string`	Operator	"DataRow(<key>)".

DataRow:GetKey#

lua

DataRow:GetKey(): string

The row's key (unique in its table's family).

Returns string

Example

lua

local key = row:GetKey()

DataRow:GetTable#

lua

DataRow:GetTable(): string

The path of the table that holds the row, below Assets/ ("Data/Weapons.ftable"). Raises an error once no row has its key.

Returns string

Example

lua

Log.Info(row:GetKey() .. " comes from " .. row:GetTable())

DataRow:IsValid#

lua

DataRow:IsValid(): boolean

Whether a row with the key still exists (false once a hot reload removed it; reading it then raises an error).

Returns boolean

Example

lua

if row:IsValid() then Log.Info(row.Name) end

DataRow.__tostring#

lua

DataRow.__tostring(a: DataRow): string

Lua syntax: tostring(a)

"DataRow(<key>)".

Parameters

a (DataRow)

Returns string

Example

lua

Log.Info(tostring(row))

DataStruct#

A Struct column's value (or an element of a list of structs): read-only, its fields as fields (loot.Rolls.Min, item.Bonuses[1].Amount), converted like a DataRow's columns.

lua

local rolls = Data.Get("LootTable", "goblin").Rolls
Log.Info(rolls.Min .. "-" .. rolls.Max)

Entity#

A reference to an entity of the scene. It stays valid while the entity exists (IsValid); afterwards only ID, IsValid, tostring and == work and every other member raises an error. Components are reached through GetComponent; Position, Rotation and Scale are shortcuts for the local Transform.

lua

local player = Scene.FindEntityByName("Player")
if player then
	player.Position = Vec2(0, 0)
	player:GetComponent("SpriteRenderer").Color = Color.Red
end

Member	Kind	Summary
`Entity.ID: integer (read-only)`	Property	The entity's persistent UUID (a 64-bit integer; large IDs read as negative numbers).
`Entity.Name: string`	Property	The entity's name (the Tag component).
`Entity.Position: Vec2`	Property	Local position (x, y of the Transform's Translation; z, the depth, is kept).
`Entity.Rotation: number`	Property	Local rotation in radians, counter-clockwise.
`Entity.Scale: Vec2`	Property	Local scale (negative values mirror).
`Entity.WorldPosition: Vec2`	Property	Position in the world (relative to the scene origin), through the parents' transforms.
`Entity:IsValid(): boolean`	Method	True while the entity exists (destruction happens at the end of the frame).
`Entity:Destroy()`	Method	Destroys the entity and its children at the end of the frame (scripts get OnDestroy).
`Entity:GetComponent(name: ComponentName): Component?`	Method	A proxy of the component with this registered name, or nil when the entity does not have it.
`Entity:AddComponent(name: ComponentName): Component`	Method	Adds a component with default values and returns its proxy.
`Entity:HasComponent(name: ComponentName): boolean`	Method	True when the entity has the component.
`Entity:RemoveComponent(name: ComponentName): boolean`	Method	Removes the component; false when the entity did not have it.
`Entity:GetParent(): Entity?`	Method	The parent entity, or nil for a root entity.
`Entity:SetParent(parent: Entity?, keepWorldTransform?: boolean)`	Method	Makes the entity a child of parent (the last child), or a root entity for nil.
`Entity:GetChildren(): Entity[]`	Method	The children in sibling order (a new table).
`Entity:GetScript(className?: string): table?`	Method	The entity's script instance (its self table), or nil when it has none or its class name (the script file name) is not className.
`Entity:SendMessage(method: string, ...: any): boolean`	Method	Calls method(self, ...) on the entity's script when it defines it.
`Entity.__eq(a: Entity, b: Entity): boolean`	Operator	True when both refer to the same entity (same UUID).
`Entity.__tostring(a: Entity): string`	Operator	"Entity(<name>, <id>)", or "Entity(destroyed, <id>)".
`Entity:IsGhost(): boolean`	Method	True for a ghost: this zone's read-only mirror of an entity a neighbouring zone owns across a seamless border.
`Entity:IsOwner(): boolean`	Method	True when this peer controls the entity: offline and for entities that are not networked always; for server-owned entities on the server; for client-owned entities on the owning client.
`Entity:GetOwner(): integer?`	Method	The owning client's id (0 = the host's player), or nil for server-owned and non-networked entities.
`Entity:GetNetworkId(): integer?`	Method	The id that names the entity on every peer of the session, or nil when it is not networked (yet).

Entity.ID#

lua

Entity.ID: integer (read-only)

The entity's persistent UUID (a 64-bit integer; large IDs read as negative numbers). Works after destruction too.

Entity.Name#

lua

Entity.Name: string

The entity's name (the Tag component).

Entity.Position#

lua

Entity.Position: Vec2

Local position (x, y of the Transform's Translation; z, the depth, is kept). Returns a copy: modify and assign it back. Non-finite values (NaN, infinity) raise an error.

Example

lua

self.Entity.Position = self.Entity.Position + Vec2(speed * dt, 0)

Entity.Rotation#

lua

Entity.Rotation: number

Local rotation in radians, counter-clockwise. Non-finite values raise an error.

Entity.Scale#

lua

Entity.Scale: Vec2

Local scale (negative values mirror). Returns a copy. Non-finite values raise an error.

Entity.WorldPosition#

lua

Entity.WorldPosition: Vec2

Position in the world (relative to the scene origin), through the parents' transforms. Returns a copy. Non-finite values raise an error.

Entity:IsValid#

lua

Entity:IsValid(): boolean

True while the entity exists (destruction happens at the end of the frame).

Returns boolean

Entity:Destroy#

lua

Entity:Destroy()

Destroys the entity and its children at the end of the frame (scripts get OnDestroy). Entities another server owns (a seamless border's ghosts: Entity:IsGhost()) are read-only: this and every other write raises an error.

Entity:GetComponent#

lua

Entity:GetComponent(name: ComponentName): Component?

A proxy of the component with this registered name, or nil when the entity does not have it. Unknown names raise an error.

Parameters

name (ComponentName)

Returns Component?

Example

lua

local sprite = self.Entity:GetComponent("SpriteRenderer")

Entity:AddComponent#

lua

Entity:AddComponent(name: ComponentName): Component

Adds a component with default values and returns its proxy. Raises an error when the entity already has one, the component is a core component (ID, Tag, Transform, Relationship) or a runtime-only one its runtime owner adds (SimulationSuspended, BorderGhost).

Parameters

name (ComponentName)

Returns Component

Example

lua

local body = self.Entity:AddComponent("Rigidbody2D")
body.GravityScale = 0

Entity:HasComponent#

lua

Entity:HasComponent(name: ComponentName): boolean

True when the entity has the component.

Parameters

name (ComponentName)

Returns boolean

Entity:RemoveComponent#

lua

Entity:RemoveComponent(name: ComponentName): boolean

Removes the component; false when the entity did not have it. Removing the Script component destroys the script instance (OnDestroy) at the next update phase.

Parameters

name (ComponentName)

Returns boolean

Entity:GetParent#

lua

Entity:GetParent(): Entity?

The parent entity, or nil for a root entity.

Returns Entity?

Entity:SetParent#

lua

Entity:SetParent(parent: Entity?, keepWorldTransform?: boolean)

Makes the entity a child of parent (the last child), or a root entity for nil. keepWorldTransform (default true) keeps the entity where it is in the world; false keeps its local transform. Parenting to a descendant raises an error.

Parameters

parent (Entity?)
keepWorldTransform? (boolean)

Example

lua

weapon:SetParent(self.Entity, false)

Entity:GetChildren#

lua

Entity:GetChildren(): Entity[]

The children in sibling order (a new table).

Returns Entity[]

Entity:GetScript#

lua

Entity:GetScript(className?: string): table?

The entity's script instance (its self table), or nil when it has none or its class name (the script file name) is not className. A script instance of a newly spawned entity already exists before its OnCreate runs, so it can be configured.

Parameters

className? (string)

Returns table?

Example

lua

local health = enemy:GetScript("Health")
if health then health:Damage(10) end

Entity:SendMessage#

lua

Entity:SendMessage(method: string, ...: any): boolean

Calls method(self, ...) on the entity's script when it defines it. Returns whether a method ran; errors in it are reported like callback errors (the receiving script is disabled).

Parameters

method (string)
...? (any)

Returns boolean

Example

lua

target:SendMessage("OnHit", 10)

Entity.__eq#

lua

Entity.__eq(a: Entity, b: Entity): boolean

Lua syntax: a == b

True when both refer to the same entity (same UUID).

Parameters

a (Entity)
b (Entity)

Returns boolean

Entity.__tostring#

lua

Entity.__tostring(a: Entity): string

Lua syntax: tostring(a)

"Entity(<name>, <id>)", or "Entity(destroyed, <id>)".

Parameters

a (Entity)

Returns string

Entity:IsGhost#

lua

Entity:IsGhost(): boolean

True for a ghost: this zone's read-only mirror of an entity a neighbouring zone owns across a seamless border. Every write to a ghost (fields, Position, AddComponent, Destroy, ...) raises an error; interact through Border.Send.

Returns boolean

Entity:IsOwner#

lua

Entity:IsOwner(): boolean

True when this peer controls the entity: offline and for entities that are not networked always; for server-owned entities on the server; for client-owned entities on the owning client.

Returns boolean

Entity:GetOwner#

lua

Entity:GetOwner(): integer?

The owning client's id (0 = the host's player), or nil for server-owned and non-networked entities.

Returns integer?

Entity:GetNetworkId#

lua

Entity:GetNetworkId(): integer?

The id that names the entity on every peer of the session, or nil when it is not networked (yet).

Returns integer?

MovementCommand#

The input of a movement step: the player's command (a predicted character's own, on its client and on the server) or the AI input of Movement.SetInput (a read-only value).

lua

function Player:OnMovementStep(state, command, dt)
	if command:IsDown("Jump") then state.Velocity = state.Velocity + Vec2(0, 2) end
end

Member	Kind	Summary
`MovementCommand.Tick: integer (read-only)`	Property	The server simulation tick the command drives (game ticks for Grid movers).
`MovementCommand.Move: Vec2 (read-only)`	Property	The move axes (Prediction.Axes 1 and 2), each in [-1, 1].
`MovementCommand.Aim: Vec2 (read-only)`	Property	The aim axes (Prediction.Axes 3 and 4), each in [-1, 1]; zero when the project names none.
`MovementCommand.Run: boolean (read-only)`	Property	The "Run" button is down (CharacterMovement runs: RunMultiplier, RunTilesPerGameTick).
`MovementCommand.Buttons: integer (read-only)`	Property	Bit i: the input action Prediction.Buttons[i + 1] is down.
`MovementCommand:IsDown(action: string): boolean`	Method	Whether a command button (an input action named in the project's Network.Prediction.Buttons) is down.

MovementCommand.Tick#

lua

MovementCommand.Tick: integer (read-only)

The server simulation tick the command drives (game ticks for Grid movers).

MovementCommand.Move#

lua

MovementCommand.Move: Vec2 (read-only)

The move axes (Prediction.Axes 1 and 2), each in [-1, 1].

MovementCommand.Aim#

lua

MovementCommand.Aim: Vec2 (read-only)

The aim axes (Prediction.Axes 3 and 4), each in [-1, 1]; zero when the project names none.

MovementCommand.Run#

lua

MovementCommand.Run: boolean (read-only)

The "Run" button is down (CharacterMovement runs: RunMultiplier, RunTilesPerGameTick).

MovementCommand.Buttons#

lua

MovementCommand.Buttons: integer (read-only)

Bit i: the input action Prediction.Buttons[i + 1] is down.

MovementCommand:IsDown#

lua

MovementCommand:IsDown(action: string): boolean

Whether a command button (an input action named in the project's Network.Prediction.Buttons) is down. Raises an error for other names.

Parameters

action (string)

Returns boolean

Example

lua

if command:IsDown("Jump") then Log.Info("jump") end

MovementState#

The state OnMovementStep(state, command, dt) receives after the native movement step: change it to change the step's result. Valid only during that call.

lua

function Player:OnMovementStep(state, command, dt)
	if self.OnMud then state.Velocity = state.Velocity * 0.5 end
end

Member	Kind	Summary
`MovementState.Position: Vec2`	Property	The position after the step (the entity's Translation, relative to the scene origin).
`MovementState.Velocity: Vec2`	Property	The velocity after the step, world units per second (the next step starts from it).
`MovementState.Rotation: number`	Property	The entity's rotation in radians (the native models keep it; a script may turn the character).
`MovementState.GridCell: Vec2`	Property	Grid movers: the cell after the game tick's steps (whole numbers).
`MovementState.GridTarget: Vec2`	Property	Grid movers: the cell the mover walks to (whole numbers); setting it redirects it from the next game tick on.

MovementState.Position#

lua

MovementState.Position: Vec2

The position after the step (the entity's Translation, relative to the scene origin).

MovementState.Velocity#

lua

MovementState.Velocity: Vec2

The velocity after the step, world units per second (the next step starts from it).

MovementState.Rotation#

lua

MovementState.Rotation: number

The entity's rotation in radians (the native models keep it; a script may turn the character).

MovementState.GridCell#

lua

MovementState.GridCell: Vec2

Grid movers: the cell after the game tick's steps (whole numbers). Setting it does not move the mover by itself: set Position too (the cell's center is (cell + 0.5) x TileSize).

MovementState.GridTarget#

lua

MovementState.GridTarget: Vec2

Grid movers: the cell the mover walks to (whole numbers); setting it redirects it from the next game tick on.

RaycastHit#

One hit of Physics.Raycast, Physics.RaycastAll or Physics.CircleCast (a read-only value).

lua

local hit = Physics.Raycast(self.Entity.WorldPosition, Vec2.Down, 2)
if hit then
	print(hit.Entity.Name, hit.Distance)
end

Member	Kind	Summary
`RaycastHit.Entity: Entity (read-only)`	Property	The entity owning the collider that was hit (IsValid() is false once it is destroyed).
`RaycastHit.Body: Entity (read-only)`	Property	The entity owning the hit collider's body: the collider's own entity, or the ancestor with the Rigidbody2D for a child collider.
`RaycastHit.Point: Vec2 (read-only)`	Property	World-space hit point.
`RaycastHit.Normal: Vec2 (read-only)`	Property	Unit surface normal at the hit point, pointing back towards the ray (zero for a CircleCast that starts overlapping).
`RaycastHit.Distance: number (read-only)`	Property	Distance from the ray origin to the hit point (CircleCast: how far the circle travelled), in world units.
`RaycastHit.Fraction: number (read-only)`	Property	Distance / maxDistance, in [0, 1].
`RaycastHit.__tostring(hit: RaycastHit): string`	Operator	"RaycastHit(<entity name>, <distance>)".

RaycastHit.Entity#

lua

RaycastHit.Entity: Entity (read-only)

The entity owning the collider that was hit (IsValid() is false once it is destroyed).

RaycastHit.Body#

lua

RaycastHit.Body: Entity (read-only)

The entity owning the hit collider's body: the collider's own entity, or the ancestor with the Rigidbody2D for a child collider.

RaycastHit.Point#

lua

RaycastHit.Point: Vec2 (read-only)

World-space hit point.

RaycastHit.Normal#

lua

RaycastHit.Normal: Vec2 (read-only)

Unit surface normal at the hit point, pointing back towards the ray (zero for a CircleCast that starts overlapping).

RaycastHit.Distance#

lua

RaycastHit.Distance: number (read-only)

Distance from the ray origin to the hit point (CircleCast: how far the circle travelled), in world units.

RaycastHit.Fraction#

lua

RaycastHit.Fraction: number (read-only)

Distance / maxDistance, in [0, 1].

RaycastHit.__tostring#

lua

RaycastHit.__tostring(hit: RaycastHit): string

Lua syntax: tostring(a)

"RaycastHit(<entity name>, <distance>)".

Parameters

hit (RaycastHit)

Returns string

ScriptInstance#

A script instance: the self of every callback. It holds self.Entity (the entity it is attached to), the script's properties and whatever the script stores, and has the methods below in addition to the class's own.

lua

function Blinker:OnCreate()
	self:StartCoroutine(function()
		while true do
			Wait(0.5)
			self.Sprite.Color = Color.Red
		end
	end)
end

Member	Kind	Summary
`ScriptInstance:StartCoroutine(fn: function, ...: any): CoroutineHandle`	Method	Runs fn(...) as a coroutine owned by this script: at once until its first Wait, WaitFrames, WaitUntil or coroutine.yield (one frame), then resumed by the engine after the OnUpdate callbacks (for a freshly spawned script: once its OnCreate ran).
`ScriptInstance:StopCoroutine(handle: CoroutineHandle): boolean`	Method	Stops a coroutine; false when it had already finished.
`ScriptInstance:StopAllCoroutines(): integer`	Method	Stops every coroutine of this script and returns how many were running.
`ScriptInstance:ServerRpc(method: string, ...: any)`	Method	Client (or host): runs method(self, ...) of this entity's script on the server.
`ScriptInstance:ClientRpc(method: string, target?: string\|integer, ...: any)`	Method	Server: runs method(self, ...) of this entity's script on clients.

ScriptInstance:StartCoroutine#

lua

ScriptInstance:StartCoroutine(fn: function, ...: any): CoroutineHandle

Runs fn(...) as a coroutine owned by this script: at once until its first Wait, WaitFrames, WaitUntil or coroutine.yield (one frame), then resumed by the engine after the OnUpdate callbacks (for a freshly spawned script: once its OnCreate ran). Errors are reported like callback errors; the coroutine stops when the script is destroyed or disabled, and a stopped coroutine is closed (its to-be-closed variables run) at the end of the update.

Parameters

fn (function)
...? (any)

Returns CoroutineHandle

Example

lua

self:StartCoroutine(function()
	Wait(1)
	Log.Info("one second later")
end)

ScriptInstance:StopCoroutine#

lua

ScriptInstance:StopCoroutine(handle: CoroutineHandle): boolean

Stops a coroutine; false when it had already finished.

Parameters

handle (CoroutineHandle)

Returns boolean

ScriptInstance:StopAllCoroutines#

lua

ScriptInstance:StopAllCoroutines(): integer

Stops every coroutine of this script and returns how many were running.

Returns integer

ScriptInstance:ServerRpc#

lua

ScriptInstance:ServerRpc(method: string, ...: any)

Client (or host): runs method(self, ...) of this entity's script on the server. The method name must end in "ServerRpc", and only the entity's owner may call it (other calls are rejected by the server) unless the server's script class declares RpcOptions = { <method> = { RequireOwnership = false } }. Arguments: nil, booleans, numbers (integers within +-2^53), strings, Vec2, Vec3, Color, Entity and flat tables of those. Limits of one call: 16 arguments, strings (table keys too) of up to 1024 bytes, tables of up to 64 entries and no table inside a table, 256 values in all (table keys and values counted); other values and calls over a limit raise an error and send nothing. Reliable and ordered unless the class declares RpcOptions = { <method> = { Reliable = false } }: such calls go unreliably (they may be lost or overtaken - for frequent calls that the next one supersedes, such as an aim direction - and are dropped when they arrive before the entity's spawn). On a host the call runs at the next network update.

Parameters

method (string)
...? (any)

Example

lua

self:ServerRpc("JumpServerRpc", self.Entity.WorldPosition)

ScriptInstance:ClientRpc#

lua

ScriptInstance:ClientRpc(method: string, target?: string|integer, ...: any)

Server: runs method(self, ...) of this entity's script on clients. The method name must end in "ClientRpc". target: nil or "All" (every client in the scene, the host's own player included), "AllExceptOwner", or one client id. Arguments and the Reliable = false option as for ServerRpc.

Parameters

method (string)
target? (string|integer)
...? (any)

Example

lua

self:ClientRpc("ExplodeClientRpc", "All", self.Entity.WorldPosition, 2.5)

TimerHandle#

A timer created by Timer.After or Timer.Every.

lua

local handle = Timer.Every(1, tick)
handle:Cancel()

Member	Kind	Summary
`TimerHandle:Cancel(): boolean`	Method	Stops the timer; false when it had already fired (once) or was cancelled.
`TimerHandle.IsActive: boolean (read-only)`	Property	True until the timer fired (After) or was cancelled.
`TimerHandle.__eq(a: TimerHandle, b: TimerHandle): boolean`	Operator	True for the same timer.
`TimerHandle.__tostring(a: TimerHandle): string`	Operator	"TimerHandle(<id>)".

TimerHandle:Cancel#

lua

TimerHandle:Cancel(): boolean

Stops the timer; false when it had already fired (once) or was cancelled.

Returns boolean

TimerHandle.IsActive#

lua

TimerHandle.IsActive: boolean (read-only)

True until the timer fired (After) or was cancelled.

TimerHandle.__eq#

lua

TimerHandle.__eq(a: TimerHandle, b: TimerHandle): boolean

Lua syntax: a == b

True for the same timer.

Parameters

a (TimerHandle)
b (TimerHandle)

Returns boolean

TimerHandle.__tostring#

lua

TimerHandle.__tostring(a: TimerHandle): string

Lua syntax: tostring(a)

"TimerHandle(<id>)".

Parameters

a (TimerHandle)

Returns string

Touch#

One touch contact of the current frame (a read-only value): see Input.GetTouch.

lua

for i = 1, Input.GetTouchCount() do
	local touch = Input.GetTouch(i)
	Debug.DrawCircle(Camera.ScreenToWorld(touch.Position), 0.2)
end

Member	Kind	Summary
`Touch.Id: integer (read-only)`	Property	Identifies the contact from touching down to lifting (1 or more); unique among the contacts that are down, reused only after its contact ended.
`Touch.Phase: TouchPhase (read-only)`	Property	What the contact did this frame.
`Touch.Position: Vec2 (read-only)`	Property	Where the contact is, in framebuffer pixels from the top-left of the window (+Y down), like the mouse.
`Touch.StartPosition: Vec2 (read-only)`	Property	Where the contact touched down.
`Touch.Delta: Vec2 (read-only)`	Property	Movement since the previous frame in framebuffer pixels; in the frame the contact began, since it touched down ((0, 0) unless it moved within that frame), so the deltas add up to Position - StartPosition.
`Touch.Pressure: number (read-only)`	Property	Pressure in [0, 1]; 1 when the device reports none (HasPressure).
`Touch.HasPressure: boolean (read-only)`	Property	Whether the device reports the contact's pressure.
`Touch.Primary: boolean (read-only)`	Property	The first contact of a gesture (it touched down while no other contact was down): it drives the UI pointer and, with Input.TouchEmulatesMouse, the mouse.
`Touch.__tostring(touch: Touch): string`	Operator	"Touch(id, Phase, (x, y))".

Touch.Id#

lua

Touch.Id: integer (read-only)

Identifies the contact from touching down to lifting (1 or more); unique among the contacts that are down, reused only after its contact ended.

Touch.Phase#

lua

Touch.Phase: TouchPhase (read-only)

What the contact did this frame.

Touch.Position#

lua

Touch.Position: Vec2 (read-only)

Where the contact is, in framebuffer pixels from the top-left of the window (+Y down), like the mouse.

Touch.StartPosition#

lua

Touch.StartPosition: Vec2 (read-only)

Where the contact touched down.

Touch.Delta#

lua

Touch.Delta: Vec2 (read-only)

Movement since the previous frame in framebuffer pixels; in the frame the contact began, since it touched down ((0, 0) unless it moved within that frame), so the deltas add up to Position - StartPosition.

Touch.Pressure#

lua

Touch.Pressure: number (read-only)

Pressure in [0, 1]; 1 when the device reports none (HasPressure).

Touch.HasPressure#

lua

Touch.HasPressure: boolean (read-only)

Whether the device reports the contact's pressure.

Touch.Primary#

lua

Touch.Primary: boolean (read-only)

The first contact of a gesture (it touched down while no other contact was down): it drives the UI pointer and, with Input.TouchEmulatesMouse, the mouse.

Touch.__tostring#

lua

Touch.__tostring(touch: Touch): string

Lua syntax: tostring(a)

"Touch(id, Phase, (x, y))".

Parameters

touch (Touch)

Returns string

Vec2#

2D vector of floats (positions, directions and sizes in world units). Vector values are userdata shared by reference: b = a shares one vector, Vec2(a) copies it. Arithmetic always creates new vectors.

lua

local position = self.Entity.Position
self.Entity.Position = position + Vec2(1, 0) * Time.DeltaTime

Member	Kind	Summary
`Vec2(x?: number\|Vec2, y?: number): Vec2`	Constructor	Creates a Vec2: Vec2() is zero, Vec2(s) has every component s, Vec2(x, y) sets each component and Vec2(v) copies a Vec2.
`Vec2.X: number`	Property	The X component.
`Vec2.Y: number`	Property	The Y component.
`Vec2:Length(): number`	Method	The Euclidean length.
`Vec2:LengthSquared(): number`	Method	The squared length (cheaper than Length; good for comparisons).
`Vec2:Normalized(): Vec2`	Method	A vector of length 1 in the same direction; the zero vector stays zero.
`Vec2:Dot(other: Vec2): number`	Method	The dot product.
`Vec2:Distance(other: Vec2): number`	Method	The distance to another point.
`Vec2:Lerp(other: Vec2, t: number): Vec2`	Method	Linear interpolation towards other (t = 0 gives this vector, 1 gives other; not clamped).
`Vec2:Unpack(): number, number`	Method	The components as separate values.
`Vec2.Lerp(a: Vec2, b: Vec2, t: number): Vec2`	Function	Linear interpolation from a to b (not clamped).
`Vec2.Distance(a: Vec2, b: Vec2): number`	Function	The distance between two points.
`Vec2.Dot(a: Vec2, b: Vec2): number`	Function	The dot product.
`Vec2.Min(a: Vec2, b: Vec2): Vec2`	Function	The component-wise minimum.
`Vec2.Max(a: Vec2, b: Vec2): Vec2`	Function	The component-wise maximum.
`Vec2.Zero: Vec2 (read-only)`	StaticProperty	A new vector with every component 0.
`Vec2.One: Vec2 (read-only)`	StaticProperty	A new vector with every component 1.
`Vec2.__add(a: Vec2, b: Vec2): Vec2`	Operator	Component-wise sum.
`Vec2.__sub(a: Vec2, b: Vec2): Vec2`	Operator	Component-wise difference.
`Vec2.__mul(a: Vec2\|number, b: Vec2\|number): Vec2`	Operator	Component-wise product, or scaling by a number (on either side).
`Vec2.__div(a: Vec2\|number, b: Vec2\|number): Vec2`	Operator	Component-wise quotient, or division by (or of) a number.
`Vec2.__unm(a: Vec2): Vec2`	Operator	The negated vector.
`Vec2.__eq(a: Vec2, b: Vec2): boolean`	Operator	True when every component is exactly equal.
`Vec2.__tostring(a: Vec2): string`	Operator	"Vec2(...)" with the shortest exact decimal form of each component.
`Vec2:Cross(other: Vec2): number`	Method	The z component of the 3D cross product (positive when other is counter-clockwise from this vector).
`Vec2:Angle(): number`	Method	The angle from +X in radians (counter-clockwise, in [-pi, pi]).
`Vec2:Rotated(radians: number): Vec2`	Method	The vector rotated counter-clockwise.
`Vec2:Perpendicular(): Vec2`	Method	The vector rotated 90 degrees counter-clockwise: Vec2(-y, x).
`Vec2.Cross(a: Vec2, b: Vec2): number`	Function	The z component of the 3D cross product of a and b.
`Vec2.FromAngle(radians: number, length?: number): Vec2`	Function	A vector pointing at the angle (counter-clockwise from +X) with the given length (default 1).
`Vec2.Up: Vec2 (read-only)`	StaticProperty	A new Vec2(0, 1) (world up).
`Vec2.Down: Vec2 (read-only)`	StaticProperty	A new Vec2(0, -1).
`Vec2.Left: Vec2 (read-only)`	StaticProperty	A new Vec2(-1, 0).
`Vec2.Right: Vec2 (read-only)`	StaticProperty	A new Vec2(1, 0).

Vec2()#

lua

Vec2(x?: number|Vec2, y?: number): Vec2

Creates a Vec2: Vec2() is zero, Vec2(s) has every component s, Vec2(x, y) sets each component and Vec2(v) copies a Vec2.

Parameters

x? (number|Vec2)
y? (number)

Returns Vec2

Example

lua

local v = Vec2(1, 2)

Vec2.X#

lua

Vec2.X: number

The X component. Assigning changes this vector value in place (vector values are shared by reference).

Vec2.Y#

lua

Vec2.Y: number

The Y component. Assigning changes this vector value in place (vector values are shared by reference).

Vec2:Length#

lua

Vec2:Length(): number

The Euclidean length.

Returns number

Example

lua

local speed = velocity:Length()

Vec2:LengthSquared#

lua

Vec2:LengthSquared(): number

The squared length (cheaper than Length; good for comparisons).

Returns number

Vec2:Normalized#

lua

Vec2:Normalized(): Vec2

A vector of length 1 in the same direction; the zero vector stays zero.

Returns Vec2

Example

lua

local direction = (target - position):Normalized()

Vec2:Dot#

lua

Vec2:Dot(other: Vec2): number

The dot product.

Parameters

other (Vec2)

Returns number

Vec2:Distance#

lua

Vec2:Distance(other: Vec2): number

The distance to another point.

Parameters

other (Vec2)

Returns number

Vec2:Lerp#

lua

Vec2:Lerp(other: Vec2, t: number): Vec2

Linear interpolation towards other (t = 0 gives this vector, 1 gives other; not clamped).

Parameters

other (Vec2)
t (number)

Returns Vec2

Vec2:Unpack#

lua

Vec2:Unpack(): number, number

The components as separate values.

Returns number, number

Example

lua

local x, y = position:Unpack()

Vec2.Lerp#

lua

Vec2.Lerp(a: Vec2, b: Vec2, t: number): Vec2

Linear interpolation from a to b (not clamped).

Parameters

a (Vec2)
b (Vec2)
t (number)

Returns Vec2

Vec2.Distance#

lua

Vec2.Distance(a: Vec2, b: Vec2): number

The distance between two points.

Parameters

a (Vec2)
b (Vec2)

Returns number

Vec2.Dot#

lua

Vec2.Dot(a: Vec2, b: Vec2): number

The dot product.

Parameters

a (Vec2)
b (Vec2)

Returns number

Vec2.Min#

lua

Vec2.Min(a: Vec2, b: Vec2): Vec2

The component-wise minimum.

Parameters

a (Vec2)
b (Vec2)

Returns Vec2

Vec2.Max#

lua

Vec2.Max(a: Vec2, b: Vec2): Vec2

The component-wise maximum.

Parameters

a (Vec2)
b (Vec2)

Returns Vec2

Vec2.Zero#

lua

Vec2.Zero: Vec2 (read-only)

A new vector with every component 0.

Vec2.One#

lua

Vec2.One: Vec2 (read-only)

A new vector with every component 1.

Vec2.__add#

lua

Vec2.__add(a: Vec2, b: Vec2): Vec2

Lua syntax: a + b

Component-wise sum.

Parameters

a (Vec2)
b (Vec2)

Returns Vec2

Vec2.__sub#

lua

Vec2.__sub(a: Vec2, b: Vec2): Vec2

Lua syntax: a - b

Component-wise difference.

Parameters

a (Vec2)
b (Vec2)

Returns Vec2

Vec2.__mul#

lua

Vec2.__mul(a: Vec2|number, b: Vec2|number): Vec2

Lua syntax: a * b

Component-wise product, or scaling by a number (on either side).

Parameters

a (Vec2|number)
b (Vec2|number)

Returns Vec2

Vec2.__div#

lua

Vec2.__div(a: Vec2|number, b: Vec2|number): Vec2

Lua syntax: a / b

Component-wise quotient, or division by (or of) a number.

Parameters

a (Vec2|number)
b (Vec2|number)

Returns Vec2

Vec2.__unm#

lua

Vec2.__unm(a: Vec2): Vec2

Lua syntax: -a

The negated vector.

Parameters

a (Vec2)

Returns Vec2

Vec2.__eq#

lua

Vec2.__eq(a: Vec2, b: Vec2): boolean

Lua syntax: a == b

True when every component is exactly equal.

Parameters

a (Vec2)
b (Vec2)

Returns boolean

Vec2.__tostring#

lua

Vec2.__tostring(a: Vec2): string

Lua syntax: tostring(a)

"Vec2(...)" with the shortest exact decimal form of each component.

Parameters

a (Vec2)

Returns string

Vec2:Cross#

lua

Vec2:Cross(other: Vec2): number

The z component of the 3D cross product (positive when other is counter-clockwise from this vector).

Parameters

other (Vec2)

Returns number

Vec2:Angle#

lua

Vec2:Angle(): number

The angle from +X in radians (counter-clockwise, in [-pi, pi]).

Returns number

Vec2:Rotated#

lua

Vec2:Rotated(radians: number): Vec2

The vector rotated counter-clockwise.

Parameters

radians (number)

Returns Vec2

Vec2:Perpendicular#

lua

Vec2:Perpendicular(): Vec2

The vector rotated 90 degrees counter-clockwise: Vec2(-y, x).

Returns Vec2

Vec2.Cross#

lua

Vec2.Cross(a: Vec2, b: Vec2): number

The z component of the 3D cross product of a and b.

Parameters

a (Vec2)
b (Vec2)

Returns number

Vec2.FromAngle#

lua

Vec2.FromAngle(radians: number, length?: number): Vec2

A vector pointing at the angle (counter-clockwise from +X) with the given length (default 1).

Parameters

radians (number)
length? (number)

Returns Vec2

Vec2.Up#

lua

Vec2.Up: Vec2 (read-only)

A new Vec2(0, 1) (world up).

Vec2.Down#

lua

Vec2.Down: Vec2 (read-only)

A new Vec2(0, -1).

Vec2.Left#

lua

Vec2.Left: Vec2 (read-only)

A new Vec2(-1, 0).

Vec2.Right#

lua

Vec2.Right: Vec2 (read-only)

A new Vec2(1, 0).

Vec3#

3D vector of floats (Transform translations, where z is depth). Shared by reference like Vec2.

lua

local translation = Vec3(1, 2, 0.5)

Member	Kind	Summary
`Vec3(x?: number\|Vec2\|Vec3, y?: number, z?: number): Vec3`	Constructor	Creates a Vec3: Vec3() is zero, Vec3(s) has every component s, Vec3(x, y, z) sets each component and Vec3(v) copies a Vec3.
`Vec3.X: number`	Property	The X component.
`Vec3.Y: number`	Property	The Y component.
`Vec3.Z: number`	Property	The Z component.
`Vec3:Length(): number`	Method	The Euclidean length.
`Vec3:LengthSquared(): number`	Method	The squared length (cheaper than Length; good for comparisons).
`Vec3:Normalized(): Vec3`	Method	A vector of length 1 in the same direction; the zero vector stays zero.
`Vec3:Dot(other: Vec3): number`	Method	The dot product.
`Vec3:Distance(other: Vec3): number`	Method	The distance to another point.
`Vec3:Lerp(other: Vec3, t: number): Vec3`	Method	Linear interpolation towards other (t = 0 gives this vector, 1 gives other; not clamped).
`Vec3:Unpack(): number, number, number`	Method	The components as separate values.
`Vec3.Lerp(a: Vec3, b: Vec3, t: number): Vec3`	Function	Linear interpolation from a to b (not clamped).
`Vec3.Distance(a: Vec3, b: Vec3): number`	Function	The distance between two points.
`Vec3.Dot(a: Vec3, b: Vec3): number`	Function	The dot product.
`Vec3.Min(a: Vec3, b: Vec3): Vec3`	Function	The component-wise minimum.
`Vec3.Max(a: Vec3, b: Vec3): Vec3`	Function	The component-wise maximum.
`Vec3.Zero: Vec3 (read-only)`	StaticProperty	A new vector with every component 0.
`Vec3.One: Vec3 (read-only)`	StaticProperty	A new vector with every component 1.
`Vec3.__add(a: Vec3, b: Vec3): Vec3`	Operator	Component-wise sum.
`Vec3.__sub(a: Vec3, b: Vec3): Vec3`	Operator	Component-wise difference.
`Vec3.__mul(a: Vec3\|number, b: Vec3\|number): Vec3`	Operator	Component-wise product, or scaling by a number (on either side).
`Vec3.__div(a: Vec3\|number, b: Vec3\|number): Vec3`	Operator	Component-wise quotient, or division by (or of) a number.
`Vec3.__unm(a: Vec3): Vec3`	Operator	The negated vector.
`Vec3.__eq(a: Vec3, b: Vec3): boolean`	Operator	True when every component is exactly equal.
`Vec3.__tostring(a: Vec3): string`	Operator	"Vec3(...)" with the shortest exact decimal form of each component.
`Vec3:Cross(other: Vec3): Vec3`	Method	The cross product.
`Vec3.Cross(a: Vec3, b: Vec3): Vec3`	Function	The cross product of a and b.
`Vec3.Up: Vec3 (read-only)`	StaticProperty	A new Vec3(0, 1, 0).
`Vec3.Down: Vec3 (read-only)`	StaticProperty	A new Vec3(0, -1, 0).
`Vec3.Left: Vec3 (read-only)`	StaticProperty	A new Vec3(-1, 0, 0).
`Vec3.Right: Vec3 (read-only)`	StaticProperty	A new Vec3(1, 0, 0).
`Vec3.Forward: Vec3 (read-only)`	StaticProperty	A new Vec3(0, 0, 1) (towards the camera: higher z draws in front).
`Vec3.Back: Vec3 (read-only)`	StaticProperty	A new Vec3(0, 0, -1).

Vec3()#

lua

Vec3(x?: number|Vec2|Vec3, y?: number, z?: number): Vec3

Creates a Vec3: Vec3() is zero, Vec3(s) has every component s, Vec3(x, y, z) sets each component and Vec3(v) copies a Vec3. Vec3(v, z) extends a Vec2.

Parameters

x? (number|Vec2|Vec3)
y? (number)
z? (number)

Returns Vec3

Example

lua

local v = Vec3(1, 2, 0.5)

Vec3.X#

lua

Vec3.X: number

The X component. Assigning changes this vector value in place (vector values are shared by reference).

Vec3.Y#

lua

Vec3.Y: number

The Y component. Assigning changes this vector value in place (vector values are shared by reference).

Vec3.Z#

lua

Vec3.Z: number

The Z component. Assigning changes this vector value in place (vector values are shared by reference).

Vec3:Length#

lua

Vec3:Length(): number

The Euclidean length.

Returns number

Example

lua

local speed = velocity:Length()

Vec3:LengthSquared#

lua

Vec3:LengthSquared(): number

The squared length (cheaper than Length; good for comparisons).

Returns number

Vec3:Normalized#

lua

Vec3:Normalized(): Vec3

A vector of length 1 in the same direction; the zero vector stays zero.

Returns Vec3

Example

lua

local direction = (target - position):Normalized()

Vec3:Dot#

lua

Vec3:Dot(other: Vec3): number

The dot product.

Parameters

other (Vec3)

Returns number

Vec3:Distance#

lua

Vec3:Distance(other: Vec3): number

The distance to another point.

Parameters

other (Vec3)

Returns number

Vec3:Lerp#

lua

Vec3:Lerp(other: Vec3, t: number): Vec3

Linear interpolation towards other (t = 0 gives this vector, 1 gives other; not clamped).

Parameters

other (Vec3)
t (number)

Returns Vec3

Vec3:Unpack#

lua

Vec3:Unpack(): number, number, number

The components as separate values.

Returns number, number, number

Example

lua

local x, y = position:Unpack()

Vec3.Lerp#

lua

Vec3.Lerp(a: Vec3, b: Vec3, t: number): Vec3

Linear interpolation from a to b (not clamped).

Parameters

a (Vec3)
b (Vec3)
t (number)

Returns Vec3

Vec3.Distance#

lua

Vec3.Distance(a: Vec3, b: Vec3): number

The distance between two points.

Parameters

a (Vec3)
b (Vec3)

Returns number

Vec3.Dot#

lua

Vec3.Dot(a: Vec3, b: Vec3): number

The dot product.

Parameters

a (Vec3)
b (Vec3)

Returns number

Vec3.Min#

lua

Vec3.Min(a: Vec3, b: Vec3): Vec3

The component-wise minimum.

Parameters

a (Vec3)
b (Vec3)

Returns Vec3

Vec3.Max#

lua

Vec3.Max(a: Vec3, b: Vec3): Vec3

The component-wise maximum.

Parameters

a (Vec3)
b (Vec3)

Returns Vec3

Vec3.Zero#

lua

Vec3.Zero: Vec3 (read-only)

A new vector with every component 0.

Vec3.One#

lua

Vec3.One: Vec3 (read-only)

A new vector with every component 1.

Vec3.__add#

lua

Vec3.__add(a: Vec3, b: Vec3): Vec3

Lua syntax: a + b

Component-wise sum.

Parameters

a (Vec3)
b (Vec3)

Returns Vec3

Vec3.__sub#

lua

Vec3.__sub(a: Vec3, b: Vec3): Vec3

Lua syntax: a - b

Component-wise difference.

Parameters

a (Vec3)
b (Vec3)

Returns Vec3

Vec3.__mul#

lua

Vec3.__mul(a: Vec3|number, b: Vec3|number): Vec3

Lua syntax: a * b

Component-wise product, or scaling by a number (on either side).

Parameters

a (Vec3|number)
b (Vec3|number)

Returns Vec3

Vec3.__div#

lua

Vec3.__div(a: Vec3|number, b: Vec3|number): Vec3

Lua syntax: a / b

Component-wise quotient, or division by (or of) a number.

Parameters

a (Vec3|number)
b (Vec3|number)

Returns Vec3

Vec3.__unm#

lua

Vec3.__unm(a: Vec3): Vec3

Lua syntax: -a

The negated vector.

Parameters

a (Vec3)

Returns Vec3

Vec3.__eq#

lua

Vec3.__eq(a: Vec3, b: Vec3): boolean

Lua syntax: a == b

True when every component is exactly equal.

Parameters

a (Vec3)
b (Vec3)

Returns boolean

Vec3.__tostring#

lua

Vec3.__tostring(a: Vec3): string

Lua syntax: tostring(a)

"Vec3(...)" with the shortest exact decimal form of each component.

Parameters

a (Vec3)

Returns string

Vec3:Cross#

lua

Vec3:Cross(other: Vec3): Vec3

The cross product.

Parameters

other (Vec3)

Returns Vec3

Vec3.Cross#

lua

Vec3.Cross(a: Vec3, b: Vec3): Vec3

The cross product of a and b.

Parameters

a (Vec3)
b (Vec3)

Returns Vec3

Vec3.Up#

lua

Vec3.Up: Vec3 (read-only)

A new Vec3(0, 1, 0).

Vec3.Down#

lua

Vec3.Down: Vec3 (read-only)

A new Vec3(0, -1, 0).

Vec3.Left#

lua

Vec3.Left: Vec3 (read-only)

A new Vec3(-1, 0, 0).

Vec3.Right#

lua

Vec3.Right: Vec3 (read-only)

A new Vec3(1, 0, 0).

Vec3.Forward#

lua

Vec3.Forward: Vec3 (read-only)

A new Vec3(0, 0, 1) (towards the camera: higher z draws in front).

Vec3.Back#

lua

Vec3.Back: Vec3 (read-only)

A new Vec3(0, 0, -1).

Vec4#

4D vector of floats (slice borders, viewport rectangles). Shared by reference like Vec2.

lua

local borders = Vec4(4, 4, 4, 4)

Member	Kind	Summary
`Vec4(x?: number\|Vec3\|Vec4, y?: number, z?: number, w?: number): Vec4`	Constructor	Creates a Vec4: Vec4() is zero, Vec4(s) has every component s, Vec4(x, y, z, w) sets each component and Vec4(v) copies a Vec4.
`Vec4.X: number`	Property	The X component.
`Vec4.Y: number`	Property	The Y component.
`Vec4.Z: number`	Property	The Z component.
`Vec4.W: number`	Property	The W component.
`Vec4:Length(): number`	Method	The Euclidean length.
`Vec4:LengthSquared(): number`	Method	The squared length (cheaper than Length; good for comparisons).
`Vec4:Normalized(): Vec4`	Method	A vector of length 1 in the same direction; the zero vector stays zero.
`Vec4:Dot(other: Vec4): number`	Method	The dot product.
`Vec4:Distance(other: Vec4): number`	Method	The distance to another point.
`Vec4:Lerp(other: Vec4, t: number): Vec4`	Method	Linear interpolation towards other (t = 0 gives this vector, 1 gives other; not clamped).
`Vec4:Unpack(): number, number, number, number`	Method	The components as separate values.
`Vec4.Lerp(a: Vec4, b: Vec4, t: number): Vec4`	Function	Linear interpolation from a to b (not clamped).
`Vec4.Distance(a: Vec4, b: Vec4): number`	Function	The distance between two points.
`Vec4.Dot(a: Vec4, b: Vec4): number`	Function	The dot product.
`Vec4.Min(a: Vec4, b: Vec4): Vec4`	Function	The component-wise minimum.
`Vec4.Max(a: Vec4, b: Vec4): Vec4`	Function	The component-wise maximum.
`Vec4.Zero: Vec4 (read-only)`	StaticProperty	A new vector with every component 0.
`Vec4.One: Vec4 (read-only)`	StaticProperty	A new vector with every component 1.
`Vec4.__add(a: Vec4, b: Vec4): Vec4`	Operator	Component-wise sum.
`Vec4.__sub(a: Vec4, b: Vec4): Vec4`	Operator	Component-wise difference.
`Vec4.__mul(a: Vec4\|number, b: Vec4\|number): Vec4`	Operator	Component-wise product, or scaling by a number (on either side).
`Vec4.__div(a: Vec4\|number, b: Vec4\|number): Vec4`	Operator	Component-wise quotient, or division by (or of) a number.
`Vec4.__unm(a: Vec4): Vec4`	Operator	The negated vector.
`Vec4.__eq(a: Vec4, b: Vec4): boolean`	Operator	True when every component is exactly equal.
`Vec4.__tostring(a: Vec4): string`	Operator	"Vec4(...)" with the shortest exact decimal form of each component.

Vec4()#

lua

Vec4(x?: number|Vec3|Vec4, y?: number, z?: number, w?: number): Vec4

Creates a Vec4: Vec4() is zero, Vec4(s) has every component s, Vec4(x, y, z, w) sets each component and Vec4(v) copies a Vec4. Vec4(v, w) extends a Vec3.

Parameters

x? (number|Vec3|Vec4)
y? (number)
z? (number)
w? (number)

Returns Vec4

Example

lua

local v = Vec4(1, 2, 3, 4)

Vec4.X#

lua

Vec4.X: number

The X component. Assigning changes this vector value in place (vector values are shared by reference).

Vec4.Y#

lua

Vec4.Y: number

The Y component. Assigning changes this vector value in place (vector values are shared by reference).

Vec4.Z#

lua

Vec4.Z: number

The Z component. Assigning changes this vector value in place (vector values are shared by reference).

Vec4.W#

lua

Vec4.W: number

The W component. Assigning changes this vector value in place (vector values are shared by reference).

Vec4:Length#

lua

Vec4:Length(): number

The Euclidean length.

Returns number

Example

lua

local speed = velocity:Length()

Vec4:LengthSquared#

lua

Vec4:LengthSquared(): number

The squared length (cheaper than Length; good for comparisons).

Returns number

Vec4:Normalized#

lua

Vec4:Normalized(): Vec4

A vector of length 1 in the same direction; the zero vector stays zero.

Returns Vec4

Example

lua

local direction = (target - position):Normalized()

Vec4:Dot#

lua

Vec4:Dot(other: Vec4): number

The dot product.

Parameters

other (Vec4)

Returns number

Vec4:Distance#

lua

Vec4:Distance(other: Vec4): number

The distance to another point.

Parameters

other (Vec4)

Returns number

Vec4:Lerp#

lua

Vec4:Lerp(other: Vec4, t: number): Vec4

Linear interpolation towards other (t = 0 gives this vector, 1 gives other; not clamped).

Parameters

other (Vec4)
t (number)

Returns Vec4

Vec4:Unpack#

lua

Vec4:Unpack(): number, number, number, number

The components as separate values.

Returns number, number, number, number

Example

lua

local x, y = position:Unpack()

Vec4.Lerp#

lua

Vec4.Lerp(a: Vec4, b: Vec4, t: number): Vec4

Linear interpolation from a to b (not clamped).

Parameters

a (Vec4)
b (Vec4)
t (number)

Returns Vec4

Vec4.Distance#

lua

Vec4.Distance(a: Vec4, b: Vec4): number

The distance between two points.

Parameters

a (Vec4)
b (Vec4)

Returns number

Vec4.Dot#

lua

Vec4.Dot(a: Vec4, b: Vec4): number

The dot product.

Parameters

a (Vec4)
b (Vec4)

Returns number

Vec4.Min#

lua

Vec4.Min(a: Vec4, b: Vec4): Vec4

The component-wise minimum.

Parameters

a (Vec4)
b (Vec4)

Returns Vec4

Vec4.Max#

lua

Vec4.Max(a: Vec4, b: Vec4): Vec4

The component-wise maximum.

Parameters

a (Vec4)
b (Vec4)

Returns Vec4

Vec4.Zero#

lua

Vec4.Zero: Vec4 (read-only)

A new vector with every component 0.

Vec4.One#

lua

Vec4.One: Vec4 (read-only)

A new vector with every component 1.

Vec4.__add#

lua

Vec4.__add(a: Vec4, b: Vec4): Vec4

Lua syntax: a + b

Component-wise sum.

Parameters

a (Vec4)
b (Vec4)

Returns Vec4

Vec4.__sub#

lua

Vec4.__sub(a: Vec4, b: Vec4): Vec4

Lua syntax: a - b

Component-wise difference.

Parameters

a (Vec4)
b (Vec4)

Returns Vec4

Vec4.__mul#

lua

Vec4.__mul(a: Vec4|number, b: Vec4|number): Vec4

Lua syntax: a * b

Component-wise product, or scaling by a number (on either side).

Parameters

a (Vec4|number)
b (Vec4|number)

Returns Vec4

Vec4.__div#

lua

Vec4.__div(a: Vec4|number, b: Vec4|number): Vec4

Lua syntax: a / b

Component-wise quotient, or division by (or of) a number.

Parameters

a (Vec4|number)
b (Vec4|number)

Returns Vec4

Vec4.__unm#

lua

Vec4.__unm(a: Vec4): Vec4

Lua syntax: -a

The negated vector.

Parameters

a (Vec4)

Returns Vec4

Vec4.__eq#

lua

Vec4.__eq(a: Vec4, b: Vec4): boolean

Lua syntax: a == b

True when every component is exactly equal.

Parameters

a (Vec4)
b (Vec4)

Returns boolean

Vec4.__tostring#

lua

Vec4.__tostring(a: Vec4): string

Lua syntax: tostring(a)

"Vec4(...)" with the shortest exact decimal form of each component.

Parameters

a (Vec4)

Returns string

Components#

Component proxies returned by Entity:GetComponent. Their properties are generated from the component registry: vectors and colors are Vec/Color values, enums are names, entity references are Entity values (or nil) and asset references are asset handles (integers; writes also accept virtual paths). A ComponentName in a signature is the name of one of these components (a string).

AIAgent#

An NPC brain the AI scheduler runs: it thinks (the script's OnThink(dt), or a native handler) often near players and rarely far from them, sleeps beyond SleepDistance and shares a per-step think budget with the other agents (higher Priority first).

lua

local component = self.Entity:GetComponent("AIAgent")

Member	Kind	Summary
`AIAgent.Enabled: boolean`	Property	Whether the agent thinks.
`AIAgent.NearIntervalMs: number`	Property	Milliseconds between thinks at NearDistance or closer to the nearest player (also when the distance is unknown).
`AIAgent.FarIntervalMs: number`	Property	Milliseconds between thinks at FarDistance or farther (linear in between; at least NearIntervalMs); also how often a sleeping agent checks whether a player came closer.
`AIAgent.NearDistance: number`	Property	World units to the nearest player within which the agent thinks every NearIntervalMs.
`AIAgent.FarDistance: number`	Property	World units to the nearest player from which the agent thinks every FarIntervalMs.
`AIAgent.SleepDistance: number`	Property	Beyond this many world units from every player the agent sleeps (no thinks) until one comes closer; 0 = never sleeps.
`AIAgent.Priority: integer`	Property	When the per-step think budget is short, higher priorities think first (bosses before rabbits).
`AIAgent.Handler: string`	Property	The native think handler to run (registered by name with the scheduler); empty = the entity script's OnThink(dt).

AIAgent.Enabled#

lua

AIAgent.Enabled: boolean

Whether the agent thinks. A disabled agent is checked every FarIntervalMs and thinks again once enabled.

AIAgent.NearIntervalMs#

lua

AIAgent.NearIntervalMs: number

Milliseconds between thinks at NearDistance or closer to the nearest player (also when the distance is unknown). Range [1, 3600000]: writes outside it are clamped with a warning.

AIAgent.FarIntervalMs#

lua

AIAgent.FarIntervalMs: number

Milliseconds between thinks at FarDistance or farther (linear in between; at least NearIntervalMs); also how often a sleeping agent checks whether a player came closer. Range [1, 3600000]: writes outside it are clamped with a warning.

AIAgent.NearDistance#

lua

AIAgent.NearDistance: number

World units to the nearest player within which the agent thinks every NearIntervalMs. Range [0, inf]: writes outside it are clamped with a warning.

AIAgent.FarDistance#

lua

AIAgent.FarDistance: number

World units to the nearest player from which the agent thinks every FarIntervalMs. Range [0, inf]: writes outside it are clamped with a warning.

AIAgent.SleepDistance#

lua

AIAgent.SleepDistance: number

Beyond this many world units from every player the agent sleeps (no thinks) until one comes closer; 0 = never sleeps. Range [0, inf]: writes outside it are clamped with a warning.

AIAgent.Priority#

lua

AIAgent.Priority: integer

When the per-step think budget is short, higher priorities think first (bosses before rabbits). A change applies from the agent's next think. Range [-100, 100]: writes outside it are clamped with a warning.

AIAgent.Handler#

lua

AIAgent.Handler: string

The native think handler to run (registered by name with the scheduler); empty = the entity script's OnThink(dt).

AmbientVolume#

An ambient loop for an area (clients): it fades in over EdgeFalloff from the volume's edge inwards, blended with other ambient volumes the local listener is in.

lua

local component = self.Entity:GetComponent("AmbientVolume")

Member	Kind	Summary
`AmbientVolume.Clip: integer?`	Property	The looping ambient clip.
`AmbientVolume.Volume: number`	Property	Linear volume deep inside the volume (1 = unchanged).
`AmbientVolume.FadeSeconds: number`	Property	Seconds the loop takes to fade in when it starts and out when it stops.
`AmbientVolume.EdgeFalloff: number`	Property	World units inside the edge over which the loop rises to its volume (0 = full volume everywhere inside).
`AmbientVolume.MixerGroup: string`	Property	Name of the project mixer group the loop plays through (empty = Master).

AmbientVolume.Clip#

lua

AmbientVolume.Clip: integer?

The looping ambient clip. Asset handle of a AudioClip (nil when none); writes also accept a virtual path such as "Assets/...".

AmbientVolume.Volume#

lua

AmbientVolume.Volume: number

Linear volume deep inside the volume (1 = unchanged). Range [0, 4]: writes outside it are clamped with a warning.

AmbientVolume.FadeSeconds#

lua

AmbientVolume.FadeSeconds: number

Seconds the loop takes to fade in when it starts and out when it stops. Range [0, 60]: writes outside it are clamped with a warning.

AmbientVolume.EdgeFalloff#

lua

AmbientVolume.EdgeFalloff: number

World units inside the edge over which the loop rises to its volume (0 = full volume everywhere inside). Range [0, inf]: writes outside it are clamped with a warning.

AmbientVolume.MixerGroup#

lua

AmbientVolume.MixerGroup: string

Name of the project mixer group the loop plays through (empty = Master).

AudioListener#

The point spatial audio is heard from (usually on the camera). Only one active listener is used.

lua

local component = self.Entity:GetComponent("AudioListener")

Member	Kind	Summary
`AudioListener.Active: boolean`	Property	Whether this listener is used; the first active listener wins.

AudioListener.Active#

lua

AudioListener.Active: boolean

Whether this listener is used; the first active listener wins.

AudioSource#

Plays an audio clip, optionally positioned in 2D relative to the AudioListener.

lua

local component = self.Entity:GetComponent("AudioSource")

Member	Kind	Summary
`AudioSource.Clip: integer?`	Property	The audio clip to play.
`AudioSource.Volume: number`	Property	Linear volume (1 = unchanged).
`AudioSource.Pitch: number`	Property	Playback speed and pitch multiplier (1 = unchanged).
`AudioSource.Loop: boolean`	Property	Restarts the clip when it ends.
`AudioSource.PlayOnAwake: boolean`	Property	Starts playing when the scene starts running or the component is created at runtime.
`AudioSource.Spatial: boolean`	Property	Attenuates and pans the sound by its position relative to the AudioListener.
`AudioSource.MinDistance: number`	Property	Distance (world units) within which a spatial sound plays at full volume.
`AudioSource.MaxDistance: number`	Property	Distance (world units) beyond which a spatial sound is no longer attenuated further.
`AudioSource.MixerGroup: string`	Property	Name of the project mixer group the sound plays through (e.g.
`AudioSource:Play(fadeInSeconds?: number): boolean`	Method	Starts the source's Clip from the beginning with its settings (restarting it when it plays or is paused), its volume rising from silence over fadeInSeconds (default 0: at once).
`AudioSource:Seek(seconds: number): boolean`	Method	Moves the playback position of the source's voice to `seconds` into the clip (wrapped for looping sources, clamped to the end otherwise: a non-looping voice sought to its end finishes).
`AudioSource:GetPlaybackPosition(): number?`	Method	Seconds into the clip of the source's voice (playing or paused), or nil when it has none.
`AudioSource:GetLength(): number?`	Method	The length in seconds of the clip the source plays, or of its Clip when that clip is loaded (it loads when the source starts, or with the scene for PlayOnAwake and listed clips); nil when unknown.
`AudioSource:FadeTo(volume: number, seconds: number): boolean`	Method	Changes the component's Volume linearly to `volume` (above 4 it is clamped to 4; a negative volume raises an error) over `seconds` of real time (also while Time.TimeScale is 0; 0 seconds: at once), whether or not the source plays.
`AudioSource:IsFading(): boolean`	Method	True while a FadeTo of the source runs; the fades of Play(fadeInSeconds) and Stop(fadeOutSeconds) do not count.
`AudioSource:GetEffectiveVolume(): number?`	Method	The gain the source's voice plays at: its Volume x the volumes of its mixer group and the groups that group routes into (0 while one is muted) x, for a Spatial source, the distance falloff between it and the active AudioListener (the listener and the source's position as of the last frame).
`AudioSource:Stop(fadeOutSeconds?: number): boolean`	Method	Stops the source's voice, optionally fading it out.
`AudioSource:Pause(): boolean`	Method	Pauses the voice at its position (it stays paused when the scene unpauses).
`AudioSource:Resume(): boolean`	Method	Resumes a voice paused with Pause.
`AudioSource:IsPlaying(): boolean`	Method	True while the source has a voice that is not paused by Pause (a voice paused only by the scene pause counts as playing).
`AudioSource:IsPaused(): boolean`	Method	True while the source's voice is paused by Pause.
`AudioSource:SetVolume(volume: number)`	Method	Sets the component's Volume (above 4 it is clamped to 4; a negative or non-finite volume raises an error) and applies it to the playing voice at once.
`AudioSource:SetPitch(pitch: number)`	Method	Sets the component's Pitch (playback speed: above 4 it is clamped to 4, below 0.01 to 0.01; 0, a negative or non-finite pitch raises an error) and applies it to the playing voice at once.

AudioSource.Clip#

lua

AudioSource.Clip: integer?

The audio clip to play. Changing it while the source plays stops the source at the next frame; Play starts the new clip. Asset handle of a AudioClip (nil when none); writes also accept a virtual path such as "Assets/...".

AudioSource.Volume#

lua

AudioSource.Volume: number

Linear volume (1 = unchanged). Range [0, 4]: writes outside it are clamped with a warning.

AudioSource.Pitch#

lua

AudioSource.Pitch: number

Playback speed and pitch multiplier (1 = unchanged). Range [0.01, 4]: writes outside it are clamped with a warning.

AudioSource.Loop#

lua

AudioSource.Loop: boolean

Restarts the clip when it ends.

AudioSource.PlayOnAwake#

lua

AudioSource.PlayOnAwake: boolean

Starts playing when the scene starts running or the component is created at runtime.

AudioSource.Spatial#

lua

AudioSource.Spatial: boolean

Attenuates and pans the sound by its position relative to the AudioListener.

AudioSource.MinDistance#

lua

AudioSource.MinDistance: number

Distance (world units) within which a spatial sound plays at full volume. Range [0, inf]: writes outside it are clamped with a warning.

AudioSource.MaxDistance#

lua

AudioSource.MaxDistance: number

Distance (world units) beyond which a spatial sound is no longer attenuated further. Range [0, inf]: writes outside it are clamped with a warning.

AudioSource.MixerGroup#

lua

AudioSource.MixerGroup: string

Name of the project mixer group the sound plays through (e.g. Master, Music, SFX, UI).

AudioSource:Play#

lua

AudioSource:Play(fadeInSeconds?: number): boolean

Starts the source's Clip from the beginning with its settings (restarting it when it plays or is paused), its volume rising from silence over fadeInSeconds (default 0: at once). When all 64 voices play, the oldest sound that does not loop is stopped to make room. Returns false when it has no clip, the clip fails to load (logged once) or all 64 voices play looping sounds.

Parameters

fadeInSeconds? (number)

Returns boolean

Example

lua

self.Entity:GetComponent("AudioSource"):Play()
music:Play(2) -- fades in over two seconds

AudioSource:Seek#

lua

AudioSource:Seek(seconds: number): boolean

Moves the playback position of the source's voice to seconds into the clip (wrapped for looping sources, clamped to the end otherwise: a non-looping voice sought to its end finishes). Works while paused. Returns false when the source has no voice; negative or non-finite positions raise an error.

Parameters

seconds (number)

Returns boolean

Example

lua

music:Seek(30.5)

AudioSource:GetPlaybackPosition#

lua

AudioSource:GetPlaybackPosition(): number?

Seconds into the clip of the source's voice (playing or paused), or nil when it has none.

Returns number?

AudioSource:GetLength#

lua

AudioSource:GetLength(): number?

The length in seconds of the clip the source plays, or of its Clip when that clip is loaded (it loads when the source starts, or with the scene for PlayOnAwake and listed clips); nil when unknown.

Returns number?

AudioSource:FadeTo#

lua

AudioSource:FadeTo(volume: number, seconds: number): boolean

Changes the component's Volume linearly to volume (above 4 it is clamped to 4; a negative volume raises an error) over seconds of real time (also while Time.TimeScale is 0; 0 seconds: at once), whether or not the source plays. A new fade replaces a running one and SetVolume cancels it; fades pause with the scene. Combine with Stop(fadeOutSeconds) to fade out and stop.

Parameters

volume (number)
seconds (number)

Returns boolean

Example

lua

music:FadeTo(0.2, 1.5) -- duck the music while a dialog shows

AudioSource:IsFading#

lua

AudioSource:IsFading(): boolean

True while a FadeTo of the source runs; the fades of Play(fadeInSeconds) and Stop(fadeOutSeconds) do not count.

Returns boolean

AudioSource:GetEffectiveVolume#

lua

AudioSource:GetEffectiveVolume(): number?

The gain the source's voice plays at: its Volume x the volumes of its mixer group and the groups that group routes into (0 while one is muted) x, for a Spatial source, the distance falloff between it and the active AudioListener (the listener and the source's position as of the last frame). The fades of Play(fadeInSeconds) and Stop(fadeOutSeconds) are not included (a FadeTo is: it changes Volume). nil when the source has no voice.

Returns number?

Example

lua

if music:GetEffectiveVolume() < 0.1 then music:Stop() end

AudioSource:Stop#

lua

AudioSource:Stop(fadeOutSeconds?: number): boolean

Stops the source's voice, optionally fading it out. Returns false when it was not playing.

Parameters

fadeOutSeconds? (number)

Returns boolean

AudioSource:Pause#

lua

AudioSource:Pause(): boolean

Pauses the voice at its position (it stays paused when the scene unpauses). Returns false when it has no voice.

Returns boolean

AudioSource:Resume#

lua

AudioSource:Resume(): boolean

Resumes a voice paused with Pause. Returns false when it has no voice.

Returns boolean

AudioSource:IsPlaying#

lua

AudioSource:IsPlaying(): boolean

True while the source has a voice that is not paused by Pause (a voice paused only by the scene pause counts as playing).

Returns boolean

AudioSource:IsPaused#

lua

AudioSource:IsPaused(): boolean

True while the source's voice is paused by Pause.

Returns boolean

AudioSource:SetVolume#

lua

AudioSource:SetVolume(volume: number)

Sets the component's Volume (above 4 it is clamped to 4; a negative or non-finite volume raises an error) and applies it to the playing voice at once.

Parameters

volume (number)

AudioSource:SetPitch#

lua

AudioSource:SetPitch(pitch: number)

Sets the component's Pitch (playback speed: above 4 it is clamped to 4, below 0.01 to 0.01; 0, a negative or non-finite pitch raises an error) and applies it to the playing voice at once.

Parameters

pitch (number)

BehaviorTree#

The behaviour tree an NPC runs (a .fbtree asset): the AI scheduler decides when it thinks - give the entity an AIAgent whose Handler is "BehaviorTree". Servers, hosts and offline games run it; Blackboard holds initial values over the tree's defaults, "Key=value" each.

lua

local component = self.Entity:GetComponent("BehaviorTree")

Member	Kind	Summary
`BehaviorTree.Tree: integer?`	Property	The behaviour tree (.fbtree).
`BehaviorTree.Enabled: boolean`	Property	Whether the NPC thinks.

BehaviorTree.Tree#

lua

BehaviorTree.Tree: integer?

The behaviour tree (.fbtree). Changing it restarts the NPC on the new tree at its next think; an empty tree stops it. Asset handle of a BehaviorTree (nil when none); writes also accept a virtual path such as "Assets/...".

BehaviorTree.Enabled#

lua

BehaviorTree.Enabled: boolean

Whether the NPC thinks. A disabled NPC keeps its tree's state (running nodes, blackboard) and continues where it stopped once enabled.

BorderGhost#

A ghost: this zone's mirror of an entity a neighbouring zone owns across a seamless border. The neighbour streams its transform, replicated components and values; this zone's clients see it through interest management like any other entity. Ghosts are kinematic, never saved or scheduled by AI here, and read-only to scripts: Border.Send forwards an interaction to the authority (OnBorderEvent there). Runtime state, not saved.

lua

local component = self.Entity:GetComponent("BorderGhost")

Member	Kind	Summary
`BorderGhost.SourceZone: string (read-only)`	Property	The zone process that owns the entity (its key, e.g.

BorderGhost.SourceZone#

lua

BorderGhost.SourceZone: string (read-only)

The zone process that owns the entity (its key, e.g. "Lumbridge@1.1"). Read-only.

BoxCollider2D#

Rectangular collision shape. It belongs to the body of the nearest Rigidbody2D on the entity or an ancestor; without one the collider gets its own static body (like every collider).

lua

local component = self.Entity:GetComponent("BoxCollider2D")

Member	Kind	Summary
`BoxCollider2D.Offset: Vec2`	Property	Center of the box in the entity's local space (world units).
`BoxCollider2D.Size: Vec2`	Property	Full width and height of the box in world units (scaled by the transform).
`BoxCollider2D.Rotation: number`	Property	Rotation of the box relative to the entity, in radians.
`BoxCollider2D.Density: number`	Property	Mass per unit area (kg/m^2) used to compute the body's mass.
`BoxCollider2D.Friction: number`	Property	Coulomb friction coefficient (usually 0-1).
`BoxCollider2D.Restitution: number`	Property	Bounciness (0 = no bounce, 1 = perfectly elastic).
`BoxCollider2D.IsSensor: boolean`	Property	Sensors detect overlaps (OnTriggerEnter/Exit) but do not collide.
`BoxCollider2D.Layer: integer`	Property	Physics layer index (0-31, named in the project settings); the collision matrix decides which layers collide.

BoxCollider2D.Offset#

lua

BoxCollider2D.Offset: Vec2

Center of the box in the entity's local space (world units).

BoxCollider2D.Size#

lua

BoxCollider2D.Size: Vec2

Full width and height of the box in world units (scaled by the transform). Range [0, inf]: writes outside it are clamped with a warning.

BoxCollider2D.Rotation#

lua

BoxCollider2D.Rotation: number

Rotation of the box relative to the entity, in radians. Radians.

BoxCollider2D.Density#

lua

BoxCollider2D.Density: number

Mass per unit area (kg/m^2) used to compute the body's mass. 0 makes the shape massless. Range [0, inf]: writes outside it are clamped with a warning.

BoxCollider2D.Friction#

lua

BoxCollider2D.Friction: number

Coulomb friction coefficient (usually 0-1). Combined with the other shape's friction by the geometric mean. Range [0, inf]: writes outside it are clamped with a warning.

BoxCollider2D.Restitution#

lua

BoxCollider2D.Restitution: number

Bounciness (0 = no bounce, 1 = perfectly elastic). Combined with the other shape by the maximum. Range [0, 1]: writes outside it are clamped with a warning.

BoxCollider2D.IsSensor#

lua

BoxCollider2D.IsSensor: boolean

Sensors detect overlaps (OnTriggerEnter/Exit) but do not collide.

BoxCollider2D.Layer#

lua

BoxCollider2D.Layer: integer

Physics layer index (0-31, named in the project settings); the collision matrix decides which layers collide. Range [0, 31]: writes outside it are clamped with a warning.

Camera#

Orthographic 2D camera: renders the scene (or the layers in its culling mask) to the screen or a render texture.

lua

local component = self.Entity:GetComponent("Camera")

Member	Kind	Summary
`Camera.Primary: boolean`	Property	Candidate for the main game view; the Primary camera with the highest Priority wins.
`Camera.OrthographicSize: number`	Property	Half of the visible height in world units (the width follows the viewport aspect ratio).
`Camera.Near: number`	Property	Near plane of the view volume: an entity is visible when its z relative to the camera lies between -Far and -Near (the defaults -100 and 100 show z from -100 to 100).
`Camera.Far: number`	Property	Far plane of the view volume (see Near).
`Camera.Priority: integer`	Property	Views render in ascending priority (higher priorities draw on top) and the highest Primary camera is the main camera.
`Camera.ViewportRect: Vec4`	Property	Normalized viewport within the target: x, y (top-left origin), width, height.
`Camera.Target: integer?`	Property	Render texture to render into (minimaps, render-to-texture effects); none renders to the screen.
`Camera.ClearColor: Color`	Property	Background color used when ClearFlags is Color.
`Camera.ClearFlags: "Color"\|"DepthOnly"\|"None"`	Property	What the view clears before rendering: color and depth, depth only (stack over previous views) or nothing.
`Camera.CullingMask: integer`	Property	Render layers this camera draws.
`Camera.PixelPerfect: boolean`	Property	Pixel-art mode: one texel covers a whole number of screen pixels and the camera position snaps to the pixel grid.
`Camera.ReferenceResolution: Vec2`	Property	Design resolution in pixels for pixel-perfect rendering (scaled by the largest integer zoom that fits the viewport).
`Camera.PixelsPerUnit: number`	Property	Texture pixels per world unit assumed by pixel-perfect mode (sprites default to 100).
`Camera.InternalResolutionScale: number`	Property	Render resolution relative to the viewport (0.5 renders at half resolution and upscales).
`Camera.DynamicResolution: boolean`	Property	Lets the renderer lower the internal resolution scale when the frame time exceeds the budget.
`Camera.BloomEnabled: boolean`	Property	Enables the bloom post-process (glow around bright pixels).
`Camera.BloomThreshold: number`	Property	Brightness above which pixels contribute to bloom.
`Camera.BloomIntensity: number`	Property	Strength of the bloom added to the image.
`Camera.BloomRadius: number`	Property	Spread of the bloom (relative upsampling filter radius).
`Camera.BloomKnee: number`	Property	Soft threshold: the fraction of BloomThreshold below it over which bloom fades in (0 = a hard cut).
`Camera.BloomMipCount: integer`	Property	Number of half-resolution blur steps of the bloom (more = wider glow).
`Camera.Exposure: number`	Property	Color grading exposure in EV stops (0 = unchanged).
`Camera.Contrast: number`	Property	Color grading contrast adjustment (-1..1, 0 = unchanged).
`Camera.Saturation: number`	Property	Color grading saturation adjustment (-1 = grayscale, 0 = unchanged, 1 = doubled).
`Camera.Temperature: number`	Property	White balance temperature shift (-1 = cooler/blue, 1 = warmer/orange).
`Camera.Tint: number`	Property	White balance tint shift (-1 = green, 1 = magenta).
`Camera.Lift: Vec3`	Property	Color grading lift: offset added to every channel, mostly visible in the shadows (0 = unchanged).
`Camera.Gamma: Vec3`	Property	Color grading gamma per channel: midtones are raised to the power 1 / Gamma (1 = unchanged).
`Camera.Gain: Vec3`	Property	Color grading gain: multiplier per channel, mostly visible in the highlights (1 = unchanged).
`Camera.ColorLut: integer?`	Property	Color lookup table: a horizontal strip of N slices ((N * N) x N texels, N = 2..64) applied after tonemapping.
`Camera.ColorLutContribution: number`	Property	Blend between the image without (0) and with (1) the color lookup table.
`Camera.Tonemapping: "None"\|"ACES"\|"Reinhard"`	Property	Tonemapping operator applied to HDR colors before output.
`Camera.VignetteIntensity: number`	Property	Darkening of the screen corners (0 = off).
`Camera.VignetteSmoothness: number`	Property	Softness of the vignette's falloff.
`Camera.VignetteColor: Color`	Property	Multiplier of the screen corners: black darkens them, a color keeps only its own channels there (alpha is unused).
`Camera.PostProcessProfile: integer?`	Property	Post-process profile (.fpost) whose settings override this camera's, blended in by PostProcessProfileWeight.
`Camera.PostProcessProfileWeight: number`	Property	How strongly the post-process profile overrides the camera's settings (0 = not at all, 1 = fully).
`Camera.LightingEnabled: boolean`	Property	Enables 2D lighting for this view; without it every sprite renders unlit.
`Camera.AmbientColor: Color`	Property	Ambient light applied to lit sprites before 2D lights are added (when lighting is enabled).

Camera.Primary#

lua

Camera.Primary: boolean

Candidate for the main game view; the Primary camera with the highest Priority wins.

Camera.OrthographicSize#

lua

Camera.OrthographicSize: number

Half of the visible height in world units (the width follows the viewport aspect ratio). Ignored when PixelPerfect is on. Range [0, inf]: writes outside it are clamped with a warning.

Camera.Near#

lua

Camera.Near: number

Near plane of the view volume: an entity is visible when its z relative to the camera lies between -Far and -Near (the defaults -100 and 100 show z from -100 to 100). Sprite order comes from layer/order/z depth keys.

Camera.Far#

lua

Camera.Far: number

Far plane of the view volume (see Near).

Camera.Priority#

lua

Camera.Priority: integer

Views render in ascending priority (higher priorities draw on top) and the highest Primary camera is the main camera.

Camera.ViewportRect#

lua

Camera.ViewportRect: Vec4

Normalized viewport within the target: x, y (top-left origin), width, height. Range [0, 1]: writes outside it are clamped with a warning.

Camera.Target#

lua

Camera.Target: integer?

Render texture to render into (minimaps, render-to-texture effects); none renders to the screen. Asset handle of a RenderTexture (nil when none); writes also accept a virtual path such as "Assets/...".

Camera.ClearColor#

lua

Camera.ClearColor: Color

Background color used when ClearFlags is Color. Writes also accept a Vec4 or Vec3 (alpha 1).

Camera.ClearFlags#

lua

Camera.ClearFlags: "Color"|"DepthOnly"|"None"

What the view clears before rendering: color and depth, depth only (stack over previous views) or nothing. Written by name.

Camera.CullingMask#

lua

Camera.CullingMask: integer

Render layers this camera draws. Bit mask; writes also accept "A|B" strings and tables of entry names.

Camera.PixelPerfect#

lua

Camera.PixelPerfect: boolean

Pixel-art mode: one texel covers a whole number of screen pixels and the camera position snaps to the pixel grid.

Camera.ReferenceResolution#

lua

Camera.ReferenceResolution: Vec2

Design resolution in pixels for pixel-perfect rendering (scaled by the largest integer zoom that fits the viewport). Range [1, inf]: writes outside it are clamped with a warning.

Camera.PixelsPerUnit#

lua

Camera.PixelsPerUnit: number

Texture pixels per world unit assumed by pixel-perfect mode (sprites default to 100). Range [0, inf]: writes outside it are clamped with a warning.

Camera.InternalResolutionScale#

lua

Camera.InternalResolutionScale: number

Render resolution relative to the viewport (0.5 renders at half resolution and upscales). Range [0.1, 2]: writes outside it are clamped with a warning.

Camera.DynamicResolution#

lua

Camera.DynamicResolution: boolean

Lets the renderer lower the internal resolution scale when the frame time exceeds the budget.

Camera.BloomEnabled#

lua

Camera.BloomEnabled: boolean

Enables the bloom post-process (glow around bright pixels).

Camera.BloomThreshold#

lua

Camera.BloomThreshold: number

Brightness above which pixels contribute to bloom. Range [0, inf]: writes outside it are clamped with a warning.

Camera.BloomIntensity#

lua

Camera.BloomIntensity: number

Strength of the bloom added to the image. Range [0, inf]: writes outside it are clamped with a warning.

Camera.BloomRadius#

lua

Camera.BloomRadius: number

Spread of the bloom (relative upsampling filter radius). Range [0, 4]: writes outside it are clamped with a warning.

Camera.BloomKnee#

lua

Camera.BloomKnee: number

Soft threshold: the fraction of BloomThreshold below it over which bloom fades in (0 = a hard cut). Range [0, 1]: writes outside it are clamped with a warning.

Camera.BloomMipCount#

lua

Camera.BloomMipCount: integer

Number of half-resolution blur steps of the bloom (more = wider glow). Range [1, 8]: writes outside it are clamped with a warning.

Camera.Exposure#

lua

Camera.Exposure: number

Color grading exposure in EV stops (0 = unchanged).

Camera.Contrast#

lua

Camera.Contrast: number

Color grading contrast adjustment (-1..1, 0 = unchanged). Range [-1, 1]: writes outside it are clamped with a warning.

Camera.Saturation#

lua

Camera.Saturation: number

Color grading saturation adjustment (-1 = grayscale, 0 = unchanged, 1 = doubled). Range [-1, 1]: writes outside it are clamped with a warning.

Camera.Temperature#

lua

Camera.Temperature: number

White balance temperature shift (-1 = cooler/blue, 1 = warmer/orange). Range [-1, 1]: writes outside it are clamped with a warning.

Camera.Tint#

lua

Camera.Tint: number

White balance tint shift (-1 = green, 1 = magenta). Range [-1, 1]: writes outside it are clamped with a warning.

Camera.Lift#

lua

Camera.Lift: Vec3

Color grading lift: offset added to every channel, mostly visible in the shadows (0 = unchanged). Range [-1, 1]: writes outside it are clamped with a warning.

Camera.Gamma#

lua

Camera.Gamma: Vec3

Color grading gamma per channel: midtones are raised to the power 1 / Gamma (1 = unchanged). Range [0.01, 10]: writes outside it are clamped with a warning.

Camera.Gain#

lua

Camera.Gain: Vec3

Color grading gain: multiplier per channel, mostly visible in the highlights (1 = unchanged). Range [0, 10]: writes outside it are clamped with a warning.

Camera.ColorLut#

lua

Camera.ColorLut: integer?

Color lookup table: a horizontal strip of N slices ((N * N) x N texels, N = 2..64) applied after tonemapping. Asset handle of a Texture2D (nil when none); writes also accept a virtual path such as "Assets/...".

Camera.ColorLutContribution#

lua

Camera.ColorLutContribution: number

Blend between the image without (0) and with (1) the color lookup table. Range [0, 1]: writes outside it are clamped with a warning.

Camera.Tonemapping#

lua

Camera.Tonemapping: "None"|"ACES"|"Reinhard"

Tonemapping operator applied to HDR colors before output. Written by name.

Camera.VignetteIntensity#

lua

Camera.VignetteIntensity: number

Darkening of the screen corners (0 = off). Range [0, 1]: writes outside it are clamped with a warning.

Camera.VignetteSmoothness#

lua

Camera.VignetteSmoothness: number

Softness of the vignette's falloff. Range [0, 1]: writes outside it are clamped with a warning.

Camera.VignetteColor#

lua

Camera.VignetteColor: Color

Multiplier of the screen corners: black darkens them, a color keeps only its own channels there (alpha is unused). Writes also accept a Vec4 or Vec3 (alpha 1).

Camera.PostProcessProfile#

lua

Camera.PostProcessProfile: integer?

Post-process profile (.fpost) whose settings override this camera's, blended in by PostProcessProfileWeight. Asset handle of a PostProcessProfile (nil when none); writes also accept a virtual path such as "Assets/...".

Camera.PostProcessProfileWeight#

lua

Camera.PostProcessProfileWeight: number

How strongly the post-process profile overrides the camera's settings (0 = not at all, 1 = fully). Range [0, 1]: writes outside it are clamped with a warning.

Camera.LightingEnabled#

lua

Camera.LightingEnabled: boolean

Enables 2D lighting for this view; without it every sprite renders unlit.

Camera.AmbientColor#

lua

Camera.AmbientColor: Color

Ambient light applied to lit sprites before 2D lights are added (when lighting is enabled). Writes also accept a Vec4 or Vec3 (alpha 1).

CapsuleCollider2D#

Capsule collision shape: a segment between two centers inflated by a radius (characters).

lua

local component = self.Entity:GetComponent("CapsuleCollider2D")

Member	Kind	Summary
`CapsuleCollider2D.Center1: Vec2`	Property	First segment end point in the entity's local space.
`CapsuleCollider2D.Center2: Vec2`	Property	Second segment end point in the entity's local space.
`CapsuleCollider2D.Radius: number`	Property	Radius around the segment in world units (scaled by the larger transform scale).
`CapsuleCollider2D.Density: number`	Property	Mass per unit area (kg/m^2) used to compute the body's mass.
`CapsuleCollider2D.Friction: number`	Property	Coulomb friction coefficient (usually 0-1).
`CapsuleCollider2D.Restitution: number`	Property	Bounciness (0 = no bounce, 1 = perfectly elastic).
`CapsuleCollider2D.IsSensor: boolean`	Property	Sensors detect overlaps (OnTriggerEnter/Exit) but do not collide.
`CapsuleCollider2D.Layer: integer`	Property	Physics layer index (0-31, named in the project settings); the collision matrix decides which layers collide.

CapsuleCollider2D.Center1#

lua

CapsuleCollider2D.Center1: Vec2

First segment end point in the entity's local space.

CapsuleCollider2D.Center2#

lua

CapsuleCollider2D.Center2: Vec2

Second segment end point in the entity's local space.

CapsuleCollider2D.Radius#

lua

CapsuleCollider2D.Radius: number

Radius around the segment in world units (scaled by the larger transform scale). Range [0, inf]: writes outside it are clamped with a warning.

CapsuleCollider2D.Density#

lua

CapsuleCollider2D.Density: number

Mass per unit area (kg/m^2) used to compute the body's mass. 0 makes the shape massless. Range [0, inf]: writes outside it are clamped with a warning.

CapsuleCollider2D.Friction#

lua

CapsuleCollider2D.Friction: number

Coulomb friction coefficient (usually 0-1). Combined with the other shape's friction by the geometric mean. Range [0, inf]: writes outside it are clamped with a warning.

CapsuleCollider2D.Restitution#

lua

CapsuleCollider2D.Restitution: number

Bounciness (0 = no bounce, 1 = perfectly elastic). Combined with the other shape by the maximum. Range [0, 1]: writes outside it are clamped with a warning.

CapsuleCollider2D.IsSensor#

lua

CapsuleCollider2D.IsSensor: boolean

Sensors detect overlaps (OnTriggerEnter/Exit) but do not collide.

CapsuleCollider2D.Layer#

lua

CapsuleCollider2D.Layer: integer

Physics layer index (0-31, named in the project settings); the collision matrix decides which layers collide. Range [0, 31]: writes outside it are clamped with a warning.

CharacterAppearance#

A character drawn as one entity from up to eight layered sprite sheets that share the animator's frame (body, clothes, equipment, hair). The SpriteRenderer gives the render layer, order, color, flip and material; the crowd extraction draws the layers in their Order instead of the SpriteRenderer's own sheet, without an entity per layer. Equipment sets layers from the equipped items' visuals.

lua

local component = self.Entity:GetComponent("CharacterAppearance")

Member	Kind	Summary
`CharacterAppearance.Layer0: integer?`	Property	Bottom layer (the body): a sprite sheet with the frame layout of the character's animator; it shows the animator's frame.
`CharacterAppearance.Tint0: integer`	Property	Tint of the layer as packed sRGB RGBA (0xRRGGBBAA: 4294967295 = white, no tint), multiplied with the SpriteRenderer's Color.
`CharacterAppearance.Order0: integer`	Property	Draw order of the layer inside the character: lower orders draw first (behind), ties by layer index; a cloak can move from behind the body to in front of it without changing sheets.
`CharacterAppearance.Layer1: integer?`	Property	A layer drawn with the same frame as the others (clothes, equipment, hair): a sprite sheet with the frame layout of Layer0 (validated, X003).
`CharacterAppearance.Tint1: integer`	Property	Tint of the layer as packed sRGB RGBA (0xRRGGBBAA: 4294967295 = white, no tint), multiplied with the SpriteRenderer's Color.
`CharacterAppearance.Order1: integer`	Property	Draw order of the layer inside the character: lower orders draw first (behind), ties by layer index; a cloak can move from behind the body to in front of it without changing sheets.
`CharacterAppearance.Layer2: integer?`	Property	A layer drawn with the same frame as the others (clothes, equipment, hair): a sprite sheet with the frame layout of Layer0 (validated, X003).
`CharacterAppearance.Tint2: integer`	Property	Tint of the layer as packed sRGB RGBA (0xRRGGBBAA: 4294967295 = white, no tint), multiplied with the SpriteRenderer's Color.
`CharacterAppearance.Order2: integer`	Property	Draw order of the layer inside the character: lower orders draw first (behind), ties by layer index; a cloak can move from behind the body to in front of it without changing sheets.
`CharacterAppearance.Layer3: integer?`	Property	A layer drawn with the same frame as the others (clothes, equipment, hair): a sprite sheet with the frame layout of Layer0 (validated, X003).
`CharacterAppearance.Tint3: integer`	Property	Tint of the layer as packed sRGB RGBA (0xRRGGBBAA: 4294967295 = white, no tint), multiplied with the SpriteRenderer's Color.
`CharacterAppearance.Order3: integer`	Property	Draw order of the layer inside the character: lower orders draw first (behind), ties by layer index; a cloak can move from behind the body to in front of it without changing sheets.
`CharacterAppearance.Layer4: integer?`	Property	A layer drawn with the same frame as the others (clothes, equipment, hair): a sprite sheet with the frame layout of Layer0 (validated, X003).
`CharacterAppearance.Tint4: integer`	Property	Tint of the layer as packed sRGB RGBA (0xRRGGBBAA: 4294967295 = white, no tint), multiplied with the SpriteRenderer's Color.
`CharacterAppearance.Order4: integer`	Property	Draw order of the layer inside the character: lower orders draw first (behind), ties by layer index; a cloak can move from behind the body to in front of it without changing sheets.
`CharacterAppearance.Layer5: integer?`	Property	A layer drawn with the same frame as the others (clothes, equipment, hair): a sprite sheet with the frame layout of Layer0 (validated, X003).
`CharacterAppearance.Tint5: integer`	Property	Tint of the layer as packed sRGB RGBA (0xRRGGBBAA: 4294967295 = white, no tint), multiplied with the SpriteRenderer's Color.
`CharacterAppearance.Order5: integer`	Property	Draw order of the layer inside the character: lower orders draw first (behind), ties by layer index; a cloak can move from behind the body to in front of it without changing sheets.
`CharacterAppearance.Layer6: integer?`	Property	A layer drawn with the same frame as the others (clothes, equipment, hair): a sprite sheet with the frame layout of Layer0 (validated, X003).
`CharacterAppearance.Tint6: integer`	Property	Tint of the layer as packed sRGB RGBA (0xRRGGBBAA: 4294967295 = white, no tint), multiplied with the SpriteRenderer's Color.
`CharacterAppearance.Order6: integer`	Property	Draw order of the layer inside the character: lower orders draw first (behind), ties by layer index; a cloak can move from behind the body to in front of it without changing sheets.
`CharacterAppearance.Layer7: integer?`	Property	A layer drawn with the same frame as the others (clothes, equipment, hair): a sprite sheet with the frame layout of Layer0 (validated, X003).
`CharacterAppearance.Tint7: integer`	Property	Tint of the layer as packed sRGB RGBA (0xRRGGBBAA: 4294967295 = white, no tint), multiplied with the SpriteRenderer's Color.
`CharacterAppearance.Order7: integer`	Property	Draw order of the layer inside the character: lower orders draw first (behind), ties by layer index; a cloak can move from behind the body to in front of it without changing sheets.
`CharacterAppearance.HiddenLayers: integer`	Property	Layers that are not drawn although they have a sheet (a helmet hiding the hair).

CharacterAppearance.Layer0#

lua

CharacterAppearance.Layer0: integer?

Bottom layer (the body): a sprite sheet with the frame layout of the character's animator; it shows the animator's frame. None draws nothing. Asset handle of a SpriteSheet (nil when none); writes also accept a virtual path such as "Assets/...". Replicated: on networked entities the authority's value reaches every peer.

CharacterAppearance.Tint0#

lua

CharacterAppearance.Tint0: integer

Tint of the layer as packed sRGB RGBA (0xRRGGBBAA: 4294967295 = white, no tint), multiplied with the SpriteRenderer's Color. Range [0, 4294967295]: writes outside it are clamped with a warning. Replicated: on networked entities the authority's value reaches every peer.

CharacterAppearance.Order0#

lua

CharacterAppearance.Order0: integer

Draw order of the layer inside the character: lower orders draw first (behind), ties by layer index; a cloak can move from behind the body to in front of it without changing sheets. Range [-64, 64]: writes outside it are clamped with a warning. Replicated: on networked entities the authority's value reaches every peer.

CharacterAppearance.Layer1#

lua

CharacterAppearance.Layer1: integer?

A layer drawn with the same frame as the others (clothes, equipment, hair): a sprite sheet with the frame layout of Layer0 (validated, X003). None draws nothing. Asset handle of a SpriteSheet (nil when none); writes also accept a virtual path such as "Assets/...". Replicated: on networked entities the authority's value reaches every peer.

CharacterAppearance.Tint1#

lua

CharacterAppearance.Tint1: integer

Tint of the layer as packed sRGB RGBA (0xRRGGBBAA: 4294967295 = white, no tint), multiplied with the SpriteRenderer's Color. Range [0, 4294967295]: writes outside it are clamped with a warning. Replicated: on networked entities the authority's value reaches every peer.

CharacterAppearance.Order1#

lua

CharacterAppearance.Order1: integer

Draw order of the layer inside the character: lower orders draw first (behind), ties by layer index; a cloak can move from behind the body to in front of it without changing sheets. Range [-64, 64]: writes outside it are clamped with a warning. Replicated: on networked entities the authority's value reaches every peer.

CharacterAppearance.Layer2#

lua

CharacterAppearance.Layer2: integer?

A layer drawn with the same frame as the others (clothes, equipment, hair): a sprite sheet with the frame layout of Layer0 (validated, X003). None draws nothing. Asset handle of a SpriteSheet (nil when none); writes also accept a virtual path such as "Assets/...". Replicated: on networked entities the authority's value reaches every peer.

CharacterAppearance.Tint2#

lua

CharacterAppearance.Tint2: integer

Tint of the layer as packed sRGB RGBA (0xRRGGBBAA: 4294967295 = white, no tint), multiplied with the SpriteRenderer's Color. Range [0, 4294967295]: writes outside it are clamped with a warning. Replicated: on networked entities the authority's value reaches every peer.

CharacterAppearance.Order2#

lua

CharacterAppearance.Order2: integer

Draw order of the layer inside the character: lower orders draw first (behind), ties by layer index; a cloak can move from behind the body to in front of it without changing sheets. Range [-64, 64]: writes outside it are clamped with a warning. Replicated: on networked entities the authority's value reaches every peer.

CharacterAppearance.Layer3#

lua

CharacterAppearance.Layer3: integer?

A layer drawn with the same frame as the others (clothes, equipment, hair): a sprite sheet with the frame layout of Layer0 (validated, X003). None draws nothing. Asset handle of a SpriteSheet (nil when none); writes also accept a virtual path such as "Assets/...". Replicated: on networked entities the authority's value reaches every peer.

CharacterAppearance.Tint3#

lua

CharacterAppearance.Tint3: integer

Tint of the layer as packed sRGB RGBA (0xRRGGBBAA: 4294967295 = white, no tint), multiplied with the SpriteRenderer's Color. Range [0, 4294967295]: writes outside it are clamped with a warning. Replicated: on networked entities the authority's value reaches every peer.

CharacterAppearance.Order3#

lua

CharacterAppearance.Order3: integer

Draw order of the layer inside the character: lower orders draw first (behind), ties by layer index; a cloak can move from behind the body to in front of it without changing sheets. Range [-64, 64]: writes outside it are clamped with a warning. Replicated: on networked entities the authority's value reaches every peer.

CharacterAppearance.Layer4#

lua

CharacterAppearance.Layer4: integer?

A layer drawn with the same frame as the others (clothes, equipment, hair): a sprite sheet with the frame layout of Layer0 (validated, X003). None draws nothing. Asset handle of a SpriteSheet (nil when none); writes also accept a virtual path such as "Assets/...". Replicated: on networked entities the authority's value reaches every peer.

CharacterAppearance.Tint4#

lua

CharacterAppearance.Tint4: integer

Tint of the layer as packed sRGB RGBA (0xRRGGBBAA: 4294967295 = white, no tint), multiplied with the SpriteRenderer's Color. Range [0, 4294967295]: writes outside it are clamped with a warning. Replicated: on networked entities the authority's value reaches every peer.

CharacterAppearance.Order4#

lua

CharacterAppearance.Order4: integer

Draw order of the layer inside the character: lower orders draw first (behind), ties by layer index; a cloak can move from behind the body to in front of it without changing sheets. Range [-64, 64]: writes outside it are clamped with a warning. Replicated: on networked entities the authority's value reaches every peer.

CharacterAppearance.Layer5#

lua

CharacterAppearance.Layer5: integer?

A layer drawn with the same frame as the others (clothes, equipment, hair): a sprite sheet with the frame layout of Layer0 (validated, X003). None draws nothing. Asset handle of a SpriteSheet (nil when none); writes also accept a virtual path such as "Assets/...". Replicated: on networked entities the authority's value reaches every peer.

CharacterAppearance.Tint5#

lua

CharacterAppearance.Tint5: integer

Tint of the layer as packed sRGB RGBA (0xRRGGBBAA: 4294967295 = white, no tint), multiplied with the SpriteRenderer's Color. Range [0, 4294967295]: writes outside it are clamped with a warning. Replicated: on networked entities the authority's value reaches every peer.

CharacterAppearance.Order5#

lua

CharacterAppearance.Order5: integer

Draw order of the layer inside the character: lower orders draw first (behind), ties by layer index; a cloak can move from behind the body to in front of it without changing sheets. Range [-64, 64]: writes outside it are clamped with a warning. Replicated: on networked entities the authority's value reaches every peer.

CharacterAppearance.Layer6#

lua

CharacterAppearance.Layer6: integer?

A layer drawn with the same frame as the others (clothes, equipment, hair): a sprite sheet with the frame layout of Layer0 (validated, X003). None draws nothing. Asset handle of a SpriteSheet (nil when none); writes also accept a virtual path such as "Assets/...". Replicated: on networked entities the authority's value reaches every peer.

CharacterAppearance.Tint6#

lua

CharacterAppearance.Tint6: integer

Tint of the layer as packed sRGB RGBA (0xRRGGBBAA: 4294967295 = white, no tint), multiplied with the SpriteRenderer's Color. Range [0, 4294967295]: writes outside it are clamped with a warning. Replicated: on networked entities the authority's value reaches every peer.

CharacterAppearance.Order6#

lua

CharacterAppearance.Order6: integer

Draw order of the layer inside the character: lower orders draw first (behind), ties by layer index; a cloak can move from behind the body to in front of it without changing sheets. Range [-64, 64]: writes outside it are clamped with a warning. Replicated: on networked entities the authority's value reaches every peer.

CharacterAppearance.Layer7#

lua

CharacterAppearance.Layer7: integer?

A layer drawn with the same frame as the others (clothes, equipment, hair): a sprite sheet with the frame layout of Layer0 (validated, X003). None draws nothing. Asset handle of a SpriteSheet (nil when none); writes also accept a virtual path such as "Assets/...". Replicated: on networked entities the authority's value reaches every peer.

CharacterAppearance.Tint7#

lua

CharacterAppearance.Tint7: integer

Tint of the layer as packed sRGB RGBA (0xRRGGBBAA: 4294967295 = white, no tint), multiplied with the SpriteRenderer's Color. Range [0, 4294967295]: writes outside it are clamped with a warning. Replicated: on networked entities the authority's value reaches every peer.

CharacterAppearance.Order7#

lua

CharacterAppearance.Order7: integer

Draw order of the layer inside the character: lower orders draw first (behind), ties by layer index; a cloak can move from behind the body to in front of it without changing sheets. Range [-64, 64]: writes outside it are clamped with a warning. Replicated: on networked entities the authority's value reaches every peer.

CharacterAppearance.HiddenLayers#

lua

CharacterAppearance.HiddenLayers: integer

Layers that are not drawn although they have a sheet (a helmet hiding the hair). Bit mask; writes also accept "A|B" strings and tables of entry names. Replicated: on networked entities the authority's value reaches every peer.

CharacterMovement#

Moves a character with a native, deterministic movement model: Kinematic (continuous: acceleration toward the input, collision by sweeping a circle) or Grid (tile steps on game ticks, RuneScape-style). The same model runs on the server, in the owner's prediction and in bots. Who drives it follows Authority; Lua: the Movement namespace and OnMovementStep.

lua

local component = self.Entity:GetComponent("CharacterMovement")

Member	Kind	Summary
`CharacterMovement.Model: "Kinematic"\|"Grid"`	Property	Kinematic: free movement with acceleration and collision every fixed step.
`CharacterMovement.Authority: "ServerPredicted"\|"Owner"\|"Server"`	Property	ServerPredicted: the owning player's input commands drive it on the server, and its client predicts and corrects it (offline: the local player).
`CharacterMovement.MaxSpeed: number`	Property	Kinematic: top speed in world units per second.
`CharacterMovement.RunMultiplier: number`	Property	Kinematic: the top speed is multiplied by this while the command's "Run" button is down.
`CharacterMovement.Acceleration: number`	Property	Kinematic: how fast the velocity turns toward the input, world units per second squared.
`CharacterMovement.Deceleration: number`	Property	Kinematic: how fast the velocity falls to zero without input, world units per second squared.
`CharacterMovement.Radius: number`	Property	Kinematic: radius of the collision circle swept against static colliders, world units.
`CharacterMovement.Collision: "Physics"\|"Tiles"\|"None"`	Property	What blocks it.
`CharacterMovement.CollisionLayers: integer`	Property	Physics layers of the static colliders (and tilemap colliders) it cannot pass.
`CharacterMovement.TileSize: number`	Property	Grid: size of a tile in world units; the mover stands on cell centers ((cell + 0.5) x TileSize).
`CharacterMovement.WalkTilesPerGameTick: integer`	Property	Grid: tiles walked per game tick.
`CharacterMovement.RunTilesPerGameTick: integer`	Property	Grid: tiles run per game tick (while running: Movement.SetInput with run, or the "Run" button).
`CharacterMovement.AllowDiagonal: boolean`	Property	Grid: diagonal steps while both axes differ (never cutting a blocked corner); otherwise straight steps only.
`CharacterMovement.ScriptExtension: boolean`	Property	After each native step, call the entity script's OnMovementStep(state, command, dt), which may change the state (slow on mud, dash).
`CharacterMovement.Velocity: Vec2`	Property	Runtime: the current velocity in world units per second (Grid: the movement over the current game tick).

CharacterMovement.Model#

lua

CharacterMovement.Model: "Kinematic"|"Grid"

Kinematic: free movement with acceleration and collision every fixed step. Grid: one tile step per game tick toward the target Movement.MoveTo sets (two while running), never predicted. Written by name.

CharacterMovement.Authority#

lua

CharacterMovement.Authority: "ServerPredicted"|"Owner"|"Server"

ServerPredicted: the owning player's input commands drive it on the server, and its client predicts and corrects it (offline: the local player). Owner: the owner moves it and the server validates. Server: only the server moves it (AI: Movement.SetInput, Movement.MoveTo); clients interpolate. Written by name.

CharacterMovement.MaxSpeed#

lua

CharacterMovement.MaxSpeed: number

Kinematic: top speed in world units per second. Range [0, 10000]: writes outside it are clamped with a warning.

CharacterMovement.RunMultiplier#

lua

CharacterMovement.RunMultiplier: number

Kinematic: the top speed is multiplied by this while the command's "Run" button is down. Range [0, 100]: writes outside it are clamped with a warning.

CharacterMovement.Acceleration#

lua

CharacterMovement.Acceleration: number

Kinematic: how fast the velocity turns toward the input, world units per second squared. Range [0, 1000000]: writes outside it are clamped with a warning.

CharacterMovement.Deceleration#

lua

CharacterMovement.Deceleration: number

Kinematic: how fast the velocity falls to zero without input, world units per second squared. Range [0, 1000000]: writes outside it are clamped with a warning.

CharacterMovement.Radius#

lua

CharacterMovement.Radius: number

Kinematic: radius of the collision circle swept against static colliders, world units. Range [0, 1000]: writes outside it are clamped with a warning.

CharacterMovement.Collision#

lua

CharacterMovement.Collision: "Physics"|"Tiles"|"None"

What blocks it. Physics: static colliders of the physics world on CollisionLayers (walls, TilemapCollider2D chunks; precise). Tiles: solid tiles of TilemapCollider2D tilemaps as whole cells, without physics (about 10x cheaper; unrotated tilemaps). None: nothing. Written by name.

CharacterMovement.CollisionLayers#

lua

CharacterMovement.CollisionLayers: integer

Physics layers of the static colliders (and tilemap colliders) it cannot pass. Bit mask; writes also accept "A|B" strings and tables of entry names.

CharacterMovement.TileSize#

lua

CharacterMovement.TileSize: number

Grid: size of a tile in world units; the mover stands on cell centers ((cell + 0.5) x TileSize). Range [0.001, 1000000]: writes outside it are clamped with a warning.

CharacterMovement.WalkTilesPerGameTick#

lua

CharacterMovement.WalkTilesPerGameTick: integer

Grid: tiles walked per game tick. Range [0, 64]: writes outside it are clamped with a warning.

CharacterMovement.RunTilesPerGameTick#

lua

CharacterMovement.RunTilesPerGameTick: integer

Grid: tiles run per game tick (while running: Movement.SetInput with run, or the "Run" button). Range [0, 64]: writes outside it are clamped with a warning.

CharacterMovement.AllowDiagonal#

lua

CharacterMovement.AllowDiagonal: boolean

Grid: diagonal steps while both axes differ (never cutting a blocked corner); otherwise straight steps only.

CharacterMovement.ScriptExtension#

lua

CharacterMovement.ScriptExtension: boolean

After each native step, call the entity script's OnMovementStep(state, command, dt), which may change the state (slow on mud, dash). It runs on the server and in the owner's prediction replays alike, so it must be deterministic.

CharacterMovement.Velocity#

lua

CharacterMovement.Velocity: Vec2

Runtime: the current velocity in world units per second (Grid: the movement over the current game tick). Replicated, so receivers extrapolate and the owner's prediction compares it. Replicated: on networked entities the authority's value reaches every peer.

CircleCollider2D#

Circular collision shape.

lua

local component = self.Entity:GetComponent("CircleCollider2D")

Member	Kind	Summary
`CircleCollider2D.Offset: Vec2`	Property	Center of the circle in the entity's local space (world units).
`CircleCollider2D.Radius: number`	Property	Radius in world units (scaled by the larger transform scale).
`CircleCollider2D.Density: number`	Property	Mass per unit area (kg/m^2) used to compute the body's mass.
`CircleCollider2D.Friction: number`	Property	Coulomb friction coefficient (usually 0-1).
`CircleCollider2D.Restitution: number`	Property	Bounciness (0 = no bounce, 1 = perfectly elastic).
`CircleCollider2D.IsSensor: boolean`	Property	Sensors detect overlaps (OnTriggerEnter/Exit) but do not collide.
`CircleCollider2D.Layer: integer`	Property	Physics layer index (0-31, named in the project settings); the collision matrix decides which layers collide.

CircleCollider2D.Offset#

lua

CircleCollider2D.Offset: Vec2

Center of the circle in the entity's local space (world units).

CircleCollider2D.Radius#

lua

CircleCollider2D.Radius: number

Radius in world units (scaled by the larger transform scale). Range [0, inf]: writes outside it are clamped with a warning.

CircleCollider2D.Density#

lua

CircleCollider2D.Density: number

Mass per unit area (kg/m^2) used to compute the body's mass. 0 makes the shape massless. Range [0, inf]: writes outside it are clamped with a warning.

CircleCollider2D.Friction#

lua

CircleCollider2D.Friction: number

Coulomb friction coefficient (usually 0-1). Combined with the other shape's friction by the geometric mean. Range [0, inf]: writes outside it are clamped with a warning.

CircleCollider2D.Restitution#

lua

CircleCollider2D.Restitution: number

Bounciness (0 = no bounce, 1 = perfectly elastic). Combined with the other shape by the maximum. Range [0, 1]: writes outside it are clamped with a warning.

CircleCollider2D.IsSensor#

lua

CircleCollider2D.IsSensor: boolean

Sensors detect overlaps (OnTriggerEnter/Exit) but do not collide.

CircleCollider2D.Layer#

lua

CircleCollider2D.Layer: integer

Physics layer index (0-31, named in the project settings); the collision matrix decides which layers collide. Range [0, 31]: writes outside it are clamped with a warning.

CircleRenderer#

Draws an anti-aliased circle or ring (signed distance field quad).

lua

local component = self.Entity:GetComponent("CircleRenderer")

Member	Kind	Summary
`CircleRenderer.Color: Color`	Property	Fill color (RGBA, straight alpha).
`CircleRenderer.Radius: number`	Property	Radius in world units (scaled by the transform).
`CircleRenderer.Thickness: number`	Property	Ring thickness as a fraction of the radius: 1 fills the circle, smaller values draw a ring.
`CircleRenderer.Fade: number`	Property	Edge softness as a fraction of the radius (anti-aliasing / glow).
`CircleRenderer.Layer: integer`	Property	Render layer index (0-31, named in the project settings).
`CircleRenderer.OrderInLayer: integer`	Property	Draw order inside the render layer (int16 range); higher values draw in front.

CircleRenderer.Color#

lua

CircleRenderer.Color: Color

Fill color (RGBA, straight alpha). Writes also accept a Vec4 or Vec3 (alpha 1).

CircleRenderer.Radius#

lua

CircleRenderer.Radius: number

Radius in world units (scaled by the transform). Range [0, inf]: writes outside it are clamped with a warning.

CircleRenderer.Thickness#

lua

CircleRenderer.Thickness: number

Ring thickness as a fraction of the radius: 1 fills the circle, smaller values draw a ring. Range [0, 1]: writes outside it are clamped with a warning.

CircleRenderer.Fade#

lua

CircleRenderer.Fade: number

Edge softness as a fraction of the radius (anti-aliasing / glow). Range [0, 1]: writes outside it are clamped with a warning.

CircleRenderer.Layer#

lua

CircleRenderer.Layer: integer

Render layer index (0-31, named in the project settings). Layers draw in ascending order; cameras cull by layer mask. Range [0, 31]: writes outside it are clamped with a warning.

CircleRenderer.OrderInLayer#

lua

CircleRenderer.OrderInLayer: integer

Draw order inside the render layer (int16 range); higher values draw in front. Ties are resolved by Translation.z. Range [-32768, 32767]: writes outside it are clamped with a warning.

DistanceJoint2D#

Keeps the anchors at a distance (rope, rod or spring between two bodies).

lua

local component = self.Entity:GetComponent("DistanceJoint2D")

Member	Kind	Summary
`DistanceJoint2D.ConnectedEntity: Entity?`	Property	The other body of the joint (an entity with a Rigidbody2D).
`DistanceJoint2D.Anchor: Vec2`	Property	Joint anchor in this entity's local space (world units).
`DistanceJoint2D.ConnectedAnchor: Vec2`	Property	Joint anchor in the connected entity's local space (world space when anchored to the world).
`DistanceJoint2D.CollideConnected: boolean`	Property	Whether the two connected bodies still collide with each other.
`DistanceJoint2D.AutoLength: boolean`	Property	Uses the anchors' distance when the joint is created as Length.
`DistanceJoint2D.Length: number`	Property	Rest length in world units (when AutoLength is off).
`DistanceJoint2D.EnableLimit: boolean`	Property	Restricts the distance to [MinLength, MaxLength] (rope behaviour with a spring).
`DistanceJoint2D.MinLength: number`	Property	Minimum distance in world units when the limit is enabled.
`DistanceJoint2D.MaxLength: number`	Property	Maximum distance in world units when the limit is enabled.
`DistanceJoint2D.EnableSpring: boolean`	Property	Makes the distance constraint soft: it behaves like a spring with the given frequency and damping.
`DistanceJoint2D.Hertz: number`	Property	Spring stiffness as an oscillation frequency in Hz (0 = rigid).
`DistanceJoint2D.DampingRatio: number`	Property	Spring damping ratio (0 = no damping, 1 = critical damping).
`DistanceJoint2D.EnableMotor: boolean`	Property	Drives the length towards MotorSpeed.
`DistanceJoint2D.MaxMotorForce: number`	Property	Maximum motor force in newtons.
`DistanceJoint2D.MotorSpeed: number`	Property	Target rate of length change in world units per second.

DistanceJoint2D.ConnectedEntity#

lua

DistanceJoint2D.ConnectedEntity: Entity?

The other body of the joint (an entity with a Rigidbody2D). None anchors the joint to the world. Writes accept an Entity, an entity ID or nil.

DistanceJoint2D.Anchor#

lua

DistanceJoint2D.Anchor: Vec2

Joint anchor in this entity's local space (world units).

DistanceJoint2D.ConnectedAnchor#

lua

DistanceJoint2D.ConnectedAnchor: Vec2

Joint anchor in the connected entity's local space (world space when anchored to the world).

DistanceJoint2D.CollideConnected#

lua

DistanceJoint2D.CollideConnected: boolean

Whether the two connected bodies still collide with each other.

DistanceJoint2D.AutoLength#

lua

DistanceJoint2D.AutoLength: boolean

Uses the anchors' distance when the joint is created as Length.

DistanceJoint2D.Length#

lua

DistanceJoint2D.Length: number

Rest length in world units (when AutoLength is off). Range [0, inf]: writes outside it are clamped with a warning.

DistanceJoint2D.EnableLimit#

lua

DistanceJoint2D.EnableLimit: boolean

Restricts the distance to [MinLength, MaxLength] (rope behaviour with a spring).

DistanceJoint2D.MinLength#

lua

DistanceJoint2D.MinLength: number

Minimum distance in world units when the limit is enabled. Range [0, inf]: writes outside it are clamped with a warning.

DistanceJoint2D.MaxLength#

lua

DistanceJoint2D.MaxLength: number

Maximum distance in world units when the limit is enabled. Range [0, inf]: writes outside it are clamped with a warning.

DistanceJoint2D.EnableSpring#

lua

DistanceJoint2D.EnableSpring: boolean

Makes the distance constraint soft: it behaves like a spring with the given frequency and damping.

DistanceJoint2D.Hertz#

lua

DistanceJoint2D.Hertz: number

Spring stiffness as an oscillation frequency in Hz (0 = rigid). Range [0, inf]: writes outside it are clamped with a warning.

DistanceJoint2D.DampingRatio#

lua

DistanceJoint2D.DampingRatio: number

Spring damping ratio (0 = no damping, 1 = critical damping). Range [0, inf]: writes outside it are clamped with a warning.

DistanceJoint2D.EnableMotor#

lua

DistanceJoint2D.EnableMotor: boolean

Drives the length towards MotorSpeed.

DistanceJoint2D.MaxMotorForce#

lua

DistanceJoint2D.MaxMotorForce: number

Maximum motor force in newtons. Range [0, inf]: writes outside it are clamped with a warning.

DistanceJoint2D.MotorSpeed#

lua

DistanceJoint2D.MotorSpeed: number

Target rate of length change in world units per second.

EdgeCollider2D#

Chain of line segments (terrain, walls, platforms). Two-sided: every segment collides from both sides, ends included, and shapes slide smoothly along the chain without catching on inner corners. Consecutive points at most 0.005 world units apart (after scaling) are merged. A sensor edge detects overlaps with each segment. JSON "Points": [[x, y], ...] in local space (at least 2).

lua

local component = self.Entity:GetComponent("EdgeCollider2D")

Member	Kind	Summary
`EdgeCollider2D.Offset: Vec2`	Property	Offset added to every point (local space).
`EdgeCollider2D.Loop: boolean`	Property	Connects the last point back to the first (closed chain).
`EdgeCollider2D.Friction: number`	Property	Coulomb friction coefficient (usually 0-1).
`EdgeCollider2D.Restitution: number`	Property	Bounciness (0 = no bounce, 1 = perfectly elastic).
`EdgeCollider2D.IsSensor: boolean`	Property	Sensors detect overlaps (OnTriggerEnter/Exit) but do not collide.
`EdgeCollider2D.Layer: integer`	Property	Physics layer index (0-31, named in the project settings); the collision matrix decides which layers collide.

EdgeCollider2D.Offset#

lua

EdgeCollider2D.Offset: Vec2

Offset added to every point (local space).

EdgeCollider2D.Loop#

lua

EdgeCollider2D.Loop: boolean

Connects the last point back to the first (closed chain). Needs at least 3 distinct points; otherwise the chain stays open, with a warning.

EdgeCollider2D.Friction#

lua

EdgeCollider2D.Friction: number

Coulomb friction coefficient (usually 0-1). Combined with the other shape's friction by the geometric mean. Range [0, inf]: writes outside it are clamped with a warning.

EdgeCollider2D.Restitution#

lua

EdgeCollider2D.Restitution: number

Bounciness (0 = no bounce, 1 = perfectly elastic). Combined with the other shape by the maximum. Range [0, 1]: writes outside it are clamped with a warning.

EdgeCollider2D.IsSensor#

lua

EdgeCollider2D.IsSensor: boolean

Sensors detect overlaps (OnTriggerEnter/Exit) but do not collide.

EdgeCollider2D.Layer#

lua

EdgeCollider2D.Layer: integer

Physics layer index (0-31, named in the project settings); the collision matrix decides which layers collide. Range [0, 31]: writes outside it are clamped with a warning.

FogOfWar#

Fog-of-war grid covering part of the world; cells are revealed through the FogOfWar scripting API.

lua

local component = self.Entity:GetComponent("FogOfWar")

Member	Kind	Summary
`FogOfWar.GridOrigin: Vec2`	Property	World position of the grid's bottom-left corner.
`FogOfWar.GridSize: Vec2`	Property	Number of cells along X and Y (whole numbers; fractions are truncated).
`FogOfWar.CellSize: number`	Property	Size of one cell in world units.
`FogOfWar.Color: Color`	Property	Color of hidden cells.
`FogOfWar.InitiallyHidden: boolean`	Property	Whether every cell starts hidden (otherwise everything starts revealed).

FogOfWar.GridOrigin#

lua

FogOfWar.GridOrigin: Vec2

World position of the grid's bottom-left corner.

FogOfWar.GridSize#

lua

FogOfWar.GridSize: Vec2

Number of cells along X and Y (whole numbers; fractions are truncated). Range [1, inf]: writes outside it are clamped with a warning.

FogOfWar.CellSize#

lua

FogOfWar.CellSize: number

Size of one cell in world units. Range [0, inf]: writes outside it are clamped with a warning.

FogOfWar.Color#

lua

FogOfWar.Color: Color

Color of hidden cells. Writes also accept a Vec4 or Vec3 (alpha 1).

FogOfWar.InitiallyHidden#

lua

FogOfWar.InitiallyHidden: boolean

Whether every cell starts hidden (otherwise everything starts revealed).

GroundItem#

An item lying in the world (Items.LootMode Ground, Inventory.Drop): visible only to its owner for Items.GroundOwnerSeconds, then to everyone near it for Items.GroundPublicSeconds; a player picks it up by interacting with it (LootDrops.PickUp).

lua

local component = self.Entity:GetComponent("GroundItem")

Member	Kind	Summary
`GroundItem.Item: string`	Property	The item's row key (Item family).
`GroundItem.ItemHash: integer (read-only)`	Property	The RPG key hash of Item, replicated so clients show the item without its key.
`GroundItem.Quantity: integer`	Property	How many items lie there.
`GroundItem.Instance: string (read-only)`	Property	Run time: the stack's canonical item JSON (server only).

GroundItem.Item#

lua

GroundItem.Item: string

The item's row key (Item family).

GroundItem.ItemHash#

lua

GroundItem.ItemHash: integer (read-only)

The RPG key hash of Item, replicated so clients show the item without its key. Read-only. Replicated: on networked entities the authority's value reaches every peer.

GroundItem.Quantity#

lua

GroundItem.Quantity: integer

How many items lie there. Range [1, 1000000]: writes outside it are clamped with a warning. Replicated: on networked entities the authority's value reaches every peer.

GroundItem.Instance#

lua

GroundItem.Instance: string (read-only)

Run time: the stack's canonical item JSON (server only). Read-only.

ID#

Persistent unique identity of the entity. Written as the entity's "ID" in scene files.

lua

local component = self.Entity:GetComponent("ID")

Member	Kind	Summary
`ID.ID: integer (read-only)`	Property	The entity's UUID (never 0).

ID.ID#

lua

ID.ID: integer (read-only)

The entity's UUID (never 0). Entity references store this value. Read-only.

Interactable#

An entity players interact with within Range (plus Combat.RangeTolerance): an NPC to talk to, a vendor, a bank, a crafting station, a gathering node, loot, a mailbox, an auction house, or a game-defined interaction. Graveyards are Interactables tagged "Graveyard".

lua

local component = self.Entity:GetComponent("Interactable")

Member	Kind	Summary
`Interactable.Kind: "Talk"\|"Vendor"\|"Bank"\|"CraftingStation"\|"Gather"\|"Loot"\|"Mailbox"\|"AuctionHouse"\|"Custom"`	Property	What interacting opens.
`Interactable.Dialogue: integer?`	Property	Talk: the dialogue started.
`Interactable.Vendor: string`	Property	Vendor: the Vendor row it sells from.
`Interactable.Station: string`	Property	CraftingStation: the station name recipes require (Recipe.Station).
`Interactable.Tag: string`	Property	A free tag: quest Interact and Talk objectives, graveyards ("Graveyard"), Lua.
`Interactable.Range: number`	Property	World units within which players interact.
`Interactable.Prompt: string`	Property	What the game's UI shows ("Talk", "Trade", ...).

Interactable.Kind#

lua

Interactable.Kind: "Talk"|"Vendor"|"Bank"|"CraftingStation"|"Gather"|"Loot"|"Mailbox"|"AuctionHouse"|"Custom"

What interacting opens. Written by name.

Interactable.Dialogue#

lua

Interactable.Dialogue: integer?

Talk: the dialogue started. Asset handle of a Dialogue (nil when none); writes also accept a virtual path such as "Assets/...".

Interactable.Vendor#

lua

Interactable.Vendor: string

Vendor: the Vendor row it sells from.

Interactable.Station#

lua

Interactable.Station: string

CraftingStation: the station name recipes require (Recipe.Station).

Interactable.Tag#

lua

Interactable.Tag: string

A free tag: quest Interact and Talk objectives, graveyards ("Graveyard"), Lua.

Interactable.Range#

lua

Interactable.Range: number

World units within which players interact. Range [0.5, 100]: writes outside it are clamped with a warning.

Interactable.Prompt#

lua

Interactable.Prompt: string

What the game's UI shows ("Talk", "Trade", ...).

Leash#

Keeps an alerted NPC near home: in the Alert or Combat state beyond Radius from Home it evades - its target is cleared, its perception ignored and its tree paused while it walks home at ReturnSpeedScale - then it is Idle again (OnLeash, OnLeashEnd). Spawners add it to their NPCs.

lua

local component = self.Entity:GetComponent("Leash")

Member	Kind	Summary
`Leash.Home: Vec2`	Property	The scene position the NPC returns to.
`Leash.Radius: number`	Property	World units around Home the NPC may chase within.
`Leash.ReturnSpeedScale: number`	Property	The fraction of the NPC's NavAgent speed it returns home at.

Leash.Home#

lua

Leash.Home: Vec2

The scene position the NPC returns to.

Leash.Radius#

lua

Leash.Radius: number

World units around Home the NPC may chase within. Range [0.5, 10000]: writes outside it are clamped with a warning.

Leash.ReturnSpeedScale#

lua

Leash.ReturnSpeedScale: number

The fraction of the NPC's NavAgent speed it returns home at. Range [0.05, 16]: writes outside it are clamped with a warning.

Light2D#

2D light (point, spot or global) for lit sprites; optionally casts soft shadows from ShadowCaster2D occluders.

lua

local component = self.Entity:GetComponent("Light2D")

Member	Kind	Summary
`Light2D.Type: "Point"\|"Spot"\|"Global"`	Property	Point lights shine in every direction, spot lights in a cone, global lights everywhere uniformly.
`Light2D.Color: Color`	Property	Light color.
`Light2D.Intensity: number`	Property	Brightness multiplier.
`Light2D.InnerRadius: number`	Property	Radius in world units within which the light has full intensity.
`Light2D.OuterRadius: number`	Property	Radius in world units at which the light fades to zero.
`Light2D.InnerAngle: number`	Property	Spot lights: full cone angle (radians) with full intensity.
`Light2D.OuterAngle: number`	Property	Spot lights: full cone angle (radians) at which the light fades to zero.
`Light2D.Direction: number`	Property	Spot lights: direction of the cone in radians relative to the entity's rotation (0 = +X).
`Light2D.Falloff: number`	Property	Exponent of the radial attenuation between the inner and outer radius (1 = linear).
`Light2D.CastShadows: boolean`	Property	Whether ShadowCaster2D occluders (and sprites with CastsShadows) block this light.
`Light2D.ShadowSoftness: number`	Property	Shadow edge softness (0 = hard, 1 = very soft).
`Light2D.LayerMask: integer`	Property	Render layers whose lit sprites receive this light.

Light2D.Type#

lua

Light2D.Type: "Point"|"Spot"|"Global"

Point lights shine in every direction, spot lights in a cone, global lights everywhere uniformly. Written by name.

Light2D.Color#

lua

Light2D.Color: Color

Light color. Writes also accept a Vec4 or Vec3 (alpha 1).

Light2D.Intensity#

lua

Light2D.Intensity: number

Brightness multiplier. Range [0, inf]: writes outside it are clamped with a warning.

Light2D.InnerRadius#

lua

Light2D.InnerRadius: number

Radius in world units within which the light has full intensity. Range [0, inf]: writes outside it are clamped with a warning.

Light2D.OuterRadius#

lua

Light2D.OuterRadius: number

Radius in world units at which the light fades to zero. Range [0, inf]: writes outside it are clamped with a warning.

Light2D.InnerAngle#

lua

Light2D.InnerAngle: number

Spot lights: full cone angle (radians) with full intensity. Range [0, 6.2831855]: writes outside it are clamped with a warning. Radians.

Light2D.OuterAngle#

lua

Light2D.OuterAngle: number

Spot lights: full cone angle (radians) at which the light fades to zero. Range [0, 6.2831855]: writes outside it are clamped with a warning. Radians.

Light2D.Direction#

lua

Light2D.Direction: number

Spot lights: direction of the cone in radians relative to the entity's rotation (0 = +X). Radians.

Light2D.Falloff#

lua

Light2D.Falloff: number

Exponent of the radial attenuation between the inner and outer radius (1 = linear). Range [0, inf]: writes outside it are clamped with a warning.

Light2D.CastShadows#

lua

Light2D.CastShadows: boolean

Whether ShadowCaster2D occluders (and sprites with CastsShadows) block this light.

Light2D.ShadowSoftness#

lua

Light2D.ShadowSoftness: number

Shadow edge softness (0 = hard, 1 = very soft). Range [0, 1]: writes outside it are clamped with a warning.

Light2D.LayerMask#

lua

Light2D.LayerMask: integer

Render layers whose lit sprites receive this light. Bit mask; writes also accept "A|B" strings and tables of entry names.

MusicVolume#

Music for an area (clients): the highest-priority music volume containing the local listener plays, cross-faded when it changes.

lua

local component = self.Entity:GetComponent("MusicVolume")

Member	Kind	Summary
`MusicVolume.Track: integer?`	Property	The music clip (a streamed clip suits long tracks).
`MusicVolume.Priority: integer`	Property	Where music volumes overlap, the highest priority containing the listener plays.
`MusicVolume.FadeSeconds: number`	Property	Seconds of the cross-fade when this track starts or stops.
`MusicVolume.Volume: number`	Property	Linear volume of the track (1 = unchanged).

MusicVolume.Track#

lua

MusicVolume.Track: integer?

The music clip (a streamed clip suits long tracks). Asset handle of a AudioClip (nil when none); writes also accept a virtual path such as "Assets/...".

MusicVolume.Priority#

lua

MusicVolume.Priority: integer

Where music volumes overlap, the highest priority containing the listener plays.

MusicVolume.FadeSeconds#

lua

MusicVolume.FadeSeconds: number

Seconds of the cross-fade when this track starts or stops. Range [0, 60]: writes outside it are clamped with a warning.

MusicVolume.Volume#

lua

MusicVolume.Volume: number

Linear volume of the track (1 = unchanged). Range [0, 4]: writes outside it are clamped with a warning.

Nameplate#

A name above the entity, with optional health and cast bars, drawn in screen-space size by the nameplate render feature within the Crowds budgets: overlapping plates of lower priority hide (target > party > hostile in combat > others, then Priority), at most Crowds.MaxNameplates per frame, fading with the distance. Health, cast, relation and the target come from the installed nameplate data provider (the RPG framework on clients).

lua

local component = self.Entity:GetComponent("Nameplate")

Member	Kind	Summary
`Nameplate.Source: "PlayerName"\|"TemplateName"\|"Custom"`	Property	Where the name comes from: the owning player's name, the NPC template's Name (from the data provider), or Text.
`Nameplate.Text: string`	Property	The name with Source Custom, and the fallback of the others while the provider knows nothing of the entity: at most 64 bytes of UTF-8.
`Nameplate.Offset: Vec2`	Property	Where the plate's bottom center sits, in world units from the entity's origin (above its head).
`Nameplate.ShowHealth: boolean`	Property	Draws a health bar under the name while the provider reports a maximum health.
`Nameplate.ShowCast: boolean`	Property	Draws a cast bar under the health bar while the entity casts.
`Nameplate.Priority: integer`	Property	Orders plates of the same class (target, party, hostile in combat, others) when they overlap: higher stays visible.

Nameplate.Source#

lua

Nameplate.Source: "PlayerName"|"TemplateName"|"Custom"

Where the name comes from: the owning player's name, the NPC template's Name (from the data provider), or Text. Written by name. Replicated: on networked entities the authority's value reaches every peer.

Nameplate.Text#

lua

Nameplate.Text: string

The name with Source Custom, and the fallback of the others while the provider knows nothing of the entity: at most 64 bytes of UTF-8. Not replicated (strings are not): set it in the prefab, or on the peer that draws the plate.

Nameplate.Offset#

lua

Nameplate.Offset: Vec2

Where the plate's bottom center sits, in world units from the entity's origin (above its head). Range [-1000, 1000]: writes outside it are clamped with a warning. Replicated: on networked entities the authority's value reaches every peer.

Nameplate.ShowHealth#

lua

Nameplate.ShowHealth: boolean

Draws a health bar under the name while the provider reports a maximum health. Replicated: on networked entities the authority's value reaches every peer.

Nameplate.ShowCast#

lua

Nameplate.ShowCast: boolean

Draws a cast bar under the health bar while the entity casts. Replicated: on networked entities the authority's value reaches every peer.

Nameplate.Priority#

lua

Nameplate.Priority: integer

Orders plates of the same class (target, party, hostile in combat, others) when they overlap: higher stays visible. Range [-1000000, 1000000]: writes outside it are clamped with a warning. Replicated: on networked entities the authority's value reaches every peer.

NavAgent#

An NPC that walks the navigation grid: a MoveTo or MoveToEntity command to the scene's nav world requests a path and the nav world moves the entity's Translation along it, avoiding other agents and sliding along walls. The entity must be a root entity without a dynamic Rigidbody2D (a kinematic body follows the agent). Its moving state lives in the nav world, not here.

lua

local component = self.Entity:GetComponent("NavAgent")

Member	Kind	Summary
`NavAgent.AgentClass: string`	Property	The agent class (a name from the project's Navigation settings) whose radius decides where the agent fits; a change applies from the next command.
`NavAgent.Speed: number`	Property	World units per second.
`NavAgent.Acceleration: number`	Property	World units per second squared: how fast the agent reaches its speed, turns and slows down into its goal.
`NavAgent.StoppingDistance: number`	Property	World units from the goal within which a MoveTo arrives (unless the command gives its own accept radius).
`NavAgent.Avoidance: boolean`	Property	Whether the agent keeps AvoidanceRadius away from other agents with Avoidance (separation); others avoid it while it does.
`NavAgent.AvoidanceRadius: number`	Property	World units within which another agent pushes this one away while it moves.
`NavAgent.Priority: integer`	Property	When two moving agents avoid each other, the higher priority keeps its line and the lower one gives way.
`NavAgent.MaxRepathsPerSecond: number`	Property	How often a MoveToEntity may repath for a target that keeps moving (0: never; the agent then fails when it reaches the end of its path short of the target).
`NavAgent:MoveTo(position: Vec2, acceptRadius?: number)`	Method	Walks the agent to `position`: a path is requested (state "Waiting"), then followed ("Moving") around walls and other agents until the agent is within `acceptRadius` (default: its StoppingDistance) of it ("Arrived", OnNavArrived), or until no path leads there or it is stuck ("Failed", OnNavFailed).
`NavAgent:MoveToEntity(target: Entity, range: number)`	Method	Follows `target` until the agent is within `range` (> 0) of it ("Arrived"), repathing when the target moved more than half the range (at most MaxRepathsPerSecond times a second); "Failed" when the target is destroyed or cannot be reached.
`NavAgent:Stop()`	Method	Stops the agent where it is (state "Idle", no callback).
`NavAgent:GetState(): string`	Method	"Idle", "Waiting" (a path is being searched), "Moving", "Arrived" or "Failed"; Arrived and Failed agents stand until their next command.

NavAgent.AgentClass#

lua

NavAgent.AgentClass: string

The agent class (a name from the project's Navigation settings) whose radius decides where the agent fits; a change applies from the next command.

NavAgent.Speed#

lua

NavAgent.Speed: number

World units per second. Range [0.001, inf]: writes outside it are clamped with a warning.

NavAgent.Acceleration#

lua

NavAgent.Acceleration: number

World units per second squared: how fast the agent reaches its speed, turns and slows down into its goal. Range [0.001, inf]: writes outside it are clamped with a warning.

NavAgent.StoppingDistance#

lua

NavAgent.StoppingDistance: number

World units from the goal within which a MoveTo arrives (unless the command gives its own accept radius). Range [0, inf]: writes outside it are clamped with a warning.

NavAgent.Avoidance#

lua

NavAgent.Avoidance: boolean

Whether the agent keeps AvoidanceRadius away from other agents with Avoidance (separation); others avoid it while it does.

NavAgent.AvoidanceRadius#

lua

NavAgent.AvoidanceRadius: number

World units within which another agent pushes this one away while it moves. Range [0, inf]: writes outside it are clamped with a warning.

NavAgent.Priority#

lua

NavAgent.Priority: integer

When two moving agents avoid each other, the higher priority keeps its line and the lower one gives way.

NavAgent.MaxRepathsPerSecond#

lua

NavAgent.MaxRepathsPerSecond: number

How often a MoveToEntity may repath for a target that keeps moving (0: never; the agent then fails when it reaches the end of its path short of the target). Range [0, inf]: writes outside it are clamped with a warning.

NavAgent:MoveTo#

lua

NavAgent:MoveTo(position: Vec2, acceptRadius?: number)

Walks the agent to position: a path is requested (state "Waiting"), then followed ("Moving") around walls and other agents until the agent is within acceptRadius (default: its StoppingDistance) of it ("Arrived", OnNavArrived), or until no path leads there or it is stuck ("Failed", OnNavFailed). The same command again keeps the path. Errors for an agent class the settings do not have, a child entity, a dynamic body or a non-finite position.

Parameters

position (Vec2)
acceptRadius? (number)

Example

lua

self.Entity:GetComponent("NavAgent"):MoveTo(Vec2(12, 4))

NavAgent:MoveToEntity#

lua

NavAgent:MoveToEntity(target: Entity, range: number)

Follows target until the agent is within range (> 0) of it ("Arrived"), repathing when the target moved more than half the range (at most MaxRepathsPerSecond times a second); "Failed" when the target is destroyed or cannot be reached.

Parameters

target (Entity)
range (number)

Example

lua

agent:MoveToEntity(player, 1.5)

NavAgent:Stop#

lua

NavAgent:Stop()

Stops the agent where it is (state "Idle", no callback).

NavAgent:GetState#

lua

NavAgent:GetState(): string

"Idle", "Waiting" (a path is being searched), "Moving", "Arrived" or "Failed"; Arrived and Failed agents stand until their next command.

Returns string

NavAreaVolume#

A navigation area for nav baking: the tiles inside get the project nav area (blocked, a road, water, ...).

lua

local component = self.Entity:GetComponent("NavAreaVolume")

Member	Kind	Summary
`NavAreaVolume.Area: string`	Property	The project nav area by name ("Blocked", "Road", "Water", ...; Project Settings > Navigation).
`NavAreaVolume.Priority: integer`	Property	Where nav area volumes overlap, the highest priority decides a tile's area.

NavAreaVolume.Area#

lua

NavAreaVolume.Area: string

The project nav area by name ("Blocked", "Road", "Water", ...; Project Settings > Navigation).

NavAreaVolume.Priority#

lua

NavAreaVolume.Priority: integer

Where nav area volumes overlap, the highest priority decides a tile's area.

NavObstacle#

Blocks the navigation tiles under it while Enabled: doors, gates, player-built walls. The scene's nav world reads it every fixed step; a change (enabled, disabled, moved, resized, removed) re-derives the nav cells around it in a job and, one step later, the agents whose paths cross them repath. A tile is blocked when at least 4 of its 4 x 4 samples lie inside the shape, scaled and rotated with the entity's world transform. Static obstacles are baked into the navigation instead (nav.bake), so they cost nothing at run time; moving things are better left to the agents' avoidance.

lua

local component = self.Entity:GetComponent("NavObstacle")

Member	Kind	Summary
`NavObstacle.Shape: "Box"\|"Circle"`	Property	Box: Size around the entity's position.
`NavObstacle.Size: Vec2`	Property	The box's width and height in local units (Shape Box).
`NavObstacle.Radius: number`	Property	The circle's radius in local units (Shape Circle).
`NavObstacle.Enabled: boolean`	Property	Whether it blocks now: a door closes when it is turned on and opens when it is turned off.
`NavObstacle.Static: boolean`	Property	Baked into the navigation (it never changes at run time): the nav world ignores it.
`NavObstacle.ClassMask: integer`	Property	The agent classes it blocks: bit i is the i-th agent class of the project's Navigation settings (a gate only large creatures cannot pass blocks those).

NavObstacle.Shape#

lua

NavObstacle.Shape: "Box"|"Circle"

Box: Size around the entity's position. Circle: Radius around it. Written by name.

NavObstacle.Size#

lua

NavObstacle.Size: Vec2

The box's width and height in local units (Shape Box). Range [0.001, inf]: writes outside it are clamped with a warning.

NavObstacle.Radius#

lua

NavObstacle.Radius: number

The circle's radius in local units (Shape Circle). Range [0.001, inf]: writes outside it are clamped with a warning.

NavObstacle.Enabled#

lua

NavObstacle.Enabled: boolean

Whether it blocks now: a door closes when it is turned on and opens when it is turned off.

NavObstacle.Static#

lua

NavObstacle.Static: boolean

Baked into the navigation (it never changes at run time): the nav world ignores it.

NavObstacle.ClassMask#

lua

NavObstacle.ClassMask: integer

The agent classes it blocks: bit i is the i-th agent class of the project's Navigation settings (a gate only large creatures cannot pass blocks those). Bit mask; writes also accept "A|B" strings and tables of entry names.

NetworkIdentity#

Makes the entity a networked object: spawned on clients by the server and addressable by RPCs.

lua

local component = self.Entity:GetComponent("NetworkIdentity")

Member	Kind	Summary
`NetworkIdentity.NetworkId: integer (read-only)`	Property	Id assigned by the server when the entity is spawned (runtime state: always saved as 0, and reset to 0 on duplicates, prefabs and scene copies).
`NetworkIdentity.ServerOwned: boolean`	Property	Whether the server owns the entity (otherwise OwnerClientId does and sends its state).
`NetworkIdentity.OwnerClientId: integer`	Property	Client that owns the entity when it is not server owned.
`NetworkIdentity.OwnerDisconnectPolicy: "UseDefault"\|"Despawn"\|"TransferToServer"`	Property	What the server does with the entity when its owning client disconnects: UseDefault follows the server's configured default (Despawn unless the game changed it), Despawn destroys it on the server and every client, TransferToServer makes the server its owner and keeps it in the game.
`NetworkIdentity.FollowOwnerOnHandoff: boolean`	Property	A spawn its owning player takes along when the player moves to another zone server (a pet, a mount): it is handed off with the player's avatar, keeping its state.

NetworkIdentity.NetworkId#

lua

NetworkIdentity.NetworkId: integer (read-only)

Id assigned by the server when the entity is spawned (runtime state: always saved as 0, and reset to 0 on duplicates, prefabs and scene copies). Read-only.

NetworkIdentity.ServerOwned#

lua

NetworkIdentity.ServerOwned: boolean

Whether the server owns the entity (otherwise OwnerClientId does and sends its state).

NetworkIdentity.OwnerClientId#

lua

NetworkIdentity.OwnerClientId: integer

Client that owns the entity when it is not server owned.

NetworkIdentity.OwnerDisconnectPolicy#

lua

NetworkIdentity.OwnerDisconnectPolicy: "UseDefault"|"Despawn"|"TransferToServer"

What the server does with the entity when its owning client disconnects: UseDefault follows the server's configured default (Despawn unless the game changed it), Despawn destroys it on the server and every client, TransferToServer makes the server its owner and keeps it in the game. Has no effect while the entity is server owned. Written by name.

NetworkIdentity.FollowOwnerOnHandoff#

lua

NetworkIdentity.FollowOwnerOnHandoff: boolean

A spawn its owning player takes along when the player moves to another zone server (a pet, a mount): it is handed off with the player's avatar, keeping its state. Other spawns the player owns stay and follow OwnerDisconnectPolicy.

NetworkLagCompensation#

A hitbox the server remembers for lag compensation: every simulation tick of the last LagCompensation.HistoryMs, so Net.RewindRaycast and Net.RewindOverlapCircle hit targets where a client saw them when it fired (at most MaxRewindMs ago). The shape follows the entity's world transform.

lua

local component = self.Entity:GetComponent("NetworkLagCompensation")

Member	Kind	Summary
`NetworkLagCompensation.Shape: "Circle"\|"Box"\|"Capsule"`	Property	Circle (Size.x = radius), Box (Size = half extents, rotated with the entity) or Capsule (Size.x = radius, Size.y = half height of its segment along the entity's local y).
`NetworkLagCompensation.Size: Vec2`	Property	The shape's size in local units (see Shape), scaled by the entity's world scale (circles and capsule radii by the larger axis).
`NetworkLagCompensation.Offset: Vec2`	Property	The shape's center relative to the entity, in local units.
`NetworkLagCompensation.Layers: integer`	Property	Physics layers the hitbox is on: rewind queries with a Layers option only hit hitboxes sharing one of them.

NetworkLagCompensation.Shape#

lua

NetworkLagCompensation.Shape: "Circle"|"Box"|"Capsule"

Circle (Size.x = radius), Box (Size = half extents, rotated with the entity) or Capsule (Size.x = radius, Size.y = half height of its segment along the entity's local y). Written by name.

NetworkLagCompensation.Size#

lua

NetworkLagCompensation.Size: Vec2

The shape's size in local units (see Shape), scaled by the entity's world scale (circles and capsule radii by the larger axis). Range [0, 1000000]: writes outside it are clamped with a warning.

NetworkLagCompensation.Offset#

lua

NetworkLagCompensation.Offset: Vec2

The shape's center relative to the entity, in local units.

NetworkLagCompensation.Layers#

lua

NetworkLagCompensation.Layers: integer

Physics layers the hitbox is on: rewind queries with a Layers option only hit hitboxes sharing one of them. Bit mask; writes also accept "A|B" strings and tables of entry names.

NetworkRelevancy#

Which clients a networked entity is replicated to (interest management, server only): its range class, mode, teams, channels, phase and send priority. Entities without it are relevant to every client (AlwaysRelevant).

lua

local component = self.Entity:GetComponent("NetworkRelevancy")

Member	Kind	Summary
`NetworkRelevancy.RangeClass: string`	Property	A range class of the project's Network.Interest settings ("Default", "Near", "Far", ...): how close a client's observer must be.
`NetworkRelevancy.Mode: "Spatial"\|"AlwaysRelevant"\|"OwnerOnly"\|"Manual"`	Property	Spatial: relevant to clients with an observer within the range class radius.
`NetworkRelevancy.TeamMask: integer`	Property	Teams that see the entity, as a bit set (0 = every team); a client sees it when its own team mask (Net.SetClientTeams) is 0 or shares a bit.
`NetworkRelevancy.Channels: integer`	Property	Channels the entity belongs to, as a bit set (0 = no restriction); only clients subscribed to one of them (Net.SetClientChannels) see it.
`NetworkRelevancy.Phase: integer`	Property	The phase the entity exists in (0 = every phase): only clients in that phase (Net.SetClientPhase) or seeing every phase see it.
`NetworkRelevancy.Priority: number`	Property	Importance in each client's send priority (with the range class's PriorityWeight and the distance): higher values are sent sooner when the bandwidth budget is short.
`NetworkRelevancy.ScriptFilter: boolean`	Property	The Lua relevancy filter (Net.SetRelevancyFilter) decides last whether a client that passed every other rule receives it (stealth, line of sight); its decision is held for the project's ScriptFilterHoldTicks.
`NetworkRelevancy.HideWhenIrrelevant: boolean`	Property	Scene-placed entities: clients hide the entity while it is not relevant to them (OnRelevancyChanged(false)) instead of keeping its last known state visible.

NetworkRelevancy.RangeClass#

lua

NetworkRelevancy.RangeClass: string

A range class of the project's Network.Interest settings ("Default", "Near", "Far", ...): how close a client's observer must be. An unknown name uses the first class (with a warning).

NetworkRelevancy.Mode#

lua

NetworkRelevancy.Mode: "Spatial"|"AlwaysRelevant"|"OwnerOnly"|"Manual"

Spatial: relevant to clients with an observer within the range class radius. AlwaysRelevant: to every client. OwnerOnly: to the owning client only. Manual: to the clients a script gave it to (Net.SetRelevantTo). The owner always receives its entities; teams, channels, phases and the script filter apply to every mode. Written by name.

NetworkRelevancy.TeamMask#

lua

NetworkRelevancy.TeamMask: integer

Teams that see the entity, as a bit set (0 = every team); a client sees it when its own team mask (Net.SetClientTeams) is 0 or shares a bit.

NetworkRelevancy.Channels#

lua

NetworkRelevancy.Channels: integer

Channels the entity belongs to, as a bit set (0 = no restriction); only clients subscribed to one of them (Net.SetClientChannels) see it.

NetworkRelevancy.Phase#

lua

NetworkRelevancy.Phase: integer

The phase the entity exists in (0 = every phase): only clients in that phase (Net.SetClientPhase) or seeing every phase see it. Changing a client's phase hides other phases at once. Range [0, 65535]: writes outside it are clamped with a warning.

NetworkRelevancy.Priority#

lua

NetworkRelevancy.Priority: number

Importance in each client's send priority (with the range class's PriorityWeight and the distance): higher values are sent sooner when the bandwidth budget is short. Range [0.001, 100]: writes outside it are clamped with a warning.

NetworkRelevancy.ScriptFilter#

lua

NetworkRelevancy.ScriptFilter: boolean

The Lua relevancy filter (Net.SetRelevancyFilter) decides last whether a client that passed every other rule receives it (stealth, line of sight); its decision is held for the project's ScriptFilterHoldTicks.

NetworkRelevancy.HideWhenIrrelevant#

lua

NetworkRelevancy.HideWhenIrrelevant: boolean

Scene-placed entities: clients hide the entity while it is not relevant to them (OnRelevancyChanged(false)) instead of keeping its last known state visible.

NetworkTransform#

Replicates the transform from the authority to the other peers, interpolated on receivers.

lua

local component = self.Entity:GetComponent("NetworkTransform")

Member	Kind	Summary
`NetworkTransform.SyncPosition: boolean`	Property	Replicates the position.
`NetworkTransform.SyncRotation: boolean`	Property	Replicates the rotation.
`NetworkTransform.SyncScale: boolean`	Property	Replicates the scale.
`NetworkTransform.SendRateHz: number`	Property	Maximum state updates per second (limited by the network tick rate).
`NetworkTransform.PositionThreshold: number`	Property	Position change (world units) below which no update is sent.
`NetworkTransform.RotationThreshold: number`	Property	Rotation change (radians) below which no update is sent.
`NetworkTransform.Interpolate: boolean`	Property	Receivers interpolate between snapshots (otherwise they snap to each update).
`NetworkTransform.InterpolationDelayMs: number`	Property	How far behind the latest snapshot receivers render, in milliseconds (jitter buffer).

NetworkTransform.SyncPosition#

lua

NetworkTransform.SyncPosition: boolean

Replicates the position.

NetworkTransform.SyncRotation#

lua

NetworkTransform.SyncRotation: boolean

Replicates the rotation.

NetworkTransform.SyncScale#

lua

NetworkTransform.SyncScale: boolean

Replicates the scale.

NetworkTransform.SendRateHz#

lua

NetworkTransform.SendRateHz: number

Maximum state updates per second (limited by the network tick rate). Range [0, 1000]: writes outside it are clamped with a warning.

NetworkTransform.PositionThreshold#

lua

NetworkTransform.PositionThreshold: number

Position change (world units) below which no update is sent. Range [0, inf]: writes outside it are clamped with a warning.

NetworkTransform.RotationThreshold#

lua

NetworkTransform.RotationThreshold: number

Rotation change (radians) below which no update is sent. Range [0, inf]: writes outside it are clamped with a warning. Radians.

NetworkTransform.Interpolate#

lua

NetworkTransform.Interpolate: boolean

Receivers interpolate between snapshots (otherwise they snap to each update).

NetworkTransform.InterpolationDelayMs#

lua

NetworkTransform.InterpolationDelayMs: number

How far behind the latest snapshot receivers render, in milliseconds (jitter buffer). Range [0, inf]: writes outside it are clamped with a warning.

NpcState#

What an NPC is doing, replicated to clients for nameplates and aggro indicators: set by the behaviour tree (SetNpcState), Lua (Npc.SetState) and leashing (Evading).

lua

local component = self.Entity:GetComponent("NpcState")

Member	Kind	Summary
`NpcState.State: "Idle"\|"Patrolling"\|"Alert"\|"Combat"\|"Evading"\|"Dead"\|"Custom"`	Property	Idle, Patrolling, Alert, Combat, Evading (walking home on its leash), Dead or Custom (Flags tell the game's own states).
`NpcState.Target: integer`	Property	The network id of the NPC's target (0: none, or a target that is not networked); Npc.GetTarget resolves it on every peer.
`NpcState.Flags: integer`	Property	Game-defined bits replicated with the state (a boss's enrage, a quest giver's mark).

NpcState.State#

lua

NpcState.State: "Idle"|"Patrolling"|"Alert"|"Combat"|"Evading"|"Dead"|"Custom"

Idle, Patrolling, Alert, Combat, Evading (walking home on its leash), Dead or Custom (Flags tell the game's own states). Written by name. Replicated: on networked entities the authority's value reaches every peer.

NpcState.Target#

lua

NpcState.Target: integer

The network id of the NPC's target (0: none, or a target that is not networked); Npc.GetTarget resolves it on every peer. Replicated: on networked entities the authority's value reaches every peer.

NpcState.Flags#

lua

NpcState.Flags: integer

Game-defined bits replicated with the state (a boss's enrage, a quest giver's mark). Replicated: on networked entities the authority's value reaches every peer.

ParticleSystem#

Particle emitter (EmitterSettings, flattened into fields). Particles spawn from the shape in the entity's space and are simulated in World or Local space. JSON: the fields below plus "Bursts" ([{ "Time", "Count", "Cycles", "Interval" }]), the gradients "StartColorGradient" and "ColorOverLifetimeGradient" ({ "Mode", "ColorKeys", "AlphaKeys" }) and the curves "SizeOverLifetimeCurve", "VelocityOverLifetimeCurveX", "VelocityOverLifetimeCurveY", "RotationOverLifetimeCurve" ({ "Keys" }).

lua

local component = self.Entity:GetComponent("ParticleSystem")

Member	Kind	Summary
`ParticleSystem.PlayOnAwake: boolean`	Property	Starts emitting when the scene starts running, or when the component appears in a running scene.
`ParticleSystem.Duration: number`	Property	Seconds per emission cycle (bursts are timed within the cycle).
`ParticleSystem.Looping: boolean`	Property	Starts a new emission cycle when one ends; otherwise emission stops after one cycle.
`ParticleSystem.Prewarm: boolean`	Property	Looping emitters only: starts as if one full cycle had already run (the start delay is skipped).
`ParticleSystem.StartDelay: number`	Property	Seconds between Play and the start of emission.
`ParticleSystem.MaxParticles: integer`	Property	Capacity: particles emitted while this many are alive are dropped.
`ParticleSystem.EmissionRate: number`	Property	Particles emitted per second (fractions accumulate across frames).
`ParticleSystem.ShapeType: "Point"\|"Circle"\|"Box"\|"Cone"`	Property	Spawn shape: Point (random direction), Circle (outwards from the center), Box (along +Y), Cone (from a base segment, spreading by ShapeConeAngle).
`ParticleSystem.ShapeRadius: number`	Property	Circle radius, or the half-width of the cone's base, in world units.
`ParticleSystem.ShapeEmitFromEdge: boolean`	Property	Circle: spawn on the circumference only.
`ParticleSystem.ShapeBoxSize: Vec2`	Property	Box: full width and height in world units.
`ParticleSystem.ShapeConeAngle: number`	Property	Cone: full opening angle (radians, shown in degrees).
`ParticleSystem.ShapeOffset: Vec2`	Property	Position of the shape relative to the entity, in world units.
`ParticleSystem.ShapeRotation: number`	Property	Rotation of the shape relative to the entity (radians, counter-clockwise).
`ParticleSystem.SimulationSpace: "World"\|"Local"`	Property	World: particles stay where they were emitted when the entity moves.
`ParticleSystem.StartLifetime: Vec2`	Property	Lifetime in seconds, picked per particle from [min, max] (x = min, y = max).
`ParticleSystem.StartSpeed: Vec2`	Property	Initial speed in world units per second along the shape's direction, picked from [min, max].
`ParticleSystem.StartSize: Vec2`	Property	Initial size (edge of the square quad) in world units, picked from [min, max].
`ParticleSystem.StartRotation: Vec2`	Property	Initial rotation (radians, counter-clockwise), picked from [min, max].
`ParticleSystem.StartAngularVelocity: Vec2`	Property	Initial angular velocity (radians per second), picked from [min, max].
`ParticleSystem.StartColorMode: "RandomBetweenColors"\|"RandomFromGradient"`	Property	How the start color is picked: between StartColorMin and StartColorMax, or from StartColorGradient at a random time.
`ParticleSystem.StartColorMin: Color`	Property	One end of the start color range (RGBA, straight alpha).
`ParticleSystem.StartColorMax: Color`	Property	Other end of the start color range (RGBA, straight alpha); equal to StartColorMin for a constant color.
`ParticleSystem.Gravity: Vec2`	Property	Per-axis multiplier of the scene gravity (0 = no gravity).
`ParticleSystem.LinearDamping: number`	Property	Velocity damping per second (velocity = 1 / (1 + dt damping)).
`ParticleSystem.ColorOverLifetimeEnabled: boolean`	Property	Multiplies the start color by ColorOverLifetimeGradient over each particle's lifetime.
`ParticleSystem.SizeOverLifetimeEnabled: boolean`	Property	Multiplies the start size by SizeOverLifetimeCurve over each particle's lifetime.
`ParticleSystem.VelocityOverLifetimeEnabled: boolean`	Property	Adds the velocity given by VelocityOverLifetimeCurveX/Y (world units per second) over each particle's lifetime.
`ParticleSystem.RotationOverLifetimeEnabled: boolean`	Property	Adds the angular velocity given by RotationOverLifetimeCurve (radians per second) over each particle's lifetime.
`ParticleSystem.TextureSheetEnabled: boolean`	Property	Flipbook animation over the texture's grid of frames (or the frames of SpriteSheet).
`ParticleSystem.TextureSheetColumns: integer`	Property	Columns of the texture's frame grid (ignored when a SpriteSheet provides the frames).
`ParticleSystem.TextureSheetRows: integer`	Property	Rows of the texture's frame grid (ignored when a SpriteSheet provides the frames).
`ParticleSystem.TextureSheetFrameCount: integer`	Property	Frames played, from frame 0 (row-major from the top-left cell); 0 = every frame.
`ParticleSystem.TextureSheetMode: "OverLifetime"\|"FrameRate"`	Property	OverLifetime: TextureSheetCycles passes over the frames per lifetime.
`ParticleSystem.TextureSheetFrameRate: number`	Property	Frames per second of particle age (TextureSheetMode FrameRate).
`ParticleSystem.TextureSheetCycles: number`	Property	Passes over the frames per particle lifetime (TextureSheetMode OverLifetime).
`ParticleSystem.TextureSheetRandomStartFrame: boolean`	Property	Starts each particle on a random frame.
`ParticleSystem.Texture: integer?`	Property	Particle texture; none uses the built-in particle texture (or the SpriteSheet's texture when one is set).
`ParticleSystem.SpriteSheet: integer?`	Property	Optional sprite sheet whose frames are the texture sheet frames (frame i of a particle = frame i of the sheet).
`ParticleSystem.BlendMode: "AlphaBlend"\|"Additive"`	Property	How particles blend with what is behind them.
`ParticleSystem.Layer: integer`	Property	Render layer index (0-31, named in the project settings).
`ParticleSystem.OrderInLayer: integer`	Property	Draw order inside the render layer (int16 range); higher values draw in front.
`ParticleSystem.RandomSeed: integer`	Property	Seed of the emitter's random sequence (identical particles on every play); 0 = a different sequence every time.
`ParticleSystem.SimulationMode: "CPU"\|"GPU"`	Property	CPU: simulated by the ParticleSystem scene system.
`ParticleSystem:Play(): boolean`	Method	Starts emitting (after the StartDelay; looping emitters with Prewarm start with a full cycle simulated), or resumes a paused emitter.
`ParticleSystem:Stop(behavior?: ParticleStopBehavior): boolean`	Method	Stops emitting and rewinds the emission cycle; with ParticleStopBehavior.StopEmittingAndClear the live particles are removed too (default: they finish their lifetime).
`ParticleSystem:Pause(): boolean`	Method	Freezes the particles and the emission until Play.
`ParticleSystem:Clear(): boolean`	Method	Removes every live particle; the playback state is unchanged.
`ParticleSystem:Emit(count: integer): integer`	Method	Spawns up to count particles at once at the emitter's current position, whatever the playback state, and returns how many were spawned (the rest did not fit into MaxParticles).
`ParticleSystem:IsPlaying(): boolean`	Method	True while the emitter emits (not paused or stopped).
`ParticleSystem:IsAlive(): boolean`	Method	True while the emitter emits or particles are alive (false once a stopped or finished emitter has none left).
`ParticleSystem:GetParticleCount(): integer`	Method	The number of live particles.

ParticleSystem.PlayOnAwake#

lua

ParticleSystem.PlayOnAwake: boolean

Starts emitting when the scene starts running, or when the component appears in a running scene.

ParticleSystem.Duration#

lua

ParticleSystem.Duration: number

Seconds per emission cycle (bursts are timed within the cycle). Range [0.01, 3600]: writes outside it are clamped with a warning.

ParticleSystem.Looping#

lua

ParticleSystem.Looping: boolean

Starts a new emission cycle when one ends; otherwise emission stops after one cycle.

ParticleSystem.Prewarm#

lua

ParticleSystem.Prewarm: boolean

Looping emitters only: starts as if one full cycle had already run (the start delay is skipped).

ParticleSystem.StartDelay#

lua

ParticleSystem.StartDelay: number

Seconds between Play and the start of emission. Range [0, 3600]: writes outside it are clamped with a warning.

ParticleSystem.MaxParticles#

lua

ParticleSystem.MaxParticles: integer

Capacity: particles emitted while this many are alive are dropped. Range [1, 1048576]: writes outside it are clamped with a warning.

ParticleSystem.EmissionRate#

lua

ParticleSystem.EmissionRate: number

Particles emitted per second (fractions accumulate across frames). Range [0, 1000000]: writes outside it are clamped with a warning.

ParticleSystem.ShapeType#

lua

ParticleSystem.ShapeType: "Point"|"Circle"|"Box"|"Cone"

Spawn shape: Point (random direction), Circle (outwards from the center), Box (along +Y), Cone (from a base segment, spreading by ShapeConeAngle). Written by name.

ParticleSystem.ShapeRadius#

lua

ParticleSystem.ShapeRadius: number

Circle radius, or the half-width of the cone's base, in world units. Range [0, 1000000]: writes outside it are clamped with a warning.

ParticleSystem.ShapeEmitFromEdge#

lua

ParticleSystem.ShapeEmitFromEdge: boolean

Circle: spawn on the circumference only.

ParticleSystem.ShapeBoxSize#

lua

ParticleSystem.ShapeBoxSize: Vec2

Box: full width and height in world units. Range [0, 1000000]: writes outside it are clamped with a warning.

ParticleSystem.ShapeConeAngle#

lua

ParticleSystem.ShapeConeAngle: number

Cone: full opening angle (radians, shown in degrees). Range [0, 6.2831855]: writes outside it are clamped with a warning. Radians.

ParticleSystem.ShapeOffset#

lua

ParticleSystem.ShapeOffset: Vec2

Position of the shape relative to the entity, in world units. Range [-1000000, 1000000]: writes outside it are clamped with a warning.

ParticleSystem.ShapeRotation#

lua

ParticleSystem.ShapeRotation: number

Rotation of the shape relative to the entity (radians, counter-clockwise). Range [-1000000, 1000000]: writes outside it are clamped with a warning. Radians.

ParticleSystem.SimulationSpace#

lua

ParticleSystem.SimulationSpace: "World"|"Local"

World: particles stay where they were emitted when the entity moves. Local: particles move with the entity. Written by name.

ParticleSystem.StartLifetime#

lua

ParticleSystem.StartLifetime: Vec2

Lifetime in seconds, picked per particle from [min, max] (x = min, y = max). Range [0.001, 3600]: writes outside it are clamped with a warning.

ParticleSystem.StartSpeed#

lua

ParticleSystem.StartSpeed: Vec2

Initial speed in world units per second along the shape's direction, picked from [min, max]. Range [-1000000, 1000000]: writes outside it are clamped with a warning.

ParticleSystem.StartSize#

lua

ParticleSystem.StartSize: Vec2

Initial size (edge of the square quad) in world units, picked from [min, max]. Range [0, 1000000]: writes outside it are clamped with a warning.

ParticleSystem.StartRotation#

lua

ParticleSystem.StartRotation: Vec2

Initial rotation (radians, counter-clockwise), picked from [min, max]. Range [-1000000, 1000000]: writes outside it are clamped with a warning. Radians.

ParticleSystem.StartAngularVelocity#

lua

ParticleSystem.StartAngularVelocity: Vec2

Initial angular velocity (radians per second), picked from [min, max]. Range [-1000000, 1000000]: writes outside it are clamped with a warning. Radians.

ParticleSystem.StartColorMode#

lua

ParticleSystem.StartColorMode: "RandomBetweenColors"|"RandomFromGradient"

How the start color is picked: between StartColorMin and StartColorMax, or from StartColorGradient at a random time. Written by name.

ParticleSystem.StartColorMin#

lua

ParticleSystem.StartColorMin: Color

One end of the start color range (RGBA, straight alpha). Range [0, 1000000]: writes outside it are clamped with a warning. Writes also accept a Vec4 or Vec3 (alpha 1).

ParticleSystem.StartColorMax#

lua

ParticleSystem.StartColorMax: Color

Other end of the start color range (RGBA, straight alpha); equal to StartColorMin for a constant color. Range [0, 1000000]: writes outside it are clamped with a warning. Writes also accept a Vec4 or Vec3 (alpha 1).

ParticleSystem.Gravity#

lua

ParticleSystem.Gravity: Vec2

Per-axis multiplier of the scene gravity (0 = no gravity). Range [-1000000, 1000000]: writes outside it are clamped with a warning.

ParticleSystem.LinearDamping#

lua

ParticleSystem.LinearDamping: number

Velocity damping per second (velocity *= 1 / (1 + dt * damping)). Range [0, 1000000]: writes outside it are clamped with a warning.

ParticleSystem.ColorOverLifetimeEnabled#

lua

ParticleSystem.ColorOverLifetimeEnabled: boolean

Multiplies the start color by ColorOverLifetimeGradient over each particle's lifetime.

ParticleSystem.SizeOverLifetimeEnabled#

lua

ParticleSystem.SizeOverLifetimeEnabled: boolean

Multiplies the start size by SizeOverLifetimeCurve over each particle's lifetime.

ParticleSystem.VelocityOverLifetimeEnabled#

lua

ParticleSystem.VelocityOverLifetimeEnabled: boolean

Adds the velocity given by VelocityOverLifetimeCurveX/Y (world units per second) over each particle's lifetime.

ParticleSystem.RotationOverLifetimeEnabled#

lua

ParticleSystem.RotationOverLifetimeEnabled: boolean

Adds the angular velocity given by RotationOverLifetimeCurve (radians per second) over each particle's lifetime.

ParticleSystem.TextureSheetEnabled#

lua

ParticleSystem.TextureSheetEnabled: boolean

Flipbook animation over the texture's grid of frames (or the frames of SpriteSheet).

ParticleSystem.TextureSheetColumns#

lua

ParticleSystem.TextureSheetColumns: integer

Columns of the texture's frame grid (ignored when a SpriteSheet provides the frames). Range [1, 256]: writes outside it are clamped with a warning.

ParticleSystem.TextureSheetRows#

lua

ParticleSystem.TextureSheetRows: integer

Rows of the texture's frame grid (ignored when a SpriteSheet provides the frames). Range [1, 256]: writes outside it are clamped with a warning.

ParticleSystem.TextureSheetFrameCount#

lua

ParticleSystem.TextureSheetFrameCount: integer

Frames played, from frame 0 (row-major from the top-left cell); 0 = every frame. At most Columns x Rows, or, with a SpriteSheet, the sheet's frame count (larger values play every frame of the sheet). Range [0, 65536]: writes outside it are clamped with a warning.

ParticleSystem.TextureSheetMode#

lua

ParticleSystem.TextureSheetMode: "OverLifetime"|"FrameRate"

OverLifetime: TextureSheetCycles passes over the frames per lifetime. FrameRate: TextureSheetFrameRate frames per second of age. Written by name.

ParticleSystem.TextureSheetFrameRate#

lua

ParticleSystem.TextureSheetFrameRate: number

Frames per second of particle age (TextureSheetMode FrameRate). Range [0, 10000]: writes outside it are clamped with a warning.

ParticleSystem.TextureSheetCycles#

lua

ParticleSystem.TextureSheetCycles: number

Passes over the frames per particle lifetime (TextureSheetMode OverLifetime). Range [0.001, 10000]: writes outside it are clamped with a warning.

ParticleSystem.TextureSheetRandomStartFrame#

lua

ParticleSystem.TextureSheetRandomStartFrame: boolean

Starts each particle on a random frame.

ParticleSystem.Texture#

lua

ParticleSystem.Texture: integer?

Particle texture; none uses the built-in particle texture (or the SpriteSheet's texture when one is set). Asset handle of a Texture2D (nil when none); writes also accept a virtual path such as "Assets/...".

ParticleSystem.SpriteSheet#

lua

ParticleSystem.SpriteSheet: integer?

Optional sprite sheet whose frames are the texture sheet frames (frame i of a particle = frame i of the sheet). Asset handle of a SpriteSheet (nil when none); writes also accept a virtual path such as "Assets/...".

ParticleSystem.BlendMode#

lua

ParticleSystem.BlendMode: "AlphaBlend"|"Additive"

How particles blend with what is behind them. Written by name.

ParticleSystem.Layer#

lua

ParticleSystem.Layer: integer

Render layer index (0-31, named in the project settings). Layers draw in ascending order; cameras cull by layer mask. Range [0, 31]: writes outside it are clamped with a warning.

ParticleSystem.OrderInLayer#

lua

ParticleSystem.OrderInLayer: integer

Draw order inside the render layer (int16 range); higher values draw in front. Ties are resolved by Translation.z. Range [-32768, 32767]: writes outside it are clamped with a warning.

ParticleSystem.RandomSeed#

lua

ParticleSystem.RandomSeed: integer

Seed of the emitter's random sequence (identical particles on every play); 0 = a different sequence every time.

ParticleSystem.SimulationMode#

lua

ParticleSystem.SimulationMode: "CPU"|"GPU"

CPU: simulated by the ParticleSystem scene system. GPU: simulated by the renderer's compute path. Written by name.

ParticleSystem:Play#

lua

ParticleSystem:Play(): boolean

Starts emitting (after the StartDelay; looping emitters with Prewarm start with a full cycle simulated), or resumes a paused emitter.

Returns boolean

Example

lua

self.Entity:GetComponent("ParticleSystem"):Play()

ParticleSystem:Stop#

lua

ParticleSystem:Stop(behavior?: ParticleStopBehavior): boolean

Stops emitting and rewinds the emission cycle; with ParticleStopBehavior.StopEmittingAndClear the live particles are removed too (default: they finish their lifetime).

Parameters

behavior? (ParticleStopBehavior)

Returns boolean

Example

lua

emitter:Stop(ParticleStopBehavior.StopEmittingAndClear)

ParticleSystem:Pause#

lua

ParticleSystem:Pause(): boolean

Freezes the particles and the emission until Play.

Returns boolean

ParticleSystem:Clear#

lua

ParticleSystem:Clear(): boolean

Removes every live particle; the playback state is unchanged.

Returns boolean

ParticleSystem:Emit#

lua

ParticleSystem:Emit(count: integer): integer

Spawns up to count particles at once at the emitter's current position, whatever the playback state, and returns how many were spawned (the rest did not fit into MaxParticles).

Parameters

count (integer)

Returns integer

Example

lua

emitter:Emit(30) -- a burst on impact

ParticleSystem:IsPlaying#

lua

ParticleSystem:IsPlaying(): boolean

True while the emitter emits (not paused or stopped).

Returns boolean

ParticleSystem:IsAlive#

lua

ParticleSystem:IsAlive(): boolean

True while the emitter emits or particles are alive (false once a stopped or finished emitter has none left).

Returns boolean

Example

lua

if not emitter:IsAlive() then self.Entity:Destroy() end

ParticleSystem:GetParticleCount#

lua

ParticleSystem:GetParticleCount(): integer

The number of live particles.

Returns integer

PatrolPath#

A path NPCs walk (the behaviour tree's Patrol node, a spawner's PatrolPath): 2-64 Points local to the entity, edited with the viewport's shape handles.

lua

local component = self.Entity:GetComponent("PatrolPath")

Member	Kind	Summary
`PatrolPath.Mode: "Loop"\|"PingPong"\|"Once"`	Property	Loop returns to the first point after the last; PingPong walks back along the path; Once stops at the last point (the Patrol node succeeds).
`PatrolPath.WaitMinSeconds: number`	Property	The shortest wait at each point (seconds, drawn uniformly up to WaitMaxSeconds).
`PatrolPath.WaitMaxSeconds: number`	Property	The longest wait at each point (at least WaitMinSeconds is used).
`PatrolPath.SpeedScale: number`	Property	The fraction of the walking NPC's NavAgent speed it patrols at.

PatrolPath.Mode#

lua

PatrolPath.Mode: "Loop"|"PingPong"|"Once"

Loop returns to the first point after the last; PingPong walks back along the path; Once stops at the last point (the Patrol node succeeds). Written by name.

PatrolPath.WaitMinSeconds#

lua

PatrolPath.WaitMinSeconds: number

The shortest wait at each point (seconds, drawn uniformly up to WaitMaxSeconds). Range [0, 3600]: writes outside it are clamped with a warning.

PatrolPath.WaitMaxSeconds#

lua

PatrolPath.WaitMaxSeconds: number

The longest wait at each point (at least WaitMinSeconds is used). Range [0, 3600]: writes outside it are clamped with a warning.

PatrolPath.SpeedScale#

lua

PatrolPath.SpeedScale: number

The fraction of the walking NPC's NavAgent speed it patrols at. Range [0.05, 16]: writes outside it are clamped with a warning.

Perceptible#

Something NPC perception can sense: players (from their prefab) and anything else of a team NPCs care about.

lua

local component = self.Entity:GetComponent("Perceptible")

Member	Kind	Summary
`Perceptible.Team: integer`	Property	The team (0-31) perceivers match against their TargetTeams.
`Perceptible.Stealth: number`	Property	0 is plainly visible; 1 is invisible: perceivers' sight and hearing radii shrink by this fraction.
`Perceptible.Enabled: boolean`	Property	Whether perceivers can sense it (a disabled target is lost at the next update).

Perceptible.Team#

lua

Perceptible.Team: integer

The team (0-31) perceivers match against their TargetTeams. Range [0, 31]: writes outside it are clamped with a warning.

Perceptible.Stealth#

lua

Perceptible.Stealth: number

0 is plainly visible; 1 is invisible: perceivers' sight and hearing radii shrink by this fraction. Range [0, 1]: writes outside it are clamped with a warning.

Perceptible.Enabled#

lua

Perceptible.Enabled: boolean

Whether perceivers can sense it (a disabled target is lost at the next update).

Perception#

What an NPC senses (servers and offline games): perceptibles of its TargetTeams within SightRadius inside its field of view (with a clear line on the navigation grid when RequireLineOfSight) or within HearingRadius, and noises (Perception.MakeNoise). Results go to the behaviour tree's Target, TargetDistance, LastKnownPosition and NoisePosition keys, as the events TargetAcquired, TargetLost and NoiseHeard and as OnPerceived / OnTargetLost on the NPC's script.

lua

local component = self.Entity:GetComponent("Perception")

Member	Kind	Summary
`Perception.SightRadius: number`	Property	World units within which a target inside the field of view is seen (scaled by the target's 1 - Stealth).
`Perception.FieldOfViewDegrees: number`	Property	The width of the sight cone in degrees, centred on the NPC's facing (its movement direction, else its rotation); 360 sees all around.
`Perception.LoseSightRadius: number`	Property	A tracked target stays tracked within this many world units (at least SightRadius) in every direction while the line of sight holds; beyond it, or unseen for 5 seconds, it is lost.
`Perception.HearingRadius: number`	Property	World units within which targets are heard in every direction, without a line of sight (scaled by 1 - Stealth); 0 is deaf, also to noises.
`Perception.RequireLineOfSight: boolean`	Property	Sight needs a clear line on the navigation grid (walls block it).
`Perception.UpdateIntervalMs: number`	Property	Milliseconds between two updates of this perceiver; perceivers are staggered by a hash of their UUID.
`Perception.TargetTeams: integer`	Property	Bit i set: perceptibles of team i are targets (all teams by default).
`Perception.MaxTargets: integer`	Property	Targets tracked at once, the highest scores (nearest) first.

Perception.SightRadius#

lua

Perception.SightRadius: number

World units within which a target inside the field of view is seen (scaled by the target's 1 - Stealth). Range [0, 1000]: writes outside it are clamped with a warning.

Perception.FieldOfViewDegrees#

lua

Perception.FieldOfViewDegrees: number

The width of the sight cone in degrees, centred on the NPC's facing (its movement direction, else its rotation); 360 sees all around. Range [1, 360]: writes outside it are clamped with a warning.

Perception.LoseSightRadius#

lua

Perception.LoseSightRadius: number

A tracked target stays tracked within this many world units (at least SightRadius) in every direction while the line of sight holds; beyond it, or unseen for 5 seconds, it is lost. Range [0, 1000]: writes outside it are clamped with a warning.

Perception.HearingRadius#

lua

Perception.HearingRadius: number

World units within which targets are heard in every direction, without a line of sight (scaled by 1 - Stealth); 0 is deaf, also to noises. Range [0, 1000]: writes outside it are clamped with a warning.

Perception.RequireLineOfSight#

lua

Perception.RequireLineOfSight: boolean

Sight needs a clear line on the navigation grid (walls block it). Scenes without navigation have no walls to test.

Perception.UpdateIntervalMs#

lua

Perception.UpdateIntervalMs: number

Milliseconds between two updates of this perceiver; perceivers are staggered by a hash of their UUID. Range [50, 60000]: writes outside it are clamped with a warning.

Perception.TargetTeams#

lua

Perception.TargetTeams: integer

Bit i set: perceptibles of team i are targets (all teams by default). Range [0, 4294967295]: writes outside it are clamped with a warning.

Perception.MaxTargets#

lua

Perception.MaxTargets: integer

Targets tracked at once, the highest scores (nearest) first. Range [1, 8]: writes outside it are clamped with a warning.

Persistence#

Saves the entity's persistent state on a server: its components' Persistent fields, its scripts' Persistent properties and its scope's data fields (Persistence.Get/Set). Character: the avatar of the player that owns it (its character record, loaded when the player connects and applied when the avatar spawns). World: a persistent object of the zone, keyed by the entity's ID (loaded when the zone starts).

lua

local component = self.Entity:GetComponent("Persistence")

Member	Kind	Summary
`Persistence.Scope: "Character"\|"World"`	Property	Character: a player's avatar (owned through its NetworkIdentity, or the local player offline).
`Persistence.IncludeChildren: boolean`	Property	Also saves the Persistent fields of the entity's descendants (by their path of names below the entity: renaming a child loses its saved values).
`Persistence.SaveTransform: boolean`	Property	Also saves the Transform (position, rotation, scale; of the descendants too with IncludeChildren) and restores it when the entity loads: where a player logged out, where a placed object stands.
`Persistence.AutosaveSeconds: number`	Property	Seconds between saves while the state changes; it is always saved on logout, zone shutdown and Persistence.SaveNow.

Persistence.Scope#

lua

Persistence.Scope: "Character"|"World"

Character: a player's avatar (owned through its NetworkIdentity, or the local player offline). World: an object of the zone. Written by name.

Persistence.IncludeChildren#

lua

Persistence.IncludeChildren: boolean

Also saves the Persistent fields of the entity's descendants (by their path of names below the entity: renaming a child loses its saved values).

Persistence.SaveTransform#

lua

Persistence.SaveTransform: boolean

Also saves the Transform (position, rotation, scale; of the descendants too with IncludeChildren) and restores it when the entity loads: where a player logged out, where a placed object stands.

Persistence.AutosaveSeconds#

lua

Persistence.AutosaveSeconds: number

Seconds between saves while the state changes; it is always saved on logout, zone shutdown and Persistence.SaveNow. Range [1, 3600]: writes outside it are clamped with a warning.

PhaseVolume#

A phased area (servers): NPCs spawned inside get its phase, and players entering raise OnPhaseVolumeEntered(player, phase) so the game can put them in it.

lua

local component = self.Entity:GetComponent("PhaseVolume")

Member	Kind	Summary
`PhaseVolume.Phase: integer`	Property	The phase (NetworkRelevancy.Phase; 0 = every phase).
`PhaseVolume.ApplyToSpawns: boolean`	Property	Whether NPCs spawned inside get the phase.

PhaseVolume.Phase#

lua

PhaseVolume.Phase: integer

The phase (NetworkRelevancy.Phase; 0 = every phase). Range [0, 65535]: writes outside it are clamped with a warning.

PhaseVolume.ApplyToSpawns#

lua

PhaseVolume.ApplyToSpawns: boolean

Whether NPCs spawned inside get the phase.

PolygonCollider2D#

Polygon collision shape from an outline of 3-8 points. A simple outline is used exactly, convex or concave (concave outlines are decomposed into convex pieces); points that do not form a simple outline (crossing edges) fall back to their convex hull, with a warning. Neighbouring points closer than 0.02 world units (after scaling) are merged and points within 0.01 of the line through their neighbours are dropped; an outline left with fewer than 3 points has no shape at all, with an error in the log. JSON "Points": [[x, y], ...] in local space.

lua

local component = self.Entity:GetComponent("PolygonCollider2D")

Member	Kind	Summary
`PolygonCollider2D.Offset: Vec2`	Property	Offset added to every point (local space).
`PolygonCollider2D.Radius: number`	Property	Rounding radius of the polygon's corners in world units (scaled by the larger transform scale; 0 = sharp).
`PolygonCollider2D.Density: number`	Property	Mass per unit area (kg/m^2) used to compute the body's mass.
`PolygonCollider2D.Friction: number`	Property	Coulomb friction coefficient (usually 0-1).
`PolygonCollider2D.Restitution: number`	Property	Bounciness (0 = no bounce, 1 = perfectly elastic).
`PolygonCollider2D.IsSensor: boolean`	Property	Sensors detect overlaps (OnTriggerEnter/Exit) but do not collide.
`PolygonCollider2D.Layer: integer`	Property	Physics layer index (0-31, named in the project settings); the collision matrix decides which layers collide.

PolygonCollider2D.Offset#

lua

PolygonCollider2D.Offset: Vec2

Offset added to every point (local space).

PolygonCollider2D.Radius#

lua

PolygonCollider2D.Radius: number

Rounding radius of the polygon's corners in world units (scaled by the larger transform scale; 0 = sharp). A concave outline with a radius uses its convex hull (rounded pieces would overlap), with a warning. Range [0, inf]: writes outside it are clamped with a warning.

PolygonCollider2D.Density#

lua

PolygonCollider2D.Density: number

Mass per unit area (kg/m^2) used to compute the body's mass. 0 makes the shape massless. Range [0, inf]: writes outside it are clamped with a warning.

PolygonCollider2D.Friction#

lua

PolygonCollider2D.Friction: number

Coulomb friction coefficient (usually 0-1). Combined with the other shape's friction by the geometric mean. Range [0, inf]: writes outside it are clamped with a warning.

PolygonCollider2D.Restitution#

lua

PolygonCollider2D.Restitution: number

Bounciness (0 = no bounce, 1 = perfectly elastic). Combined with the other shape by the maximum. Range [0, 1]: writes outside it are clamped with a warning.

PolygonCollider2D.IsSensor#

lua

PolygonCollider2D.IsSensor: boolean

Sensors detect overlaps (OnTriggerEnter/Exit) but do not collide.

PolygonCollider2D.Layer#

lua

PolygonCollider2D.Layer: integer

Physics layer index (0-31, named in the project settings); the collision matrix decides which layers collide. Range [0, 31]: writes outside it are clamped with a warning.

Portal#

A server portal activated by the character avatar entering its sensor collider. Zone and layer portals begin a handoff; instance portals reserve a group instance. ArrivalPosition is {Cell: [x, y], Local: [x, y]} in the component JSON: where a zone portal's player arrives. Instance portals ignore it: players entering an instance arrive at its template's Arrival in the realm topology (content validation warns, V020). Requires a trigger collider on this entity or a child.

lua

local component = self.Entity:GetComponent("Portal")

Member	Kind	Summary
`Portal.Destination: "Zone"\|"Instance"\|"Layer"`	Property	The kind of destination: a topology zone, instance template, or layer of the current zone.
`Portal.Target: string`	Property	Topology zone or instance template name; for Layer, the destination layer number in [1, 64].
`Portal.RequireParty: boolean`	Property	Instance portals: the whole party enters together.
`Portal.CooldownSeconds: number`	Property	Seconds after arriving by handoff during which this portal cannot send the character back.

Portal.Destination#

lua

Portal.Destination: "Zone"|"Instance"|"Layer"

The kind of destination: a topology zone, instance template, or layer of the current zone. Written by name.

Portal.Target#

lua

Portal.Target: string

Topology zone or instance template name; for Layer, the destination layer number in [1, 64].

Portal.RequireParty#

lua

Portal.RequireParty: boolean

Instance portals: the whole party enters together. Only the party's leader may use the portal, and every member must be online; a ready check (Social.json's ReadyCheckSeconds) asks each member, and once all accept, one instance is reserved for the party and every member is moved there, wherever they stand. Refused without a party, for another member than the leader, while a member is offline or declines, or when the check times out. Off: the character enters alone.

Portal.CooldownSeconds#

lua

Portal.CooldownSeconds: number

Seconds after arriving by handoff during which this portal cannot send the character back. Range [0, 60]: writes outside it are clamped with a warning.

PrefabInstance#

Links an entity created from a prefab to the prefab asset (removing it unpacks the instance).

lua

local component = self.Entity:GetComponent("PrefabInstance")

Member	Kind	Summary
`PrefabInstance.Prefab: integer? (read-only)`	Property	The prefab asset this entity was instantiated from.
`PrefabInstance.PrefabEntityId: integer (read-only)`	Property	Local id of the corresponding entity inside the prefab document.
`PrefabInstance.IsRoot: boolean (read-only)`	Property	Whether this entity is the root of the prefab instance.

PrefabInstance.Prefab#

lua

PrefabInstance.Prefab: integer? (read-only)

The prefab asset this entity was instantiated from. Asset handle of a Prefab (nil when none); writes also accept a virtual path such as "Assets/...". Read-only.

PrefabInstance.PrefabEntityId#

lua

PrefabInstance.PrefabEntityId: integer (read-only)

Local id of the corresponding entity inside the prefab document. Read-only.

PrefabInstance.IsRoot#

lua

PrefabInstance.IsRoot: boolean (read-only)

Whether this entity is the root of the prefab instance. Read-only.

PrismaticJoint2D#

Lets the bodies slide relative to each other along an axis without rotating (pistons, elevators).

lua

local component = self.Entity:GetComponent("PrismaticJoint2D")

Member	Kind	Summary
`PrismaticJoint2D.ConnectedEntity: Entity?`	Property	The other body of the joint (an entity with a Rigidbody2D).
`PrismaticJoint2D.Anchor: Vec2`	Property	Joint anchor in this entity's local space (world units).
`PrismaticJoint2D.ConnectedAnchor: Vec2`	Property	Joint anchor in the connected entity's local space (world space when anchored to the world).
`PrismaticJoint2D.CollideConnected: boolean`	Property	Whether the two connected bodies still collide with each other.
`PrismaticJoint2D.Axis: Vec2`	Property	Slide direction in this entity's local space (normalized by the physics system).
`PrismaticJoint2D.EnableSpring: boolean`	Property	Makes the translation (towards zero) soft: it behaves like a spring with the given frequency and damping.
`PrismaticJoint2D.Hertz: number`	Property	Spring stiffness as an oscillation frequency in Hz (0 = rigid).
`PrismaticJoint2D.DampingRatio: number`	Property	Spring damping ratio (0 = no damping, 1 = critical damping).
`PrismaticJoint2D.EnableLimit: boolean`	Property	Restricts the translation to [LowerTranslation, UpperTranslation].
`PrismaticJoint2D.LowerTranslation: number`	Property	Lower translation limit in world units.
`PrismaticJoint2D.UpperTranslation: number`	Property	Upper translation limit in world units.
`PrismaticJoint2D.EnableMotor: boolean`	Property	Drives the translation at MotorSpeed.
`PrismaticJoint2D.MaxMotorForce: number`	Property	Maximum motor force in newtons.
`PrismaticJoint2D.MotorSpeed: number`	Property	Target translation speed in world units per second.

PrismaticJoint2D.ConnectedEntity#

lua

PrismaticJoint2D.ConnectedEntity: Entity?

The other body of the joint (an entity with a Rigidbody2D). None anchors the joint to the world. Writes accept an Entity, an entity ID or nil.

PrismaticJoint2D.Anchor#

lua

PrismaticJoint2D.Anchor: Vec2

Joint anchor in this entity's local space (world units).

PrismaticJoint2D.ConnectedAnchor#

lua

PrismaticJoint2D.ConnectedAnchor: Vec2

Joint anchor in the connected entity's local space (world space when anchored to the world).

PrismaticJoint2D.CollideConnected#

lua

PrismaticJoint2D.CollideConnected: boolean

Whether the two connected bodies still collide with each other.

PrismaticJoint2D.Axis#

lua

PrismaticJoint2D.Axis: Vec2

Slide direction in this entity's local space (normalized by the physics system).

PrismaticJoint2D.EnableSpring#

lua

PrismaticJoint2D.EnableSpring: boolean

Makes the translation (towards zero) soft: it behaves like a spring with the given frequency and damping.

PrismaticJoint2D.Hertz#

lua

PrismaticJoint2D.Hertz: number

Spring stiffness as an oscillation frequency in Hz (0 = rigid). Range [0, inf]: writes outside it are clamped with a warning.

PrismaticJoint2D.DampingRatio#

lua

PrismaticJoint2D.DampingRatio: number

Spring damping ratio (0 = no damping, 1 = critical damping). Range [0, inf]: writes outside it are clamped with a warning.

PrismaticJoint2D.EnableLimit#

lua

PrismaticJoint2D.EnableLimit: boolean

Restricts the translation to [LowerTranslation, UpperTranslation].

PrismaticJoint2D.LowerTranslation#

lua

PrismaticJoint2D.LowerTranslation: number

Lower translation limit in world units.

PrismaticJoint2D.UpperTranslation#

lua

PrismaticJoint2D.UpperTranslation: number

Upper translation limit in world units.

PrismaticJoint2D.EnableMotor#

lua

PrismaticJoint2D.EnableMotor: boolean

Drives the translation at MotorSpeed.

PrismaticJoint2D.MaxMotorForce#

lua

PrismaticJoint2D.MaxMotorForce: number

Maximum motor force in newtons. Range [0, inf]: writes outside it are clamped with a warning.

PrismaticJoint2D.MotorSpeed#

lua

PrismaticJoint2D.MotorSpeed: number

Target translation speed in world units per second.

PvPVolume#

The player-versus-player rules of an area (Volumes.GetPvPMode, for the game's combat rules): clients and servers give the same answer, both read the cell.

lua

local component = self.Entity:GetComponent("PvPVolume")

Member	Kind	Summary
`PvPVolume.Mode: "Sanctuary"\|"Contested"\|"FreeForAll"\|"Arena"`	Property	Sanctuary: no player combat; Contested: combat between enemies; FreeForAll: everyone may fight; Arena: an arena's rules.
`PvPVolume.Priority: integer`	Property	Where PvP volumes overlap, the highest priority containing a point decides (validation reports exclusive overlaps of equal priority).

PvPVolume.Mode#

lua

PvPVolume.Mode: "Sanctuary"|"Contested"|"FreeForAll"|"Arena"

Sanctuary: no player combat; Contested: combat between enemies; FreeForAll: everyone may fight; Arena: an arena's rules. Written by name.

PvPVolume.Priority#

lua

PvPVolume.Priority: integer

Where PvP volumes overlap, the highest priority containing a point decides (validation reports exclusive overlaps of equal priority).

RegionVolume#

A named region (map labels, discovery, the region a player is in): tracked entities get OnRegionChanged(entity, region, previous) when the highest-priority region containing them changes.

lua

local component = self.Entity:GetComponent("RegionVolume")

Member	Kind	Summary
`RegionVolume.Name: string`	Property	The region's id, 1-64 characters of A-Z, a-z, 0-9, '_', '.' and '-': unique in a world (validation reports duplicates, e.g.
`RegionVolume.DisplayName: string`	Property	The name players see (map labels, a region banner); empty uses Name.
`RegionVolume.Priority: integer`	Property	Where regions overlap, the highest priority containing a point is that point's region.
`RegionVolume.ShowOnMap: boolean`	Property	Whether maps show the region's name.

RegionVolume.Name#

lua

RegionVolume.Name: string

The region's id, 1-64 characters of A-Z, a-z, 0-9, '_', '.' and '-': unique in a world (validation reports duplicates, e.g. after copying cells).

RegionVolume.DisplayName#

lua

RegionVolume.DisplayName: string

The name players see (map labels, a region banner); empty uses Name.

RegionVolume.Priority#

lua

RegionVolume.Priority: integer

Where regions overlap, the highest priority containing a point is that point's region.

RegionVolume.ShowOnMap#

lua

RegionVolume.ShowOnMap: boolean

Whether maps show the region's name.

Relationship#

Parent/children links of the hierarchy, by entity UUID. Change it through Scene.SetParent so both sides stay consistent. JSON: "Parent" plus "Children": [ids in sibling order].

lua

local component = self.Entity:GetComponent("Relationship")

Member	Kind	Summary
`Relationship.Parent: Entity? (read-only)`	Property	The parent entity; none for root entities.

Relationship.Parent#

lua

Relationship.Parent: Entity? (read-only)

The parent entity; none for root entities. Writes accept an Entity, an entity ID or nil. Read-only.

ResourceNode#

A gathering node (ore, a tree, a herb) players gather from with a Gather request of the RPG lane: the GatheringNode row names the skill level, tool, loot table, charges and respawn time (servers and offline games with an RPG store). At zero charges it is Depleted until it respawns; the respawn time survives zone restarts (the node's World-scope persistent record).

lua

local component = self.Entity:GetComponent("ResourceNode")

Member	Kind	Summary
`ResourceNode.Node: string`	Property	The GatheringNode row (of any table of the GatheringNode family) the node gathers by.
`ResourceNode.Depleted: boolean (read-only)`	Property	Run time, written by the server and replicated: the node has no charges left and waits to respawn.
`ResourceNode.RespawnState: string (read-only)`	Property	Run time: the charges left and the respawn time (UTC milliseconds), kept in the node's persistent record.

ResourceNode.Node#

lua

ResourceNode.Node: string

The GatheringNode row (of any table of the GatheringNode family) the node gathers by.

ResourceNode.Depleted#

lua

ResourceNode.Depleted: boolean (read-only)

Run time, written by the server and replicated: the node has no charges left and waits to respawn. Read-only. Replicated: on networked entities the authority's value reaches every peer.

ResourceNode.RespawnState#

lua

ResourceNode.RespawnState: string (read-only)

Run time: the charges left and the respawn time (UTC milliseconds), kept in the node's persistent record. Read-only. Persistent: saved with the entity's persistent record (PersistenceComponent).

RevoluteJoint2D#

Pins two bodies at a shared point around which they rotate (hinges, wheels, ragdolls).

lua

local component = self.Entity:GetComponent("RevoluteJoint2D")

Member	Kind	Summary
`RevoluteJoint2D.ConnectedEntity: Entity?`	Property	The other body of the joint (an entity with a Rigidbody2D).
`RevoluteJoint2D.Anchor: Vec2`	Property	Joint anchor in this entity's local space (world units).
`RevoluteJoint2D.ConnectedAnchor: Vec2`	Property	Joint anchor in the connected entity's local space (world space when anchored to the world).
`RevoluteJoint2D.CollideConnected: boolean`	Property	Whether the two connected bodies still collide with each other.
`RevoluteJoint2D.EnableSpring: boolean`	Property	Makes the rotation (towards the reference angle) soft: it behaves like a spring with the given frequency and damping.
`RevoluteJoint2D.Hertz: number`	Property	Spring stiffness as an oscillation frequency in Hz (0 = rigid).
`RevoluteJoint2D.DampingRatio: number`	Property	Spring damping ratio (0 = no damping, 1 = critical damping).
`RevoluteJoint2D.EnableLimit: boolean`	Property	Restricts the relative angle to [LowerAngle, UpperAngle].
`RevoluteJoint2D.LowerAngle: number`	Property	Lower angle limit in radians.
`RevoluteJoint2D.UpperAngle: number`	Property	Upper angle limit in radians.
`RevoluteJoint2D.EnableMotor: boolean`	Property	Drives the relative rotation at MotorSpeed.
`RevoluteJoint2D.MaxMotorTorque: number`	Property	Maximum motor torque in newton-meters.
`RevoluteJoint2D.MotorSpeed: number`	Property	Target relative angular speed in radians per second.

RevoluteJoint2D.ConnectedEntity#

lua

RevoluteJoint2D.ConnectedEntity: Entity?

The other body of the joint (an entity with a Rigidbody2D). None anchors the joint to the world. Writes accept an Entity, an entity ID or nil.

RevoluteJoint2D.Anchor#

lua

RevoluteJoint2D.Anchor: Vec2

Joint anchor in this entity's local space (world units).

RevoluteJoint2D.ConnectedAnchor#

lua

RevoluteJoint2D.ConnectedAnchor: Vec2

Joint anchor in the connected entity's local space (world space when anchored to the world).

RevoluteJoint2D.CollideConnected#

lua

RevoluteJoint2D.CollideConnected: boolean

Whether the two connected bodies still collide with each other.

RevoluteJoint2D.EnableSpring#

lua

RevoluteJoint2D.EnableSpring: boolean

Makes the rotation (towards the reference angle) soft: it behaves like a spring with the given frequency and damping.

RevoluteJoint2D.Hertz#

lua

RevoluteJoint2D.Hertz: number

Spring stiffness as an oscillation frequency in Hz (0 = rigid). Range [0, inf]: writes outside it are clamped with a warning.

RevoluteJoint2D.DampingRatio#

lua

RevoluteJoint2D.DampingRatio: number

Spring damping ratio (0 = no damping, 1 = critical damping). Range [0, inf]: writes outside it are clamped with a warning.

RevoluteJoint2D.EnableLimit#

lua

RevoluteJoint2D.EnableLimit: boolean

Restricts the relative angle to [LowerAngle, UpperAngle].

RevoluteJoint2D.LowerAngle#

lua

RevoluteJoint2D.LowerAngle: number

Lower angle limit in radians. Radians.

RevoluteJoint2D.UpperAngle#

lua

RevoluteJoint2D.UpperAngle: number

Upper angle limit in radians. Radians.

RevoluteJoint2D.EnableMotor#

lua

RevoluteJoint2D.EnableMotor: boolean

Drives the relative rotation at MotorSpeed.

RevoluteJoint2D.MaxMotorTorque#

lua

RevoluteJoint2D.MaxMotorTorque: number

Maximum motor torque in newton-meters. Range [0, inf]: writes outside it are clamped with a warning.

RevoluteJoint2D.MotorSpeed#

lua

RevoluteJoint2D.MotorSpeed: number

Target relative angular speed in radians per second. Radians.

Rigidbody2D#

Makes the entity a Box2D body at its world pose. Colliders on the entity and on descendants without their own Rigidbody2D become its shapes; the simulation writes the body's motion back into the transform.

lua

local component = self.Entity:GetComponent("Rigidbody2D")

Member	Kind	Summary
`Rigidbody2D.BodyType: "Static"\|"Dynamic"\|"Kinematic"`	Property	Static bodies are not simulated, dynamic bodies are, kinematic bodies move by their velocity.
`Rigidbody2D.GravityScale: number`	Property	Multiplier of the physics gravity (the scene gravity unless the physics system overrides it) for this body.
`Rigidbody2D.LinearDamping: number`	Property	Reduces the linear velocity over time (air resistance).
`Rigidbody2D.AngularDamping: number`	Property	Reduces the angular velocity over time.
`Rigidbody2D.FixedRotation: boolean`	Property	Prevents the body from rotating.
`Rigidbody2D.IsBullet: boolean`	Property	Continuous collision against dynamic bodies for fast-moving objects (more expensive).
`Rigidbody2D.InitialLinearVelocity: Vec2`	Property	Linear velocity (world units per second) when the body is created.
`Rigidbody2D.InitialAngularVelocity: number`	Property	Angular velocity (radians per second, counter-clockwise) when the body is created.
`Rigidbody2D.Enabled: boolean`	Property	Disabled bodies are removed from the simulation (no collisions) until enabled again.
`Rigidbody2D.Interpolate: boolean`	Property	Draws the body (and the entities attached to it) between its poses of the last two fixed steps instead of at the last one: smooth motion when the frame rate differs from the fixed step rate, at the cost of showing the body up to one step behind the simulation.
`Rigidbody2D:ApplyForce(force: Vec2, wake?: boolean)`	Method	Applies a world-space force (newtons) at the center of mass for the next fixed step; forces do not accumulate across steps, so apply them every OnFixedUpdate.
`Rigidbody2D:ApplyForceAtPoint(force: Vec2, point: Vec2, wake?: boolean)`	Method	Applies a world-space force at a world point (off-center forces also turn the body).
`Rigidbody2D:ApplyImpulse(impulse: Vec2, point?: Vec2, wake?: boolean)`	Method	Applies a world-space linear impulse (changes the velocity at once by impulse / mass) at the center of mass or at a world point.
`Rigidbody2D:ApplyTorque(torque: number, wake?: boolean)`	Method	Applies a torque (counter-clockwise positive) for the next fixed step.
`Rigidbody2D:ApplyAngularImpulse(impulse: number, wake?: boolean)`	Method	Applies an angular impulse (changes the angular velocity at once by impulse / rotational inertia).
`Rigidbody2D:GetLinearVelocity(): Vec2`	Method	The body's velocity in world units per second: what the simulation moves it with.
`Rigidbody2D:SetLinearVelocity(velocity: Vec2)`	Method	Sets the body's velocity (static bodies ignore it).
`Rigidbody2D:GetAngularVelocity(): number`	Method	The body's angular velocity in radians per second (counter-clockwise positive).
`Rigidbody2D:SetAngularVelocity(velocity: number)`	Method	Sets the angular velocity in radians per second.
`Rigidbody2D:GetMass(): number`	Method	The body's mass in kilograms (from its colliders' areas and densities; 0 for static and kinematic bodies).
`Rigidbody2D:SetMass(mass: number)`	Method	Overrides the mass of a dynamic body (> 0; the rotational inertia scales along) until its colliders are rebuilt or a collider's Density changes.
`Rigidbody2D:SetTransform(position: Vec2, rotation: number)`	Method	Teleports the body and its entity to a world position and rotation (radians, as the entity's Transform expresses it) at once: no sweep, no interpolation, the velocity is kept.
`Rigidbody2D:Teleport(position: Vec2, rotation?: number)`	Method	SetTransform that keeps the current rotation when rotation is omitted.
`Rigidbody2D:IsAwake(): boolean`	Method	False while the body sleeps (it came to rest; sleeping bodies cost almost nothing until something touches them).
`Rigidbody2D:WakeUp()`	Method	Wakes a sleeping body (and the bodies resting on it).
`Rigidbody2D:Sleep()`	Method	Puts the body (and the bodies it touches) to sleep until a force, contact or velocity change wakes it again.

Rigidbody2D.BodyType#

lua

Rigidbody2D.BodyType: "Static"|"Dynamic"|"Kinematic"

Static bodies are not simulated, dynamic bodies are, kinematic bodies move by their velocity. Editing the transform teleports static and dynamic bodies and sweeps kinematic ones to the new pose. Written by name.

Rigidbody2D.GravityScale#

lua

Rigidbody2D.GravityScale: number

Multiplier of the physics gravity (the scene gravity unless the physics system overrides it) for this body.

Rigidbody2D.LinearDamping#

lua

Rigidbody2D.LinearDamping: number

Reduces the linear velocity over time (air resistance). Range [0, inf]: writes outside it are clamped with a warning.

Rigidbody2D.AngularDamping#

lua

Rigidbody2D.AngularDamping: number

Reduces the angular velocity over time. Range [0, inf]: writes outside it are clamped with a warning.

Rigidbody2D.FixedRotation#

lua

Rigidbody2D.FixedRotation: boolean

Prevents the body from rotating.

Rigidbody2D.IsBullet#

lua

Rigidbody2D.IsBullet: boolean

Continuous collision against dynamic bodies for fast-moving objects (more expensive).

Rigidbody2D.InitialLinearVelocity#

lua

Rigidbody2D.InitialLinearVelocity: Vec2

Linear velocity (world units per second) when the body is created.

Rigidbody2D.InitialAngularVelocity#

lua

Rigidbody2D.InitialAngularVelocity: number

Angular velocity (radians per second, counter-clockwise) when the body is created. Radians.

Rigidbody2D.Enabled#

lua

Rigidbody2D.Enabled: boolean

Disabled bodies are removed from the simulation (no collisions) until enabled again.

Rigidbody2D.Interpolate#

lua

Rigidbody2D.Interpolate: boolean

Draws the body (and the entities attached to it) between its poses of the last two fixed steps instead of at the last one: smooth motion when the frame rate differs from the fixed step rate, at the cost of showing the body up to one step behind the simulation. Rendering only: scripts and physics keep the simulated pose.

Rigidbody2D:ApplyForce#

lua

Rigidbody2D:ApplyForce(force: Vec2, wake?: boolean)

Applies a world-space force (newtons) at the center of mass for the next fixed step; forces do not accumulate across steps, so apply them every OnFixedUpdate. A sleeping body ignores it unless wake (default true) is set; static bodies ignore it.

Parameters

force (Vec2)
wake? (boolean)

Example

lua

function Ship:OnFixedUpdate(dt)
	self.Body:ApplyForce(Vec2(0, self.Thrust))
end

Rigidbody2D:ApplyForceAtPoint#

lua

Rigidbody2D:ApplyForceAtPoint(force: Vec2, point: Vec2, wake?: boolean)

Applies a world-space force at a world point (off-center forces also turn the body).

Parameters

force (Vec2)
point (Vec2)
wake? (boolean)

Rigidbody2D:ApplyImpulse#

lua

Rigidbody2D:ApplyImpulse(impulse: Vec2, point?: Vec2, wake?: boolean)

Applies a world-space linear impulse (changes the velocity at once by impulse / mass) at the center of mass or at a world point.

Parameters

impulse (Vec2)
point? (Vec2)
wake? (boolean)

Example

lua

self.Body:ApplyImpulse(Vec2(0, self.JumpImpulse))

Rigidbody2D:ApplyTorque#

lua

Rigidbody2D:ApplyTorque(torque: number, wake?: boolean)

Applies a torque (counter-clockwise positive) for the next fixed step.

Parameters

torque (number)
wake? (boolean)

Rigidbody2D:ApplyAngularImpulse#

lua

Rigidbody2D:ApplyAngularImpulse(impulse: number, wake?: boolean)

Applies an angular impulse (changes the angular velocity at once by impulse / rotational inertia).

Parameters

impulse (number)
wake? (boolean)

Rigidbody2D:GetLinearVelocity#

lua

Rigidbody2D:GetLinearVelocity(): Vec2

The body's velocity in world units per second: what the simulation moves it with. A kinematic body moved by setting its Transform (not by SetLinearVelocity) reads (0, 0).

Returns Vec2

Rigidbody2D:SetLinearVelocity#

lua

Rigidbody2D:SetLinearVelocity(velocity: Vec2)

Sets the body's velocity (static bodies ignore it).

Parameters

velocity (Vec2)

Example

lua

local velocity = self.Body:GetLinearVelocity()
self.Body:SetLinearVelocity(Vec2(input * self.Speed, velocity.Y))

Rigidbody2D:GetAngularVelocity#

lua

Rigidbody2D:GetAngularVelocity(): number

The body's angular velocity in radians per second (counter-clockwise positive).

Returns number

Rigidbody2D:SetAngularVelocity#

lua

Rigidbody2D:SetAngularVelocity(velocity: number)

Sets the angular velocity in radians per second.

Parameters

velocity (number)

Rigidbody2D:GetMass#

lua

Rigidbody2D:GetMass(): number

The body's mass in kilograms (from its colliders' areas and densities; 0 for static and kinematic bodies).

Returns number

Rigidbody2D:SetMass#

lua

Rigidbody2D:SetMass(mass: number)

Overrides the mass of a dynamic body (> 0; the rotational inertia scales along) until its colliders are rebuilt or a collider's Density changes. Other body types raise an error.

Parameters

mass (number)

Rigidbody2D:SetTransform#

lua

Rigidbody2D:SetTransform(position: Vec2, rotation: number)

Teleports the body and its entity to a world position and rotation (radians, as the entity's Transform expresses it) at once: no sweep, no interpolation, the velocity is kept. Positions beyond the physics world range raise an error.

Parameters

position (Vec2)
rotation (number)

Example

lua

self.Body:SetTransform(self.SpawnPoint, 0)

Rigidbody2D:Teleport#

lua

Rigidbody2D:Teleport(position: Vec2, rotation?: number)

SetTransform that keeps the current rotation when rotation is omitted.

Parameters

position (Vec2)
rotation? (number)

Example

lua

self.Body:Teleport(Vec2(0, 5))

Rigidbody2D:IsAwake#

lua

Rigidbody2D:IsAwake(): boolean

False while the body sleeps (it came to rest; sleeping bodies cost almost nothing until something touches them).

Returns boolean

Rigidbody2D:WakeUp#

lua

Rigidbody2D:WakeUp()

Wakes a sleeping body (and the bodies resting on it).

Rigidbody2D:Sleep#

lua

Rigidbody2D:Sleep()

Puts the body (and the bodies it touches) to sleep until a force, contact or velocity change wakes it again.

RpgActor#

An actor of the RPG framework: a player character (Class) or an NPC (Template) whose stats, resources, status effects, combat state and faction the server's RPG store keeps. Its public state (health, resource, level, faction, states, cast, target, classification) replicates to every client; clients never write it.

lua

local component = self.Entity:GetComponent("RpgActor")

Member	Kind	Summary
`RpgActor.Template: string`	Property	NPCs: the NpcTemplate row whose stat profile, faction and level range the NPC has.
`RpgActor.Class: string`	Property	Player characters: the CharacterClass row whose stat profile and resource the character has.
`RpgActor.Level: integer`	Property	The actor's level: its stat profile's base values grow by PerLevel per level.
`RpgActor.Faction: string`	Property	The actor's Faction row; empty: its template's.
`RpgActor.Flags: integer`	Property	Game-defined bits, free for Lua.
`RpgActor.Persist: boolean`	Property	Whether the actor's RPG state is saved with its Persistence record (player characters).

RpgActor.Template#

lua

RpgActor.Template: string

NPCs: the NpcTemplate row whose stat profile, faction and level range the NPC has.

RpgActor.Class#

lua

RpgActor.Class: string

Player characters: the CharacterClass row whose stat profile and resource the character has.

RpgActor.Level#

lua

RpgActor.Level: integer

The actor's level: its stat profile's base values grow by PerLevel per level. Range [1, 1000]: writes outside it are clamped with a warning. Persistent: saved with the entity's persistent record (PersistenceComponent).

RpgActor.Faction#

lua

RpgActor.Faction: string

The actor's Faction row; empty: its template's.

RpgActor.Flags#

lua

RpgActor.Flags: integer

Game-defined bits, free for Lua.

RpgActor.Persist#

lua

RpgActor.Persist: boolean

Whether the actor's RPG state is saved with its Persistence record (player characters).

Script#

Runs a Lua script on the entity. Property values set in the editor are stored as overrides in "Fields": { "<Name>": <value> } (Bool, Int, Float, String and Vec2/3/4 as plain JSON values; types that cannot be inferred from the value, such as Entity, UInt, Color or typed assets, as { "Type": "Entity", "Value": 42 }; an asset property by the Type its script declares and a path or handle, e.g. { "Type": "Scene", "Value": "Assets/Scenes/Level2.fscene" }; an Enum property by its option's name; an Array property as { "Type": "Array", "ElementType": "Vec2", "Value": [[0, 0], [4, 0]] }).

lua

local component = self.Entity:GetComponent("Script")

Member	Kind	Summary
`Script.Script: integer?`	Property	The Lua script asset (a table with Properties and OnCreate/OnUpdate/...

Script.Script#

lua

Script.Script: integer?

The Lua script asset (a table with Properties and OnCreate/OnUpdate/... callbacks). Asset handle of a Script (nil when none); writes also accept a virtual path such as "Assets/...".

ShadowCaster2D#

Occluder that blocks shadow-casting 2D lights. JSON "Points": [[x, y], ...] (local polygon used when UseColliderShape is off; fewer than 3 points cast no shadow).

lua

local component = self.Entity:GetComponent("ShadowCaster2D")

Member	Kind	Summary
`ShadowCaster2D.UseColliderShape: boolean`	Property	Uses the entity's collider outline as the occluder instead of Points.
`ShadowCaster2D.SelfShadows: boolean`	Property	Whether the occluder also shadows its own sprite.

ShadowCaster2D.UseColliderShape#

lua

ShadowCaster2D.UseColliderShape: boolean

Uses the entity's collider outline as the occluder instead of Points.

ShadowCaster2D.SelfShadows#

lua

ShadowCaster2D.SelfShadows: boolean

Whether the occluder also shadows its own sprite.

SimulationSuspended#

Runtime authority suspension: scripts, timers, coroutines, RPCs, movement, AI and physics wait while a handoff owns this entity. Never saved, copied or replicated.

lua

local component = self.Entity:GetComponent("SimulationSuspended")

Member	Kind	Summary
`SimulationSuspended.OwnerToken: integer (read-only)`	Property	The runtime operation that owns the suspension.

SimulationSuspended.OwnerToken#

lua

SimulationSuspended.OwnerToken: integer (read-only)

The runtime operation that owns the suspension. Read-only.

SpawnedBy#

Run time: the spawner an NPC came from, its slot, its spawn point (home) and the patrol path it walks. Added by the spawner.

lua

local component = self.Entity:GetComponent("SpawnedBy")

Member	Kind	Summary
`SpawnedBy.Spawner: Entity? (read-only)`	Property	The spawner entity.
`SpawnedBy.Slot: integer (read-only)`	Property	The spawner's slot (0 to Count - 1) the NPC fills.
`SpawnedBy.Home: Vec2 (read-only)`	Property	The spawn point (scene position): ReturnHome walks here.
`SpawnedBy.PatrolPath: Entity? (read-only)`	Property	The spawner's patrol path entity (the Patrol node's default path).

SpawnedBy.Spawner#

lua

SpawnedBy.Spawner: Entity? (read-only)

The spawner entity. Writes accept an Entity, an entity ID or nil. Read-only.

SpawnedBy.Slot#

lua

SpawnedBy.Slot: integer (read-only)

The spawner's slot (0 to Count - 1) the NPC fills. Read-only.

SpawnedBy.Home#

lua

SpawnedBy.Home: Vec2 (read-only)

The spawn point (scene position): ReturnHome walks here. Read-only.

SpawnedBy.PatrolPath#

lua

SpawnedBy.PatrolPath: Entity? (read-only)

The spawner's patrol path entity (the Patrol node's default path). Writes accept an Entity, an entity ID or nil. Read-only.

Spawner#

Spawns Count NPCs around itself (servers and offline games) and respawns them after they die: a row of a SpawnTable table rolled per spawn, or a direct Prefab. Respawn times survive cell unloads and zone restarts (the spawner's World-scope persistent record).

lua

local component = self.Entity:GetComponent("Spawner")

Member	Kind	Summary
`Spawner.SpawnTable: integer?`	Property	A data table of the built-in SpawnTable schema; Entry names its row.
`Spawner.Entry: string`	Property	The row key of SpawnTable whose Entries (weighted prefabs) each spawn rolls.
`Spawner.Prefab: integer?`	Property	The prefab every spawn instantiates when no SpawnTable is set (a networked prefab spawns on every client).
`Spawner.Count: integer`	Property	How many NPCs (slots) the spawner keeps alive.
`Spawner.Area: Entity?`	Property	An entity with a VolumeShape: spawn points are reachable points inside it.
`Spawner.Radius: number`	Property	World units around the spawner spawn points are taken from when no Area is set.
`Spawner.RespawnMinSeconds: number`	Property	The shortest delay before a dead slot respawns (seconds; drawn uniformly up to RespawnMaxSeconds per death).
`Spawner.RespawnMaxSeconds: number`	Property	The longest respawn delay (at least RespawnMinSeconds is used).
`Spawner.RespawnRule: "Individual"\|"Wave"\|"Scripted"`	Property	Individual: each slot respawns after its own delay.
`Spawner.InitialDelaySeconds: number`	Property	Seconds after the spawner appears (scene start or cell load) before its first spawns.
`Spawner.PatrolPath: Entity?`	Property	An entity with a PatrolPath its NPCs walk (the behaviour tree's Patrol node).
`Spawner.LeashRadius: number`	Property	World units around its spawn point an alerted NPC may chase before it evades home (a Leash); 0 = no leash.
`Spawner.Behavior: integer?`	Property	A behaviour tree its NPCs run instead of their prefab's.
`Spawner.Phase: integer`	Property	The network phase its NPCs exist in (NetworkRelevancy.Phase); 0 = the phase of a PhaseVolume with ApplyToSpawns at the spawn point, if any.
`Spawner.Enabled: boolean`	Property	A disabled spawner spawns and respawns nothing; its NPCs stay.
`Spawner.RespawnState: string (read-only)`	Property	Run time: the dead slots and their respawn times (UTC milliseconds), kept in the spawner's persistent record.

Spawner.SpawnTable#

lua

Spawner.SpawnTable: integer?

A data table of the built-in SpawnTable schema; Entry names its row. Takes precedence over Prefab. Asset handle of a DataTable (nil when none); writes also accept a virtual path such as "Assets/...".

Spawner.Entry#

lua

Spawner.Entry: string

The row key of SpawnTable whose Entries (weighted prefabs) each spawn rolls.

Spawner.Prefab#

lua

Spawner.Prefab: integer?

The prefab every spawn instantiates when no SpawnTable is set (a networked prefab spawns on every client). Asset handle of a Prefab (nil when none); writes also accept a virtual path such as "Assets/...".

Spawner.Count#

lua

Spawner.Count: integer

How many NPCs (slots) the spawner keeps alive. Range [1, 256]: writes outside it are clamped with a warning.

Spawner.Area#

lua

Spawner.Area: Entity?

An entity with a VolumeShape: spawn points are reachable points inside it. None: within Radius of the spawner. Writes accept an Entity, an entity ID or nil.

Spawner.Radius#

lua

Spawner.Radius: number

World units around the spawner spawn points are taken from when no Area is set. Range [0, 1000]: writes outside it are clamped with a warning.

Spawner.RespawnMinSeconds#

lua

Spawner.RespawnMinSeconds: number

The shortest delay before a dead slot respawns (seconds; drawn uniformly up to RespawnMaxSeconds per death). Range [0, 604800]: writes outside it are clamped with a warning.

Spawner.RespawnMaxSeconds#

lua

Spawner.RespawnMaxSeconds: number

The longest respawn delay (at least RespawnMinSeconds is used). Range [0, 604800]: writes outside it are clamped with a warning.

Spawner.RespawnRule#

lua

Spawner.RespawnRule: "Individual"|"Wave"|"Scripted"

Individual: each slot respawns after its own delay. Wave: all slots respawn together once every one is dead. Scripted: a due slot respawns when the spawner's script's OnSpawnerRespawnDue(slot) allows it (or Spawner.Respawn). Written by name.

Spawner.InitialDelaySeconds#

lua

Spawner.InitialDelaySeconds: number

Seconds after the spawner appears (scene start or cell load) before its first spawns. Range [0, 86400]: writes outside it are clamped with a warning.

Spawner.PatrolPath#

lua

Spawner.PatrolPath: Entity?

An entity with a PatrolPath its NPCs walk (the behaviour tree's Patrol node). Writes accept an Entity, an entity ID or nil.

Spawner.LeashRadius#

lua

Spawner.LeashRadius: number

World units around its spawn point an alerted NPC may chase before it evades home (a Leash); 0 = no leash. Range [0, 10000]: writes outside it are clamped with a warning.

Spawner.Behavior#

lua

Spawner.Behavior: integer?

A behaviour tree its NPCs run instead of their prefab's. Asset handle of a BehaviorTree (nil when none); writes also accept a virtual path such as "Assets/...".

Spawner.Phase#

lua

Spawner.Phase: integer

The network phase its NPCs exist in (NetworkRelevancy.Phase); 0 = the phase of a PhaseVolume with ApplyToSpawns at the spawn point, if any. Range [0, 65535]: writes outside it are clamped with a warning.

Spawner.Enabled#

lua

Spawner.Enabled: boolean

A disabled spawner spawns and respawns nothing; its NPCs stay.

Spawner.RespawnState#

lua

Spawner.RespawnState: string (read-only)

Run time: the dead slots and their respawn times (UTC milliseconds), kept in the spawner's persistent record. Read-only. Persistent: saved with the entity's persistent record (PersistenceComponent).

SpriteAnimator#

Plays sprite animation clips (.fanim) on the entity's SpriteRenderer: every frame the animation system writes the clip's sprite sheet and current frame into SpriteRenderer.SpriteSheet and FrameIndex, and reports the clip's events. JSON: the fields below plus "Clips": [{ "Name", "Clip": asset }], the named clips code can play by name.

lua

local component = self.Entity:GetComponent("SpriteAnimator")

Member	Kind	Summary
`SpriteAnimator.Clip: integer?`	Property	Default clip: played on awake, and when the animator is told to play without naming a clip.
`SpriteAnimator.Speed: number`	Property	Playback speed multiplier (1 = the clip's own timing, 0 = frozen).
`SpriteAnimator.PlayOnAwake: boolean`	Property	Starts playing Clip when the scene starts running, or when the component appears in a running scene.
`SpriteAnimator.LoopOverride: "UseClip"\|"ForceLoop"\|"ForceOnce"`	Property	UseClip plays with the clip's loop mode; ForceLoop always loops; ForceOnce plays once and holds the last frame.
`SpriteAnimator:Play(clip?: integer\|string, restart?: boolean): boolean`	Method	Plays a clip: nil plays the component's default Clip, a name plays the clip of that name from the component's Clips, an asset handle (such as an AnimationClip property) or a virtual path ("Assets/...") plays that AnimationClip asset.
`SpriteAnimator:Stop(): boolean`	Method	Stops playback and rewinds to the clip's first frame.
`SpriteAnimator:Pause(): boolean`	Method	Freezes the animation on its current frame.
`SpriteAnimator:Resume(): boolean`	Method	Continues a paused animation.
`SpriteAnimator:IsPlaying(): boolean`	Method	True while a clip plays (not paused, stopped or finished, and the animator is awake: it wakes at the first animation update or playback call).
`SpriteAnimator:IsFinished(): boolean`	Method	True once a non-looping clip reached its end.
`SpriteAnimator:GetNormalizedTime(): number`	Method	The playhead as a fraction of the clip's length, in [0, 1] (0 without a clip).
`SpriteAnimator:SetSpeed(speed: number)`	Method	Sets the playback speed multiplier (the component's Speed, in [0, 1000]; 0 holds the frame).
`SpriteAnimator:GetCurrentClip(): integer?`	Method	The asset handle of the clip requested by the last Play (the default clip after an automatic start), or nil.

SpriteAnimator.Clip#

lua

SpriteAnimator.Clip: integer?

Default clip: played on awake, and when the animator is told to play without naming a clip. Asset handle of a AnimationClip (nil when none); writes also accept a virtual path such as "Assets/...".

SpriteAnimator.Speed#

lua

SpriteAnimator.Speed: number

Playback speed multiplier (1 = the clip's own timing, 0 = frozen). Range [0, 1000]: writes outside it are clamped with a warning. Replicated: on networked entities the authority's value reaches every peer.

SpriteAnimator.PlayOnAwake#

lua

SpriteAnimator.PlayOnAwake: boolean

Starts playing Clip when the scene starts running, or when the component appears in a running scene.

SpriteAnimator.LoopOverride#

lua

SpriteAnimator.LoopOverride: "UseClip"|"ForceLoop"|"ForceOnce"

UseClip plays with the clip's loop mode; ForceLoop always loops; ForceOnce plays once and holds the last frame. Written by name. Replicated: on networked entities the authority's value reaches every peer.

SpriteAnimator:Play#

lua

SpriteAnimator:Play(clip?: integer|string, restart?: boolean): boolean

Plays a clip: nil plays the component's default Clip, a name plays the clip of that name from the component's Clips, an asset handle (such as an AnimationClip property) or a virtual path ("Assets/...") plays that AnimationClip asset. With restart = false (default true) a clip that already plays continues and a paused one resumes. Returns false when the clip cannot be loaded. The new frame shows after the next animation update.

Parameters

clip? (integer|string): nil, a clip name of SpriteAnimator.Clips, an AnimationClip asset handle or a virtual path.
restart? (boolean)

Returns boolean

Example

lua

local animator = self.Entity:GetComponent("SpriteAnimator")
animator:Play("Run", false)

SpriteAnimator:Stop#

lua

SpriteAnimator:Stop(): boolean

Stops playback and rewinds to the clip's first frame.

Returns boolean

SpriteAnimator:Pause#

lua

SpriteAnimator:Pause(): boolean

Freezes the animation on its current frame.

Returns boolean

SpriteAnimator:Resume#

lua

SpriteAnimator:Resume(): boolean

Continues a paused animation.

Returns boolean

SpriteAnimator:IsPlaying#

lua

SpriteAnimator:IsPlaying(): boolean

True while a clip plays (not paused, stopped or finished, and the animator is awake: it wakes at the first animation update or playback call).

Returns boolean

SpriteAnimator:IsFinished#

lua

SpriteAnimator:IsFinished(): boolean

True once a non-looping clip reached its end.

Returns boolean

SpriteAnimator:GetNormalizedTime#

lua

SpriteAnimator:GetNormalizedTime(): number

The playhead as a fraction of the clip's length, in [0, 1] (0 without a clip).

Returns number

SpriteAnimator:SetSpeed#

lua

SpriteAnimator:SetSpeed(speed: number)

Sets the playback speed multiplier (the component's Speed, in [0, 1000]; 0 holds the frame). Other values raise an error.

Parameters

speed (number)

Example

lua

animator:SetSpeed(2)

SpriteAnimator:GetCurrentClip#

lua

SpriteAnimator:GetCurrentClip(): integer?

The asset handle of the clip requested by the last Play (the default clip after an automatic start), or nil.

Returns integer?

SpriteMask#

Invisible mask shape: the texels of Sprite whose alpha is above AlphaCutoff clip the SpriteRenderers of the render layers LayerRangeBack..LayerRangeFront that have a MaskInteraction (visible inside or outside the mask). Masks with the same layer range unite; up to 8 distinct layer ranges per frame. Text, tilemaps, particles and circles are never masked.

lua

local component = self.Entity:GetComponent("SpriteMask")

Member	Kind	Summary
`SpriteMask.Sprite: integer?`	Property	Texture whose alpha defines the mask shape, sized by its pixels per unit and centered on the entity; none masks a 1 x 1 unit square.
`SpriteMask.AlphaCutoff: number`	Property	Texels with alpha above this value are inside the mask.
`SpriteMask.LayerRangeFront: integer`	Property	Frontmost render layer affected by the mask (inclusive).
`SpriteMask.LayerRangeBack: integer`	Property	Backmost render layer affected by the mask (inclusive).

SpriteMask.Sprite#

lua

SpriteMask.Sprite: integer?

Texture whose alpha defines the mask shape, sized by its pixels per unit and centered on the entity; none masks a 1 x 1 unit square. Asset handle of a Texture2D (nil when none); writes also accept a virtual path such as "Assets/...".

SpriteMask.AlphaCutoff#

lua

SpriteMask.AlphaCutoff: number

Texels with alpha above this value are inside the mask. Range [0, 1]: writes outside it are clamped with a warning.

SpriteMask.LayerRangeFront#

lua

SpriteMask.LayerRangeFront: integer

Frontmost render layer affected by the mask (inclusive). Range [0, 31]: writes outside it are clamped with a warning.

SpriteMask.LayerRangeBack#

lua

SpriteMask.LayerRangeBack: integer

Backmost render layer affected by the mask (inclusive). Range [0, 31]: writes outside it are clamped with a warning.

SpriteRenderer#

Draws a textured (or solid color) quad at the entity's transform. JSON "MaterialOverrides": { "<Parameter>": { "Type", "Value" } } sets parameters of its material for this sprite only (the .fmat parameter format; Lua SetMaterialParameter / GetMaterialParameter): sprites with equal overrides share one material instance.

lua

local component = self.Entity:GetComponent("SpriteRenderer")

Member	Kind	Summary
`SpriteRenderer.Color: Color`	Property	Tint multiplied with the texture (RGBA, straight alpha).
`SpriteRenderer.Texture: integer?`	Property	Texture to draw: a texture, or a render texture showing what a camera renders into it (a minimap); none draws a solid quad in Color.
`SpriteRenderer.SpriteSheet: integer?`	Property	Optional sprite sheet; when set, FrameIndex selects the region of the sheet to draw.
`SpriteRenderer.FrameIndex: integer`	Property	Frame of the sprite sheet to draw (written by the SpriteAnimator while animating).
`SpriteRenderer.Pivot: Vec2`	Property	Normalized origin of the sprite: (0, 0) bottom-left, (0.5, 0.5) center, (1, 1) top-right.
`SpriteRenderer.FlipX: boolean`	Property	Mirrors the sprite horizontally (texture coordinates only; colliders are unaffected).
`SpriteRenderer.FlipY: boolean`	Property	Mirrors the sprite vertically (texture coordinates only).
`SpriteRenderer.DrawMode: "Simple"\|"Sliced"\|"Tiled"`	Property	Simple stretches the texture over Size; Sliced keeps the borders unscaled (nine-slice); Tiled repeats the texture.
`SpriteRenderer.SliceBorders: Vec4`	Property	Nine-slice borders in texture pixels: left, right, top, bottom (DrawMode Sliced).
`SpriteRenderer.Size: Vec2`	Property	Size in world units; (0, 0) derives it from the texture size and its pixels per unit (100 by default).
`SpriteRenderer.TilingFactor: number`	Property	Texture repetitions per sprite (DrawMode Tiled) or texture coordinate scale.
`SpriteRenderer.Material: integer?`	Property	Material (shader, blend mode, parameters); none uses the default sprite material.
`SpriteRenderer.Layer: integer`	Property	Render layer index (0-31, named in the project settings).
`SpriteRenderer.OrderInLayer: integer`	Property	Draw order inside the render layer (int16 range); higher values draw in front.
`SpriteRenderer.MaskInteraction: "None"\|"VisibleInsideMask"\|"VisibleOutsideMask"`	Property	How SpriteMask components affect this sprite: ignored, visible only where a mask whose layer range contains the sprite's Layer covers it (nowhere when no mask affects its layer), or only where none does.
`SpriteRenderer.CastsShadows: boolean`	Property	Whether the sprite's quad occludes shadow-casting 2D lights.
`SpriteRenderer.Lit: boolean`	Property	Whether 2D lights affect the sprite; they reach it only with a LIT material (Builtin/DefaultLitMaterial or an .fmat with the LIT feature) in views with lighting enabled.
`SpriteRenderer.Static: boolean`	Property	For scenery that rarely changes: the renderer keeps the sprite in its render world and draws it from there, so frames do no extraction work for it until it moves or changes (then it is sent again).
`SpriteRenderer:SetMaterialParameter(name: string, value: number\|Vec2\|Vec3\|Vec4\|Color\|integer\|string\|nil, type?: string)`	Method	Sets a parameter of the sprite's material for this sprite only (SpriteRenderer.MaterialOverrides): a MaterialParams member of its program, such as Tint, AlphaCutoff or EmissiveIntensity of the Sprite program.
`SpriteRenderer:GetMaterialParameter(name: string): number\|Vec2\|Vec3\|Vec4\|Color\|integer\|nil`	Method	This sprite's override of a material parameter (SetMaterialParameter): a number (Float), Vec2, Vec3, Vec4, Color, integer (Int, UInt, or a Texture's asset handle), or nil when the sprite does not override it (the material's value applies).

SpriteRenderer.Color#

lua

SpriteRenderer.Color: Color

Tint multiplied with the texture (RGBA, straight alpha). Writes also accept a Vec4 or Vec3 (alpha 1). Replicated: on networked entities the authority's value reaches every peer.

SpriteRenderer.Texture#

lua

SpriteRenderer.Texture: integer?

Texture to draw: a texture, or a render texture showing what a camera renders into it (a minimap); none draws a solid quad in Color. Asset handle of a Texture2D or a RenderTexture (nil when none); writes also accept a virtual path such as "Assets/...". Replicated: on networked entities the authority's value reaches every peer.

SpriteRenderer.SpriteSheet#

lua

SpriteRenderer.SpriteSheet: integer?

Optional sprite sheet; when set, FrameIndex selects the region of the sheet to draw. Asset handle of a SpriteSheet (nil when none); writes also accept a virtual path such as "Assets/...". Replicated: on networked entities the authority's value reaches every peer.

SpriteRenderer.FrameIndex#

lua

SpriteRenderer.FrameIndex: integer

Frame of the sprite sheet to draw (written by the SpriteAnimator while animating). Replicated: on networked entities the authority's value reaches every peer.

SpriteRenderer.Pivot#

lua

SpriteRenderer.Pivot: Vec2

Normalized origin of the sprite: (0, 0) bottom-left, (0.5, 0.5) center, (1, 1) top-right. Range [0, 1]: writes outside it are clamped with a warning.

SpriteRenderer.FlipX#

lua

SpriteRenderer.FlipX: boolean

Mirrors the sprite horizontally (texture coordinates only; colliders are unaffected). Replicated: on networked entities the authority's value reaches every peer.

SpriteRenderer.FlipY#

lua

SpriteRenderer.FlipY: boolean

Mirrors the sprite vertically (texture coordinates only). Replicated: on networked entities the authority's value reaches every peer.

SpriteRenderer.DrawMode#

lua

SpriteRenderer.DrawMode: "Simple"|"Sliced"|"Tiled"

Simple stretches the texture over Size; Sliced keeps the borders unscaled (nine-slice); Tiled repeats the texture. Written by name.

SpriteRenderer.SliceBorders#

lua

SpriteRenderer.SliceBorders: Vec4

Nine-slice borders in texture pixels: left, right, top, bottom (DrawMode Sliced). Range [0, inf]: writes outside it are clamped with a warning.

SpriteRenderer.Size#

lua

SpriteRenderer.Size: Vec2

Size in world units; (0, 0) derives it from the texture size and its pixels per unit (100 by default). Range [0, inf]: writes outside it are clamped with a warning.

SpriteRenderer.TilingFactor#

lua

SpriteRenderer.TilingFactor: number

Texture repetitions per sprite (DrawMode Tiled) or texture coordinate scale. Range [0, inf]: writes outside it are clamped with a warning.

SpriteRenderer.Material#

lua

SpriteRenderer.Material: integer?

Material (shader, blend mode, parameters); none uses the default sprite material. Asset handle of a Material (nil when none); writes also accept a virtual path such as "Assets/...".

SpriteRenderer.Layer#

lua

SpriteRenderer.Layer: integer

Render layer index (0-31, named in the project settings). Layers draw in ascending order; cameras cull by layer mask. Range [0, 31]: writes outside it are clamped with a warning. Replicated: on networked entities the authority's value reaches every peer.

SpriteRenderer.OrderInLayer#

lua

SpriteRenderer.OrderInLayer: integer

Draw order inside the render layer (int16 range); higher values draw in front. Ties are resolved by Translation.z. Range [-32768, 32767]: writes outside it are clamped with a warning. Replicated: on networked entities the authority's value reaches every peer.

SpriteRenderer.MaskInteraction#

lua

SpriteRenderer.MaskInteraction: "None"|"VisibleInsideMask"|"VisibleOutsideMask"

How SpriteMask components affect this sprite: ignored, visible only where a mask whose layer range contains the sprite's Layer covers it (nowhere when no mask affects its layer), or only where none does. Written by name.

SpriteRenderer.CastsShadows#

lua

SpriteRenderer.CastsShadows: boolean

Whether the sprite's quad occludes shadow-casting 2D lights.

SpriteRenderer.Lit#

lua

SpriteRenderer.Lit: boolean

Whether 2D lights affect the sprite; they reach it only with a LIT material (Builtin/DefaultLitMaterial or an .fmat with the LIT feature) in views with lighting enabled. With any other material, or Lit off, the sprite draws at full brightness.

SpriteRenderer.Static#

lua

SpriteRenderer.Static: boolean

For scenery that rarely changes: the renderer keeps the sprite in its render world and draws it from there, so frames do no extraction work for it until it moves or changes (then it is sent again). It draws exactly like a dynamic sprite; among sprites of equal sort order, static ones draw after dynamic ones. A sprite with MaterialOverrides is extracted every frame like a dynamic one.

SpriteRenderer:SetMaterialParameter#

lua

SpriteRenderer:SetMaterialParameter(name: string, value: number|Vec2|Vec3|Vec4|Color|integer|string|nil, type?: string)

Sets a parameter of the sprite's material for this sprite only (SpriteRenderer.MaterialOverrides): a MaterialParams member of its program, such as Tint, AlphaCutoff or EmissiveIntensity of the Sprite program. The type follows the value (number: Float, Vec2, Vec3, Vec4, Color) unless given: "Int" and "UInt" take integers, "Texture" a texture asset (handle or "Assets/..." path), "Color" a Color or Vec4 (sRGB). nil removes the override (the material's value applies again). Sprites with the same material and overrides share one material instance; the value draws in the same frame, also when it changes every frame (a fade, a flash). A Texture override draws once its texture has loaded. A parameter the material's program does not have is ignored by the renderer (logged). At most 16 overrides per sprite.

Parameters

name (string): The parameter (a MaterialParams member name).
value (number|Vec2|Vec3|Vec4|Color|integer|string|nil): The value, or nil to remove the override.
type? (string): Float, Vec2, Vec3, Vec4, Color, Int, UInt or Texture (default: from the value).

Example

lua

local sprite = self.Entity:GetComponent("SpriteRenderer")
sprite:SetMaterialParameter("Tint", Color(1, 0.4, 0.4))
sprite:SetMaterialParameter("Tint", nil) -- back to the material's tint

SpriteRenderer:GetMaterialParameter#

lua

SpriteRenderer:GetMaterialParameter(name: string): number|Vec2|Vec3|Vec4|Color|integer|nil

This sprite's override of a material parameter (SetMaterialParameter): a number (Float), Vec2, Vec3, Vec4, Color, integer (Int, UInt, or a Texture's asset handle), or nil when the sprite does not override it (the material's value applies).

Parameters

name (string): The parameter (a MaterialParams member name).

Returns number|Vec2|Vec3|Vec4|Color|integer|nil

Example

lua

local tint = sprite:GetMaterialParameter("Tint") -- a Color, or nil

Tag#

Display name of the entity, shown in the hierarchy and used by Scene.FindEntityByName.

lua

local component = self.Entity:GetComponent("Tag")

Member	Kind	Summary
`Tag.Tag: string`	Property	The entity's name (UTF-8, not required to be unique).

Tag.Tag#

lua

Tag.Tag: string

The entity's name (UTF-8, not required to be unique).

TextRenderer#

Draws text in the world (MSDF glyphs from a font asset).

lua

local component = self.Entity:GetComponent("TextRenderer")

Member	Kind	Summary
`TextRenderer.Text: string`	Property	UTF-8 text; line breaks start new lines.
`TextRenderer.Font: integer?`	Property	Font asset; none uses the engine's default font.
`TextRenderer.FontSize: number`	Property	Em size in world units.
`TextRenderer.Color: Color`	Property	Text color (RGBA, straight alpha).
`TextRenderer.HorizontalAlignment: "Left"\|"Center"\|"Right"`	Property	Horizontal alignment of every line relative to the entity's position.
`TextRenderer.VerticalAlignment: "Top"\|"Middle"\|"Bottom"`	Property	Vertical alignment of the text block relative to the entity's position.
`TextRenderer.MaxWidth: number`	Property	Wrap width in world units; 0 disables wrapping.
`TextRenderer.LineSpacing: number`	Property	Line height multiplier (1 = the font's line height).
`TextRenderer.LetterSpacing: number`	Property	Extra space between characters, in ems.
`TextRenderer.OutlineWidth: number`	Property	Outline drawn around the glyphs, in ems (0 = none; at most 0.125 em, the reach of the glyph atlas's distance band).
`TextRenderer.OutlineColor: Color`	Property	Outline color (RGBA, straight alpha).
`TextRenderer.ShadowColor: Color`	Property	Drop shadow color (RGBA, straight alpha); alpha 0 draws no shadow.
`TextRenderer.ShadowOffset: Vec2`	Property	Drop shadow offset in ems, along the text's own axes (+Y up).
`TextRenderer.ShadowSoftness: number`	Property	Drop shadow blur in ems (0 = a sharp shadow; at most 0.125 em, like OutlineWidth).
`TextRenderer.Layer: integer`	Property	Render layer index (0-31, named in the project settings).
`TextRenderer.OrderInLayer: integer`	Property	Draw order inside the render layer (int16 range); higher values draw in front.

TextRenderer.Text#

lua

TextRenderer.Text: string

UTF-8 text; line breaks start new lines.

TextRenderer.Font#

lua

TextRenderer.Font: integer?

Font asset; none uses the engine's default font. Asset handle of a Font (nil when none); writes also accept a virtual path such as "Assets/...".

TextRenderer.FontSize#

lua

TextRenderer.FontSize: number

Em size in world units. Range [0, inf]: writes outside it are clamped with a warning.

TextRenderer.Color#

lua

TextRenderer.Color: Color

Text color (RGBA, straight alpha). Writes also accept a Vec4 or Vec3 (alpha 1).

TextRenderer.HorizontalAlignment#

lua

TextRenderer.HorizontalAlignment: "Left"|"Center"|"Right"

Horizontal alignment of every line relative to the entity's position. Written by name.

TextRenderer.VerticalAlignment#

lua

TextRenderer.VerticalAlignment: "Top"|"Middle"|"Bottom"

Vertical alignment of the text block relative to the entity's position. Written by name.

TextRenderer.MaxWidth#

lua

TextRenderer.MaxWidth: number

Wrap width in world units; 0 disables wrapping. Range [0, inf]: writes outside it are clamped with a warning.

TextRenderer.LineSpacing#

lua

TextRenderer.LineSpacing: number

Line height multiplier (1 = the font's line height). Range [0, inf]: writes outside it are clamped with a warning.

TextRenderer.LetterSpacing#

lua

TextRenderer.LetterSpacing: number

Extra space between characters, in ems.

TextRenderer.OutlineWidth#

lua

TextRenderer.OutlineWidth: number

Outline drawn around the glyphs, in ems (0 = none; at most 0.125 em, the reach of the glyph atlas's distance band). Range [0, 0.125]: writes outside it are clamped with a warning.

TextRenderer.OutlineColor#

lua

TextRenderer.OutlineColor: Color

Outline color (RGBA, straight alpha). Writes also accept a Vec4 or Vec3 (alpha 1).

TextRenderer.ShadowColor#

lua

TextRenderer.ShadowColor: Color

Drop shadow color (RGBA, straight alpha); alpha 0 draws no shadow. Writes also accept a Vec4 or Vec3 (alpha 1).

TextRenderer.ShadowOffset#

lua

TextRenderer.ShadowOffset: Vec2

Drop shadow offset in ems, along the text's own axes (+Y up).

TextRenderer.ShadowSoftness#

lua

TextRenderer.ShadowSoftness: number

Drop shadow blur in ems (0 = a sharp shadow; at most 0.125 em, like OutlineWidth). Range [0, 0.125]: writes outside it are clamped with a warning.

TextRenderer.Layer#

lua

TextRenderer.Layer: integer

Render layer index (0-31, named in the project settings). Layers draw in ascending order; cameras cull by layer mask. Range [0, 31]: writes outside it are clamped with a warning.

TextRenderer.OrderInLayer#

lua

TextRenderer.OrderInLayer: integer

Draw order inside the render layer (int16 range); higher values draw in front. Ties are resolved by Translation.z. Range [-32768, 32767]: writes outside it are clamped with a warning.

Tilemap#

Draws a grid of tiles from a tileset in the entity's local space (cell (x, y) spans [x, x + 1) * CellSize.x by [y, y + 1) * CellSize.y before the transform). Chunked and sparse: memory grows only with the painted area. JSON: the fields below plus "Tiles": { "Version": 2, "ChunkSize": 32, "Chunks": [ { "X", "Y", "Rows": 32 strings, each the base64 RLE of a row's 32 tile ids, bottom row first } ] } (one line per tile row, so painted rows merge line by line; version 1's single "Data" string per chunk still loads).

lua

local component = self.Entity:GetComponent("Tilemap")

Member	Kind	Summary
`Tilemap.Tileset: integer?`	Property	Tileset (.ftileset) providing the tile images, collision shapes and animations; none draws nothing.
`Tilemap.CellSize: Vec2`	Property	Size of one cell in world units (before the entity's scale).
`Tilemap.Color: Color`	Property	Tint multiplied with every tile (RGBA, straight alpha).
`Tilemap.RenderMode: "Cutout"\|"Blended"`	Property	Cutout draws opaque tiles cut out at alpha 0.5 (fastest); Blended alpha-blends them in depth order with the other transparent sprites, for tilesets with translucent texels.
`Tilemap.Layer: integer`	Property	Render layer index (0-31, named in the project settings).
`Tilemap.OrderInLayer: integer`	Property	Draw order inside the render layer (int16 range); higher values draw in front.
`Tilemap:SetTile(x: integer, y: integer, tile: integer, flags?: integer): boolean`	Method	Places tile number `tile` of the tileset (0-based, row-major from the tileset image's top-left) in cell (x, y) with the given TileFlags (default none).
`Tilemap:GetTile(x: integer, y: integer): integer?, integer`	Method	The tile number in cell (x, y) and its TileFlags; nil and 0 for an empty cell.
`Tilemap:ClearTile(x: integer, y: integer): boolean`	Method	Empties cell (x, y); returns whether it held a tile.
`Tilemap:Fill(rect: CellRect, tile?: integer, flags?: integer): integer`	Method	Sets every cell of rect to the tile (nil clears them) and returns how many cells changed.
`Tilemap:Clear()`	Method	Removes every tile.
`Tilemap:GetTileCount(): integer`	Method	The number of non-empty cells.
`Tilemap:GetUsedBounds(): CellRect?`	Method	The smallest rectangle containing every tile, or nil for an empty tilemap.
`Tilemap:WorldToCell(position: Vec2): integer, integer`	Method	The cell (x, y) containing a world position, through the entity's world transform (cells are anchored at their bottom-left corner).
`Tilemap:CellToWorld(x: integer, y: integer, center?: boolean): Vec2`	Method	The world position of cell (x, y): its bottom-left corner, or its center with center = true.
`Tilemap:SetTerrain(x: integer, y: integer, terrain: string\|integer?, set?: string): integer`	Method	Paints tile (x, y) with a terrain of the tileset's terrain set `set` (default: its first set) through the auto-tiler: the tile and its neighbours get the set's tiles for their corners and edges, rule tiles around them are resolved again.
`Tilemap:GetTerrain(x: integer, y: integer, set?: string): string?`	Method	The terrain of terrain set `set` (default: the tileset's first set) at tile (x, y), derived from the tiles: for Corner and Mixed sets the vertex at the tile's bottom-left corner, for Edge sets the tile's bottom edge (what most of the tiles touching it give).
`Tilemap:RetileRect(rect: CellRect): integer`	Method	Resolves the tiles of a rectangle again from their terrains after tiles were set by id (a door opened with SetTile, a stamped room): the rectangle's tiles decide their corners and edges, the ring around it adapts, rule tiles are resolved from their neighbours.

Tilemap.Tileset#

lua

Tilemap.Tileset: integer?

Tileset (.ftileset) providing the tile images, collision shapes and animations; none draws nothing. Asset handle of a Tileset (nil when none); writes also accept a virtual path such as "Assets/...".

Tilemap.CellSize#

lua

Tilemap.CellSize: Vec2

Size of one cell in world units (before the entity's scale). Range [0.001, 1000000]: writes outside it are clamped with a warning.

Tilemap.Color#

lua

Tilemap.Color: Color

Tint multiplied with every tile (RGBA, straight alpha). Writes also accept a Vec4 or Vec3 (alpha 1).

Tilemap.RenderMode#

lua

Tilemap.RenderMode: "Cutout"|"Blended"

Cutout draws opaque tiles cut out at alpha 0.5 (fastest); Blended alpha-blends them in depth order with the other transparent sprites, for tilesets with translucent texels. A Color alpha below 1 always blends. Written by name.

Tilemap.Layer#

lua

Tilemap.Layer: integer

Render layer index (0-31, named in the project settings). Layers draw in ascending order; cameras cull by layer mask. Range [0, 31]: writes outside it are clamped with a warning.

Tilemap.OrderInLayer#

lua

Tilemap.OrderInLayer: integer

Draw order inside the render layer (int16 range); higher values draw in front. Ties are resolved by Translation.z. Range [-32768, 32767]: writes outside it are clamped with a warning.

Tilemap:SetTile#

lua

Tilemap:SetTile(x: integer, y: integer, tile: integer, flags?: integer): boolean

Places tile number tile of the tileset (0-based, row-major from the tileset image's top-left) in cell (x, y) with the given TileFlags (default none). Returns whether the cell changed. Cells are int32 coordinates (negative included).

Parameters

x (integer)
y (integer)
tile (integer)
flags? (integer): TileFlags combined with |.

Returns boolean

Example

lua

local tilemap = self.Entity:GetComponent("Tilemap")
tilemap:SetTile(0, 0, 5)
tilemap:SetTile(1, 0, 5, TileFlags.FlipX)

Tilemap:GetTile#

lua

Tilemap:GetTile(x: integer, y: integer): integer?, integer

The tile number in cell (x, y) and its TileFlags; nil and 0 for an empty cell.

Parameters

x (integer)
y (integer)

Returns integer?, integer

Example

lua

local tile, flags = tilemap:GetTile(3, 4)
if tile == nil then print("empty") end

Tilemap:ClearTile#

lua

Tilemap:ClearTile(x: integer, y: integer): boolean

Empties cell (x, y); returns whether it held a tile.

Parameters

x (integer)
y (integer)

Returns boolean

Tilemap:Fill#

lua

Tilemap:Fill(rect: CellRect, tile?: integer, flags?: integer): integer

Sets every cell of rect to the tile (nil clears them) and returns how many cells changed. Writing a tile into more than 16,777,216 cells at once raises an error (clearing has no limit).

Parameters

rect (CellRect)
tile? (integer)
flags? (integer)

Returns integer

Example

lua

tilemap:Fill(CellRect(0, 0, 19, 0), 1) -- a floor
tilemap:Fill(CellRect(5, 0, 6, 0)) -- a gap

Tilemap:Clear#

lua

Tilemap:Clear()

Removes every tile.

Tilemap:GetTileCount#

lua

Tilemap:GetTileCount(): integer

The number of non-empty cells.

Returns integer

Tilemap:GetUsedBounds#

lua

Tilemap:GetUsedBounds(): CellRect?

The smallest rectangle containing every tile, or nil for an empty tilemap.

Returns CellRect?

Tilemap:WorldToCell#

lua

Tilemap:WorldToCell(position: Vec2): integer, integer

The cell (x, y) containing a world position, through the entity's world transform (cells are anchored at their bottom-left corner).

Parameters

position (Vec2)

Returns integer, integer

Example

lua

local x, y = tilemap:WorldToCell(Camera.ScreenToWorld(Input.GetMousePosition()))

Tilemap:CellToWorld#

lua

Tilemap:CellToWorld(x: integer, y: integer, center?: boolean): Vec2

The world position of cell (x, y): its bottom-left corner, or its center with center = true.

Parameters

x (integer)
y (integer)
center? (boolean)

Returns Vec2

Example

lua

coin.WorldPosition = tilemap:CellToWorld(4, 2, true)

Tilemap:SetTerrain#

lua

Tilemap:SetTerrain(x: integer, y: integer, terrain: string|integer?, set?: string): integer

Paints tile (x, y) with a terrain of the tileset's terrain set set (default: its first set) through the auto-tiler: the tile and its neighbours get the set's tiles for their corners and edges, rule tiles around them are resolved again. terrain is the terrain's name, its index in the set (1-based) or nil / 0 to clear terrain. Returns how many tiles changed. Raises an error for an unknown set or terrain or a tileset that cannot be loaded (one not loaded yet is loaded the first time). Allocates nothing per tile.

Parameters

x (integer)
y (integer)
terrain (string|integer?): The terrain's name ("Water"), its 1-based index, or nil to clear.
set? (string): The terrain set's name.

Returns integer

Example

lua

-- A dug hole: the water spreads and the shore follows.
tilemap:SetTerrain(12, 4, "Water")

Tilemap:GetTerrain#

lua

Tilemap:GetTerrain(x: integer, y: integer, set?: string): string?

The terrain of terrain set set (default: the tileset's first set) at tile (x, y), derived from the tiles: for Corner and Mixed sets the vertex at the tile's bottom-left corner, for Edge sets the tile's bottom edge (what most of the tiles touching it give). nil where no tile of the set touches it. After SetTerrain(x, y, t) it is t.

Parameters

x (integer)
y (integer)
set? (string): The terrain set's name.

Returns string?

Example

lua

if tilemap:GetTerrain(x, y) == "Water" then player:Swim() end

Tilemap:RetileRect#

lua

Tilemap:RetileRect(rect: CellRect): integer

Resolves the tiles of a rectangle again from their terrains after tiles were set by id (a door opened with SetTile, a stamped room): the rectangle's tiles decide their corners and edges, the ring around it adapts, rule tiles are resolved from their neighbours. Returns how many tiles changed; raises an error for a rectangle of more than 1,048,576 tiles.

Parameters

rect (CellRect)

Returns integer

Example

lua

tilemap:Fill(CellRect(10, 2, 11, 3)) -- open a hole
tilemap:RetileRect(CellRect(10, 2, 11, 3))

TilemapCollider2D#

Static colliders for the entity's Tilemap: the tileset's Full tiles become solid cells (outline chains or merged boxes, see GeometryType), Custom tiles add their polygon (flips and rotation applied), None tiles do not collide. Every non-empty 32 x 32 chunk is one static body that is rebuilt when its tiles change; the bodies follow the entity's transform. Physics events and queries report the tilemap entity.

lua

local component = self.Entity:GetComponent("TilemapCollider2D")

Member	Kind	Summary
`TilemapCollider2D.GeometryType: "Outlines"\|"Boxes"`	Property	Outlines: one-sided chains along the outline of the solid tiles; bodies slide across tile and chunk borders without catching, but solid areas are hollow (a point inside overlaps nothing).
`TilemapCollider2D.Friction: number`	Property	Coulomb friction coefficient of every tile shape (usually 0-1).
`TilemapCollider2D.Restitution: number`	Property	Bounciness of every tile shape (0 = no bounce, 1 = perfectly elastic).
`TilemapCollider2D.Layer: integer`	Property	Physics layer index of the tile shapes (0-31, named in the project settings); the collision matrix decides which layers collide.
`TilemapCollider2D.IsSensor: boolean`	Property	The tiles detect overlaps (OnTriggerEnter/Exit) instead of colliding (with boxes, whatever GeometryType says).

TilemapCollider2D.GeometryType#

lua

TilemapCollider2D.GeometryType: "Outlines"|"Boxes"

Outlines: one-sided chains along the outline of the solid tiles; bodies slide across tile and chunk borders without catching, but solid areas are hollow (a point inside overlaps nothing). Boxes: solid greedy-merged boxes; points inside overlap, but sliding bodies can catch where boxes meet. Sensors always use boxes. Written by name.

TilemapCollider2D.Friction#

lua

TilemapCollider2D.Friction: number

Coulomb friction coefficient of every tile shape (usually 0-1). Combined with the other shape's friction by the geometric mean. Range [0, inf]: writes outside it are clamped with a warning.

TilemapCollider2D.Restitution#

lua

TilemapCollider2D.Restitution: number

Bounciness of every tile shape (0 = no bounce, 1 = perfectly elastic). Combined with the other shape by the maximum. Range [0, 1]: writes outside it are clamped with a warning.

TilemapCollider2D.Layer#

lua

TilemapCollider2D.Layer: integer

Physics layer index of the tile shapes (0-31, named in the project settings); the collision matrix decides which layers collide. Range [0, 31]: writes outside it are clamped with a warning.

TilemapCollider2D.IsSensor#

lua

TilemapCollider2D.IsSensor: boolean

The tiles detect overlaps (OnTriggerEnter/Exit) instead of colliding (with boxes, whatever GeometryType says).

Transform#

Position, rotation and scale relative to the parent entity (or the scene origin for root entities).

lua

local component = self.Entity:GetComponent("Transform")

Member	Kind	Summary
`Transform.Translation: Vec3`	Property	Local position in world units; z is depth (higher z is closer to the camera and draws in front within the same layer and order).
`Transform.Rotation: number`	Property	Local rotation in radians, counter-clockwise (shown in degrees).
`Transform.Scale: Vec2`	Property	Local scale along X and Y; negative values mirror.

Transform.Translation#

lua

Transform.Translation: Vec3

Local position in world units; z is depth (higher z is closer to the camera and draws in front within the same layer and order).

Transform.Rotation#

lua

Transform.Rotation: number

Local rotation in radians, counter-clockwise (shown in degrees). Radians.

Transform.Scale#

lua

Transform.Scale: Vec2

Local scale along X and Y; negative values mirror.

TriggerVolume#

A script trigger: OnVolumeEnter(volume, entity) and OnVolumeExit(volume, entity) on the volume's script and as global callbacks when a tracked entity the filter accepts enters or leaves.

lua

local component = self.Entity:GetComponent("TriggerVolume")

Member	Kind	Summary
`TriggerVolume.Tag: string`	Property	A free label for scripts to tell triggers apart ("cave-entrance").
`TriggerVolume.Filter: "Players"\|"Npcs"\|"All"`	Property	Who raises the events: players, NPCs (VolumeTracker entities that are not players) or both.
`TriggerVolume.Once: boolean`	Property	Only the first entry raises the events: the trigger is spent afterwards for every entity, until the volume loads again (its scene or cell).
`TriggerVolume.CooldownSeconds: number`	Property	Seconds after an enter event before the volume raises the next one, whichever entity enters (0 = none).

TriggerVolume.Tag#

lua

TriggerVolume.Tag: string

A free label for scripts to tell triggers apart ("cave-entrance").

TriggerVolume.Filter#

lua

TriggerVolume.Filter: "Players"|"Npcs"|"All"

Who raises the events: players, NPCs (VolumeTracker entities that are not players) or both. Written by name.

TriggerVolume.Once#

lua

TriggerVolume.Once: boolean

Only the first entry raises the events: the trigger is spent afterwards for every entity, until the volume loads again (its scene or cell). Per-player once-only logic belongs in the script (OnVolumeEnter with the player's saved state).

TriggerVolume.CooldownSeconds#

lua

TriggerVolume.CooldownSeconds: number

Seconds after an enter event before the volume raises the next one, whichever entity enters (0 = none). Range [0, inf]: writes outside it are clamped with a warning.

UIButton#

Clickable element: tints its UIImage and UIPanel by state; a click (pointer press and release on it, or Submit while it has the focus) calls its script's OnClick method, then the Lua listeners of UIButton:AddClickListener.

lua

local component = self.Entity:GetComponent("UIButton")

Member	Kind	Summary
`UIButton.NormalColor: Color`	Property	Tint when idle.
`UIButton.HoverColor: Color`	Property	Tint while the pointer is over the button or it has the keyboard/gamepad focus.
`UIButton.PressedColor: Color`	Property	Tint while the button is held down by the pointer (over it) or by Submit.
`UIButton.DisabledColor: Color`	Property	Tint while Interactable is off.
`UIButton.Interactable: boolean`	Property	Whether the button reacts to the pointer and to Submit and can have the focus; off shows DisabledColor.
`UIButton.OnClick: string`	Property	Name of the method (no arguments) called on the entity's script when the button is clicked (empty = none).
`UIButton:SetInteractable(interactable: boolean)`	Method	Enables or disables the button: a disabled button shows DisabledColor, ignores the pointer and Submit and loses the focus.
`UIButton:GetState(): UIButtonState`	Method	The button's state of this frame's UI update (Disabled at once when Interactable is off).
`UIButton:AddClickListener(listener: function): integer`	Method	Calls `listener(buttonEntity)` on every click of the button (after its OnClick method; listeners in registration order).
`UIButton:RemoveClickListener(id: integer): boolean`	Method	Removes a listener added to this button with AddClickListener; false when the id is not one of its listeners.

UIButton.NormalColor#

lua

UIButton.NormalColor: Color

Tint when idle. Writes also accept a Vec4 or Vec3 (alpha 1).

UIButton.HoverColor#

lua

UIButton.HoverColor: Color

Tint while the pointer is over the button or it has the keyboard/gamepad focus. Writes also accept a Vec4 or Vec3 (alpha 1).

UIButton.PressedColor#

lua

UIButton.PressedColor: Color

Tint while the button is held down by the pointer (over it) or by Submit. Writes also accept a Vec4 or Vec3 (alpha 1).

UIButton.DisabledColor#

lua

UIButton.DisabledColor: Color

Tint while Interactable is off. Writes also accept a Vec4 or Vec3 (alpha 1).

UIButton.Interactable#

lua

UIButton.Interactable: boolean

Whether the button reacts to the pointer and to Submit and can have the focus; off shows DisabledColor.

UIButton.OnClick#

lua

UIButton.OnClick: string

Name of the method (no arguments) called on the entity's script when the button is clicked (empty = none).

UIButton:SetInteractable#

lua

UIButton:SetInteractable(interactable: boolean)

Enables or disables the button: a disabled button shows DisabledColor, ignores the pointer and Submit and loses the focus.

Parameters

interactable (boolean)

UIButton:GetState#

lua

UIButton:GetState(): UIButtonState

The button's state of this frame's UI update (Disabled at once when Interactable is off).

Returns UIButtonState

UIButton:AddClickListener#

lua

UIButton:AddClickListener(listener: function): integer

Calls listener(buttonEntity) on every click of the button (after its OnClick method; listeners in registration order). An error in a listener is reported like every script error. Returns an id for RemoveClickListener. Listeners belong to the button entity: they end when it is destroyed (also after its UI components were removed) and when the scene's scripts stop; removing and adding UIButton again keeps them.

Parameters

listener (function): A function receiving the button entity.

Returns integer: The listener's id.

Example

lua

local id = button:AddClickListener(function(entity) Log.Info(entity.Name .. " clicked") end)

UIButton:RemoveClickListener#

lua

UIButton:RemoveClickListener(id: integer): boolean

Removes a listener added to this button with AddClickListener; false when the id is not one of its listeners.

Parameters

id (integer): The id AddClickListener returned.

Returns boolean

UICanvas#

Root of an in-game UI tree, laid out every frame in canvas units (origin top-left, +Y down). A canvas below another canvas is a nested canvas: laid out as an element of its parent canvas and drawn with its root canvas, ordered by its own SortOrder relative to the root.

lua

local component = self.Entity:GetComponent("UICanvas")

Member	Kind	Summary
`UICanvas.RenderMode: "ScreenSpace"\|"WorldSpace"`	Property	ScreenSpace draws over the game view; WorldSpace places the canvas in the world at the entity's transform.
`UICanvas.ReferenceResolution: Vec2`	Property	Canvas size in canvas units the layout is designed for.
`UICanvas.ScaleMode: "ScaleWithScreenSize"\|"ConstantPixelSize"`	Property	ScaleWithScreenSize scales the reference resolution to the screen; ConstantPixelSize makes one canvas unit one pixel times the window's content scale (the same physical size on HiDPI displays).
`UICanvas.MatchWidthOrHeight: number`	Property	ScaleWithScreenSize: 0 matches the screen width, 1 the height, values in between blend (logarithmically).
`UICanvas.SortOrder: integer`	Property	Root canvases draw in ascending sort order; higher values are on top and receive input first.
`UICanvas.PixelsPerUnit: number`	Property	WorldSpace: canvas units per world unit (the canvas is ReferenceResolution canvas units large, centered on the entity).
`UICanvas.Visible: boolean`	Property	Whether the canvas and everything below it is drawn and receives input.
`UICanvas.Layer: integer`	Property	WorldSpace: render layer of the canvas (0-31); cameras whose CullingMask excludes it do not draw it.
`UICanvas.AutoFocus: boolean`	Property	Keyboard/gamepad navigation starts here: while no button has the focus, the first direction or Submit input focuses the first interactable button below the front-most AutoFocus canvas.

UICanvas.RenderMode#

lua

UICanvas.RenderMode: "ScreenSpace"|"WorldSpace"

ScreenSpace draws over the game view; WorldSpace places the canvas in the world at the entity's transform. Written by name.

UICanvas.ReferenceResolution#

lua

UICanvas.ReferenceResolution: Vec2

Canvas size in canvas units the layout is designed for. Range [1, inf]: writes outside it are clamped with a warning.

UICanvas.ScaleMode#

lua

UICanvas.ScaleMode: "ScaleWithScreenSize"|"ConstantPixelSize"

ScaleWithScreenSize scales the reference resolution to the screen; ConstantPixelSize makes one canvas unit one pixel times the window's content scale (the same physical size on HiDPI displays). Written by name.

UICanvas.MatchWidthOrHeight#

lua

UICanvas.MatchWidthOrHeight: number

ScaleWithScreenSize: 0 matches the screen width, 1 the height, values in between blend (logarithmically). Range [0, 1]: writes outside it are clamped with a warning.

UICanvas.SortOrder#

lua

UICanvas.SortOrder: integer

Root canvases draw in ascending sort order; higher values are on top and receive input first. A nested canvas is ordered among the canvases of its root by this value relative to the root's own elements (0): negative values draw below them.

UICanvas.PixelsPerUnit#

lua

UICanvas.PixelsPerUnit: number

WorldSpace: canvas units per world unit (the canvas is ReferenceResolution canvas units large, centered on the entity). Range [0, inf]: writes outside it are clamped with a warning.

UICanvas.Visible#

lua

UICanvas.Visible: boolean

Whether the canvas and everything below it is drawn and receives input.

UICanvas.Layer#

lua

UICanvas.Layer: integer

WorldSpace: render layer of the canvas (0-31); cameras whose CullingMask excludes it do not draw it. Range [0, 31]: writes outside it are clamped with a warning.

UICanvas.AutoFocus#

lua

UICanvas.AutoFocus: boolean

Keyboard/gamepad navigation starts here: while no button has the focus, the first direction or Submit input focuses the first interactable button below the front-most AutoFocus canvas. For menus; leave it off for HUDs whose buttons are for the pointer (their movement keys then never reach the UI).

UIDraggable#

The element can be dragged onto UIDropTargets: with the pointer (mouse, touch) once a press moves past DragThreshold, or picked up and put down with the gamepad (PickUp action, gamepad X). A ghost of the element follows the pointer; the scripts get OnUIDragBegin(source, pointerId), OnUIDrop(payload, source, target, payloadType) on the target and OnUIDragEnd(source, target) (bubbling up to the root canvas).

lua

local component = self.Entity:GetComponent("UIDraggable")

Member	Kind	Summary
`UIDraggable.PayloadType: string`	Property	The kind of thing dragged ("item", "spell"); drop targets accept drags by type.
`UIDraggable.Payload: string`	Property	What the drop target receives (an item key, a slot index); scripts may set it in OnUIDragBegin with UI.SetDragPayload.
`UIDraggable.DragThreshold: number`	Property	How far a press must move before it drags, in pixels at content scale 1 (a shorter press stays a click).
`UIDraggable.GhostAlpha: number`	Property	Opacity of the copy of the element that follows the pointer (0 = no ghost).
`UIDraggable.Interactable: boolean`	Property	Whether the element can be dragged and have the focus.

UIDraggable.PayloadType#

lua

UIDraggable.PayloadType: string

The kind of thing dragged ("item", "spell"); drop targets accept drags by type.

UIDraggable.Payload#

lua

UIDraggable.Payload: string

What the drop target receives (an item key, a slot index); scripts may set it in OnUIDragBegin with UI.SetDragPayload.

UIDraggable.DragThreshold#

lua

UIDraggable.DragThreshold: number

How far a press must move before it drags, in pixels at content scale 1 (a shorter press stays a click). Range [0, inf]: writes outside it are clamped with a warning.

UIDraggable.GhostAlpha#

lua

UIDraggable.GhostAlpha: number

Opacity of the copy of the element that follows the pointer (0 = no ghost). Range [0, 1]: writes outside it are clamped with a warning.

UIDraggable.Interactable#

lua

UIDraggable.Interactable: boolean

Whether the element can be dragged and have the focus.

UIDropTarget#

Receives drops of UIDraggable elements whose PayloadType it accepts: OnUIDrop(payload, source, target, payloadType) on its script (or the nearest script above it). While an accepted drag is over it, its UIImage and UIPanel are tinted HighlightColor.

lua

local component = self.Entity:GetComponent("UIDropTarget")

Member	Kind	Summary
`UIDropTarget.AcceptedTypes: string`	Property	Payload types separated by commas ("item,spell"); empty accepts every type.
`UIDropTarget.HighlightColor: Color`	Property	Tint of the target's UIImage and UIPanel while a drag it accepts is over it (white = none).
`UIDropTarget.Interactable: boolean`	Property	Whether the target accepts drops.

UIDropTarget.AcceptedTypes#

lua

UIDropTarget.AcceptedTypes: string

Payload types separated by commas ("item,spell"); empty accepts every type.

UIDropTarget.HighlightColor#

lua

UIDropTarget.HighlightColor: Color

Tint of the target's UIImage and UIPanel while a drag it accepts is over it (white = none). Writes also accept a Vec4 or Vec3 (alpha 1).

UIDropTarget.Interactable#

lua

UIDropTarget.Interactable: boolean

Whether the target accepts drops.

UIDropdown#

A choice of one option out of Options: the element shows the selected option (or Placeholder) inside its rectangle minus Padding; a click (or Submit) opens a popup list below it (above it when there is no room) where a click, or the arrows and Submit, select an option and call OnUIDropdownChanged(index, option, dropdown) on the scripts (bubbling up to the root canvas); a click outside the popup, Cancel or another click on the dropdown close it. A UIImage or UIPanel on the entity is its background; a UIButton adds hover and focus tints.

lua

local component = self.Entity:GetComponent("UIDropdown")

Member	Kind	Summary
`UIDropdown.Selected: integer`	Property	The selected option's index in Options (0-based); -1 (or an index past the end) selects none and shows Placeholder.
`UIDropdown.Placeholder: string`	Property	Shown (at half the text's opacity) while no option is selected.
`UIDropdown.Font: integer?`	Property	Font asset of the caption and the options (none = the default fonts).
`UIDropdown.FontSize: number`	Property	Text size in canvas units per em.
`UIDropdown.TextColor: Color`	Property	Color of the caption and the options.
`UIDropdown.Padding: Vec4`	Property	Space between the edges and the text in canvas units (left, right, top, bottom): the caption inside the element, each option inside its row.
`UIDropdown.ItemHeight: number`	Property	Height of an option row of the popup in canvas units (the popup is as wide as the element).
`UIDropdown.MaxVisibleItems: integer`	Property	Rows the popup shows at most; longer lists scroll with the mouse wheel and the arrows.
`UIDropdown.PopupColor: Color`	Property	Background of the popup.
`UIDropdown.HighlightColor: Color`	Property	Background of the row under the pointer, or the one chosen with the arrows.
`UIDropdown.SelectedColor: Color`	Property	Background of the selected option's row.
`UIDropdown.Interactable: boolean`	Property	Whether the pointer and Submit open it and it can have the focus.
`UIDropdown:GetOptions(): {string}`	Method	The options as a list (option i + 1 of the list has index i: indices are 0-based like Selected).
`UIDropdown:SetOptions(options: {string}, selected?: integer)`	Method	Replaces the options (a list of at most 1024 strings of valid UTF-8, 256 bytes each) and selects `selected` (0-based; -1 or an index past the end selects none); without it the selection stays if its index is still in the list.
`UIDropdown:GetSelected(): integer`	Method	The selected option's index (0-based), or -1 when none is selected (also for a Selected past the end of Options).
`UIDropdown:SetSelected(index: integer)`	Method	Selects an option by its 0-based index; -1 or an index past the end selects none (Placeholder shows).
`UIDropdown:GetSelectedText(): string?`	Method	The selected option's text, or nil when none is selected.
`UIDropdown:Open(): boolean`	Method	Opens the popup (closing another one); false when the dropdown is not interactable, not visible or has no options.
`UIDropdown:Close(): boolean`	Method	Closes this dropdown's popup; false when it is not open.
`UIDropdown:IsOpen(): boolean`	Method	Whether this dropdown's popup is open.

UIDropdown.Selected#

lua

UIDropdown.Selected: integer

The selected option's index in Options (0-based); -1 (or an index past the end) selects none and shows Placeholder. Range [-1, inf]: writes outside it are clamped with a warning.

UIDropdown.Placeholder#

lua

UIDropdown.Placeholder: string

Shown (at half the text's opacity) while no option is selected.

UIDropdown.Font#

lua

UIDropdown.Font: integer?

Font asset of the caption and the options (none = the default fonts). Asset handle of a Font (nil when none); writes also accept a virtual path such as "Assets/...".

UIDropdown.FontSize#

lua

UIDropdown.FontSize: number

Text size in canvas units per em. Range [0, inf]: writes outside it are clamped with a warning.

UIDropdown.TextColor#

lua

UIDropdown.TextColor: Color

Color of the caption and the options. Writes also accept a Vec4 or Vec3 (alpha 1).

UIDropdown.Padding#

lua

UIDropdown.Padding: Vec4

Space between the edges and the text in canvas units (left, right, top, bottom): the caption inside the element, each option inside its row.

UIDropdown.ItemHeight#

lua

UIDropdown.ItemHeight: number

Height of an option row of the popup in canvas units (the popup is as wide as the element). Range [1, inf]: writes outside it are clamped with a warning.

UIDropdown.MaxVisibleItems#

lua

UIDropdown.MaxVisibleItems: integer

Rows the popup shows at most; longer lists scroll with the mouse wheel and the arrows. Range [1, 1024]: writes outside it are clamped with a warning.

UIDropdown.PopupColor#

lua

UIDropdown.PopupColor: Color

Background of the popup. Writes also accept a Vec4 or Vec3 (alpha 1).

UIDropdown.HighlightColor#

lua

UIDropdown.HighlightColor: Color

Background of the row under the pointer, or the one chosen with the arrows. Writes also accept a Vec4 or Vec3 (alpha 1).

UIDropdown.SelectedColor#

lua

UIDropdown.SelectedColor: Color

Background of the selected option's row. Writes also accept a Vec4 or Vec3 (alpha 1).

UIDropdown.Interactable#

lua

UIDropdown.Interactable: boolean

Whether the pointer and Submit open it and it can have the focus.

UIDropdown:GetOptions#

lua

UIDropdown:GetOptions(): {string}

The options as a list (option i + 1 of the list has index i: indices are 0-based like Selected).

Returns {string}

UIDropdown:SetOptions#

lua

UIDropdown:SetOptions(options: {string}, selected?: integer)

Replaces the options (a list of at most 1024 strings of valid UTF-8, 256 bytes each) and selects selected (0-based; -1 or an index past the end selects none); without it the selection stays if its index is still in the list. Sends no OnUIDropdownChanged.

Parameters

options ({string}): The new options, in order.
selected? (integer): The option to select (0-based), or -1 for none (optional).

Example

lua

quality:SetOptions({ "Low", "Medium", "High" }, 1)

UIDropdown:GetSelected#

lua

UIDropdown:GetSelected(): integer

The selected option's index (0-based), or -1 when none is selected (also for a Selected past the end of Options).

Returns integer

UIDropdown:SetSelected#

lua

UIDropdown:SetSelected(index: integer)

Selects an option by its 0-based index; -1 or an index past the end selects none (Placeholder shows). Sends no OnUIDropdownChanged.

Parameters

index (integer)

UIDropdown:GetSelectedText#

lua

UIDropdown:GetSelectedText(): string?

The selected option's text, or nil when none is selected.

Returns string?

UIDropdown:Open#

lua

UIDropdown:Open(): boolean

Opens the popup (closing another one); false when the dropdown is not interactable, not visible or has no options.

Returns boolean

UIDropdown:Close#

lua

UIDropdown:Close(): boolean

Closes this dropdown's popup; false when it is not open.

Returns boolean

UIDropdown:IsOpen#

lua

UIDropdown:IsOpen(): boolean

Whether this dropdown's popup is open.

Returns boolean

UIImage#

Draws a texture, a sprite-sheet frame or a solid color filling the element's UIRect.

lua

local component = self.Entity:GetComponent("UIImage")

Member	Kind	Summary
`UIImage.Texture: integer?`	Property	Texture to draw; none draws a solid rectangle in Color.
`UIImage.Color: Color`	Property	Tint multiplied with the texture.
`UIImage.DrawMode: "Simple"\|"Sliced"`	Property	Simple stretches the texture; Sliced keeps SliceBorders unscaled (nine-slice).
`UIImage.SliceBorders: Vec4`	Property	Nine-slice borders in texture pixels: left, right, top, bottom.
`UIImage.RaycastTarget: boolean`	Property	Whether the image blocks pointer input to elements and gameplay behind it.
`UIImage.SpriteSheet: integer?`	Property	Sprite sheet whose frame FrameIndex is drawn instead of Texture (none = Texture).
`UIImage.FrameIndex: integer`	Property	Frame of SpriteSheet to draw (SliceBorders are in that frame's texels).

UIImage.Texture#

lua

UIImage.Texture: integer?

Texture to draw; none draws a solid rectangle in Color. Asset handle of a Texture2D (nil when none); writes also accept a virtual path such as "Assets/...".

UIImage.Color#

lua

UIImage.Color: Color

Tint multiplied with the texture. Writes also accept a Vec4 or Vec3 (alpha 1).

UIImage.DrawMode#

lua

UIImage.DrawMode: "Simple"|"Sliced"

Simple stretches the texture; Sliced keeps SliceBorders unscaled (nine-slice). Written by name.

UIImage.SliceBorders#

lua

UIImage.SliceBorders: Vec4

Nine-slice borders in texture pixels: left, right, top, bottom. Range [0, inf]: writes outside it are clamped with a warning.

UIImage.RaycastTarget#

lua

UIImage.RaycastTarget: boolean

Whether the image blocks pointer input to elements and gameplay behind it.

UIImage.SpriteSheet#

lua

UIImage.SpriteSheet: integer?

Sprite sheet whose frame FrameIndex is drawn instead of Texture (none = Texture). Asset handle of a SpriteSheet (nil when none); writes also accept a virtual path such as "Assets/...".

UIImage.FrameIndex#

lua

UIImage.FrameIndex: integer

Frame of SpriteSheet to draw (SliceBorders are in that frame's texels).

UIInputField#

An editable text box: a click (or UI.SetFocus) gives it the keyboard; typed text (IME input included), the caret and selection keys (with Shift, Ctrl for words), the mouse (click, drag, double-click a word), Ctrl+A/C/X/V, Ctrl+Z/Y edit Text. Enter calls OnUISubmit(text, field), every edit OnUITextChanged(text, field) on the scripts (bubbling up to the root canvas); Tab moves to the next field or button. It draws its text, placeholder, selection and caret inside its rectangle minus Padding; a UIImage or UIPanel on the entity is its background.

lua

local component = self.Entity:GetComponent("UIInputField")

Member	Kind	Summary
`UIInputField.Text: string`	Property	The text (UTF-8, at most 65536 bytes: longer texts are cut).
`UIInputField.Placeholder: string`	Property	Shown in PlaceholderColor while Text is empty (a hint such as "Name").
`UIInputField.Font: integer?`	Property	Font asset (none = the default fonts).
`UIInputField.FontSize: number`	Property	Text size in canvas units per em.
`UIInputField.TextColor: Color`	Property	Color of the text.
`UIInputField.PlaceholderColor: Color`	Property	Color of the placeholder.
`UIInputField.SelectionColor: Color`	Property	Color of the selection drawn behind the selected text.
`UIInputField.CaretColor: Color`	Property	Color of the caret.
`UIInputField.CaretWidth: number`	Property	Width of the caret in canvas units.
`UIInputField.CaretBlinkInterval: number`	Property	Seconds the caret is shown, then hidden, while the field has the focus (0 = always shown; every edit restarts it).
`UIInputField.Padding: Vec4`	Property	Space between the rectangle and the text in canvas units: left, right, top, bottom.
`UIInputField.MultiLine: boolean`	Property	Enter starts a new line (Ctrl+Enter submits) and the text wraps at the width; off keeps one line that scrolls sideways.
`UIInputField.Password: boolean`	Property	Shows MaskCharacter for every character and refuses copying and cutting.
`UIInputField.MaskCharacter: string`	Property	The character that masks a password (its first character; '*' when it is empty).
`UIInputField.MaxLength: integer`	Property	The most characters typing and pasting may reach (0 = no limit; 65536 bytes at most in any case).
`UIInputField.CharacterFilter: "Any"\|"Integer"\|"Decimal"\|"Name"\|"Email"`	Property	The characters the player may type or paste: Any; Integer (digits, a leading minus); Decimal (also one point); Name (letters with single spaces, apostrophes and hyphens between them); Email (letters, digits, one @ and the symbols of addresses).
`UIInputField.Interactable: boolean`	Property	Whether the field can have the focus and be edited.
`UIInputField:GetText(): string`	Method	The field's text (the same as .Text).
`UIInputField:SetText(text: string)`	Method	Replaces the text (valid UTF-8), cut to MaxLength characters; while the field is edited the caret moves to the end and its undo history is dropped.
`UIInputField:Focus(): boolean`	Method	Gives the field the focus and the keyboard (UI.SetFocus); false when it is not interactable.
`UIInputField:IsFocused(): boolean`	Method	Whether the field has the focus (and the keyboard).
`UIInputField:SelectAll(): boolean`	Method	Selects the whole text of the focused field (typing replaces it); false when the field does not have the focus.

UIInputField.Text#

lua

UIInputField.Text: string

The text (UTF-8, at most 65536 bytes: longer texts are cut). Scripts set it with UIInputField:SetText.

UIInputField.Placeholder#

lua

UIInputField.Placeholder: string

Shown in PlaceholderColor while Text is empty (a hint such as "Name").

UIInputField.Font#

lua

UIInputField.Font: integer?

Font asset (none = the default fonts). Asset handle of a Font (nil when none); writes also accept a virtual path such as "Assets/...".

UIInputField.FontSize#

lua

UIInputField.FontSize: number

Text size in canvas units per em. Range [0, inf]: writes outside it are clamped with a warning.

UIInputField.TextColor#

lua

UIInputField.TextColor: Color

Color of the text. Writes also accept a Vec4 or Vec3 (alpha 1).

UIInputField.PlaceholderColor#

lua

UIInputField.PlaceholderColor: Color

Color of the placeholder. Writes also accept a Vec4 or Vec3 (alpha 1).

UIInputField.SelectionColor#

lua

UIInputField.SelectionColor: Color

Color of the selection drawn behind the selected text. Writes also accept a Vec4 or Vec3 (alpha 1).

UIInputField.CaretColor#

lua

UIInputField.CaretColor: Color

Color of the caret. Writes also accept a Vec4 or Vec3 (alpha 1).

UIInputField.CaretWidth#

lua

UIInputField.CaretWidth: number

Width of the caret in canvas units. Range [0, inf]: writes outside it are clamped with a warning.

UIInputField.CaretBlinkInterval#

lua

UIInputField.CaretBlinkInterval: number

Seconds the caret is shown, then hidden, while the field has the focus (0 = always shown; every edit restarts it). Range [0, inf]: writes outside it are clamped with a warning.

UIInputField.Padding#

lua

UIInputField.Padding: Vec4

Space between the rectangle and the text in canvas units: left, right, top, bottom.

UIInputField.MultiLine#

lua

UIInputField.MultiLine: boolean

Enter starts a new line (Ctrl+Enter submits) and the text wraps at the width; off keeps one line that scrolls sideways.

UIInputField.Password#

lua

UIInputField.Password: boolean

Shows MaskCharacter for every character and refuses copying and cutting.

UIInputField.MaskCharacter#

lua

UIInputField.MaskCharacter: string

The character that masks a password (its first character; '*' when it is empty).

UIInputField.MaxLength#

lua

UIInputField.MaxLength: integer

The most characters typing and pasting may reach (0 = no limit; 65536 bytes at most in any case).

UIInputField.CharacterFilter#

lua

UIInputField.CharacterFilter: "Any"|"Integer"|"Decimal"|"Name"|"Email"

The characters the player may type or paste: Any; Integer (digits, a leading minus); Decimal (also one point); Name (letters with single spaces, apostrophes and hyphens between them); Email (letters, digits, one @ and the symbols of addresses). Written by name.

UIInputField.Interactable#

lua

UIInputField.Interactable: boolean

Whether the field can have the focus and be edited.

UIInputField:GetText#

lua

UIInputField:GetText(): string

The field's text (the same as .Text).

Returns string

UIInputField:SetText#

lua

UIInputField:SetText(text: string)

Replaces the text (valid UTF-8), cut to MaxLength characters; while the field is edited the caret moves to the end and its undo history is dropped. Sends no OnUITextChanged (the character filter applies to the player's input only).

Parameters

text (string)

Example

lua

self.Name:GetComponent("UIInputField"):SetText("")

UIInputField:Focus#

lua

UIInputField:Focus(): boolean

Gives the field the focus and the keyboard (UI.SetFocus); false when it is not interactable.

Returns boolean

Example

lua

function Chat:Open()
	self.Input:GetComponent("UIInputField"):Focus()
end

UIInputField:IsFocused#

lua

UIInputField:IsFocused(): boolean

Whether the field has the focus (and the keyboard).

Returns boolean

UIInputField:SelectAll#

lua

UIInputField:SelectAll(): boolean

Selects the whole text of the focused field (typing replaces it); false when the field does not have the focus.

Returns boolean

UILayoutGroup#

Places the children's UIRects: in a row (Horizontal), a column (Vertical) or cells (Grid), with Padding, Spacing and alignment. A child is as large as its UIRect offsets (OffsetMax - OffsetMin; its anchors are not used), Grid children as CellSize; hidden children take no space. FitContent resizes the group to its content (inventory grids, lists in scroll views, action bars).

lua

local component = self.Entity:GetComponent("UILayoutGroup")

Member	Kind	Summary
`UILayoutGroup.Kind: "Horizontal"\|"Vertical"\|"Grid"`	Property	Horizontal: a row, left to right; Vertical: a column, top to bottom; Grid: cells row by row.
`UILayoutGroup.Padding: Vec4`	Property	Space inside the group's edges in canvas units: left, right, top, bottom.
`UILayoutGroup.Spacing: Vec2`	Property	Space between columns (x) and rows (y) in canvas units.
`UILayoutGroup.HorizontalAlignment: "Left"\|"Center"\|"Right"`	Property	Where narrower children sit: the row of a Horizontal group, each child of a Vertical one, the block of a Grid.
`UILayoutGroup.VerticalAlignment: "Top"\|"Middle"\|"Bottom"`	Property	Where lower children sit: the column of a Vertical group, each child of a Horizontal one, the block of a Grid.
`UILayoutGroup.StretchChildren: boolean`	Property	Horizontal: every child takes the padded height; Vertical: the padded width.
`UILayoutGroup.CellSize: Vec2`	Property	Grid: the size of every cell in canvas units.
`UILayoutGroup.Constraint: "Flexible"\|"FixedColumnCount"\|"FixedRowCount"`	Property	Grid: Flexible fits as many columns as the width holds; FixedColumnCount has ConstraintCount columns; FixedRowCount ConstraintCount rows.
`UILayoutGroup.ConstraintCount: integer`	Property	Grid: the column or row count of the fixed constraints (at least 1).
`UILayoutGroup.FitContent: boolean`	Property	The group takes the size of its content plus padding (around its UIRect Pivot): Horizontal its width (and height unless StretchChildren), Vertical its height (and width unless StretchChildren), Grid its height (and width with a fixed constraint).

UILayoutGroup.Kind#

lua

UILayoutGroup.Kind: "Horizontal"|"Vertical"|"Grid"

Horizontal: a row, left to right; Vertical: a column, top to bottom; Grid: cells row by row. Written by name.

UILayoutGroup.Padding#

lua

UILayoutGroup.Padding: Vec4

Space inside the group's edges in canvas units: left, right, top, bottom.

UILayoutGroup.Spacing#

lua

UILayoutGroup.Spacing: Vec2

Space between columns (x) and rows (y) in canvas units.

UILayoutGroup.HorizontalAlignment#

lua

UILayoutGroup.HorizontalAlignment: "Left"|"Center"|"Right"

Where narrower children sit: the row of a Horizontal group, each child of a Vertical one, the block of a Grid. Written by name.

UILayoutGroup.VerticalAlignment#

lua

UILayoutGroup.VerticalAlignment: "Top"|"Middle"|"Bottom"

Where lower children sit: the column of a Vertical group, each child of a Horizontal one, the block of a Grid. Written by name.

UILayoutGroup.StretchChildren#

lua

UILayoutGroup.StretchChildren: boolean

Horizontal: every child takes the padded height; Vertical: the padded width.

UILayoutGroup.CellSize#

lua

UILayoutGroup.CellSize: Vec2

Grid: the size of every cell in canvas units.

UILayoutGroup.Constraint#

lua

UILayoutGroup.Constraint: "Flexible"|"FixedColumnCount"|"FixedRowCount"

Grid: Flexible fits as many columns as the width holds; FixedColumnCount has ConstraintCount columns; FixedRowCount ConstraintCount rows. Written by name.

UILayoutGroup.ConstraintCount#

lua

UILayoutGroup.ConstraintCount: integer

Grid: the column or row count of the fixed constraints (at least 1). Range [1, inf]: writes outside it are clamped with a warning.

UILayoutGroup.FitContent#

lua

UILayoutGroup.FitContent: boolean

The group takes the size of its content plus padding (around its UIRect Pivot): Horizontal its width (and height unless StretchChildren), Vertical its height (and width unless StretchChildren), Grid its height (and width with a fixed constraint).

UIPanel#

Background rectangle that groups UI elements and can clip them.

lua

local component = self.Entity:GetComponent("UIPanel")

Member	Kind	Summary
`UIPanel.ClipChildren: boolean`	Property	Clips the descendants to the panel's rectangle (scissor rectangles on screen-space canvases, exact cuts on world-space ones; nested clips intersect).
`UIPanel.Color: Color`	Property	Background color (alpha 0 = invisible).
`UIPanel.RaycastTarget: boolean`	Property	Whether the panel blocks pointer input to elements and gameplay behind it (also when its color is invisible).

UIPanel.ClipChildren#

lua

UIPanel.ClipChildren: boolean

Clips the descendants to the panel's rectangle (scissor rectangles on screen-space canvases, exact cuts on world-space ones; nested clips intersect).

UIPanel.Color#

lua

UIPanel.Color: Color

Background color (alpha 0 = invisible). Writes also accept a Vec4 or Vec3 (alpha 1).

UIPanel.RaycastTarget#

lua

UIPanel.RaycastTarget: boolean

Whether the panel blocks pointer input to elements and gameplay behind it (also when its color is invisible).

UIRect#

Rectangle of a UI element relative to its parent rectangle: anchors (normalized) plus offsets in canvas units. The entity's Transform Scale scales the element and its descendants around Pivot; UI elements never rotate.

lua

local component = self.Entity:GetComponent("UIRect")

Member	Kind	Summary
`UIRect.AnchorMin: Vec2`	Property	Normalized parent position of the rectangle's top-left anchor ((0, 0) = parent top-left).
`UIRect.AnchorMax: Vec2`	Property	Normalized parent position of the rectangle's bottom-right anchor ((1, 1) = parent bottom-right).
`UIRect.Pivot: Vec2`	Property	Normalized point of the rectangle the Transform Scale scales around ((0.5, 0.5) = center).
`UIRect.OffsetMin: Vec2`	Property	Offset of the top-left corner from AnchorMin in canvas units.
`UIRect.OffsetMax: Vec2`	Property	Offset of the bottom-right corner from AnchorMax in canvas units.
`UIRect.Visible: boolean`	Property	Whether the element and its descendants are drawn and receive input.

UIRect.AnchorMin#

lua

UIRect.AnchorMin: Vec2

Normalized parent position of the rectangle's top-left anchor ((0, 0) = parent top-left). Range [0, 1]: writes outside it are clamped with a warning.

UIRect.AnchorMax#

lua

UIRect.AnchorMax: Vec2

Normalized parent position of the rectangle's bottom-right anchor ((1, 1) = parent bottom-right). Range [0, 1]: writes outside it are clamped with a warning.

UIRect.Pivot#

lua

UIRect.Pivot: Vec2

Normalized point of the rectangle the Transform Scale scales around ((0.5, 0.5) = center). Range [0, 1]: writes outside it are clamped with a warning.

UIRect.OffsetMin#

lua

UIRect.OffsetMin: Vec2

Offset of the top-left corner from AnchorMin in canvas units.

UIRect.OffsetMax#

lua

UIRect.OffsetMax: Vec2

Offset of the bottom-right corner from AnchorMax in canvas units.

UIRect.Visible#

lua

UIRect.Visible: boolean

Whether the element and its descendants are drawn and receive input.

UIScrollView#

Scrolls Content inside the element's rectangle, which clips everything below it: pointer and touch drags move the content (a press on a button inside becomes a scroll once it moves past the drag threshold; the button is not clicked), the mouse wheel scrolls it. Content's own rectangle sets how far it scrolls. Scrolling calls the script method OnUIScroll(offset) of the scroll view entity.

lua

local component = self.Entity:GetComponent("UIScrollView")

Member	Kind	Summary
`UIScrollView.Content: Entity?`	Property	The descendant element (with UIRect, usually larger than the view) that scrolls; none = nothing scrolls.
`UIScrollView.Horizontal: boolean`	Property	Whether the content scrolls horizontally.
`UIScrollView.Vertical: boolean`	Property	Whether the content scrolls vertically.
`UIScrollView.ScrollOffset: Vec2`	Property	How far the content is scrolled, in canvas units of the content's parent (+X shows more to the right, +Y more below); drawn clamped so the content covers the view where it is large enough (0 on axes that do not scroll).
`UIScrollView.ScrollSensitivity: number`	Property	Canvas units scrolled per mouse wheel step (0 = the wheel does not scroll).
`UIScrollView.Inertia: boolean`	Property	Whether the content keeps moving after a drag is released, slowing down by DecelerationRate.
`UIScrollView.DecelerationRate: number`	Property	Fraction of the inertia velocity left after one second (0 = stops at once, close to 1 = glides long).
`UIScrollView:GetScrollRange(): Vec2, Vec2`	Method	The smallest and largest ScrollOffset of this frame's layout (the content covers the view in between); both (0, 0) on axes that do not scroll, and while the scroll view is hidden or has no laid-out Content.

UIScrollView.Content#

lua

UIScrollView.Content: Entity?

The descendant element (with UIRect, usually larger than the view) that scrolls; none = nothing scrolls. Writes accept an Entity, an entity ID or nil.

UIScrollView.Horizontal#

lua

UIScrollView.Horizontal: boolean

Whether the content scrolls horizontally.

UIScrollView.Vertical#

lua

UIScrollView.Vertical: boolean

Whether the content scrolls vertically.

UIScrollView.ScrollOffset#

lua

UIScrollView.ScrollOffset: Vec2

How far the content is scrolled, in canvas units of the content's parent (+X shows more to the right, +Y more below); drawn clamped so the content covers the view where it is large enough (0 on axes that do not scroll).

UIScrollView.ScrollSensitivity#

lua

UIScrollView.ScrollSensitivity: number

Canvas units scrolled per mouse wheel step (0 = the wheel does not scroll). Range [0, inf]: writes outside it are clamped with a warning.

UIScrollView.Inertia#

lua

UIScrollView.Inertia: boolean

Whether the content keeps moving after a drag is released, slowing down by DecelerationRate.

UIScrollView.DecelerationRate#

lua

UIScrollView.DecelerationRate: number

Fraction of the inertia velocity left after one second (0 = stops at once, close to 1 = glides long). Range [0, 0.99]: writes outside it are clamped with a warning.

UIScrollView:GetScrollRange#

lua

UIScrollView:GetScrollRange(): Vec2, Vec2

The smallest and largest ScrollOffset of this frame's layout (the content covers the view in between); both (0, 0) on axes that do not scroll, and while the scroll view is hidden or has no laid-out Content.

Returns Vec2, Vec2: The minimum and the maximum offset.

Example

lua

local _, last = list:GetScrollRange()
list.ScrollOffset = Vec2(0, last.y) -- scroll to the bottom

UISlider#

A value between MinValue and MaxValue the pointer (mouse or touch) sets by pressing and dragging along the element. The layout stretches Fill from the minimum to the value and centers Handle on it (their UIRect anchors along Direction are overridden); the track is Handle's parent rectangle (else Fill's, else the slider's). Changes by the pointer call the script method OnUIValueChanged(value) of the slider entity.

lua

local component = self.Entity:GetComponent("UISlider")

Member	Kind	Summary
`UISlider.MinValue: number`	Property	Value at the start of the track (it may be larger than MaxValue).
`UISlider.MaxValue: number`	Property	Value at the end of the track.
`UISlider.Value: number`	Property	The current value; drawn clamped between MinValue and MaxValue (the pointer only sets values in that range).
`UISlider.WholeNumbers: boolean`	Property	The pointer sets whole numbers only.
`UISlider.Direction: "LeftToRight"\|"RightToLeft"\|"BottomToTop"\|"TopToBottom"`	Property	Where the minimum is: LeftToRight puts it at the left end of the track, BottomToTop at the bottom, ...
`UISlider.Fill: Entity?`	Property	A descendant element (with UIRect) stretched from the minimum to the value, e.g.
`UISlider.Handle: Entity?`	Property	A descendant element (with UIRect) centered on the value, e.g.
`UISlider.Interactable: boolean`	Property	Whether the pointer can change the value.

UISlider.MinValue#

lua

UISlider.MinValue: number

Value at the start of the track (it may be larger than MaxValue).

UISlider.MaxValue#

lua

UISlider.MaxValue: number

Value at the end of the track.

UISlider.Value#

lua

UISlider.Value: number

The current value; drawn clamped between MinValue and MaxValue (the pointer only sets values in that range).

UISlider.WholeNumbers#

lua

UISlider.WholeNumbers: boolean

The pointer sets whole numbers only.

UISlider.Direction#

lua

UISlider.Direction: "LeftToRight"|"RightToLeft"|"BottomToTop"|"TopToBottom"

Where the minimum is: LeftToRight puts it at the left end of the track, BottomToTop at the bottom, ... Written by name.

UISlider.Fill#

lua

UISlider.Fill: Entity?

A descendant element (with UIRect) stretched from the minimum to the value, e.g. a colored bar; none = no fill. Writes accept an Entity, an entity ID or nil.

UISlider.Handle#

lua

UISlider.Handle: Entity?

A descendant element (with UIRect) centered on the value, e.g. a knob; its own offsets give its size. None = no handle. Writes accept an Entity, an entity ID or nil.

UISlider.Interactable#

lua

UISlider.Interactable: boolean

Whether the pointer can change the value.

UIText#

Draws text inside the element's UIRect, aligned to its edges or center (WordWrap wraps it at the rectangle's width).

lua

local component = self.Entity:GetComponent("UIText")

Member	Kind	Summary
`UIText.Text: string`	Property	UTF-8 text; line breaks start new lines.
`UIText.Font: integer?`	Property	Font asset; none uses the engine's default font.
`UIText.FontSize: number`	Property	Em size in canvas units.
`UIText.Color: Color`	Property	Text color.
`UIText.HorizontalAlignment: "Left"\|"Center"\|"Right"`	Property	Horizontal alignment inside the rectangle.
`UIText.VerticalAlignment: "Top"\|"Middle"\|"Bottom"`	Property	Vertical alignment inside the rectangle.
`UIText.WordWrap: boolean`	Property	Wraps lines at the rectangle's width (words longer than a line break between characters); off keeps every line whole.
`UIText.LineSpacing: number`	Property	Line height multiplier (1 = the font's line height).
`UIText.LetterSpacing: number`	Property	Extra space between characters, in ems.
`UIText.OutlineWidth: number`	Property	Outline drawn around the glyphs, in ems (0 = none; at most 0.125 em, the reach of the glyph atlas's distance band).
`UIText.OutlineColor: Color`	Property	Outline color (RGBA, straight alpha).
`UIText.ShadowColor: Color`	Property	Drop shadow color (RGBA, straight alpha); alpha 0 draws no shadow.
`UIText.ShadowOffset: Vec2`	Property	Drop shadow offset in ems, in canvas orientation (+X right, +Y down).
`UIText.ShadowSoftness: number`	Property	Drop shadow blur in ems (0 = a sharp shadow; at most 0.125 em, like OutlineWidth).
`UIText:SetText(text: string)`	Method	Replaces the text (valid UTF-8; line breaks start new lines).

UIText.Text#

lua

UIText.Text: string

UTF-8 text; line breaks start new lines.

UIText.Font#

lua

UIText.Font: integer?

Font asset; none uses the engine's default font. Asset handle of a Font (nil when none); writes also accept a virtual path such as "Assets/...".

UIText.FontSize#

lua

UIText.FontSize: number

Em size in canvas units. Range [0, inf]: writes outside it are clamped with a warning.

UIText.Color#

lua

UIText.Color: Color

Text color. Writes also accept a Vec4 or Vec3 (alpha 1).

UIText.HorizontalAlignment#

lua

UIText.HorizontalAlignment: "Left"|"Center"|"Right"

Horizontal alignment inside the rectangle. Written by name.

UIText.VerticalAlignment#

lua

UIText.VerticalAlignment: "Top"|"Middle"|"Bottom"

Vertical alignment inside the rectangle. Written by name.

UIText.WordWrap#

lua

UIText.WordWrap: boolean

Wraps lines at the rectangle's width (words longer than a line break between characters); off keeps every line whole.

UIText.LineSpacing#

lua

UIText.LineSpacing: number

Line height multiplier (1 = the font's line height). Range [0, inf]: writes outside it are clamped with a warning.

UIText.LetterSpacing#

lua

UIText.LetterSpacing: number

Extra space between characters, in ems.

UIText.OutlineWidth#

lua

UIText.OutlineWidth: number

Outline drawn around the glyphs, in ems (0 = none; at most 0.125 em, the reach of the glyph atlas's distance band). Range [0, 0.125]: writes outside it are clamped with a warning.

UIText.OutlineColor#

lua

UIText.OutlineColor: Color

Outline color (RGBA, straight alpha). Writes also accept a Vec4 or Vec3 (alpha 1).

UIText.ShadowColor#

lua

UIText.ShadowColor: Color

Drop shadow color (RGBA, straight alpha); alpha 0 draws no shadow. Writes also accept a Vec4 or Vec3 (alpha 1).

UIText.ShadowOffset#

lua

UIText.ShadowOffset: Vec2

Drop shadow offset in ems, in canvas orientation (+X right, +Y down).

UIText.ShadowSoftness#

lua

UIText.ShadowSoftness: number

Drop shadow blur in ems (0 = a sharp shadow; at most 0.125 em, like OutlineWidth). Range [0, 0.125]: writes outside it are clamped with a warning.

UIText:SetText#

lua

UIText:SetText(text: string)

Replaces the text (valid UTF-8; line breaks start new lines). The same as assigning .Text; the new text shows this frame.

Parameters

text (string)

Example

lua

self.Entity:GetComponent("UIText"):SetText("Score: " .. tostring(self.Score))

UIToggle#

On or off: a click (pointer press and release on it, or Submit while it has the focus) switches it and calls OnUIToggleChanged(isOn, toggle) on the scripts (bubbling up to the root canvas). Toggles with the same Group below the same root canvas form a radio group (turning one on turns the others off). Checkmark is shown only while it is on; a UIButton on the entity adds hover, pressed and focus tints.

lua

local component = self.Entity:GetComponent("UIToggle")

Member	Kind	Summary
`UIToggle.On: boolean`	Property	Whether the toggle is on (scripts use UIToggle:SetOn to keep a radio group consistent).
`UIToggle.Group: string`	Property	Radio group name: of the toggles with this name below the same root canvas at most one is on.
`UIToggle.AllowSwitchOff: boolean`	Property	Radio groups: a click on the toggle that is on turns it off (leaving none on); off, it stays on.
`UIToggle.Checkmark: Entity?`	Property	A descendant element (a tick, a fill) laid out and drawn only while the toggle is on; none = nothing is driven.
`UIToggle.Interactable: boolean`	Property	Whether the pointer and Submit switch it and it can have the focus.
`UIToggle:IsOn(): boolean`	Method	Whether the toggle is on (the same as .On).
`UIToggle:SetOn(on: boolean)`	Method	Turns the toggle on or off; turning on a toggle with a Group turns the other toggles of that group below the same root canvas off.

UIToggle.On#

lua

UIToggle.On: boolean

Whether the toggle is on (scripts use UIToggle:SetOn to keep a radio group consistent).

UIToggle.Group#

lua

UIToggle.Group: string

Radio group name: of the toggles with this name below the same root canvas at most one is on. Empty = an independent toggle.

UIToggle.AllowSwitchOff#

lua

UIToggle.AllowSwitchOff: boolean

Radio groups: a click on the toggle that is on turns it off (leaving none on); off, it stays on.

UIToggle.Checkmark#

lua

UIToggle.Checkmark: Entity?

A descendant element (a tick, a fill) laid out and drawn only while the toggle is on; none = nothing is driven. Writes accept an Entity, an entity ID or nil.

UIToggle.Interactable#

lua

UIToggle.Interactable: boolean

Whether the pointer and Submit switch it and it can have the focus.

UIToggle:IsOn#

lua

UIToggle:IsOn(): boolean

Whether the toggle is on (the same as .On).

Returns boolean

UIToggle:SetOn#

lua

UIToggle:SetOn(on: boolean)

Turns the toggle on or off; turning on a toggle with a Group turns the other toggles of that group below the same root canvas off. Sends no OnUIToggleChanged (scripts know what they set).

Parameters

on (boolean)

Example

lua

self.Music:GetComponent("UIToggle"):SetOn(Settings.MusicOn)

UITooltip#

A tooltip for the element and everything below it: once the pointer rested on it for Delay seconds (or the keyboard/gamepad focus did), Text shows in a box next to the pointer, or the Content element is moved there and made visible instead (hidden again afterwards); kept on screen. A press, a drag or leaving the element hides it. Scripts get OnUITooltipShown(owner, content) and OnUITooltipHidden(owner) (bubbling up to the root canvas) to fill the content. The element blocks pointer input.

lua

local component = self.Entity:GetComponent("UITooltip")

Member	Kind	Summary
`UITooltip.Text: string`	Property	The tooltip's text (UTF-8; line breaks start new lines), shown when Content is none.
`UITooltip.Content: Entity?`	Property	An element with a UIRect shown as the tooltip instead of Text (a panel with an item's name and stats, usually not Visible by default): its UIRect is moved next to the pointer and made Visible while the tooltip is up.
`UITooltip.Delay: number`	Property	Seconds the pointer rests on the element before the tooltip shows (0 = at once).
`UITooltip.Offset: Vec2`	Property	From the pointer to the tooltip's top-left corner (flipped to the other side of the pointer where it would leave the screen), in canvas units of the tooltip's canvas (pixels at content scale 1 for text tooltips of world-space canvases).
`UITooltip.Font: integer?`	Property	Font asset of Text (none = the default fonts).
`UITooltip.FontSize: number`	Property	Size of Text in canvas units per em.
`UITooltip.TextColor: Color`	Property	Color of Text.
`UITooltip.BackgroundColor: Color`	Property	Color of the box behind Text.
`UITooltip.Padding: Vec4`	Property	Space between the box and Text in canvas units: left, right, top, bottom.
`UITooltip.MaxWidth: number`	Property	Text wraps at this width in canvas units (0 = every line stays whole).

UITooltip.Text#

lua

UITooltip.Text: string

The tooltip's text (UTF-8; line breaks start new lines), shown when Content is none.

UITooltip.Content#

lua

UITooltip.Content: Entity?

An element with a UIRect shown as the tooltip instead of Text (a panel with an item's name and stats, usually not Visible by default): its UIRect is moved next to the pointer and made Visible while the tooltip is up. Writes accept an Entity, an entity ID or nil.

UITooltip.Delay#

lua

UITooltip.Delay: number

Seconds the pointer rests on the element before the tooltip shows (0 = at once). Range [0, inf]: writes outside it are clamped with a warning.

UITooltip.Offset#

lua

UITooltip.Offset: Vec2

From the pointer to the tooltip's top-left corner (flipped to the other side of the pointer where it would leave the screen), in canvas units of the tooltip's canvas (pixels at content scale 1 for text tooltips of world-space canvases).

UITooltip.Font#

lua

UITooltip.Font: integer?

Font asset of Text (none = the default fonts). Asset handle of a Font (nil when none); writes also accept a virtual path such as "Assets/...".

UITooltip.FontSize#

lua

UITooltip.FontSize: number

Size of Text in canvas units per em. Range [0, inf]: writes outside it are clamped with a warning.

UITooltip.TextColor#

lua

UITooltip.TextColor: Color

Color of Text. Writes also accept a Vec4 or Vec3 (alpha 1).

UITooltip.BackgroundColor#

lua

UITooltip.BackgroundColor: Color

Color of the box behind Text. Writes also accept a Vec4 or Vec3 (alpha 1).

UITooltip.Padding#

lua

UITooltip.Padding: Vec4

Space between the box and Text in canvas units: left, right, top, bottom.

UITooltip.MaxWidth#

lua

UITooltip.MaxWidth: number

Text wraps at this width in canvas units (0 = every line stays whole). Range [0, inf]: writes outside it are clamped with a warning.

VendorStock#

The stock of a vendor whose Vendor row limits entries: what is left and when each entry restocks, in the vendor's World-scope persistent record (added by the inventory system).

lua

local component = self.Entity:GetComponent("VendorStock")

Member	Kind	Summary
`VendorStock.Stock: string (read-only)`	Property	Run time: the limited entries' stock and restock times (UTC milliseconds).

VendorStock.Stock#

lua

VendorStock.Stock: string (read-only)

Run time: the limited entries' stock and restock times (UTC milliseconds). Read-only. Persistent: saved with the entity's persistent record (PersistenceComponent).

VolumeShape#

The area of a volume: a box, a circle or a polygon in the entity's local space (the transform places, rotates and scales it; a circle under a non-uniform scale is an ellipse). The kind components on the same entity (RegionVolume, MusicVolume, AmbientVolume, PvPVolume, PhaseVolume, TriggerVolume, NavAreaVolume) give the area its meaning, several at once. Points is [[x, y], ...] in the component JSON: 3-64 points every shape keeps (switching to Polygon uses them), which must form a simple polygon for a Polygon.

lua

local component = self.Entity:GetComponent("VolumeShape")

Member	Kind	Summary
`VolumeShape.Shape: "Box"\|"Circle"\|"Polygon"`	Property	The area's shape: Box (Size), Circle (Radius) or Polygon (Points, concave allowed).
`VolumeShape.Size: Vec2`	Property	Box: full width and height in local units.
`VolumeShape.Radius: number`	Property	Circle: radius in local units.
`VolumeShape.Offset: Vec2`	Property	Shift of the shape from the entity's origin, in local units.

VolumeShape.Shape#

lua

VolumeShape.Shape: "Box"|"Circle"|"Polygon"

The area's shape: Box (Size), Circle (Radius) or Polygon (Points, concave allowed). Written by name.

VolumeShape.Size#

lua

VolumeShape.Size: Vec2

Box: full width and height in local units. Range [0.001, inf]: writes outside it are clamped with a warning.

VolumeShape.Radius#

lua

VolumeShape.Radius: number

Circle: radius in local units. Range [0.001, inf]: writes outside it are clamped with a warning.

VolumeShape.Offset#

lua

VolumeShape.Offset: Vec2

Shift of the shape from the entity's origin, in local units.

VolumeTracker#

Gives an entity that is not a player (an NPC) volume events: region changes and triggers. Players - networked roots a client owns - are tracked without one; Player marks the player's character of a game without a network session.

lua

local component = self.Entity:GetComponent("VolumeTracker")

Member	Kind	Summary
`VolumeTracker.Enabled: boolean`	Property	Whether the entity gets volume events (a disabled tracker also stops a networked player's).
`VolumeTracker.Player: boolean`	Property	The entity counts as a player (TriggerVolume filters, OnPhaseVolumeEntered), as client-owned networked roots do: the player's character of a single-player game.

VolumeTracker.Enabled#

lua

VolumeTracker.Enabled: boolean

Whether the entity gets volume events (a disabled tracker also stops a networked player's).

VolumeTracker.Player#

lua

VolumeTracker.Player: boolean

The entity counts as a player (TriggerVolume filters, OnPhaseVolumeEntered), as client-owned networked roots do: the player's character of a single-player game.

WeldJoint2D#

Glues two bodies together, rigidly or softly (breakable structures, soft bodies).

lua

local component = self.Entity:GetComponent("WeldJoint2D")

Member	Kind	Summary
`WeldJoint2D.ConnectedEntity: Entity?`	Property	The other body of the joint (an entity with a Rigidbody2D).
`WeldJoint2D.Anchor: Vec2`	Property	Joint anchor in this entity's local space (world units).
`WeldJoint2D.ConnectedAnchor: Vec2`	Property	Joint anchor in the connected entity's local space (world space when anchored to the world).
`WeldJoint2D.CollideConnected: boolean`	Property	Whether the two connected bodies still collide with each other.
`WeldJoint2D.LinearHertz: number`	Property	Linear stiffness as a frequency in Hz (0 = rigid).
`WeldJoint2D.AngularHertz: number`	Property	Angular stiffness as a frequency in Hz (0 = rigid).
`WeldJoint2D.LinearDampingRatio: number`	Property	Linear damping ratio of the soft weld (1 = critical damping).
`WeldJoint2D.AngularDampingRatio: number`	Property	Angular damping ratio of the soft weld (1 = critical damping).

WeldJoint2D.ConnectedEntity#

lua

WeldJoint2D.ConnectedEntity: Entity?

The other body of the joint (an entity with a Rigidbody2D). None anchors the joint to the world. Writes accept an Entity, an entity ID or nil.

WeldJoint2D.Anchor#

lua

WeldJoint2D.Anchor: Vec2

Joint anchor in this entity's local space (world units).

WeldJoint2D.ConnectedAnchor#

lua

WeldJoint2D.ConnectedAnchor: Vec2

Joint anchor in the connected entity's local space (world space when anchored to the world).

WeldJoint2D.CollideConnected#

lua

WeldJoint2D.CollideConnected: boolean

Whether the two connected bodies still collide with each other.

WeldJoint2D.LinearHertz#

lua

WeldJoint2D.LinearHertz: number

Linear stiffness as a frequency in Hz (0 = rigid). Range [0, inf]: writes outside it are clamped with a warning.

WeldJoint2D.AngularHertz#

lua

WeldJoint2D.AngularHertz: number

Angular stiffness as a frequency in Hz (0 = rigid). Range [0, inf]: writes outside it are clamped with a warning.

WeldJoint2D.LinearDampingRatio#

lua

WeldJoint2D.LinearDampingRatio: number

Linear damping ratio of the soft weld (1 = critical damping). Range [0, inf]: writes outside it are clamped with a warning.

WeldJoint2D.AngularDampingRatio#

lua

WeldJoint2D.AngularDampingRatio: number

Angular damping ratio of the soft weld (1 = critical damping). Range [0, inf]: writes outside it are clamped with a warning.

WheelJoint2D#

Wheel suspension: the connected body rotates freely and slides along a spring axis (vehicles).

lua

local component = self.Entity:GetComponent("WheelJoint2D")

Member	Kind	Summary
`WheelJoint2D.ConnectedEntity: Entity?`	Property	The other body of the joint (an entity with a Rigidbody2D).
`WheelJoint2D.Anchor: Vec2`	Property	Joint anchor in this entity's local space (world units).
`WheelJoint2D.ConnectedAnchor: Vec2`	Property	Joint anchor in the connected entity's local space (world space when anchored to the world).
`WheelJoint2D.CollideConnected: boolean`	Property	Whether the two connected bodies still collide with each other.
`WheelJoint2D.Axis: Vec2`	Property	Suspension axis in this entity's local space (normalized by the physics system).
`WheelJoint2D.EnableSpring: boolean`	Property	Makes the suspension soft: it behaves like a spring with the given frequency and damping.
`WheelJoint2D.Hertz: number`	Property	Spring stiffness as an oscillation frequency in Hz (0 = rigid).
`WheelJoint2D.DampingRatio: number`	Property	Spring damping ratio (0 = no damping, 1 = critical damping).
`WheelJoint2D.EnableLimit: boolean`	Property	Restricts the suspension travel to [LowerTranslation, UpperTranslation].
`WheelJoint2D.LowerTranslation: number`	Property	Lower suspension limit in world units.
`WheelJoint2D.UpperTranslation: number`	Property	Upper suspension limit in world units.
`WheelJoint2D.EnableMotor: boolean`	Property	Drives the wheel rotation at MotorSpeed.
`WheelJoint2D.MaxMotorTorque: number`	Property	Maximum motor torque in newton-meters.
`WheelJoint2D.MotorSpeed: number`	Property	Target wheel speed in radians per second.

WheelJoint2D.ConnectedEntity#

lua

WheelJoint2D.ConnectedEntity: Entity?

The other body of the joint (an entity with a Rigidbody2D). None anchors the joint to the world. Writes accept an Entity, an entity ID or nil.

WheelJoint2D.Anchor#

lua

WheelJoint2D.Anchor: Vec2

Joint anchor in this entity's local space (world units).

WheelJoint2D.ConnectedAnchor#

lua

WheelJoint2D.ConnectedAnchor: Vec2

Joint anchor in the connected entity's local space (world space when anchored to the world).

WheelJoint2D.CollideConnected#

lua

WheelJoint2D.CollideConnected: boolean

Whether the two connected bodies still collide with each other.

WheelJoint2D.Axis#

lua

WheelJoint2D.Axis: Vec2

Suspension axis in this entity's local space (normalized by the physics system).

WheelJoint2D.EnableSpring#

lua

WheelJoint2D.EnableSpring: boolean

Makes the suspension soft: it behaves like a spring with the given frequency and damping.

WheelJoint2D.Hertz#

lua

WheelJoint2D.Hertz: number

Spring stiffness as an oscillation frequency in Hz (0 = rigid). Range [0, inf]: writes outside it are clamped with a warning.

WheelJoint2D.DampingRatio#

lua

WheelJoint2D.DampingRatio: number

Spring damping ratio (0 = no damping, 1 = critical damping). Range [0, inf]: writes outside it are clamped with a warning.

WheelJoint2D.EnableLimit#

lua

WheelJoint2D.EnableLimit: boolean

Restricts the suspension travel to [LowerTranslation, UpperTranslation].

WheelJoint2D.LowerTranslation#

lua

WheelJoint2D.LowerTranslation: number

Lower suspension limit in world units.

WheelJoint2D.UpperTranslation#

lua

WheelJoint2D.UpperTranslation: number

Upper suspension limit in world units.

WheelJoint2D.EnableMotor#

lua

WheelJoint2D.EnableMotor: boolean

Drives the wheel rotation at MotorSpeed.

WheelJoint2D.MaxMotorTorque#

lua

WheelJoint2D.MaxMotorTorque: number

Maximum motor torque in newton-meters. Range [0, inf]: writes outside it are clamped with a warning.

WheelJoint2D.MotorSpeed#

lua

WheelJoint2D.MotorSpeed: number

Target wheel speed in radians per second. Radians.

WorldStreamingSource#

Cells of the scene's world (SceneSettings.World) stream in around this entity: those within its radius load, and unload once no source is within the radius plus the world's hysteresis margin. Players (servers) and the local player and camera (clients) are sources already; add it for extra points such as a scripted fly-over or a teleport destination being prepared.

lua

local component = self.Entity:GetComponent("WorldStreamingSource")

Member	Kind	Summary
`WorldStreamingSource.RadiusCells: integer`	Property	Cells loaded around the entity in every direction (Chebyshev distance); 0 uses the world's (or each layer's) load radius.
`WorldStreamingSource.Layers: integer`	Property	The world's layers this source streams: bit i is layer i of the .fworld (65535, every bit: every layer).
`WorldStreamingSource.Priority: integer`	Property	Among requests at the same distance, cells of higher-priority sources load first.

WorldStreamingSource.RadiusCells#

lua

WorldStreamingSource.RadiusCells: integer

Cells loaded around the entity in every direction (Chebyshev distance); 0 uses the world's (or each layer's) load radius. Range [0, 64]: writes outside it are clamped with a warning.

WorldStreamingSource.Layers#

lua

WorldStreamingSource.Layers: integer

The world's layers this source streams: bit i is layer i of the .fworld (65535, every bit: every layer). Range [0, 65535]: writes outside it are clamped with a warning.

WorldStreamingSource.Priority#

lua

WorldStreamingSource.Priority: integer

Among requests at the same distance, cells of higher-priority sources load first. Range [-100, 100]: writes outside it are clamped with a warning.

Enums#

Read-only tables of named integer values.

CursorMode#

Cursor modes for Input.SetCursorMode.

lua

Input.SetCursorMode(CursorMode.Hidden)

Member	Kind	Summary
`CursorMode.Normal = 0`	EnumValue	The system cursor, visible and free.
`CursorMode.Hidden = 1`	EnumValue	Invisible while over the window; moves freely (draw your own cursor).
`CursorMode.Locked = 2`	EnumValue	Invisible and captured by the window: the position is virtual and unbounded, read Input.GetMouseDelta (camera control).

FogCellState#

The state of one fog-of-war cell (ordered: Hidden < Explored < Visible).

lua

if FogOfWar.GetCellState(x, y) >= FogCellState.Explored then
	showOnMinimap(x, y)
end

Member	Kind	Summary
`FogCellState.Hidden = 0`	EnumValue	Never seen: drawn with the fog's color.
`FogCellState.Explored = 1`	EnumValue	Seen before but not now: drawn with the fog's color at its explored opacity.
`FogCellState.Visible = 2`	EnumValue	Seen now: no fog.

GamepadAxis#

Gamepad axes for Input.GetGamepadAxis.

lua

local x = Input.GetGamepadAxis(GamepadAxis.LeftX)

Member	Kind	Summary
`GamepadAxis.LeftX = 0`	EnumValue	The LeftX axis.
`GamepadAxis.LeftY = 1`	EnumValue	The LeftY axis.
`GamepadAxis.RightX = 2`	EnumValue	The RightX axis.
`GamepadAxis.RightY = 3`	EnumValue	The RightY axis.
`GamepadAxis.LeftTrigger = 4`	EnumValue	The LeftTrigger axis.
`GamepadAxis.RightTrigger = 5`	EnumValue	The RightTrigger axis.

GamepadButton#

Gamepad buttons (Xbox layout names) for the Input functions.

lua

if Input.IsGamepadButtonPressed(GamepadButton.A) then jump() end

Member	Kind	Summary
`GamepadButton.A = 0`	EnumValue	The A button.
`GamepadButton.B = 1`	EnumValue	The B button.
`GamepadButton.X = 2`	EnumValue	The X button.
`GamepadButton.Y = 3`	EnumValue	The Y button.
`GamepadButton.LeftBumper = 4`	EnumValue	The LeftBumper button.
`GamepadButton.RightBumper = 5`	EnumValue	The RightBumper button.
`GamepadButton.Back = 6`	EnumValue	The Back button.
`GamepadButton.Start = 7`	EnumValue	The Start button.
`GamepadButton.Guide = 8`	EnumValue	The Guide button.
`GamepadButton.LeftThumb = 9`	EnumValue	The LeftThumb button.
`GamepadButton.RightThumb = 10`	EnumValue	The RightThumb button.
`GamepadButton.DpadUp = 11`	EnumValue	The DpadUp button.
`GamepadButton.DpadRight = 12`	EnumValue	The DpadRight button.
`GamepadButton.DpadDown = 13`	EnumValue	The DpadDown button.
`GamepadButton.DpadLeft = 14`	EnumValue	The DpadLeft button.

Key#

Keyboard key codes (US layout positions) for the Input functions.

lua

if Input.IsKeyDown(Key.LeftShift) then speed = speed * 2 end

Member	Kind	Summary
`Key.Space = 32`	EnumValue	The Space key.
`Key.Apostrophe = 39`	EnumValue	The Apostrophe key.
`Key.Comma = 44`	EnumValue	The Comma key.
`Key.Minus = 45`	EnumValue	The Minus key.
`Key.Period = 46`	EnumValue	The Period key.
`Key.Slash = 47`	EnumValue	The Slash key.
`Key.Num0 = 48`	EnumValue	The Num0 key.
`Key.Num1 = 49`	EnumValue	The Num1 key.
`Key.Num2 = 50`	EnumValue	The Num2 key.
`Key.Num3 = 51`	EnumValue	The Num3 key.
`Key.Num4 = 52`	EnumValue	The Num4 key.
`Key.Num5 = 53`	EnumValue	The Num5 key.
`Key.Num6 = 54`	EnumValue	The Num6 key.
`Key.Num7 = 55`	EnumValue	The Num7 key.
`Key.Num8 = 56`	EnumValue	The Num8 key.
`Key.Num9 = 57`	EnumValue	The Num9 key.
`Key.Semicolon = 59`	EnumValue	The Semicolon key.
`Key.Equal = 61`	EnumValue	The Equal key.
`Key.A = 65`	EnumValue	The A key.
`Key.B = 66`	EnumValue	The B key.
`Key.C = 67`	EnumValue	The C key.
`Key.D = 68`	EnumValue	The D key.
`Key.E = 69`	EnumValue	The E key.
`Key.F = 70`	EnumValue	The F key.
`Key.G = 71`	EnumValue	The G key.
`Key.H = 72`	EnumValue	The H key.
`Key.I = 73`	EnumValue	The I key.
`Key.J = 74`	EnumValue	The J key.
`Key.K = 75`	EnumValue	The K key.
`Key.L = 76`	EnumValue	The L key.
`Key.M = 77`	EnumValue	The M key.
`Key.N = 78`	EnumValue	The N key.
`Key.O = 79`	EnumValue	The O key.
`Key.P = 80`	EnumValue	The P key.
`Key.Q = 81`	EnumValue	The Q key.
`Key.R = 82`	EnumValue	The R key.
`Key.S = 83`	EnumValue	The S key.
`Key.T = 84`	EnumValue	The T key.
`Key.U = 85`	EnumValue	The U key.
`Key.V = 86`	EnumValue	The V key.
`Key.W = 87`	EnumValue	The W key.
`Key.X = 88`	EnumValue	The X key.
`Key.Y = 89`	EnumValue	The Y key.
`Key.Z = 90`	EnumValue	The Z key.
`Key.LeftBracket = 91`	EnumValue	The LeftBracket key.
`Key.Backslash = 92`	EnumValue	The Backslash key.
`Key.RightBracket = 93`	EnumValue	The RightBracket key.
`Key.GraveAccent = 96`	EnumValue	The GraveAccent key.
`Key.World1 = 161`	EnumValue	The World1 key.
`Key.World2 = 162`	EnumValue	The World2 key.
`Key.Escape = 256`	EnumValue	The Escape key.
`Key.Enter = 257`	EnumValue	The Enter key.
`Key.Tab = 258`	EnumValue	The Tab key.
`Key.Backspace = 259`	EnumValue	The Backspace key.
`Key.Insert = 260`	EnumValue	The Insert key.
`Key.Delete = 261`	EnumValue	The Delete key.
`Key.Right = 262`	EnumValue	The Right key.
`Key.Left = 263`	EnumValue	The Left key.
`Key.Down = 264`	EnumValue	The Down key.
`Key.Up = 265`	EnumValue	The Up key.
`Key.PageUp = 266`	EnumValue	The PageUp key.
`Key.PageDown = 267`	EnumValue	The PageDown key.
`Key.Home = 268`	EnumValue	The Home key.
`Key.End = 269`	EnumValue	The End key.
`Key.CapsLock = 280`	EnumValue	The CapsLock key.
`Key.ScrollLock = 281`	EnumValue	The ScrollLock key.
`Key.NumLock = 282`	EnumValue	The NumLock key.
`Key.PrintScreen = 283`	EnumValue	The PrintScreen key.
`Key.Pause = 284`	EnumValue	The Pause key.
`Key.F1 = 290`	EnumValue	The F1 key.
`Key.F2 = 291`	EnumValue	The F2 key.
`Key.F3 = 292`	EnumValue	The F3 key.
`Key.F4 = 293`	EnumValue	The F4 key.
`Key.F5 = 294`	EnumValue	The F5 key.
`Key.F6 = 295`	EnumValue	The F6 key.
`Key.F7 = 296`	EnumValue	The F7 key.
`Key.F8 = 297`	EnumValue	The F8 key.
`Key.F9 = 298`	EnumValue	The F9 key.
`Key.F10 = 299`	EnumValue	The F10 key.
`Key.F11 = 300`	EnumValue	The F11 key.
`Key.F12 = 301`	EnumValue	The F12 key.
`Key.F13 = 302`	EnumValue	The F13 key.
`Key.F14 = 303`	EnumValue	The F14 key.
`Key.F15 = 304`	EnumValue	The F15 key.
`Key.F16 = 305`	EnumValue	The F16 key.
`Key.F17 = 306`	EnumValue	The F17 key.
`Key.F18 = 307`	EnumValue	The F18 key.
`Key.F19 = 308`	EnumValue	The F19 key.
`Key.F20 = 309`	EnumValue	The F20 key.
`Key.F21 = 310`	EnumValue	The F21 key.
`Key.F22 = 311`	EnumValue	The F22 key.
`Key.F23 = 312`	EnumValue	The F23 key.
`Key.F24 = 313`	EnumValue	The F24 key.
`Key.F25 = 314`	EnumValue	The F25 key.
`Key.Keypad0 = 320`	EnumValue	The Keypad0 key.
`Key.Keypad1 = 321`	EnumValue	The Keypad1 key.
`Key.Keypad2 = 322`	EnumValue	The Keypad2 key.
`Key.Keypad3 = 323`	EnumValue	The Keypad3 key.
`Key.Keypad4 = 324`	EnumValue	The Keypad4 key.
`Key.Keypad5 = 325`	EnumValue	The Keypad5 key.
`Key.Keypad6 = 326`	EnumValue	The Keypad6 key.
`Key.Keypad7 = 327`	EnumValue	The Keypad7 key.
`Key.Keypad8 = 328`	EnumValue	The Keypad8 key.
`Key.Keypad9 = 329`	EnumValue	The Keypad9 key.
`Key.KeypadDecimal = 330`	EnumValue	The KeypadDecimal key.
`Key.KeypadDivide = 331`	EnumValue	The KeypadDivide key.
`Key.KeypadMultiply = 332`	EnumValue	The KeypadMultiply key.
`Key.KeypadSubtract = 333`	EnumValue	The KeypadSubtract key.
`Key.KeypadAdd = 334`	EnumValue	The KeypadAdd key.
`Key.KeypadEnter = 335`	EnumValue	The KeypadEnter key.
`Key.KeypadEqual = 336`	EnumValue	The KeypadEqual key.
`Key.LeftShift = 340`	EnumValue	The LeftShift key.
`Key.LeftControl = 341`	EnumValue	The LeftControl key.
`Key.LeftAlt = 342`	EnumValue	The LeftAlt key.
`Key.LeftSuper = 343`	EnumValue	The LeftSuper key.
`Key.RightShift = 344`	EnumValue	The RightShift key.
`Key.RightControl = 345`	EnumValue	The RightControl key.
`Key.RightAlt = 346`	EnumValue	The RightAlt key.
`Key.RightSuper = 347`	EnumValue	The RightSuper key.
`Key.Menu = 348`	EnumValue	The Menu key.

MouseButton#

Mouse buttons for the Input functions.

lua

if Input.IsMouseButtonPressed(MouseButton.Left) then fire() end

Member	Kind	Summary
`MouseButton.Left = 0`	EnumValue	The Left mouse button.
`MouseButton.Right = 1`	EnumValue	The Right mouse button.
`MouseButton.Middle = 2`	EnumValue	The Middle mouse button.
`MouseButton.Button4 = 3`	EnumValue	The Button4 mouse button.
`MouseButton.Button5 = 4`	EnumValue	The Button5 mouse button.
`MouseButton.Button6 = 5`	EnumValue	The Button6 mouse button.
`MouseButton.Button7 = 6`	EnumValue	The Button7 mouse button.
`MouseButton.Button8 = 7`	EnumValue	The Button8 mouse button.

ParticleStopBehavior#

What ParticleSystem:Stop does with the particles that are alive.

lua

emitter:Stop(ParticleStopBehavior.StopEmittingAndClear)

Member	Kind	Summary
`ParticleStopBehavior.StopEmitting = 0`	EnumValue	Stops emitting; live particles finish their lifetime.
`ParticleStopBehavior.StopEmittingAndClear = 1`	EnumValue	Stops emitting and removes the live particles at once.

TileFlags#

Orientation flags of a tile (combine them with |): the image is rotated first, then mirrored.

lua

tilemap:SetTile(4, 2, 7, TileFlags.FlipX | TileFlags.Rotate90)

Member	Kind	Summary
`TileFlags.FlipX = 1`	EnumValue	Mirrors the tile horizontally.
`TileFlags.FlipY = 2`	EnumValue	Mirrors the tile vertically.
`TileFlags.Rotate90 = 4`	EnumValue	Rotates the tile 90 degrees clockwise.

TouchPhase#

What a touch contact did in the current frame (Touch.Phase).

lua

local touch = Input.GetTouch(1)
if touch.Phase == TouchPhase.Began then self:StartAim(touch.Position) end

Member	Kind	Summary
`TouchPhase.Began = 0`	EnumValue	Touched down this frame (a contact that also lifted in that frame reports Ended in the next one, so no tap is missed).
`TouchPhase.Moved = 1`	EnumValue	Moved this frame.
`TouchPhase.Stationary = 2`	EnumValue	Held without moving this frame.
`TouchPhase.Ended = 3`	EnumValue	Lifted this frame (the last frame the contact is listed).
`TouchPhase.Cancelled = 4`	EnumValue	Taken away by the system this frame (no tap must follow from it; also the last frame the contact is listed).

UIButtonState#

The visual state of a UI button (UIButton:GetState).

lua

if button:GetState() == UIButtonState.Pressed then ... end

Member	Kind	Summary
`UIButtonState.Normal = 0`	EnumValue	Idle.
`UIButtonState.Hover = 1`	EnumValue	The pointer is over the button (while the pointer is in use), or it has the focus (while keyboard/gamepad navigation is in use).
`UIButtonState.Pressed = 2`	EnumValue	Held down by the pointer (while over it), or by the Submit that clicked it.
`UIButtonState.Disabled = 3`	EnumValue	Interactable is off.

Lua standard library#

The subset of the Lua 5.4 standard library available in the script sandbox (see the Lua 5.4 reference manual for details).

coroutine#

Lua coroutines. Engine-scheduled coroutines are started with self:StartCoroutine.

Member	Kind	Summary
`coroutine.close(co: thread): boolean, any`	Function	Closes a suspended or dead coroutine (running its pending to-be-closed variables).
`coroutine.create(f: function): thread`	Function	A new coroutine running f.
`coroutine.isyieldable(co?: thread): boolean`	Function	True when the coroutine (default: the running one) can yield.
`coroutine.resume(co: thread, ...: any): boolean, any`	Function	Starts or continues co; returns true plus the values passed to yield (or returned), or false plus the error.
`coroutine.running(): thread, boolean`	Function	The running coroutine and whether it is the main one.
`coroutine.status(co: thread): string`	Function	"running", "suspended", "normal" or "dead".
`coroutine.wrap(f: function): function`	Function	A function that resumes a new coroutine running f on every call (errors propagate).
`coroutine.yield(...: any): any`	Function	Suspends the running coroutine; the values go to resume.

debug#

The safe part of Lua's debug library: traceback.

Member	Kind	Summary
`debug.traceback(message?: any, level?: integer): string`	Function	message followed by a traceback of the call stack (for xpcall handlers and error reports).

math#

Lua math library. See also the engine's Math namespace (Lerp, Clamp, seeded Random, ...).

Member	Kind	Summary
`math.abs(x: number): number`	Function	Absolute value.
`math.acos(x: number): number`	Function	Arc cosine in radians.
`math.asin(x: number): number`	Function	Arc sine in radians.
`math.atan(y: number, x?: number): number`	Function	Arc tangent of y/x in radians, using both signs for the quadrant (x defaults to 1).
`math.ceil(x: number): integer`	Function	Smallest integral value >= x.
`math.cos(x: number): number`	Function	Cosine of an angle in radians.
`math.deg(x: number): number`	Function	Converts radians to degrees.
`math.exp(x: number): number`	Function	e raised to the power x.
`math.floor(x: number): integer`	Function	Largest integral value <= x.
`math.fmod(x: number, y: number): number`	Function	Remainder of x / y rounded towards zero.
`math.huge: number (read-only)`	Constant	Positive infinity.
`math.log(x: number, base?: number): number`	Function	Logarithm of x in base (default e).
`math.max(x: number, ...: number): number`	Function	The largest argument.
`math.maxinteger: integer (read-only)`	Constant	The largest integer (2^63 - 1).
`math.min(x: number, ...: number): number`	Function	The smallest argument.
`math.mininteger: integer (read-only)`	Constant	The smallest integer (-2^63).
`math.modf(x: number): number, number`	Function	Integral and fractional parts of x.
`math.pi: number (read-only)`	Constant	The value of pi.
`math.rad(x: number): number`	Function	Converts degrees to radians.
`math.random(m?: integer, n?: integer): number`	Function	Lua's own generator (seeded from the scene seed when the engine starts): a float in [0, 1), or an integer in [1, m] or [m, n].
`math.randomseed(x?: integer, y?: integer): integer, integer`	Function	Reseeds Lua's own generator (math.random).
`math.sin(x: number): number`	Function	Sine of an angle in radians.
`math.sqrt(x: number): number`	Function	Square root.
`math.tan(x: number): number`	Function	Tangent of an angle in radians.
`math.tointeger(x: any): integer?`	Function	x as an integer when it has an exact integer value; nil otherwise.
`math.type(x: any): string?`	Function	"integer" or "float" for numbers, nil for anything else.
`math.ult(m: integer, n: integer): boolean`	Function	Unsigned comparison m < n.

os#

The safe part of Lua's os library: clock, time and date (no process, file or environment access).

Member	Kind	Summary
`os.clock(): number`	Function	CPU time used by the program, in seconds (for profiling; not game time).
`os.date(format?: string, time?: integer): any`	Function	Formats a time (default: now) like strftime; "t" / "!t" return a table of its fields.
`os.time(t?: table): integer`	Function	The current time, or the time described by a date table, in seconds since the epoch.

string#

Lua string library (patterns, formatting, binary packing). Strings also support method syntax: s:upper().

Member	Kind	Summary
`string.byte(s: string, i?: integer, j?: integer): integer`	Function	Numeric byte codes of s[i..j] (i defaults to 1, j to i).
`string.char(...: integer): string`	Function	A string made of the given byte codes.
`string.find(s: string, pattern: string, init?: integer, plain?: boolean): integer?, integer?`	Function	Start and end of the first match of pattern in s (plain = no pattern magic); nil when not found.
`string.format(format: string, ...: any): string`	Function	printf-style formatting (%d, %5.2f, %s, %q, %x, ...).
`string.gmatch(s: string, pattern: string, init?: integer): function`	Function	Iterator over the matches (or captures) of pattern in s (see find about expensive patterns).
`string.gsub(s: string, pattern: string, replacement: string\|table\|function, n?: integer): string, integer`	Function	Copy of s with (the first n) matches replaced; also returns the number of replacements (see find about expensive patterns).
`string.len(s: string): integer`	Function	Length in bytes.
`string.lower(s: string): string`	Function	Copy with ASCII letters in lower case.
`string.match(s: string, pattern: string, init?: integer): any`	Function	Captures of the first match of pattern (the whole match without captures); nil when not found (see find about expensive patterns).
`string.pack(format: string, ...: any): string`	Function	Binary string with the values serialized according to format.
`string.packsize(format: string): integer`	Function	Size of a string produced by string.pack with this fixed-size format.
`string.rep(s: string, n: integer, separator?: string): string`	Function	s repeated n times, separated by separator.
`string.reverse(s: string): string`	Function	s with its bytes in reverse order.
`string.sub(s: string, i: integer, j?: integer): string`	Function	Substring s[i..j]; negative indices count from the end.
`string.unpack(format: string, s: string, position?: integer): any`	Function	Values serialized in s by string.pack, followed by the position after them.
`string.upper(s: string): string`	Function	Copy with ASCII letters in upper case.
`string.__add(a: string\|number, b: string\|number): number`	Operator	a + b with numeric strings converted to numbers ("10" + 1 == 11).
`string.__sub(a: string\|number, b: string\|number): number`	Operator	a - b with numeric strings converted to numbers.
`string.__mul(a: string\|number, b: string\|number): number`	Operator	a * b with numeric strings converted to numbers.
`string.__div(a: string\|number, b: string\|number): number`	Operator	a / b with numeric strings converted to numbers.
`string.__mod(a: string\|number, b: string\|number): number`	Operator	a % b with numeric strings converted to numbers.
`string.__pow(a: string\|number, b: string\|number): number`	Operator	a ^ b with numeric strings converted to numbers.
`string.__idiv(a: string\|number, b: string\|number): number`	Operator	a // b with numeric strings converted to numbers.
`string.__unm(a: string): number`	Operator	-a with a numeric string converted to a number.

table#

Lua table library (insert, remove, sort, concat, ...).

Member	Kind	Summary
`table.concat(t: table, separator?: string, i?: integer, j?: integer): string`	Function	Concatenation of the strings/numbers t[i..j] with separator between them.
`table.insert(t: table, position: any, value?: any)`	Function	Inserts value at position (shifting later elements up), or appends position's value when only two arguments are given.
`table.move(a1: table, f: integer, e: integer, t: integer, a2?: table): table`	Function	Copies a1[f..e] to a2[t..] (a2 defaults to a1) and returns a2.
`table.pack(...: any): table`	Function	A table with the arguments at 1..n and n holding their count.
`table.remove(t: table, position?: integer): any`	Function	Removes and returns t[position] (default: the last element), shifting later elements down.
`table.sort(t: table, comparator?: function)`	Function	Sorts t[1..#t] in place (not stable); comparator(a, b) returns true when a goes first.
`table.unpack(t: table, i?: integer, j?: integer): any`	Function	Returns t[i], ..., t[j] (default 1..#t).

utf8#

Lua UTF-8 support (strings are UTF-8 encoded).

Member	Kind	Summary
`utf8.char(...: integer): string`	Function	UTF-8 encoding of the given code points.
`utf8.charpattern: string (read-only)`	Constant	Pattern matching exactly one UTF-8 byte sequence.
`utf8.codepoint(s: string, i?: integer, j?: integer, lax?: boolean): integer`	Function	Code points of the characters starting between byte positions i and j.
`utf8.codes(s: string, lax?: boolean): function`	Function	Iterator over (byte position, code point) of every character.
`utf8.len(s: string, i?: integer, j?: integer, lax?: boolean): integer?`	Function	Number of characters between byte positions i and j; nil plus the position of the first invalid byte.
`utf8.offset(s: string, n: integer, i?: integer): integer?`	Function	Byte position where the n-th character (counted from position i) starts.