Types and handles

These values cross the sandbox boundary. Only the members and operations below are permitted. CLR names are secondary references for reading the engine source.

Tile View

TileView is a readonly snapshot returned by World.getTile. Its TileID is copied when the view is created; it does not expose a tile or map. Retaining the view retains that ID even when the world tile changes or is replaced. Read TileID for an integer type ID and query again for current tile data. No host method accepts the view itself, and Lua cannot change its members or use it to change the world tile.

Lua type: TileView. CLR: LuaTileView. Source: Utils/Lua/LuaWorldHost.cs.

Properties

Name	Lua type	Access	Notes
TileID	integer	Read-only	Read the selected tile's type ID. Readonly tile type ID captured when the view is created.

Entity View

EntityView is a live view of a living entity or nearby flora. Living-backed views come from World's findClosestTarget, findRandomTarget, getEntitiesTouchingCircle, and spawnCreature, from Creature.FindTarget, and from hit/status callbacks and non-player living-owner reads. Flora-backed views come from World.getNearestFlora. Living-backed views permit position, size, and maximum-health changes and accept StatusEffectHandle through AddStatusEffect. They also work as living targets for World, Item, Projectile, and Creature helpers and as owner values for Item and Projectile. Flora-backed views report position, return 0 for size/health, ignore writes and status effects, and do not unwrap as living targets or owners. They are distinct from the Flora proxy returned by World.createFlora. Views retain the original object: death or removal does not turn a retained view into nil or stop its living-property setters. Check IsValid for current-world presence and Dying/Health before acting. Compare Id values across queries or proxy types; wrapper equality is not entity identity. Id is process-local and must not be saved or sent to peers. This view is distinct from a pack creature's Creature script proxy.

Lua type: EntityView. CLR: LuaEntityView. Source: Utils/Lua/LuaWorldHost.cs.

Properties

Name	Lua type	Access	Notes
CurGlobalCenter	Vector2	Read-only	Read the living entity's center or the flora's position. Readonly world-space position in pixels.
Dying	boolean	Read-only	Whether a living entity is in its dying phase. False for flora or an absent host.
Health	number	Read-only	Read the living entity's current health. Current health in damage points; flora-backed and absent views return 0. Read-only.
Height	integer	Read/write	Read or change the living entity's height. Height in pixels; flora-backed views return 0 and ignore writes.
Id	string or nil	Read-only	Opaque identity shared by all views and proxies of this object. Stable for this object in this running process, including before insertion. Compare Id values or use them as Lua table keys. Not a save, content, or network ID; nil for an absent host.
IsDead	boolean	Read-only	Whether the host is marked dead by the engine. Live death flag for living entities or flora; false for an absent host. Removal alone need not mark a host dead; use IsValid for world presence.
IsPlayer	boolean	Read-only	Whether this view refers to an actual player. Human NPCs and flora return false.
IsValid	boolean	Read-only	Whether this object is present and not marked dead in the current Lua world. False before insertion, after removal or replacement, on another world, or when marked dead. Dying entities can remain valid until removal; check Dying or Health before targeting.
MaxHealth	number	Read/write	Read or change the living entity's maximum health. Maximum health; flora-backed views return 0 and ignore writes.
TypeId	string or nil	Read-only	Read the content identity separately from the instance Id. Namespaced pack identifier, built-in living entity enum name, or PLAYER for a player. Flora uses its registered content identifier. Nil for an absent host.
Width	integer	Read/write	Read or change the living entity's width. Width in pixels; flora-backed views return 0 and ignore writes.
X	number	Read/write	Read or change the entity's horizontal world position. X position in pixels; writes affect living entities only.
Y	number	Read/write	Read or change the entity's vertical world position. Y position in pixels; writes affect living entities only.

Methods

Lua call	Arguments	Returns	Notes
entityView:AddStatusEffect(statusEffect)	statusEffect: StatusEffectHandle or nil — Handle created for this entity by World.createStatusEffect; nil and flora-backed views do nothing.	no return value — No result.	Attach a status-effect handle created for the living entity behind this view. Wrong-target, expired, or already attached handles do nothing. A merged handle tracks the exact retained effect.
entityView:HasTag(tag)	tag: string — Authored tag to look up.	boolean — False when no matching tag or host is available.	Check an exact, case-sensitive authored entity or flora tag.
entityView:Heal(amount)	amount: number — Finite nonnegative health points; invalid values raise an error. Healing does not revive dead or dying targets.	number — Actual health restored, or zero for a flora-backed, absent, dead, dying, or fully healed target.	Heal the living target in the local simulation, clamped to maximum health.

Spawned Item View

SpawnedItemView is a live position, size, and velocity view returned by World.getNewItem before the item is added to the world. Set its spawn values, then pass it to World.addItemToWorld. The view's fields are mutable and write directly to the retained item. Adding the item is allowed only while it is fresh and detached; repeated insertion and retained views of removed items do nothing. It does not consume the view or convert it to an Item script proxy; subsequent reads and writes still affect that same item. World removal does not clear the reference, and the view has no existence check or automatic registration/recreation. The world-add helper is its only host consumer. It exposes no inventory, owner, or general Item API.

Lua type: SpawnedItemView. CLR: LuaSpawnedItemView. Source: Utils/Lua/LuaWorldHost.cs.

Properties

Name	Lua type	Access	Notes
Height	integer	Read/write	Read or change the item's height. Height in pixels.
VelX	number	Read/write	Read or change the item's horizontal velocity. X velocity used when the item is added to the world.
VelY	number	Read/write	Read or change the item's vertical velocity. Y velocity used when the item is added to the world.
Width	integer	Read/write	Read or change the item's width. Width in pixels.
X	number	Read/write	Read or change the item's horizontal spawn position. World X position in pixels.
Y	number	Read/write	Read or change the item's vertical spawn position. World Y position in pixels.

Melee Collision Point View

MeleeCollisionPointView is a readonly snapshot returned by Item.GetRandomGlobalCollisionPoint on supported loaded held-item hosts, or nil when no point is available. It copies a collision point's bone name and texture offsets. Retaining the snapshot does not track later animation or collision-point changes. Despite the acquisition method's name, these offsets are bone-relative texture coordinates, not a world-position Vector2. Read its fields as inputs to the Item's bone-position/effect helpers, respecting their offset conventions. No host method consumes the whole snapshot, and Lua cannot write its fields or change the underlying collision point.

Lua type: MeleeCollisionPointView. CLR: LuaMeleeCollisionPointView. Source: Utils/Lua/LuaWorldHost.cs.

Properties

Name	Lua type	Access	Notes
BoneName	string or nil	Read-only	Read the authored bone name. Readonly bone name, or nil when unspecified.
TextureOffsetX	number	Read-only	Read the horizontal texture offset. Readonly X offset relative to the named bone.
TextureOffsetY	number	Read-only	Read the vertical texture offset. Readonly Y offset relative to the named bone.

Owner Token

OwnerToken is an opaque fallback obtained from Item.Owner or Projectile.Owner when the owner has no Player, EntityView, Item, or Projectile proxy. It is not the type name for all owner values. Pass the token back to either Owner setter, or to World.playSpriterFX or betterExplosion as an entity/source value. It does not unwrap as a living-entity target. The token retains the original entity reference even after world removal; it provides no existence check and does not register or recreate that entity. Reacquire owner values after world changes rather than treating a retained token as proof of membership. It has no readable or writable Lua members and exposes no entity graph.

Lua type: OwnerToken. CLR: LuaOwnerView. Source: Utils/Lua/LuaOwner.cs.

This opaque handle has no permitted members. Use only the operations documented above.

Sound Effect Handle

SoundEffectHandle is a live audio-instance handle returned by Item.PlaySoundEffect or PlayLoopingSoundEffect. Either acquisition can return nil for an unsupported host or unavailable clip; a loaded melee one-shot plays without returning a handle. Retain the handle while controlling that sound. It has Pause and Resume methods and is accepted by Item's IsSoundPlaying, PauseSound, ResumeSound, StopSound, UpdateSFXPosition, and CleanUpSFXInstance. The last two require a loaded held-item host; the other item controls also support loaded melee hosts. These helpers operate on the referenced instance without checking that the receiving item created it. Cleanup stops and disposes the instance; finished one-shots and completed sound fades can also be disposed by the engine. Discard the handle after cleanup or disposal; retaining it does not keep the instance usable or expose an existence flag. Direct Pause and Resume tolerate disposed instances, but this is not a guarantee for all item helpers. Lua cannot assign instance state or access the underlying MonoGame instance and its members.

Lua type: SoundEffectHandle. CLR: LuaSoundEffectHandle. Source: Utils/Lua/LuaSoundEffectHandle.cs.

Methods

Lua call	Arguments	Returns	Notes
soundEffectHandle:Pause()	None	no return value — No result.	Pause this sound instance; missing or disposed instances do nothing.
soundEffectHandle:Resume()	None	no return value — No result.	Resume this sound instance; missing or disposed instances and an exhausted audio-instance limit do nothing.

Status Effect Handle

StatusEffectHandle is an opaque token returned by World.createStatusEffect, or nil for an unsupported type or unavailable world host. Creation does not attach the effect. Pass the handle to Player.AddStatusEffect or EntityView.AddStatusEffect for the same affected entity. The effect keeps the target selected at creation; passing its handle to another entity does not rebind that target. Attachment can merge with an existing effect under the engine's stacking/intensity rules. Once attached, the effect's duration counts down in milliseconds and it can expire or be removed with the affected entity. After attachment, the handle tracks the retained effect, including an existing effect refreshed by a merge. Cancelling that handle removes that exact retained effect and can therefore cancel a merged application. It never selects a later replacement effect. Read its type, intensity, remaining duration, and active/expired state; cancel it with Cancel. Retaining the handle does not refresh or restart it; create a new handle for a new application. The target and underlying status-effect object remain hidden. These operations affect the local simulation.

Lua type: StatusEffectHandle. CLR: LuaStatusEffectHandle. Source: Utils/Lua/LuaStatusEffectHandle.cs.

Properties

Name	Lua type	Access	Notes
Duration	number	Read-only	Read the remaining duration in milliseconds. Remaining milliseconds, clamped to zero after expiry or cancellation. Before attachment time does not count down.
Intensity	number	Read-only	Read the effect-specific intensity. Current intensity, including a retained merged effect's intensity.
IsActive	boolean	Read-only	Check whether this exact effect remains attached to a living target. True while attached, unexpired, and the target is alive. A weaker non-stacking effect can be active while its application is suppressed by a stronger effect.
IsExpired	boolean	Read-only	Check whether duration elapsed, cancellation occurred, or the target is dead or dying. False for a fresh unattached effect. An effect removed by another operation can be inactive without being expired.
TypeId	string or nil	Read-only	Read the registered custom identity or built-in status-effect enum name. Pack StatusEffectTypeString, built-in enum name, or nil for an absent effect.

Methods

Lua call	Arguments	Returns	Notes
statusEffectHandle:Cancel()	None	boolean — True for the first cancellation of an unexpired effect; false when already expired. Removal is immediate, while modifiers already calculated for the current frame reset on the next status update.	Cancel this exact effect, attached or fresh, without cancelling other instances of its type.

Static Light Handle

StaticLightHandle is an opaque removal token returned by World.addStaticLightSource, or nil when no world/chunk is available at the requested position. Retain it while that light is needed, then pass it to World.removeStaticLightSource once. Removing the light does not clear a stored Lua handle. Clear your reference after removal, and do not reuse it across world changes. The handle has no existence flag, readable light state, or writable position/radius. It is only a removal token: retaining it does not keep the light registered, move the light, or create a replacement. No light object or map is exposed.

Lua type: StaticLightHandle. CLR: LuaStaticLightHandle. Source: Utils/Lua/LuaStaticLightHandle.cs.

This opaque handle has no permitted members. Use only the operations documented above.

Vector2

Obtain a vector from an API position property or Utils:angleRadToVector2(angle). X and Y are readable and writable numbers; normal vector operators are retained. World position/range consumers and damage/FX APIs accept vectors. Position properties can return value copies: editing the vector's fields may not move the source entity; use its documented X/Y setters. CLR: Microsoft.Xna.Framework.Vector2.

Lua call	Arguments	Returns	Notes
vector:Length()	None	number	Euclidean magnitude in the vector's units; for velocity, this is speed. This method does not change the vector.

Name	Lua type	Access	Notes
X	number	Read/write	Horizontal component.
Y	number	Read/write	Vertical component.

Game time

The runtime passes GameTime to update hooks. Treat it as a callback timing value; retain derived numbers rather than assuming a retained object stays unchanged. CLR: Microsoft.Xna.Framework.GameTime.

Name	Lua type	Access	Notes
ElapsedGameTime	TimeSpan	Read-only	Time since the preceding update.
TotalGameTime	TimeSpan	Read-only	Time since the game started.
IsRunningSlowly	boolean	Read-only	Runtime timing flag.

Time span

Obtain spans from GameTime. The exposed fields are read-only timing values; no other CLR methods are available. CLR: System.TimeSpan.

Name	Lua type	Access	Notes
Milliseconds	integer	Read-only	Millisecond component, rather than the entire duration.
Seconds	integer	Read-only	Second component.
Ticks	integer	Read-only	Entire duration in 100-nanosecond ticks.
TotalMilliseconds	number	Read-only	Entire duration in milliseconds.
TotalSeconds	number	Read-only	Entire duration in seconds.

Time token

Lua type: TimeToken. World:getTime() returns this opaque time token. It exposes no members. Save it and pass it to World:getTimeDiffMS(time1, time2) to measure milliseconds; do not call DateTime methods. CLR: System.DateTime.

Rectangle

The five-argument Item:ProjectTrajectory overload declares a Rectangle argument. The current sandbox has no Rectangle constructor or API producer and exposes no members on such a value, so ordinary scripts should use the four-argument overload. CLR: Microsoft.Xna.Framework.Rectangle.

Item type token

Lua type: ItemTypeToken. Obtain it from self.item:GetCurAmmoType(). The bundled NLua bridge returns this built-in ammo enum as userdata rather than a Lua integer; comparison with a numeric ID is false. Retaining a token retains that enum value and does not track later ammo changes. It exposes no fields or methods. Pass it to self.item:FireItem(token, speed, emitBoneName, emitBoneOffsetX, emitBoneOffsetY) or the Player methods GetItemQuantity, HasItemQuantity, and RemoveItemQuantity to use the built-in ammo type. Numeric enum IDs do not bind to those overloads; prefer their string overloads for namespaced pack IDs. Use tostring(token) for a diagnostic enum label and value. Unsupported item hosts return the NULL enum token. CLR: InventoryItemType. Source: Entities/Items/InventoryItemEnums.cs.

Query collections

World queries return QueryList<T>; APIs may also return QueryArray<T>. Here T is the registered API view/proxy element type linked in each contract. Lists expose read-only Count, arrays read-only Length. Both use zero-based integer indexing from 0 through count minus one. Collection mutation and CLR collection methods are unavailable. The collection holds the query results at that time; its views can still refer to live objects. Use list.Count rather than the currently broken generic Utils:countList helper; pass each element to an operation accepting its linked type.

Name	Lua type	Access	Notes
Count	integer	Read-only	QueryList only.
Length	integer	Read-only	QueryArray only.
[index]	Element type	Read-only	Zero-based indexing.

Examples

Nil-safe targeting from a creature hook:

local target = self.creature:FindTarget(200)
if target ~= nil then
    self.creature:DealMeleeDamage(target, 5)
end

Iterating a query list from a creature hook:

local nearby = World:getEntitiesTouchingCircle(self.creature.CurGlobalCenter, 100)
if nearby ~= nil then
    for i = 0, nearby.Count - 1 do
        local entity = nearby[i]
        local x = entity.X
    end
end

Passing a returned handle to its consumer (each call can return nil):

local effect = World:createStatusEffect("POISON", 1, 1000, self.player)
if effect ~= nil then
    self.player:AddStatusEffect(effect)
end

Generated 2026-10-02T21:05:27.5090099Z · b8c9ae78 · types and handles.

Official modding overview · Signs of Life on Steam