GameObject

A node in the 3D scene graph: a transform (position / rotation / scale), a place in the parent
→ child hierarchy, and a lifecycle (active / inactive / destroyed). Components — renderers,
colliders, lights, controllers, scripts — attach to a GameObject and read its transform.

Static calls use the type table (GameObject.Create()); instance methods use colon syntax on a
handle (gameObject:SetLocalPosition(...)).

Types

GameObject — an opaque handle (userdata) to a scene node. A handle may be null or stale
(its object destroyed); it is safe to keep and pass around. Calling a method on a null/stale
handle logs a warning and returns nil (or a documented default) — it never raises.
tostring(gameObject) yields GameObject{name}, or GameObject{NULL} if dead.

Creation & Destruction

GameObject.Create( ) : GameObject
Creates a new, active GameObject at the origin. Returns nil and logs an error if the scene
object pool is exhausted.

GameObject.CreateInactive( ) : GameObject
Same as Create, but the object starts disabled (its components do not run until activated).

GameObject.Instantiate( GameObject source ) : GameObject
Recursively clones source and its children. Returns nil and logs a warning if source is
null.

GameObject.Get( string name ) : GameObject
Finds a GameObject by its unique name. Returns nil and logs a warning if no match exists.

GameObject.Exists( GameObject object ) : boolean
Returns true if the handle refers to a live object. Safe on null/stale handles (returns
false) — this is the one call that never warns.

gameObject:Destroy( ) : void
Destroys the object (and its children) if it exists; logs a warning otherwise. Destruction is
deferred to the next safe point, so calling it on self from a callback is safe.

Functions

Read-only queries. Every getter returns nil and logs a warning on a null/stale handle unless
noted.

gameObject:Active( ) : boolean
The object’s own enabled flag, ignoring ancestors.

gameObject:ActiveInHierarchy( ) : boolean
true only if this object and every ancestor are active.

gameObject:Parent( ) : GameObject
The parent, or nil if the object is a scene root (a root is not an error — no warning).

gameObject:Root( ) : GameObject
The topmost ancestor (itself if already a root).

gameObject:Children( ) : table
An array (1-based) of the direct children.

gameObject:ChildCount( ) : integer
Number of direct children.

gameObject:GetChild( integer index ) : GameObject
The child at index (1-based); nil if out of range.

gameObject:FindChild( string name ) : GameObject
Depth-first search for a descendant named name; nil if none.

gameObject:IsChildOf( GameObject parent ) : boolean
true if parent is this object’s ancestor.

gameObject:IsRoot( ) : boolean
true if the object has no parent.

gameObject:FirstChild( ) : GameObject
First direct child, or nil.

gameObject:NextSibling( ) : GameObject
Next sibling under the shared parent, or nil.

gameObject:PreviousSibling( ) : GameObject
Previous sibling, or nil.

gameObject:Forward( ) : Vector3
World-space forward axis (+Z rotated by world rotation).

gameObject:Right( ) : Vector3
World-space right axis.

gameObject:Up( ) : Vector3
World-space up axis.

gameObject:TransformPoint( Vector3 point ) : Vector3
Transforms point from local to world space (scale, rotation, translation). Accepts a Vector3
or three numbers.

gameObject:TransformVector( Vector3 vector ) : Vector3
Local → world using scale and rotation (no translation).

gameObject:TransformDirection( Vector3 direction ) : Vector3
Local → world using rotation only.

gameObject:InverseTransformPoint( Vector3 point ) : Vector3
World → local (scale, rotation, translation).

gameObject:InverseTransformVector( Vector3 vector ) : Vector3
World → local using scale and rotation.

gameObject:InverseTransformDirection( Vector3 direction ) : Vector3
World → local using rotation only.

Properties (get / set)

Setters return void and no-op with a warning on a null/stale handle.

ID

gameObject:ID( ) : string — the object’s unique name.
gameObject:SetID( string name ) : void — renames the object.

LocalPosition

gameObject:LocalPosition( ) : Vector3 — position relative to the parent.
gameObject:SetLocalPosition( Vector3 position ) : void — accepts a Vector3 or three
numbers; three numbers preserve f64 precision through the floating-origin split.

LocalRotation

gameObject:LocalRotation( ) : Quaternion — rotation relative to the parent.
gameObject:SetLocalRotation( Quaternion rotation ) : void

LocalScale

gameObject:LocalScale( ) : number — uniform local scale.
gameObject:SetLocalScale( number scale ) : void

LocalEulerAngles

gameObject:LocalEulerAngles( ) : Vector3 — local rotation as YXZ Euler angles, in
degrees.
gameObject:SetLocalEulerAngles( Vector3 degrees ) : void

WorldPosition

gameObject:WorldPosition( ) : number, number, number — the precise world position as three
f64 numbers x, y, z (not a Vector3, which would be f32-lossy at range):
local x, y, z = go:WorldPosition().
gameObject:SetWorldPosition( Vector3 position ) : void — accepts a Vector3 or three f64
numbers.

WorldRotation

gameObject:WorldRotation( ) : Quaternion
gameObject:SetWorldRotation( Quaternion rotation ) : void

WorldScale

gameObject:WorldScale( ) : number — accumulated world scale.
gameObject:SetWorldScale( number scale ) : void

EulerAngles

gameObject:EulerAngles( ) : Vector3 — world rotation as YXZ Euler angles, in degrees.
gameObject:SetEulerAngles( Vector3 degrees ) : void

Layer

gameObject:Layer( ) : integer — the render/collision layer index.
gameObject:SetLayer( integer layer ) : void

Euler angle order variants

For each of the six rotation orders there are four accessors: world/local getter (returns a
Vector3 of degrees) and world/local setter (takes a Vector3 or three numbers of degrees).
EulerAngles / SetEulerAngles above are the default (YXZ) forms.

Methods

Actions that mutate the object. All no-op with a warning on a null/stale handle.

gameObject:Activate( ) : void
Enables the object and recursively updates children.

gameObject:Deactivate( ) : void
Disables the object and recursively updates children.

gameObject:SetParent( GameObject parent ) : void
Reparents the object, keeping it in the scene. parent may be a GameObject handle or a
string name. No-op with a warning if either object is invalid or the reparent would form a cycle.

gameObject:MakeRoot( ) : void
Detaches from the current parent, making the object a scene root.

gameObject:DetachChildren( ) : void
Unparents every direct child, making each a root.

gameObject:Translate( Vector3 delta ) : void
Moves the object by delta. Accepts a Vector3 or three numbers.

gameObject:Rotate( Quaternion rotation ) : void
Applies rotation on top of the current rotation.

gameObject:RotateAround( Vector3 point, Vector3 axis, number angle ) : void
Rotates the object angle radians about the world-space axis through point. point and
axis each accept a Vector3 or three numbers. (Note: unlike the SetEulerAngles* setters,
which take degrees, this angle is radians.)

gameObject:SetPositionAndRotation( Vector3 position, Quaternion rotation ) : void
Sets world position and rotation in one call. position accepts a Vector3 or three f64
numbers (three numbers preserve precision).

gameObject:LookAt( Vector3 target ) : void
gameObject:LookAt( Vector3 target, Vector3 up ) : void
Orients the object’s forward axis toward target. The optional up biases roll (defaults to
world up). target / up accept a Vector3 or three numbers.

Example

-- Orbit a child marker around its parent and keep it facing the parent's origin.
-- (Adapted from data/scripts/camera_orbit.lua.)
function Script.Update(self)
    local go = self.object
    local t  = Time.Time()
    local r  = 5.0

    -- Position relative to the parent, on a circle in the XZ plane.
    go:SetLocalPosition(math.cos(t) * r, 1.5, math.sin(t) * r)

    -- Face the parent's world origin (three f64 numbers, precise at range).
    local px, py, pz = go:Parent():WorldPosition()
    go:LookAt(px, py, pz)
end

Behavior

A Behavior is the handle to a ScriptBehavior component: the running instance of a
Script asset attached to a GameObject. Behavior.Attach creates one
from a loaded Script, giving the instance its own duplicated copy of the script’s function
references; the component then receives the script’s lifecycle callbacks.

Static calls use the type table (Behavior.Attach(...)); instance methods use colon syntax on a
handle (behavior:Activate()).

Types

Behavior — an opaque 8-byte handle (userdata) to a ScriptBehavior component. A handle may go
stale (its component destroyed). The two failure modes differ:

• Calling an instance method on a value that is not a Behavior userdata — including nil —
  raises a Lua type error. check_handle rejects any udata whose embedded type_id byte
  isn’t the ScriptBehavior id, so it never silently returns nil the way the GameObject getters
  do.
• A stale but correctly-typed handle is tolerated: each method degrades as documented below
  (nil, false, or a silent no-op).

tostring(behavior) always yields the constant string Behavior — it carries no object name and
does not change when the handle goes stale.

Creation & Destruction

Behavior.Attach( GameObject object, Script script ) : Behavior or nil
Creates a new ScriptBehavior on object using the functions from the script asset (each
instance gets its own duplicated function refs). Raises a Lua type error if object is not a
GameObject or script is not a Script. Returns nil and logs otherwise: NotFound if the script
cache is unavailable or the script index is not loaded, InvalidArgument if the component cannot
be added (e.g. object is stale).

Behavior.Get( GameObject object ) : Behavior or nil
Returns the ScriptBehavior already attached to object. Raises a Lua type error if object is not
a GameObject; returns nil and logs a warning (NotFound) if the object has no ScriptBehavior.

Behavior.Exists( Behavior behavior ) : boolean
The safe test. Uses luaL_testudata, so any non-Behavior value (including nil) returns false
without raising or warning. Returns true only if the handle resolves to live component data.

behavior:Destroy( ) : void
Destroys the component if the handle is live; silently no-ops on a stale handle (the result is
discarded — no warning, unlike GameObject:Destroy). Destruction is deferred to the next safe
point.

Functions

behavior:GameObject( ) : GameObject or nil
The GameObject this behavior is attached to (pushed with its cached slot resolved, so the returned
handle’s transform getters take the fast path). Returns nil and logs a warning (NotFound) if
the owner cannot be resolved (stale handle).

behavior:Active( ) : boolean or nil
The component’s own enabled flag — what Activate()/Deactivate() write. Mirrors
GameObject:Active(). Returns nil and logs a warning (NotFound) on a stale handle, so a
destroyed behavior is distinguishable from a merely disabled one.

Note this is intent, not effect: a behavior whose own flag is enabled but whose owning
GameObject is deactivated still reports true here — and does not run. Use
ActiveInHierarchy() for the effective answer.

behavior:ActiveInHierarchy( ) : boolean or nil
true only when this behavior’s own flag is enabled and its owning GameObject is active in
hierarchy — i.e. the behavior is actually receiving OnUpdate. This is the predicate the engine
itself uses to gate dispatch. Returns nil on a stale handle.

Fixed 2026-07 (was: behavior:Active() returned handle liveness, not enabled state — it
called get_component_data, which applies no active-flag filter, so it stayed true after
behavior:Deactivate() and duplicated Behavior.Exists). Active() now reads the component’s
enabled flag and ActiveInHierarchy() was added, matching the C reference’s
IcoComponent_ActiveSelf / IcoComponent_ActiveInHierarchy split. The three predicates are now
distinct: Behavior.Exists = the handle resolves; Active = own flag; ActiveInHierarchy =
own flag AND owner active.

Methods

behavior:Activate( ) : void
Sets the component’s own enabled flag. Its enable callback runs only if the owning GameObject is
also active. Silently no-ops on a stale handle — the result is discarded, so no warning is logged.

behavior:Deactivate( ) : void
Clears the component’s own enabled flag; the disable callback runs only if the behavior was
actually active. Silently no-ops on a stale handle.

Example

-- Load a script once, then attach it as a behavior on a new object.
local script = Script.Create("spinner", "scripts/spinner.lua")

local go = GameObject.Create()
local behavior = Behavior.Attach(go, script)

-- Attach can fail (returns nil) — guard before using the handle.
if Behavior.Exists(behavior) then
    behavior:Activate()
end

-- The three predicates answer three different questions.
behavior:Deactivate()
print(Behavior.Exists(behavior))     --> true   (the handle still resolves)
print(behavior:Active())             --> false  (its own flag is off)
print(behavior:ActiveInHierarchy())  --> false  (so it is not running)

behavior:Activate()
go:Deactivate()
print(behavior:Active())             --> true   (own flag untouched by the owner)
print(behavior:ActiveInHierarchy())  --> false  (but the owner is off, so it still isn't running)

Script

A Script is a named, cached asset holding the function references parsed from a .lua file.
Scripts are loaded once into a fixed-size cache (max 256) and retrieved by name; a
Behavior is what actually runs one on a GameObject.

Static calls use the type table (Script.Create(...)); the one instance method uses colon syntax
on a handle (script:ID()).

Types

Script — an opaque 8-byte handle (userdata) into the script cache. The handle encodes
cache_index + 1 in a Handle64 with a fixed generation of 1: scripts are append-only and never
recycled, so a handle stays valid for the life of the Lua state. tostring(script) yields
Script{name}, or the bare string Script if the entry cannot be resolved.

The safe test is Script.Exists (never raises). By contrast script:ID() runs check_handle,
which raises a Lua type error if called on a value that is not a Script userdata.

Creation & Destruction

Script.Create( string name, string filename ) : Script or nil
Loads the script at filename (resolved against the cache’s base directory) and registers it
under name. name and filename must be strings — a non-string argument raises, and non-UTF-8
bytes raise a Lua argument error. Returns nil if the cache pointer is unset (silent) or the file
fails to load (silent); if the cache is full it returns nil and prints [Script] Cache full… to
stderr.

Known issue: Script.Create is idempotent on name alone — if a script with that name is
already cached it returns the existing handle and ignores the new filename
(lua_script.rs:311). Registering two different files under one name is silently impossible; the
first load wins. There is also no Lua-side unload or replace (the cache is append-only, capacity
256); reloading from disk is a Rust-only path (ScriptCache::reload_all).

Script.Get( string name ) : Script or nil
Returns the handle for an already-loaded script name. name must be a string (non-string /
non-UTF-8 raises). Returns nil — with no warning — if the cache is unset or no script by that
name is registered.

Script.Exists( Script script ) : boolean
The safe test. Returns false for a null pointer, any userdata whose length isn’t 8 bytes, or any
whose embedded type_id isn’t the Script id; otherwise checks that the cache slot is loaded. Never
raises — safe on null / wrong-type / unresolved handles.

Functions

script:ID( ) : string or nil
The script’s registered name. Raises a Lua type error if called on a non-Script value; returns
nil if the handle’s cache entry cannot be resolved.

Example

-- Load once at startup; look it up by name later.
local script = Script.Create("enemy", "scripts/enemy.lua")

-- ...elsewhere...
local same = Script.Get("enemy")
if Script.Exists(same) then
    print(same:ID())   -- "enemy"
end

Vector2

A 2-component float vector. Like Vector3, Vector2 is a native Lua value (stored inline in
the Lua fork’s vector TValue — no garbage collection), so passing and returning them is cheap.

Static math functions are called on the type table (Vector2.Dot(a, b)); the two instance methods
use colon syntax (v:magnitude()).

Types

Vector2 — a native vector value with components x, y (f32). Read them as fields: v.x,
v.y. tostring(v) yields Vec2{x,y}. Vectors participate in the fork’s native vector arithmetic
(a + b, a - b, v * scalar); for element-wise product and quotient use ComponentMul /
ComponentDiv.

Every static function below reads its vector arguments with check_vector, which requires an
actual native Vector2 value (from .new, .zero, arithmetic, or an engine getter) and
raises a Lua type error on a number or a wrong vector variant. Loose numbers are accepted only
by .new. There is no null/stale concept — these are values, not handles.

Construction

Vector2.new( number x, number y ) : Vector2
Constructs a vector. Missing — or non-numeric — arguments default to 0 (no error), so
Vector2.new() is the zero vector and Vector2.new(1) is (1, 0).

Vector2.zero( ) : Vector2
Returns (0, 0).

Functions

Static operations. Each takes native Vector2 values (see Types).

Vector2.Dot( Vector2 a, Vector2 b ) : number
Dot product.

Vector2.Distance( Vector2 a, Vector2 b ) : number
Euclidean distance between two points.

Vector2.Normalize( Vector2 v ) : Vector2
Returns v scaled to unit length.

Vector2.Lerp( Vector2 a, Vector2 b, number t ) : Vector2
Linear interpolation from a to b by t. t is a required number (raises if missing); it is
not clamped to [0, 1].

Vector2.Min( Vector2 a, Vector2 b ) : Vector2
Component-wise minimum.

Vector2.Max( Vector2 a, Vector2 b ) : Vector2
Component-wise maximum.

Vector2.Abs( Vector2 v ) : Vector2
Component-wise absolute value.

Vector2.ComponentMul( Vector2 a, Vector2 b ) : Vector2
Element-wise product (a.x*b.x, a.y*b.y).

Vector2.ComponentDiv( Vector2 a, Vector2 b ) : Vector2
Element-wise quotient.

Vector2 intentionally exposes a smaller surface than Vector3: it has no Cross,
SqrDistance, Angle, SignedAngle, Project, ProjectOnPlane, Reflect, MoveTowards, or
ClampMagnitude.

Methods

v:magnitude( ) : number
The vector’s length.

v:sqrMagnitude( ) : number
The squared length (cheaper than magnitude).

Example

-- Normalize a 2D steering direction and scale it to a fixed speed.
local dir  = Vector2.Normalize(Vector2.new(dx, dy))
local step = dir * speed          -- native scalar multiply
print(step.x, step.y)

Vector3

A 3-component float vector. Unlike handle types, Vector3 is a native Lua value (stored
inline in the Lua fork’s vector TValue — no garbage collection), so passing and returning them
is cheap. Most engine APIs that take a Vector3 also accept three loose numbers.

Static math functions are called on the type table (Vector3.Dot(a, b)); the two instance
methods use colon syntax (v:magnitude()).

Types

Vector3 — a native vector value with components x, y, z (f32). Read them as fields:
v.x, v.y, v.z. tostring(v) yields Vec3{x,y,z}. Vectors participate in the fork’s native
vector arithmetic (a + b, a - b, v * scalar); for element-wise product and quotient use
ComponentMul / ComponentDiv.

Construction

Vector3.new( number x, number y, number z ) : Vector3
Constructs a vector. Missing arguments default to 0, so Vector3.new() is the zero vector and
Vector3.new(1) is (1, 0, 0).

Vector3.zero( ) : Vector3
Returns (0, 0, 0).

Functions

Static operations. Angles are in radians (the math primitives use radians; the GameObject
Euler setters, which take degrees, are the exception).

Vector3.Dot( Vector3 a, Vector3 b ) : number
Dot product.

Vector3.Cross( Vector3 a, Vector3 b ) : Vector3
Cross product a × b.

Vector3.Distance( Vector3 a, Vector3 b ) : number
Euclidean distance between two points.

Vector3.SqrDistance( Vector3 a, Vector3 b ) : number
Squared distance (cheaper — no square root).

Vector3.Normalize( Vector3 v ) : Vector3
Returns v scaled to unit length.

Vector3.Lerp( Vector3 a, Vector3 b, number t ) : Vector3
Linear interpolation from a to b by t.

Vector3.Min( Vector3 a, Vector3 b ) : Vector3
Component-wise minimum.

Vector3.Max( Vector3 a, Vector3 b ) : Vector3
Component-wise maximum.

Vector3.Abs( Vector3 v ) : Vector3
Component-wise absolute value.

Vector3.ComponentMul( Vector3 a, Vector3 b ) : Vector3
Element-wise product (a.x*b.x, a.y*b.y, a.z*b.z).

Vector3.ComponentDiv( Vector3 a, Vector3 b ) : Vector3
Element-wise quotient.

Vector3.Angle( Vector3 from, Vector3 to ) : number
Unsigned angle (radians) between two directions.

Vector3.SignedAngle( Vector3 from, Vector3 to, Vector3 axis ) : number
Signed angle (radians) about axis.

Vector3.Project( Vector3 v, Vector3 onto ) : Vector3
Projection of v onto onto.

Vector3.ProjectOnPlane( Vector3 v, Vector3 normal ) : Vector3
Component of v in the plane with the given normal.

Vector3.Reflect( Vector3 v, Vector3 normal ) : Vector3
Reflects v across the plane defined by normal.

Vector3.MoveTowards( Vector3 current, Vector3 target, number maxDistance ) : Vector3
Moves current toward target by at most maxDistance.

Vector3.ClampMagnitude( Vector3 v, number maxLength ) : Vector3
Returns v shortened to maxLength if longer.

Methods

v:magnitude( ) : number
The vector’s length. (Also computed inline in the type — call it as a method.)

v:sqrMagnitude( ) : number
The squared length (cheaper than magnitude).

Example

-- Steer toward a target at fixed speed, clamped so we never overshoot.
function Script.Update(self)
    local x, y, z = self.object:WorldPosition()
    local here = Vector3.new(x, y, z)
    local step = Vector3.MoveTowards(here, self.target, self.speed * Time.DeltaTime())
    self.object:SetWorldPosition(step)

    if Vector3.SqrDistance(step, self.target) < 0.01 then
        self.arrived = true
    end
end

Vector4

A 4-component float vector. Like Vector3, Vector4 is a native Lua value (stored inline in
the Lua fork’s vector TValue — no garbage collection), so passing and returning them is cheap.

Static math functions are called on the type table (Vector4.Dot(a, b)); the two instance methods
use colon syntax (v:magnitude()).

Types

Vector4 — a native vector value with components x, y, z, w (f32). Read them as fields:
v.x, v.y, v.z, v.w. tostring(v) yields Vec4{x,y,z,w}. Vectors participate in the fork’s
native vector arithmetic (a + b, a - b, v * scalar); for element-wise product and quotient
use ComponentMul / ComponentDiv.

Every static function below reads its vector arguments with check_vector, which requires an
actual native Vector4 value (from .new, .zero, arithmetic, or an engine getter) and
raises a Lua type error on a number or a wrong vector variant. Loose numbers are accepted only
by .new. There is no null/stale concept — these are values, not handles.

Construction

Vector4.new( number x, number y, number z, number w ) : Vector4
Constructs a vector. Missing — or non-numeric — arguments default to 0 (no error), so
Vector4.new() is the zero vector and Vector4.new(1) is (1, 0, 0, 0).

Vector4.zero( ) : Vector4
Returns (0, 0, 0, 0).

Functions

Static operations. Each takes native Vector4 values (see Types); all operate over all four
components.

Vector4.Dot( Vector4 a, Vector4 b ) : number
Dot product (4-component).

Vector4.Distance( Vector4 a, Vector4 b ) : number
Euclidean distance between two 4-component points.

Vector4.Normalize( Vector4 v ) : Vector4
Returns v scaled to unit length (4-component magnitude).

Vector4.Lerp( Vector4 a, Vector4 b, number t ) : Vector4
Linear interpolation from a to b by t. t is a required number (raises if missing); it is
not clamped to [0, 1].

Vector4.Min( Vector4 a, Vector4 b ) : Vector4
Component-wise minimum.

Vector4.Max( Vector4 a, Vector4 b ) : Vector4
Component-wise maximum.

Vector4.Abs( Vector4 v ) : Vector4
Component-wise absolute value.

Vector4.ComponentMul( Vector4 a, Vector4 b ) : Vector4
Element-wise product (a.x*b.x, a.y*b.y, a.z*b.z, a.w*b.w).

Vector4.ComponentDiv( Vector4 a, Vector4 b ) : Vector4
Element-wise quotient.

Vector4 exposes only this basic surface — none of Vector3’s geometric helpers
(Cross, Angle, Project, Reflect, MoveTowards, ClampMagnitude, SqrDistance) exist for
it.

Methods

v:magnitude( ) : number
The vector’s length (over all four components).

v:sqrMagnitude( ) : number
The squared length (cheaper than magnitude).

Example

-- Pack an RGBA color as a Vector4 and read a channel back.
local c = Vector4.new(0.2, 0.6, 1.0, 1.0)
local dim = c * 0.5           -- native scalar multiply
print(dim.x, dim.y, dim.z, dim.w)

Quaternion

A rotation stored as a 4-component quaternion. Like the vector types, Quaternion is a native
Lua value (stored inline in the Lua fork’s vector TValue — no garbage collection), so passing
and returning them is cheap.

Static constructors and math functions are called on the type table (Quaternion.AngleAxis(...),
Quaternion.Slerp(...)); the * operator composes and applies rotations. There are no colon
instance methods.

Types

Quaternion — a native quaternion value with components x, y, z, w (f32). Read them as
fields: q.x, q.y, q.z, q.w. tostring(q) yields Quat{x,y,z,w}. Every function reads its
arguments with check_vector (or luaL_checknumber), so a wrong type raises a Lua type error;
there is no null/stale concept — these are values, not handles.

Quaternions support the * operator (the __mul metamethod), dispatched on the right-hand
operand:

• a * b (both Quaternion) — the Hamilton product, composing the two rotations (the
  right-hand operand is applied first: a * b applies b, then a).
• q * v (where v is a Vector3) — rotates the vector v by q, returning a Vector3.
  v must be a native Vector3.

The quaternion must be the left operand. q * x where x is neither a Quaternion nor a
Vector3 raises a type error, and v * q (vector on the left) does not rotate — it falls to
the native vector arithmetic path, not this metamethod.

Unless noted, functions do not re-normalize their inputs; Slerp normalizes its result to
compensate for SIMD rsqrt error.

Construction

Quaternion.new( number x, number y, number z, number w ) : Quaternion
Constructs from raw components — all four are required (luaL_checknumber; a missing argument
raises). No normalization is applied.

Quaternion.identity( ) : Quaternion
The identity rotation (0, 0, 0, 1).

Quaternion.RadiansAxis( number radians, Vector3 axis ) : Quaternion
Rotation of radians (radians) about axis. axis accepts a Vector3 or three loose
numbers.

Quaternion.AngleAxis( number degrees, Vector3 axis ) : Quaternion
Rotation of degrees (degrees — converted internally) about axis. axis accepts a Vector3
or three loose numbers.

Known issue: AngleAxis / RadiansAxis assume a unit-length axis and do not
normalize it (Quat::from_angle_axis, core/math/src/simd/quat.rs:42). A non-unit axis yields a
non-unit quaternion (a scaled/incorrect rotation) — this diverges from Unity’s AngleAxis, which
normalizes. Normalize the axis yourself, or use Vector3.Normalize first.

Quaternion.Euler( Vector3 degrees ) : Quaternion
Rotation from Euler angles in degrees, applied in YXZ order. Accepts a Vector3 or three
loose numbers. This is the same function as EulerYXZ (an alias), and matches the default
order used by GameObject’s EulerAngles.

Quaternion.EulerXYZ( Vector3 degrees ) : Quaternion
Euler angles in degrees, XYZ order. Accepts a Vector3 or three loose numbers.

Quaternion.EulerXZY( Vector3 degrees ) : Quaternion
Euler angles in degrees, XZY order.

Quaternion.EulerYXZ( Vector3 degrees ) : Quaternion
Euler angles in degrees, YXZ order (identical to Euler).

Quaternion.EulerYZX( Vector3 degrees ) : Quaternion
Euler angles in degrees, YZX order.

Quaternion.EulerZXY( Vector3 degrees ) : Quaternion
Euler angles in degrees, ZXY order.

Quaternion.EulerZYX( Vector3 degrees ) : Quaternion
Euler angles in degrees, ZYX order.

Functions

Static operations. Note the mixed angle units: constructors and Angle use degrees, while
RadiansAxis and Radians use radians.

Quaternion.Normalize( Quaternion q ) : Quaternion
Returns q scaled to unit length (falls back to identity for a zero-length quaternion).

Quaternion.Inverse( Quaternion q ) : Quaternion
Returns the conjugate (negates x, y, z, keeps w).

Known issue: Inverse is the conjugate, which equals the true inverse only for unit
quaternions (Quat::inverse, core/math/src/simd/quat.rs:300). Because new and AngleAxis
don’t normalize, Inverse (and Delta, which is built on it) is wrong for a non-unit
quaternion. Normalize first if you’re unsure the quaternion is unit-length.

Quaternion.Reverse( Quaternion q ) : Quaternion
Negates all four components — the antipodal representation of the same rotation.

Quaternion.Lerp( Quaternion a, Quaternion b, number t ) : Quaternion
Component-wise linear interpolation from a to b by t. The result is not re-normalized.

Quaternion.Slerp( Quaternion a, Quaternion b, number t ) : Quaternion
Spherical linear interpolation from a to b by t. The result is normalized.

Quaternion.Angle( Quaternion a, Quaternion b ) : number
Angle between the two rotations, in degrees. Computed as 2·acos(|dot|) with the dot clamped
to 1, so it is robust to non-unit inputs.

Quaternion.Radians( Quaternion a, Quaternion b ) : number
Same angle, in radians.

Quaternion.Dot( Quaternion a, Quaternion b ) : number
Four-component dot product.

Quaternion.Delta( Quaternion a, Quaternion b ) : Quaternion
The rotation from a to b, computed as inverse(a) * b. It is a right delta:
a * Delta(a, b) == b.

Known issue: Delta uses the plain inverse(a) * b and does not take the shortest path
(Quat::delta, core/math/src/simd/quat.rs:355). When a and b are more than 180° apart in
their stored representation (negative dot), the result winds the long way around — the
shortest_delta variant that flips the sign is not the one bound to Lua. It also inherits
the unit-only limitation of Inverse above.

Example

-- Build a yaw rotation and spin a direction vector by it.
local yaw = Quaternion.AngleAxis(90, 0, 1, 0)   -- 90° about +Y (degrees; axis already unit)
local fwd = yaw * Vector3.new(0, 0, -1)          -- Quat * Vector3 rotates the vector

-- Compose two rotations, then blend halfway toward identity.
local r    = yaw * Quaternion.EulerXYZ(0, 0, 45)  -- Quat * Quat = Hamilton product
local half = Quaternion.Slerp(Quaternion.identity(), r, 0.5)

Camera

A camera component attached to a GameObject: it defines the projection (FOV, clip planes, aspect),
what it clears, which layers it draws, its render order and viewport rect, and the point/ray
transforms between world, viewport, and screen space.

Static calls use the type table (Camera.Add(go)); instance methods use colon syntax on a handle
(camera:SetVerticalFOV(...)).

Camera.Add always creates a perspective camera (Camera::default), and there is no Lua
binding to switch a camera to orthographic — so in practice every Lua-facing camera is perspective.
The FOV / aspect accessors below note their orthographic behavior for completeness only.

Types

Camera — an opaque handle (userdata) to a camera component. A handle may be null or stale
(its component destroyed); it is safe to keep and pass around.

• Queries (getters and the projection transforms) on a null/stale handle log a warning
  (NotFound) and return nil — they never raise.
• Setters and actions on a null/stale handle silently no-op — no warning, unlike the
  getters. (This asymmetry differs from GameObject, whose setters warn.)
• Argument type checks still raise. The receiver must be a Camera userdata, and every vector
  argument must be a native Vector3/Vector4 (built with Vector3.new(...)): passing loose
  numbers raises a Lua type error. Unlike the GameObject transform setters, these calls do not
  accept three numbers in place of a vector.

tostring(camera) always yields the literal Camera — it does not include the object name or a
NULL marker (unlike GameObject/Shader).

Creation & Destruction

Camera.Add( GameObject gameObject ) : Camera
Adds a default (perspective, 60° FOV) Camera component to gameObject and returns its handle.
Returns nil and logs InvalidArgument if the component cannot be added.

Camera.Get( GameObject gameObject ) : Camera
Returns the Camera component on gameObject, or nil (logs NotFound) if it has none.

Camera.Exists( Camera camera ) : boolean
Returns true if the handle refers to a live Camera component. Safe on null/stale/foreign handles
(returns false) — the one call here that never warns or raises.

There is no Lua Destroy for a Camera; remove it by destroying its GameObject.

Functions

Read-only queries and projection transforms. Vector arguments must be native Vector3/Vector4
values; each call logs NotFound and returns nil on a null/stale handle.

camera:WorldToViewportPoint( Vector3 worldPoint ) : Vector3
Projects a world-space point into viewport space (x, y normalized in [0,1]; z carries view-space
depth).

camera:ViewportToWorldPoint( Vector3 viewportPoint ) : Vector3
Unprojects a viewport-space point (x, y in [0,1], z = distance from the camera) back to world space.

camera:WorldToScreenPoint( Vector3 worldPoint ) : Vector3
Projects a world-space point to pixel screen coordinates, using the current screen size (render
pixel dimensions). z carries depth.

camera:ScreenToWorldPoint( Vector3 screenPoint ) : Vector3
Unprojects a pixel screen point (z = distance from the camera) back to world space, using the
current screen size.

camera:ScreenPointToRay( Vector3 screenPoint ) : table { origin: Vector3, direction: Vector3 }
Builds a world-space ray through the given pixel screen point, using the current screen size. The
result is a table with origin and direction fields (both Vector3).

camera:ViewportPointToRay( Vector3 viewportPoint ) : table { origin: Vector3, direction: Vector3 }
Builds a world-space ray through the given viewport point (x, y in [0,1]). Unlike
ScreenPointToRay, this needs no screen size — viewport coordinates are already normalized.

camera:Active( ) : boolean or nil
The component’s own enabled flag — what Activate()/Deactivate() write. This is intent,
not effect: a camera whose own flag is enabled but whose GameObject is deactivated still reports
true. The nil on a stale handle keeps “destroyed” distinguishable from “disabled”.

camera:ActiveInHierarchy( ) : boolean or nil
true only when the own flag is enabled and the owning GameObject is active in hierarchy —
i.e. the component is actually running. This is the predicate the engine uses to gate update
dispatch.

Properties (get / set)

Getters warn (NotFound) and return nil on a null/stale handle; setters silently no-op on a
null/stale handle. Clip-plane setters (SetNearClip/SetFarClip) rebuild the projection matrix
immediately; SetVerticalFOV/SetAspect defer the rebuild to the next cull pass (see notes).

Aspect

camera:Aspect( ) : number — viewport aspect ratio (width / height). Returns 0.0 for an
orthographic camera.
camera:SetAspect( number aspect ) : void — no-op on an orthographic camera. See the known
issue below.

Known issue: on a perspective camera SetAspect does not stick. Every frame on_pre_cull
recomputes aspect = (viewportRect.width · screenWidth) / (viewportRect.height · screenHeight)
and rebuilds the projection (engine/scenegraph/src/camera.rs:507-518), overwriting whatever you
set. Aspect() therefore reports the auto-derived ratio, not your argument. To change the framed
aspect, change the window size or SetViewportRect, not SetAspect.

VerticalFOV

camera:VerticalFOV( ) : number — vertical field of view in degrees (the stored value; the
projection converts it to radians internally via (fov/2).to_radians()). Returns 0.0 for an
orthographic camera.
camera:SetVerticalFOV( number degrees ) : void — sets the vertical FOV, in degrees. No-op
on an orthographic camera. The setter mutates the stored FOV but does not rebuild the projection on
the spot (unlike SetNearClip/SetFarClip); the change is picked up by the per-frame rebuild in
on_pre_cull, so it takes visible effect on the next frame.

NearClip

camera:NearClip( ) : number — near clip-plane distance.
camera:SetNearClip( number near ) : void — rebuilds the projection immediately.

FarClip

camera:FarClip( ) : number — far clip-plane distance.
camera:SetFarClip( number far ) : void — rebuilds the projection immediately.

LayerMask

camera:LayerMask( ) : integer — bitmask of render layers this camera draws.
camera:SetLayerMask( integer mask ) : void

RenderOrder

camera:RenderOrder( ) : integer — draw order among cameras (lower renders first).
camera:SetRenderOrder( integer order ) : void

ClearColor

camera:ClearColor( ) : Vector4 — clear color as sRGB RGBA (converted back from the linear
value stored internally).
camera:SetClearColor( Vector4 srgba ) : void — accepts an sRGB RGBA Vector4 (stored as
linear). Requires a native Vector4.

ClearDepth

camera:ClearDepth( ) : number — depth clear value.
camera:SetClearDepth( number depth ) : void

ClearMode

camera:ClearMode( ) : string — one of "DontClear", "ClearColorOnly", "ClearDepthOnly",
"ClearColorAndDepth".
camera:SetClearMode( string mode ) : void — takes the same four names the getter returns, so
a:SetClearMode(b:ClearMode()) round-trips. Matched exactly — no case folding, and numbers are
rejected. An unrecognized value raises a Lua error listing the four spellings; it no longer falls
back to color + depth, which was both the most expensive mode and the one that hid the mistake
behind plausible-looking output. There is no constants table for these — pass the string literally.

CullTolerance

camera:CullTolerance( ) : number — frustum-cull tolerance expansion.
camera:SetCullTolerance( number tolerance ) : void

SkipCulling

camera:SkipCulling( ) : boolean — whether frustum culling is bypassed for this camera.
camera:SetSkipCulling( boolean skip ) : void

ViewportRect

camera:ViewportRect( ) : Vector4 — viewport rect (x, y, width, height) in [0,1] normalized
coords.
camera:SetViewportRect( Vector4 rect ) : void — (x, y, width, height) in [0,1]. Values are
clamped to a valid range (x,y ≥ 0; width/height in [0.001, 1 − offset]). Requires a native
Vector4.

Methods

Actions that mutate the camera. All silently no-op on a null/stale handle.

camera:SetRenderTarget( integer gpuHandle ) : void
Directs this camera’s color output to an off-screen target. gpuHandle is a packed 4-byte
GpuHandle<GpuRenderTarget> passed as an integer — obtain it from a
RenderTexture via rt:GpuColorHandle(). The integer is reinterpreted directly
(transmute) with no validation, so an integer from any other source yields an undefined target
rather than an error.

camera:SetDepthRenderTarget( integer gpuHandle ) : void
As above for the depth target; obtain the integer from rt:GpuDepthHandle().

camera:SetReplacementShader( Shader shader ) : void
Overrides every draw for this camera with shader (e.g. a depth-only or debug pass). Pass nil to
clear the override. If a live Shader handle is given, its pipeline is resolved and
installed; if the handle cannot be resolved, logs InvalidArgument and clears the override. A
non-nil argument that is not a Shader userdata raises a type error.

camera:Activate( ) : void
Sets the component’s own enabled flag. Its enable callback runs only if the owning GameObject is
also active.

camera:Deactivate( ) : void
Clears the own enabled flag; the disable callback runs only if the component was actually active.

Example

-- Attach a perspective camera, frame the scene, and pick under the mouse.
-- (Adapted from data/scripts/session_setup.lua + editor_pick.lua.)
function Script.OnEnable(self)
    local cam = Camera.Add(self.object)
    cam:SetVerticalFOV(60)          -- degrees
    cam:SetNearClip(0.1)
    cam:SetFarClip(1000)
    cam:SetClearColor(Vector4.new(0.02, 0.02, 0.04, 1))  -- sRGB RGBA
    self.cam = cam
end

function Script.Update(self)
    if not Input.LeftMouseDown() then return end
    local mx, my = Input.MousePosition()
    -- There is no Camera:Pick — build a ray and raycast the physics world.
    local ray = self.cam:ScreenPointToRay(Vector3.new(mx, my, 0))
    local hit = Physics.Raycast(ray.origin, ray.direction, self.pickMask)
    if hit then self.hovered = hit.gameObject end
end

Light

A light component attached to a GameObject: type (directional / point / spot), color and
intensity, spot cone shape, shadow parameters, an optional projected cookie, and a layer mask.
Range is not settable — it is auto-computed from intensity and the attenuation cutoff (the TR7
lighting model, sqrt(intensity / cutoff − 0.1)).

Static calls use the type table (Light.Point(go, ...)); instance methods use colon syntax on a
handle (light:SetIntensity(...)).

Color spaces are not uniform across this API — read carefully. Color / SetColor and the
r, g, b arguments to the constructors take sRGB (converted to linear on the way in). ColorLinear
/ SetColorLinear take linear RGB with no conversion. (Scene-wide ambient on Lighting
is linear too.)

Types

Light — an opaque handle (userdata) to a light component. A handle may be null or stale
(its component destroyed); it is safe to keep and pass around. Calling a getter on a null/stale
handle logs a warning and returns nil; calling a setter silently no-ops (see the note under
Properties). tostring(light) always yields the literal Light (it does not encode the handle’s
name or liveness).

Creation & Destruction

There is no light:Destroy() — a light is removed by destroying (or removing the component from)
its owning GameObject. Every constructor adds a component to gameObject and returns the handle,
or returns nil and logs an error if the component cannot be added (a null/stale gameObject, or
the light component pool — default capacity 256 — is exhausted).

Light.Add( GameObject gameObject ) : Light
Adds a default light to gameObject. The default is a point light: white, intensity 1.0, spot
angle 45° / falloff 0.8 (unused), cutoff 0 (→ global default), no shadows, cookie −1 (none), layer
mask 0xFFFFFFFF.

Light.Point( GameObject gameObject, number r, number g, number b, number intensity ) : Light
Adds a point light with the given sRGB color and intensity.

Light.Spot( GameObject gameObject, number r, number g, number b, number intensity, number spotAngle, number spotFalloff ) : Light
Adds a spot light. spotAngle is the full cone angle in degrees; spotFalloff is the
umbra→penumbra ratio in [0,1] (0 = hard edge, 1 = the whole cone is penumbra).

Light.Directional( GameObject gameObject, number r, number g, number b, number intensity ) : Light
Adds a directional light with the given sRGB color and intensity. The direction is the owning
GameObject’s forward axis (orient it with gameObject:LookAt(...)).

Light.Get( GameObject gameObject ) : Light
Returns the Light component on gameObject, or nil (with a warning) if it has none.

Light.Exists( Light light ) : boolean
Returns true if the handle refers to a live Light component. Safe on null/stale handles (returns
false) and on non-Light values — this call never warns or raises.

Functions

Class-level attenuation default

Static calls on the Light table (a process-global, not per-light). A per-light cutoff of 0
resolves to this value.

Light.DefaultAttenuationCutoff( ) : number
The global default attenuation cutoff (initial value 0.01).

Light.SetDefaultAttenuationCutoff( number cutoff ) : void
Sets the global default attenuation cutoff.

Known issue: changing the global default after lights are already live does not re-sync
their spatial-octree extents or light-grid coverage — only their per-light SSBO range is refreshed
through the normal dirty path. Set it once at startup, before enabling lights; otherwise toggle a
light’s intensity or per-light cutoff to force a full re-sync. (engine/scenegraph/src/light.rs:380-386,
the set_attenuation_cutoff doc comment.)

Properties (get / set)

Getters return nil and log a warning on a null/stale handle. Setters no-op silently on a
null/stale handle — no warning is logged (unlike the GameObject setters, which warn). Guard with
Light.Exists(light) if a silent no-op would hide a bug.

Type

light:Type( ) : string — "Directional", "Point", or "Spot" (see
Enum names).
light:SetType( string type ) : void — takes the same three names the getter returns, so
a:SetType(b:Type()) round-trips. An unrecognized name raises. See the known issue below about
switching type on a live light.

Known issue: SetType on an already-enabled light does not re-bind its GPU slot (point/spot
use an SSBO slot, directional uses a UBO slot), so switching to or from directional at runtime
leaves the light on the wrong GPU path. Disable and re-enable the owning GameObject to switch
types reliably. (engine/scenegraph/src/light.rs:336-345, the set_type doc comment.)

Color

light:Color( ) : Vector3 — light color as sRGB RGB (converted back from the linear store).
light:SetColor( Vector3 srgb ) : void — accepts sRGB RGB (converted to linear internally).

ColorLinear

light:ColorLinear( ) : Vector3 — light color as linear RGB (the raw stored value, no conversion).
light:SetColorLinear( Vector3 linear ) : void — sets linear RGB directly (no conversion).

Intensity

light:Intensity( ) : number — HDR intensity multiplier on the color.
light:SetIntensity( number intensity ) : void — also drives Range (re-syncs grid/octree coverage).

Range

light:Range( ) : number — effective attenuation range in world units. Read-only (no
setter): auto-computed as sqrt(intensity / effective_cutoff − 0.1), clamped to 0 for
non-positive/non-finite inputs.

SpotAngle

light:SpotAngle( ) : number — full spot cone angle in degrees (spot only; default 45).
light:SetSpotAngle( number degrees ) : void — no radians conversion; the value is stored and
returned as-is.

SpotFalloff

light:SpotFalloff( ) : number — umbra→penumbra falloff ratio in [0,1] (default 0.8).
light:SetSpotFalloff( number ratio ) : void

AttenuationCutoff

light:AttenuationCutoff( ) : number — per-light attenuation cutoff (default 0 = use the global default).
light:SetAttenuationCutoff( number cutoff ) : void — 0 = use the global default; also drives Range.

Shadows

light:Shadows( ) : boolean — whether the light casts shadows (default false).
light:SetShadows( boolean cast ) : void

ShadowBias

light:ShadowBias( ) : number — depth bias for this light’s shadow map (default 0.005).
light:SetShadowBias( number bias ) : void

ShadowResolution

light:ShadowResolution( ) : integer — shadow-map resolution (default 0 = use engine default 2048).
light:SetShadowResolution( integer resolution ) : void — 0 = use default.

ShadowExtent

light:ShadowExtent( ) : number — orthographic shadow half-extent in world units, for
directional shadows (default 0 = use engine default 50).
light:SetShadowExtent( number extent ) : void — 0 = use default.

ShadowNearClip

light:ShadowNearClip( ) : number — near clip for the shadow projection (default 0.1).
light:SetShadowNearClip( number near ) : void

ShadowFarClip

light:ShadowFarClip( ) : number — far clip for the shadow projection (default 0 = use the
auto-computed Range).
light:SetShadowFarClip( number far ) : void — 0 = use the computed range.

CookieIndex

light:CookieIndex( ) : number — projected-cookie texture index (default −1). Stored as a
float, not an integer.
light:SetCookieIndex( number index ) : void — any negative value disables the cookie.

LayerMask

light:LayerMask( ) : integer — bitmask of layers this light affects (default 0xFFFFFFFF).
light:SetLayerMask( integer mask ) : void

Lifecycle

light:Active( ) : boolean or nil — the component’s own enabled flag, what Activate()/
Deactivate() write. nil plus a logged NotFound warning on a stale handle. This is intent, not
effect: a light whose own flag is enabled but whose GameObject is deactivated still reports true
here, and does not contribute to the scene.

light:ActiveInHierarchy( ) : boolean or nil — true only when the own flag is enabled and
the owning GameObject is active in hierarchy, i.e. the light is actually live. This is the predicate
the engine uses to gate update dispatch. nil on a stale handle.

light:Activate( ) : void — sets the own enabled flag. The enable callback runs only if the
owning GameObject is also active. Silently no-ops on a stale handle.

light:Deactivate( ) : void — clears the own enabled flag; the disable callback runs only if the
component was actually active. Silently no-ops on a stale handle.

Enum names

The light type is a string, matched exactly — one spelling each, no case folding
("point" is rejected; only "Point" is accepted). These are both the values Type() returns and
the values SetType() accepts (verified against LightType, light_types.rs:63-75):

"Directional"
"Point"
"Spot"

The Light.DIRECTIONAL / .POINT / .SPOT integer constants were deleted (2026-07), along
with the integer SetType path. They are absent from the Light table now, so Light.POINT
evaluates to nil and passing it raises. They were not reinstated as string constants: a
mistyped table field (Light.SPOTT) is nil and indistinguishable from an omitted argument,
while a present-but-wrong string can always be rejected by name.

Example

-- Warm directional "sun" plus colored point lights.
-- (Adapted from data/scripts/main_scene_setup.lua.)
function Script.OnEnable(self)
    -- Directional light: aim it by orienting its GameObject's forward axis.
    local sun_go = GameObject.Create()
    sun_go:SetID("Sun")
    sun_go:LookAt(Vector3.new(1, -2, -1))
    local sun = Light.Directional(sun_go, 1.0, 0.95, 0.85, 1.5)  -- sRGB color
    if sun then
        sun:SetShadows(true)
        sun:SetShadowExtent(60)  -- widen the orthographic shadow volume
    end

    -- A colored point light. Range is auto-computed from intensity + cutoff.
    local lamp = GameObject.Create()
    lamp:SetWorldPosition(4, 2, 0)
    local pt = Light.Point(lamp, 1.0, 0.3, 0.1, 8.0)
    pt:SetAttenuationCutoff(0)   -- 0 = use the global default (0.01)
end

Lighting

A module singleton (global functions only, no handles) for scene-wide lighting settings on the
engine’s LightManager: hemisphere ambient, fog, and global shadow parameters. These are not
per-light properties — those live on the Light component.

All functions act on the app’s global LightManager (always present when the engine is running);
there is no per-call null handling. Getters return the current stored value; setters return
void.

Ambient colors are linear RGB (passed through verbatim, no sRGB conversion) — unlike the
Light component’s Color/SetColor, which are sRGB.

Functions

Ambient

Lighting.AmbientSky( ) : Vector3
Sky (upper-hemisphere) ambient color, linear RGB.

Lighting.AmbientGround( ) : Vector3
Ground (lower-hemisphere) ambient color, linear RGB.

Lighting.AmbientIntensity( ) : number
Ambient intensity multiplier (default 1.0).

Lighting.SetAmbient( Vector3 skyColor, Vector3 groundColor, number intensity ) : void
Sets sky/ground ambient colors (linear RGB) and the intensity multiplier in one call. Colors are
Vector3; there is no separate per-channel or per-field setter.

Fog

Fog mode is stored internally as a float, but is only ever meaningful at the four values below;
FogMode() returns it as an integer and the FOG_* constants are integers.

Lighting.FogDensity( ) : number
Fog density (used by the exponential modes).

Lighting.FogStart( ) : number
Linear-fog start distance.

Lighting.FogEnd( ) : number
Linear-fog end distance.

Lighting.FogMode( ) : integer
Active fog mode: 0 = none, 1 = linear, 2 = exp, 3 = exp2 (see Constants).

Lighting.SetFog( number density, number start, number end, number mode ) : void
Sets all four fog fields directly. mode is a number — pass a Lighting.FOG_* constant; a
fractional value is stored verbatim and read back truncated by FogMode().

Lighting.SetFogLinear( number start, number end ) : void
Convenience for linear fog: sets start/end and mode = 1, and forces density = 0.

Lighting.SetFogExp( number density ) : void
Convenience for exponential fog: sets density and mode = 2, and forces start = end = 0.

Lighting.SetFogExp2( number density ) : void
Convenience for exp² fog: sets density and mode = 3, and forces start = end = 0.

Lighting.DisableFog( ) : void
Resets fog to defaults — mode = 0 (none) and density = start = end = 0.

Shadow parameters

Global shadow parameters shared by every shadow-casting light (per-light bias/resolution live on
the Light component).

Lighting.ShadowBias( ) : number
Global shadow depth bias (default 0.005).

Lighting.ShadowNormalBias( ) : number
Global shadow normal bias (default 0.02).

Lighting.ShadowSoftness( ) : number
Global shadow softness / PCF filter radius (default 1.0).

Lighting.ShadowStrength( ) : number
Global shadow strength (opacity of shadows), nominally [0,1] (default 1.0). Not clamped by the
binding.

Lighting.SetShadowParams( number bias, number normalBias, number softness, number strength ) : void
Sets all four global shadow parameters in one call. There is no individual setter for any of them.

Lighting.ShadowType( ) : string
Active shadow-map filtering technique, by name (see Constants).

Lighting.SetShadowType( string type ) : void
Sets the shadow-map filtering technique by name. Takes the same spellings the getter returns, so
Lighting.SetShadowType(Lighting.ShadowType()) round-trips. An unrecognized name raises a Lua error
listing the four valid spellings — it no longer falls back to Normal, which mattered because each
technique also selects a different shadow render-target format.

Constants

Fog modes (plain integers on the Lighting table) — these stay integers: FogParams.mode is an
f32 shipped straight to the GPU, not a Rust enum, so there is nothing to resolve by name:

Lighting.FOG_NONE = 0
Lighting.FOG_LINEAR = 1
Lighting.FOG_EXP = 2
Lighting.FOG_EXP2 = 3

Shadow techniques (from the ShadowType enum, light_types.rs:18-36) are names, not constants
— strings matched exactly, one spelling each, with no case folding ("vsm" is rejected; only
"VSM" is accepted). Each selects a different render-target format / shader set:

"Normal" — standard depth comparison (D32).
"VSM" — variance shadow maps (RG32F).
"ESM" — exponential shadow maps (R32F).
"CSM" — convolution/Fourier shadow maps (RGBA16F ×2).

The Lighting.SHADOW_NORMAL / _VSM / _ESM / _CSM integer constants were deleted
(2026-07) along with the integer SetShadowType path. They are absent from the Lighting
table now, so Lighting.SHADOW_VSM evaluates to nil and passing it raises. FOG_* above is
unaffected — it was never an enum crossing.

Example

-- Warm dusk ambient with linear distance fog and soft variance shadows.
function Script.OnEnable(self)
    -- Ambient colors are LINEAR RGB (no sRGB conversion).
    Lighting.SetAmbient(
        Vector3.new(0.30, 0.34, 0.45),  -- sky
        Vector3.new(0.12, 0.10, 0.08),  -- ground
        1.0)                            -- intensity
    Lighting.SetFogLinear(40, 220)      -- mode = linear, density forced to 0
    Lighting.SetShadowType("VSM")
    Lighting.SetShadowParams(0.005, 0.02, 1.5, 0.9)  -- bias, normalBias, softness, strength
end

Material

A material resource: a shader plus its bound textures, up to 16 color/vector slots, per-slot UV
scale/offset, and a render queue. Materials are named manager resources (not scene components) —
created by name, looked up by name, cloned, and destroyed. Colors are stored linear internally;
the Color/MainColor accessors convert to and from sRGB at the boundary, while
SetColorLinear bypasses conversion.

Static calls use the type table (Material.Create("name")); instance methods use colon syntax on a
handle (material:SetShader(...)).

Types

Material — an opaque handle (userdata) to a material resource. A handle may be null or
stale (its resource destroyed); it is safe to keep and pass around, and a method never raises on
one. Null/stale behavior is not uniform: ID() logs a warning and returns nil, but the color,
UV, and render-queue getters return a silent default (see the known issue below), and every setter
silently no-ops. Passing a non-Material value where a method expects self raises a Lua type
error. tostring(material) yields Material{name}, or Material{NULL} if the handle is dead.

Known issue — dead-handle reads fail silently. Only ID() reports a null/stale handle (logs
NotFound, returns nil). The other getters return a manager default with no warning:
MainColor()/Color() return transparent black (0,0,0,0), UVScaleOffset() returns
(1,1,0,0), and RenderQueue() returns 65535 (RENDER_QUEUE_USE_DEFAULT). Out-of-range color
indices and UV slots behave the same way, and every setter no-ops without warning
(material_manager.rs:375, :392, :518, :547). Use Material.Exists(mat) to test liveness —
do not infer it from a getter’s result.

Creation & Destruction

Material.Create( string name ) : Material
Creates a new named material resource. Returns nil and logs InvalidArgument on failure — a
duplicate name (AlreadyExists) or pool exhaustion (OutOfMemory) both surface as the same log.

Material.Get( string name ) : Material
Looks up an existing material by name. Returns nil and logs NotFound if none matches.

Material.Exists( Material material ) : boolean
Returns true if the handle refers to a live material. Safe on null, stale, or foreign (non-material
userdata / nil) arguments — returns false without raising or warning. This is the reliable
liveness check.

Material.Clone( Material material ) : Material
Duplicates material into a new anonymous resource (not registered by name; gets its own GPU
slot) and returns it. Returns nil and logs NotFound if the source is null/stale. Note this is a
static call — Material.Clone(mat), not mat:Clone().

material:Destroy( ) : boolean
Marks the material for deferred destruction. Returns true if the handle was valid and got marked,
false if it was already null/invalid. (Unlike most instance methods, this one returns a value.)

Functions

Read-only queries. See the known issue above — only ID() reports a dead handle; the rest return
silent defaults.

material:ID( ) : string
The material’s unique name. Returns nil and logs NotFound on a null/stale handle, or on an
anonymous clone (which has no registered name).

Properties (get / set)

Setters return void and silently no-op on a null/stale handle or out-of-range index (no
warning). Color indices and UV/texture slots are 0-based: color indices 0..15
(MAX_MATERIAL_COLORS = 16), UV slots 0..7 (MAX_MATERIAL_TEXTURES = 8).

RenderQueue

material:RenderQueue( ) : integer — the material’s render-queue override, or 65535
(use-shader-default) if unset or the handle is dead.
material:SetRenderQueue( integer queue ) : void — stores the raw 16-bit override (recomputes
the effective 8-bit sort key internally).

MainColor

material:MainColor( ) : Vector4 — color slot 0 as sRGB RGBA.
material:SetMainColor( Vector4 srgba ) : void — accepts sRGB RGBA (stored linear).
Alias for Color(0) / SetColor(0, …) — the same slot-0 color (material_manager.rs:365, :370).

Color

material:Color( integer index ) : Vector4 — the color at 0-based index (0..15) as sRGB
RGBA. Out-of-range or dead handle → (0,0,0,0).
material:SetColor( integer index, Vector4 srgba ) : void — sets 0-based index from sRGB
RGBA (stored linear).

UVScaleOffset

material:UVScaleOffset( integer slot ) : Vector4 — (scaleU, scaleV, offsetU, offsetV) for
0-based texture slot (0..7). Out-of-range or dead handle → (1,1,0,0).
material:SetUVScale( integer slot, number scaleU, number scaleV ) : void — sets scale only,
preserving the existing offset.
material:SetUVOffset( integer slot, number offsetU, number offsetV ) : void — sets offset
only, preserving the existing scale.

Methods

Actions that mutate the material. All silently no-op on a null/stale handle (no warning).

material:SetShader( Shader shader ) : void
Sets the material’s shader, pulling the pipeline handle, texture count, and default render queue from
the ShaderManager. No-ops and logs NotFound if the shader handle does not resolve.

material:SetTexture( integer slot, Texture texture ) : void
Binds texture at the given 0-based texture slot (0..7), copying its GPU image/sampler and
dimensions. No-ops and logs NotFound if the texture handle does not resolve.

material:SetColorLinear( integer index, Vector4 linearRgba ) : void
Sets the color at 0-based index to a linear-space value, verbatim (no sRGB conversion). The
counterpart write path to SetColor; there is no linear getter exposed to Lua (read back through
Color, which re-applies sRGB).

Example

-- Clone a base material and tint it, then swap its albedo texture and tile the UVs.
function Script.OnEnable(self)
    local mat = Material.Clone(Material.Get("crate"))
    mat:SetMainColor(Vector4.new(0.9, 0.2, 0.2, 1.0))   -- sRGB red tint (== SetColor(0, ...))
    mat:SetTexture(0, Texture.Load("crate_red", "textures/crate_red.dds"))
    mat:SetUVScale(0, 2.0, 2.0)                          -- slot 0, 2x2 tiling
    self.material = mat
end

function Script.OnDisable(self)
    if Material.Exists(self.material) then
        self.material:Destroy()
    end
end

Mesh

A mesh resource: vertex/index/bone data and its spherical bounds. Meshes are named manager resources
(not scene components) — built from Lua vertex data, loaded from a binary .mesh file, or looked up
by name — and are bound to a MeshRenderer for drawing.

Static calls use the type table (Mesh.Load("name", "path")); instance methods use colon syntax on
a handle (mesh:VertexCount()).

Types

Mesh — an opaque handle (userdata) to a mesh resource. A handle may be null or stale (its
resource destroyed); it is safe to keep and pass around, and a method never raises on one. Every
getter returns nil and logs NotFound on a null/stale handle; the one setter (SetFileScale)
silently no-ops. Passing a non-Mesh value where a method expects self raises a Lua type error.
tostring(mesh) yields Mesh{name}, or Mesh{NULL} if the handle is dead. There is no instance
Destroy — meshes are released by the manager, not from Lua.

Creation & Destruction

Mesh.Create( string name, table vertices, table indices ) : Mesh
Creates and GPU-uploads a named mesh. vertices is a 1-based array of { posVec3, normalVec3, uvVec2 } sub-tables (position at sub-index 1, normal at 2, uv at 3; uv optional, defaults to
(0,0)). indices is a flat 1-based array of 0-based vertex indices. Returns nil and logs
InvalidArgument on failure. Lua-built vertices carry only position/normal/uv — no vertex color and
no skin weights — so Mesh.Create always produces a static (un-skinned) mesh.

Known issue — mesh indices truncate to 16-bit. Mesh.Create reads each index as
lua_tointeger(...) as u16 (lua_mesh.rs:101), so any index ≥ 65536 silently wraps with no error
or clamp. A Lua-built mesh therefore cannot reference more than 65536 vertices.

Mesh.Load( string name, string path ) : Mesh
Creates a named mesh and kicks off an asynchronous load from a binary .mesh file; the GPU
upload completes later in the frame loop (via the engine’s load poll). path is resolved relative
to the content directory. Returns nil and logs InvalidArgument if the name allocation or the
async-load kickoff fails (the coarse status does not distinguish a missing file from a name clash).

Mesh.Get( string name ) : Mesh
Looks up an existing mesh by name. Returns nil and logs NotFound if none matches.

Mesh.Exists( Mesh mesh ) : boolean
Returns true if the handle refers to a live mesh. Safe on null, stale, or foreign (non-mesh
userdata / nil) arguments — returns false without raising or warning.

Functions

Read-only queries. Each returns nil and logs NotFound on a null/stale handle.

mesh:ID( ) : string
The mesh’s unique name.

mesh:VertexCount( ) : integer
Number of vertices.

mesh:IndexCount( ) : integer
Number of indices.

mesh:BoneCount( ) : integer
Number of skeleton bones (0 for static meshes, including everything built by Mesh.Create).

mesh:Bounds( ) : Vector4
Bounding sphere packed as (centerX, centerY, centerZ, radius) — center in x, y, z, radius in
w.

Properties (get / set)

The setter returns void and silently no-ops on a null/stale handle (no warning).

FileScale

mesh:FileScale( ) : number — the import/file scale factor applied to the mesh. Returns nil
and logs NotFound on a dead handle.
mesh:SetFileScale( number scale ) : void — updates the scale; silently no-ops on a dead
handle.

Example

-- Load a mesh, adjust its import scale, and query its bounds.
function Script.OnEnable(self)
    local mesh = Mesh.Load("barrel", "meshes/barrel.mesh")
    mesh:SetFileScale(0.01)  -- centimeters -> meters
    self.mesh = mesh
end

function Script.Update(self)
    -- Load is async: guard on Exists + a populated vertex count before reading bounds.
    if Mesh.Exists(self.mesh) and self.mesh:VertexCount() > 0 then
        local b = self.mesh:Bounds()   -- (cx, cy, cz, radius)
        self.radius = b.w
    end
end

MeshRenderer

A component that draws a static (non-skinned) mesh with a material. Attach one to a
GameObject; it reads the object’s transform each frame, submits the mesh to the render queue, and
carries per-instance state (tint color, render scale, cull bounds). For animated/skinned meshes
use SkinnedMeshRenderer.

Static calls use the type table (MeshRenderer.Add(...)); instance methods use colon syntax on a
component handle (mr:SetMaterial(...)).

Types

MeshRenderer — an opaque handle (userdata) to a MeshRenderer component. A handle may be null
or stale (its component/GameObject destroyed); it is safe to keep and pass around, and a method
never raises on one. On an unresolvable handle, getters log NotFound and return nil (except
HasMaterialInstance, which returns false, and GetMaterialInstance, which returns nil
silently); setters silently no-op (no warning). Passing a non-MeshRenderer value where a
method expects self raises a Lua type error. tostring(mr) yields the constant string
MeshRenderer — it does not reflect a dead handle, so never use it to test liveness (use
MeshRenderer.Exists).

Creation & Destruction

MeshRenderer.Get( GameObject object ) : MeshRenderer
Returns the MeshRenderer component on object, or nil (logs NotFound) if the object has none.

MeshRenderer.Exists( MeshRenderer mr ) : boolean
Returns true if the handle refers to a live component. Safe on null, stale, or foreign
(non-MeshRenderer userdata / nil) arguments — returns false without raising or warning.

MeshRenderer.Add( GameObject object, Mesh mesh, Material material ) : MeshRenderer
Adds a new MeshRenderer to object bound to mesh and material (both resolve lazily at first
cull). Returns the new component handle, or nil if the component could not be added. Unlike
Get, the failure path is silent — it returns nil with no log (lua_mesh_renderer.rs:139).

MeshRenderer has no instance Destroy — its lifetime follows its GameObject (destroy the object,
or use Deactivate() to stop it drawing).

Functions

Read-only queries. Each logs NotFound and returns nil on a null/stale handle unless noted.

mr:EffectiveMaterial( ) : Material
The material actually used for drawing — the per-instance override if one exists, else the shared
material. Returns nil (no log) if the renderer resolves but has no material set.

mr:HasMaterialInstance( ) : boolean
true if a per-instance material clone has been created (via GetMaterialInstance). Returns
false — not nil — on a dead handle (though it still logs NotFound).

mr:Active( ) : boolean
The component’s own enabled flag — what Activate()/Deactivate() write. This is intent, not
effect: a renderer whose own flag is enabled but whose GameObject is deactivated still reports
true here — and is not drawing. Use ActiveInHierarchy() for the effective answer.

mr:ActiveInHierarchy( ) : boolean
true only when the own flag is enabled and the owning GameObject is active in hierarchy — i.e.
the component is actually running. This is the predicate the engine uses to gate update dispatch.

Removed 2026-07. mr:Enabled() / mr:SetEnabled(bool) are gone — they were exact duplicates
of this lifecycle pair, routing to the same activate/deactivate calls. SetEnabled(true) /
SetEnabled(false) become Activate() / Deactivate(). The honest replacement for the
Enabled() getter is ActiveInHierarchy(), not Active(): the old getter read a field
maintained by the enable/disable callbacks, which fire on effective-activity transitions.

Properties (get / set)

Setters return void and silently no-op on a null/stale handle (no warning). Getters follow the
NotFound-log-and-nil rule above.

Mesh

mr:Mesh( ) : Mesh — the bound mesh, or nil (no log) if the renderer has no mesh.
mr:SetMesh( Mesh mesh ) : void — binds a new mesh (marks the transform dirty so bounds
re-sync).

Material

mr:Material( ) : Material — the shared material handle, or nil (no log) if unset.
mr:SetMaterial( Material material ) : void — sets the shared material and destroys any
existing per-instance override (preventing a stale clone from outliving its source).

NeverCull

mr:NeverCull( ) : boolean — whether frustum culling is bypassed for this renderer.
mr:SetNeverCull( boolean value ) : void — when true, the mesh is always drawn regardless
of the camera frustum. Takes any truthy value (lua_toboolean).

RenderScale

mr:RenderScale( ) : Vector3 — the per-renderer visual scale (default (1,1,1)).
mr:SetRenderScale( Vector3 scale ) : void — sets a non-uniform render scale (marks the
transform dirty).
mr:SetRenderScaleUniform( number scale ) : void — sets all three axes to scale.

Methods

Mutating actions. Setters silently no-op on a null/stale handle (no warning).

mr:Activate( ) : void
Sets the component’s own enabled flag, driving it through the component lifecycle so on_enable
fires (re-retaining the cull entry) rather than flipping a bare flag. The enable callback runs only
if the owning GameObject is also active.

mr:Deactivate( ) : void
Clears the own enabled flag — the renderer stops drawing. The disable callback runs only if the
renderer was actually active.

mr:GetMaterialInstance( ) : Material
Returns a per-instance clone of the shared material, creating it on the first call and caching it
thereafter (subsequent calls return the same instance). Use this to set per-object colors without
affecting other renderers. Returns nil (silently — no log) if the renderer is dead or there is no
material to clone.

mr:SetColor( Vector4 color ) : void
Sets the renderer’s per-instance color tint, interpreting color as sRGB (converted to
linear). This is a push constant — free, and truly local to this renderer. It is the renderer’s only
color channel and never touches the material.

mr:SetColorLinear( Vector4 color ) : void
As SetColor, but stores color verbatim with no sRGB→linear conversion.

Setting material color slots. The renderer tint above is a single per-instance color. A
material’s color slots (1..15) live in the material’s constant buffer — shared GPU memory — so
the renderer no longer exposes an indexed color setter. Reach the slots through the material
explicitly, choosing shared vs. per-instance deliberately:

• mr:Material():SetColor(i, …) — mutates the shared material, recoloring every renderer that uses it.
• mr:GetMaterialInstance():SetColor(i, …) — clones the material first, so the change is local to this renderer.

mr:SetBounds( number cx, number cy, number cz, number radius ) : void
Overrides the local-space bounding sphere (center + radius) used for culling, and arms the
transform-update countdown so the cull list re-syncs.

Example

-- Give each spawned cube its own tinted material instance (NOT the shared material).
-- (Adapted from data/scripts/session_setup.lua + main_scene_setup.lua.)
local mr = MeshRenderer.Add(go, Mesh.Get("cube"), material)
if mr then
    -- The per-instance push-constant tint — always safe, never shared.
    mr:SetColor(Vector4.new(0.8, 0.2, 0.2, 1.0))  -- sRGB red

    -- To vary a *material* color slot per object, clone first so you don't
    -- recolor every cube sharing `material`.
    local inst = mr:GetMaterialInstance()
    inst:SetColorLinear(1, Vector4.new(0.05, 0.05, 0.05, 1.0))

    mr:SetBounds(0, 0, 0, 0.866)  -- unit-cube bounding sphere
end

SkinnedMeshRenderer

A component that draws a skinned mesh deformed by a bone skeleton. Attach one to a GameObject,
bind a mesh + material, then drive its skeleton each frame — either by playing an
AnimController or by posing individual bones directly. For static meshes use
MeshRenderer.

Static calls use the type table (SkinnedMeshRenderer.Add(...)); instance methods use colon
syntax on a component handle (smr:Sample(...)).

Types

SkinnedMeshRenderer — an opaque handle (userdata) to a SkinnedMeshRenderer component. A handle
may be null or stale (its component destroyed); it is safe to keep and pass around.
tostring(smr) yields the constant string SkinnedMeshRenderer (it does not embed a name).

Dead-handle behavior is not uniform, so it is stated per entry below. In general: most getters
log a NotFound warning and return nil; HasMaterialInstance logs and returns false;
GetMaterialInstance and ControllerInstance return nil silently (no warning); and all
setters / animation drivers no-op silently (no warning — unlike GameObject,
whose setters warn).

Bone indices are 0-based and index the skeleton array directly (skeleton()[index], no offset);
0 is the first bone and BoneCount() - 1 the last. An out-of-range index returns nil from a
getter and is ignored by SetBoneLocal.

Creation & Destruction

SkinnedMeshRenderer.Get( GameObject object ) : SkinnedMeshRenderer
Returns the SkinnedMeshRenderer on object, or nil (logs NotFound) if it has none. Raises if
object is not a GameObject userdata.

SkinnedMeshRenderer.Exists( SkinnedMeshRenderer smr ) : boolean
Returns true if the handle refers to a live component. Safe on null / stale / foreign handles
(returns false, never warns).

SkinnedMeshRenderer.Add( GameObject object, Mesh mesh, Material material ) : SkinnedMeshRenderer
Adds a new SkinnedMeshRenderer to object bound to mesh and material (mesh, bones, and
material all resolve lazily at first cull). Returns the new component handle, or nil
silently (no log) if the scene rejects the component. Raises if any argument is not the
expected userdata.

The component has no instance Destroy — its lifetime follows its GameObject.

Functions

Read-only queries. Each logs NotFound and returns nil on a null/stale handle unless noted.

smr:EffectiveMaterial( ) : Material
The material actually used for drawing — the per-instance override if one exists, otherwise the
shared material; nil if neither is set.

smr:HasMaterialInstance( ) : boolean
true if a per-instance material clone exists. On a dead handle it logs NotFound and returns
false (not nil), since its type is boolean.

smr:BoneCount( ) : integer
Number of bones in the skeleton. Valid bone indices are 0 .. BoneCount() - 1.

smr:BoneLocalPosition( integer index ) : Vector3
The bone’s position relative to its parent bone; nil (no warning) if index is out of range.

smr:BoneLocalRotation( integer index ) : Quaternion
The bone’s rotation relative to its parent bone; nil (no warning) if out of range.

smr:BoneWorldPosition( integer index ) : Vector3
The bone’s accumulated model-space position (skeleton root frame); nil (no warning) if out of
range.

smr:BoneWorldRotation( integer index ) : Quaternion
The bone’s accumulated model-space rotation; nil (no warning) if out of range.

smr:ControllerInstance( ) : AnimController
This renderer’s private AnimController instance created by PlayController,
for advanced per-instance control (states, weights, crossfade, SetTime). Returns nil
silently if PlayController was never called (or on a dead handle). The handle is
generational — it goes stale safely when the renderer is destroyed.

smr:Active( ) : boolean
The component’s own enabled flag — what Activate()/Deactivate() write. This is intent, not
effect: a renderer whose own flag is enabled but whose GameObject is deactivated still reports
true here — and is not drawing. Use ActiveInHierarchy() for the effective answer.

smr:ActiveInHierarchy( ) : boolean
true only when the own flag is enabled and the owning GameObject is active in hierarchy — i.e.
the component is actually running. This is the predicate the engine uses to gate update dispatch.

Removed 2026-07. smr:Enabled() / smr:SetEnabled(bool) are gone — they were exact
duplicates of this lifecycle pair, routing to the same activate/deactivate calls.
SetEnabled(true) / SetEnabled(false) become Activate() / Deactivate(). The honest
replacement for the Enabled() getter is ActiveInHierarchy(), not Active(): the old
getter read a field maintained by the enable/disable callbacks, which fire on
effective-activity transitions.

Properties (get / set)

Setters return void and no-op silently (no warning) on a null/stale handle.

Mesh

smr:Mesh( ) : Mesh — the bound skinned mesh, or nil if unset.
smr:SetMesh( Mesh mesh ) : void — binds a new mesh. Raises if mesh is not a Mesh userdata.

Material

smr:Material( ) : Material — the shared material, or nil if unset.
smr:SetMaterial( Material material ) : void — sets the shared material and destroys any
per-instance override; resolves lazily at the next cull.

RenderScale

smr:RenderScale( ) : Vector3 — the per-renderer visual scale (default (1, 1, 1)).
smr:SetRenderScale( Vector3 scale ) : void — sets a non-uniform render scale (accepts a
Vector3).
smr:SetRenderScaleUniform( number scale ) : void — sets all three axes to scale.

Methods

Mutating actions. All no-op silently (no warning) on a null/stale handle.

smr:Activate( ) : void
Sets the component’s own enabled flag, driving it through the component lifecycle (re-retaining the
cull entry and re-checking the animation slot’s bone capacity) rather than flipping a bare flag. The
enable callback runs only if the owning GameObject is also active.

smr:Deactivate( ) : void
Clears the own enabled flag — the renderer stops drawing. The disable callback runs only if the
renderer was actually active.

smr:GetMaterialInstance( ) : Material
Returns a per-instance clone of the shared material, creating it on the first call and caching it
thereafter (set per-instance colors on this material). Returns nil if there is no material to
clone, or silently nil on a dead handle.

smr:SetBoneLocal( integer index, Vector3 position, Quaternion rotation ) : void
Directly poses bone index in its parent-local frame and marks the animation dirty. Out-of-range
indices are ignored (no warning).

smr:PlayController( AnimController controller ) : boolean
Clones controller (a template) into a private per-renderer instance stored on this renderer,
so it advances its own play-head; any prior instance is destroyed first. The instance is reaped
automatically when the renderer is destroyed. Returns true on success, false on failure or a
dead handle. Drive playback each frame with smr:Sample(dt). This is the per-instance replacement
for SampleController.

smr:Sample( number dt ) : void
Advances this renderer’s own controller instance (from PlayController) by dt seconds and
samples the pose into the skeleton, marking it dirty for GPU upload. No-op if PlayController was
never called. Call smr:Sample(offset) once before the per-frame loop to seed a start phase (the
play-head advances and Loop-wraps to that phase).

smr:SampleController( AnimController controller, number dt ) : void
Samples the given controller directly into this renderer’s skeleton and advances that
controller’s single play-head by dt seconds, marking the animation dirty. Takes both the
controller and dt (unlike Sample, which takes only dt).

Known issue — deprecated (verified in source). SampleController advances the shared
controller’s single play-head, so if the same controller is sampled by N renderers in a frame
its play-head advances N times — animation runs N×-too-fast for a shared controller
(lua_skinned_mesh_renderer.rs:447-465). Prefer PlayController + Sample, which give each
renderer an independent play-head. It is kept only for the rare case of one genuinely shared
play-head.

Example

-- A herd of dogs, each with its OWN animation play-head, seeded to a staggered
-- phase so a walk-wave travels across the pack.
-- (Adapted from data/scripts/main_scene_setup.lua.)
local function spawn_dog(object, mesh, mat, ctrl, phase)
    local smr = SkinnedMeshRenderer.Add(object, mesh, mat)
    if smr and smr:PlayController(ctrl) then
        smr:Sample(phase)   -- seed a start offset (one-time)
        return smr
    end
    return nil
end

function Script.Update(self)
    -- Each dog advances its own instance by the frame dt; phase offsets are kept.
    for i = 1, #self.dogs do
        self.dogs[i]:Sample(Time.DeltaTime())
    end
end

Texture

A handle to a GPU texture. Most textures are loaded assets you look up by name and read dimensions
from. Dynamic textures (created via CreateDynamic / CreateDynamic3D) add a CPU-side staging
copy you can edit pixel-by-pixel and push to the GPU with Apply.

Static calls use the type table (Texture.Get(...)); instance methods use colon syntax on a handle
(tex:SetPixel(...)).

Types

Texture — an opaque handle (userdata) to a texture. A handle may be null or stale (its
texture destroyed); it is safe to keep and pass around. tostring(tex) yields Texture{name}, or
Texture{NULL} if dead.

The pixel-editing methods only apply to dynamic textures; on a non-dynamic or dead texture they
log InvalidArgument and no-op. Pixel coordinates are 0-based texel indices (x in 0 .. Width()-1, y in 0 .. Height()-1, z in 0 .. Depth()-1); an out-of-range coordinate is
rejected by the manager (logs InvalidArgument). Color components are integers in 0–255 (see
the known issue below), not normalized floats.

Creation & Destruction

Texture.Get( string name ) : Texture
Looks up a texture by its unique name. Returns nil (logs NotFound) if none exists.

Texture.Exists( Texture texture ) : boolean
Returns true if the handle refers to a live texture. Safe on null / stale / foreign handles
(returns false, never warns).

Texture.CreateDynamic( string name, integer width, integer height, integer format ) : Texture
Creates a 2D dynamic (CPU-editable) texture. format is a Texture.PixelFormat value. Returns the
new handle, or nil (logs InvalidArgument) if the format is unknown, the name is taken, or GPU
allocation fails.

Texture.CreateDynamic3D( string name, integer width, integer height, integer depth, integer format ) : Texture
Creates a 3D dynamic texture (a 2D texture when depth <= 1). format is a Texture.PixelFormat
value. Returns the new handle, or nil (logs InvalidArgument) on failure.

tex:Destroy( ) : void
Releases the GPU image (if any) and destroys the texture. No-op on a null handle.

Functions

Read-only queries. Instance getters log NotFound and return nil on a dead handle unless noted.

Texture.IsDynamic( Texture texture ) : boolean
true if texture is a dynamic (CPU-editable) texture. Safe on null / foreign handles (returns
false).

tex:ID( ) : string
The texture’s unique name.

tex:Width( ) : integer
Width in texels.

tex:Height( ) : integer
Height in texels.

tex:Depth( ) : integer
Depth in texels (1 for 2D textures). Returns 0 (not nil) on error.

tex:AspectRatio( ) : number
Width / height. Returns nil on error.

tex:GetPixel( integer x, integer y ) : integer, integer, integer, integer
Reads a texel from the current frame’s CPU staging copy of a dynamic texture as four 0–255
components r, g, b, a. Returns 0, 0, 0, 0 and logs InvalidArgument on error (non-dynamic, dead,
or out-of-range coordinate).

tex:GetPixel3D( integer x, integer y, integer z ) : integer, integer, integer, integer
As GetPixel, for a 3D dynamic texture. Returns 0, 0, 0, 0 on error.

tex:GetPixelData( ) : string
Returns the entire CPU staging buffer as a raw byte string — the texels packed in the texture’s
pixel format (e.g. 4 bytes/texel for RGBA8), row-major. Returns an empty string (logs NotFound)
on error.

Methods

Mutating actions on dynamic textures. They log InvalidArgument on a non-dynamic or dead
texture. Edits touch the current frame’s CPU staging copy; call Apply to schedule the GPU upload.

tex:SetPixel( integer x, integer y, integer r, integer g, integer b, integer a ) : void
Writes one RGBA texel into the staging copy. Components are integers (see the known issue).

tex:SetPixel3D( integer x, integer y, integer z, integer r, integer g, integer b, integer a ) : void
Writes one RGBA texel into a 3D dynamic texture.

tex:SetPixelData( string bytes ) : void
Overwrites the whole staging buffer from a raw byte string (must match the buffer’s size and format
layout, else InvalidArgument).

tex:SetPixelDataRange( integer offset, string bytes ) : void
Writes bytes into the staging buffer starting at byte offset. A negative offset logs
InvalidArgument and is rejected; an offset + length past the buffer end is rejected by the manager.

tex:Apply( ) : void
Drains the accumulated dirty region and marks it on the GPU image so the backend can issue a
targeted subregion copy for the current frame. No-op on a null handle or a texture with no GPU image.

Known issue — components are integers cast to u8, no clamp (verified in source).
SetPixel / SetPixel3D read each of r, g, b, a with luaL_checkinteger(...) as u8
(lua_texture.rs:387-390, :433-436). Two consequences: (1) they are integers, not
normalized floats — pass 255, not 1.0 (a fractional Lua number such as 0.5 raises “number
has no integer representation”); (2) values outside 0–255 wrap modulo 256 rather than
clamping (256 -> 0, -1 -> 255). Clamp/round in Lua (e.g. math.floor into 0..255) before
calling.

Constants

Texture.PixelFormat — pixel format discriminants passed to CreateDynamic / CreateDynamic3D.
An unrecognized value fails creation with InvalidArgument.

None (0), BGRA8_sRGB (1), R8 (2), RG8 (3), R16F (4), BGRA8 (5), RG16F (6),
R32F (7), RGBA16F (8), RG32F (9), D32 (10), D32_S8 (11), BC1 (12), BC1_sRGB (13),
BC2 (14), BC2_sRGB (15), BC3 (16), BC3_sRGB (17), BC4 (18), BC5 (19), BC6 (20),
BC7 (21), BC7_sRGB (22), RGBA8 (23), RGBA8_sRGB (24).

Example

-- Walk a colored texel across a 64x64 dynamic texture each frame.
-- (Adapted from data/scripts/dyn_texture_demo.lua.)
local px, py, frame = 0, 0, 0

function Script.Update(self)
    local tex = Texture.Get("dyn_demo")
    if not tex then return end

    -- Integer 0-255 components (math.floor keeps them in range).
    local r = math.floor((px / 64) * 255)
    local g = math.floor((py / 64) * 255)
    local b = frame % 256
    tex:SetPixel(px, py, r, g, b, 255)
    tex:Apply()

    px = px + 1
    if px >= 64 then px, py = 0, (py + 1) % 64 end
    frame = frame + 1
end

RenderTexture

An off-screen render target — a paired color and depth texture a Camera can draw into
instead of the swapchain. Create one, hand its GPU handles to a camera’s render targets, then sample
its color Texture in a material (e.g. for a mirror, minimap, or picture-in-picture).

Static calls use the type table (RenderTexture.Create(...)); instance methods use colon syntax on
a handle (rt:ColorTexture()).

Types

RenderTexture — an opaque 8-byte handle (userdata) to a render-target pair. A handle may be
null or stale (its target destroyed); it is safe to keep and pass around. tostring(rt)
yields the constant string RenderTexture (it does not embed a name).

Creation & Destruction

RenderTexture.Create( string name, integer width, integer height, integer colorFormat, integer depthFormat, string msaa ) : RenderTexture
Creates a render target named name. colorFormat / depthFormat are still RenderTexture.PixelFormat
integers (e.g. RGBA8 color, D32 depth); msaa is a multisample-level name (see
Constants). Returns the new handle, or nil (logs InvalidArgument) if either format
is unknown or GPU allocation fails. A bad msaa name does not return nil — it raises, because
it is resolved before any allocation happens.

RenderTexture.Get( string name ) : RenderTexture
Looks up an existing render texture by name. Returns nil (logs NotFound) if none exists.

RenderTexture.Exists( RenderTexture rt ) : boolean
Returns true if the handle refers to a live render texture. Safe on null / stale / foreign handles
(returns false, never warns).

rt:Destroy( ) : void
Destroys the render texture and releases its GPU color and depth images. No-op on a null handle.

Functions

Read-only queries on a handle.

rt:GpuColorHandle( ) : integer
The color target’s GPU handle, packed into an integer for a camera’s color render target. Returns
0 (logs NotFound) on error. See “GPU handles” below.

rt:GpuDepthHandle( ) : integer
The depth target’s packed GPU handle, for a camera’s depth render target. Returns 0 (logs
NotFound) on error.

rt:ColorTexture( ) : Texture
The color attachment as a sampleable Texture handle (bind it in a material). nil if
unset, or nil (logs NotFound) on a dead handle.

rt:DepthTexture( ) : Texture
The depth attachment as a Texture handle. nil if unset, or nil (logs NotFound) on
a dead handle.

rt:Width( ) : integer
Width in pixels. Returns 0 (not nil, logs NotFound) on error.

rt:Height( ) : integer
Height in pixels. Returns 0 on error.

GPU handles

GpuColorHandle / GpuDepthHandle return a GpuHandle<GpuRenderTarget> reinterpreted as a raw
u32 integer (a 4-byte handle, layout [gen:8 | pool_type:8 | index:16]). Treat it as opaque:
do not do arithmetic on it — just pass it straight to camera:SetRenderTarget(...) /
camera:SetDepthRenderTarget(...), which transmute the same integer back into a handle. 0 is the
null handle and is also the error return, so a failed lookup passes through harmlessly as “no
target.”

Constants

RenderTexture.PixelFormat — pixel format discriminants for colorFormat / depthFormat. An
unrecognized value fails Create with InvalidArgument.

None (0), BGRA8_sRGB (1), R8 (2), RG8 (3), R16F (4), BGRA8 (5), RG16F (6),
R32F (7), RGBA16F (8), RG32F (9), D32 (10), D32_S8 (11), BC1 (12), BC1_sRGB (13),
BC2 (14), BC2_sRGB (15), BC3 (16), BC3_sRGB (17), BC4 (18), BC5 (19), BC6 (20),
BC7 (21), BC7_sRGB (22), RGBA8 (23), RGBA8_sRGB (24).

The multisample level for msaa is a name, matched exactly with no case folding — one of
"None", "X2", "X4", "X8", "X16". An unrecognized value raises a Lua error listing all
five. The name is deliberately not the sample count: "4" is rejected, because the engine
numbers these levels 1/2/4/8/16 while the settings layer numbers the same five 0..4, and a bare
integer is ambiguous between the two.

The RenderTexture.MSAALevel sub-table was deleted (2026-07), so RenderTexture.MSAALevel
is now nil. It had only ever exposed None/X4/X8 — X2 and X16 were unreachable from
Lua, and Create matched only 1/4/8, so asking for 2 or 16 samples silently produced
none. Both halves are gone; all five levels are now reachable and anything else raises.

Example

-- Render a second camera into a 1024x1024 target and show it on a UI quad.
-- (Adapted from data/scripts/main_scene_setup.lua.)
local PF = RenderTexture.PixelFormat
local rt = RenderTexture.Create("mini_camera", 1024, 1024, PF.RGBA8, PF.D32, "None")
if rt then
    -- Packed GPU handles go straight to the camera's render targets.
    cam:SetRenderTarget(rt:GpuColorHandle())
    cam:SetDepthRenderTarget(rt:GpuDepthHandle())
    -- The color attachment is a sampleable Texture for a material.
    rt_material:SetTexture(0, rt:ColorTexture())
end

Shader

A handle to a compiled graphics pipeline (a vertex + fragment program plus its pipeline state).
Shaders are looked up by name and assigned to a Material (material:SetShader(...));
the geometry (3D) variant can also be created at runtime from named SPIR-V stages via CreateGeo.

Static calls use the type table (Shader.Get(...)); instance methods use colon syntax on a handle
(shader:RenderQueue()). The Lua surface is read-only — there are no property setters and no
Destroy.

Types

Shader — an opaque handle (userdata) to a compiled pipeline. A handle may be null or
stale. The instance queries on a dead handle log a warning (NotFound) and return nil; they
never raise on a live-but-empty result. Passing a non-Shader userdata (or wrong argument types)
to a method raises a Lua type error. tostring(shader) yields Shader{name}, or Shader{NULL} if
the handle is dead.

Creation & Destruction

Shader.CreateGeo( string name, string vertName, string fragName, integer renderQueue, integer textureCount ) : Shader
Creates a geometry (3D) shader named name from the named vertex and fragment SPIR-V stages, with
the given render-queue order and texture-binding count. Allocates a GPU pipeline through the render
backend, so it is only meaningful with a live backend. Returns the new handle, or nil (logs
InvalidArgument) on failure. renderQueue and textureCount are truncated to u16 (values
≥ 65536 wrap silently).

Shader.Get( string name ) : Shader
Looks up a shader by its unique name. Returns nil (logs NotFound) if none exists.

Shader.Exists( Shader shader ) : boolean
Returns true if the handle refers to a live shader. Safe on null/stale/foreign handles (returns
false) — the one call here that never warns or raises.

Shaders have no instance Destroy from Lua.

Functions

Read-only queries. Each logs NotFound and returns nil on a null/stale handle.

shader:ID( ) : string
The shader’s unique name.

shader:RenderQueue( ) : integer
The render-queue order value (a u16; controls draw sorting relative to other shaders).

shader:DepthWrite( ) : boolean
Whether the pipeline writes to the depth buffer.

shader:AlphaToCoverage( ) : boolean
Whether alpha-to-coverage is enabled on the pipeline.

Example

-- Assign a looked-up shader to a material, and inspect its pipeline state.
-- (Adapted from data/scripts/session_setup.lua.)
local mat = Material.Create("lit_material")
local geo = Shader.Get("geo_lit")
mat:SetShader(geo)
mat:SetColorLinear(0, Vector4.new(1, 1, 1, 1))

if Shader.Exists(geo) then
    -- geo:ID(), geo:RenderQueue(), geo:DepthWrite(), geo:AlphaToCoverage()
    print(geo:ID(), "queue=" .. geo:RenderQueue(), "depthWrite=" .. tostring(geo:DepthWrite()))
end

Physics

A module singleton (global functions only, no handles) for querying the deterministic physics
world: raycasts, shape sweeps, overlap tests, and the layer-collision matrix. Fixed-point
results are converted to f32 at this script boundary. Queries whose name is unsuffixed run
against rigid bodies; the engine merges voxel-terrain hits by distance where a collision world is
wired.

Vector arguments (origin, direction, center, halfExtents, …) take a Vector3.
layerMask is an integer bitmask selecting which layers the query tests.

Result tables

A single hit is a table { point: Vector3, normal: Vector3, distance: number, gameObject: GameObject }. Multi-hit queries return a 1-based array of these (or of GameObjects, as noted).

Functions

Physics.Raycast( Vector3 origin, Vector3 direction, integer layerMask ) : table or nil
Physics.Raycast( Vector3 origin, Vector3 direction, integer layerMask, number maxDistance ) : table or nil
Casts a ray and returns the closest hit as a {point, normal, distance, gameObject} table, or
nil if nothing was hit. maxDistance defaults to unbounded.

Physics.RaycastAll( Vector3 origin, Vector3 direction, integer layerMask ) : table
Physics.RaycastAll( Vector3 origin, Vector3 direction, integer layerMask, number maxDistance ) : table
Returns an array of every hit along the ray (empty table if none).

Physics.LinecastAll( Vector3 start, Vector3 end, integer layerMask ) : table
Returns an array of all hits on the segment from start to end.

Physics.SphereTestAll( Vector3 center, number radius, integer layerMask ) : table
Returns an array of the GameObjects whose colliders overlap the sphere.

Physics.SphereCast( Vector3 center, number radius, Vector3 direction, number maxDistance, integer layerMask ) : table or nil
Sweeps a sphere and returns the closest hit, or nil.

Physics.CapsuleCast( Vector3 center, Quaternion rotation, number radius, number halfHeight, Vector3 direction, number maxDistance, integer layerMask ) : table or nil
Sweeps an oriented capsule and returns the closest hit, or nil.

Physics.BoxCast( Vector3 center, Quaternion rotation, Vector3 halfExtents, Vector3 direction, number maxDistance, integer layerMask ) : table or nil
Sweeps an oriented box and returns the closest hit, or nil.

Physics.OverlapBox( Vector3 center, Quaternion rotation, Vector3 halfExtents, integer layerMask ) : table
Returns an array of the GameObjects overlapping the oriented box.

Physics.CheckSphere( Vector3 center, number radius, integer layerMask ) : boolean
true if any collider overlaps the sphere.

Physics.CheckBox( Vector3 center, Quaternion rotation, Vector3 halfExtents, integer layerMask ) : boolean
true if any collider overlaps the oriented box.

Physics.IgnoreLayerCollision( integer a, integer b, boolean ignore ) : void
Sets whether layers a and b ignore each other in the solver (Unity semantics: ignore == true clears the collide bit). Intended for startup/config — the layer table is treated as
immutable during simulation. Out-of-range indices (≥ 32) are a no-op.

Physics.GetIgnoreLayerCollision( integer a, integer b ) : boolean
true if layers a and b are set not to collide. Out-of-range or unwired returns
false.

Constants

Physics exposes no constants. Force modes are quoted strings, not a constants table — see
FixedRigidBody → AddForce.

rb:AddForce(Vector3.new(0, 12, 0), "Impulse")   -- correct

Removed (2026-07). A global ForceMode table of integers (Force=0 … Acceleration=3)
used to be registered here. It was added for an earlier integer-taking rigid-body binding that
the fixed-dynamics rewrite retired; the replacement takes mode names, so every use of the
table silently applied Force (luaL_checkstring coerces 1 → "1", which matched nothing).
The table is gone, and an unrecognized mode name now raises a Lua error instead of defaulting.
ForceMode is nil — reaching for it is a loud error at the call site, which is the point.

Example

-- Ground check: cast a short ray straight down from the player.
function Script.Update(self)
    local x, y, z = self.object:WorldPosition()
    local hit = Physics.Raycast(Vector3.new(x, y, z), Vector3.new(0, -1, 0), self.groundMask, 1.2)
    self.grounded = hit ~= nil
    if hit then
        -- hit.point, hit.normal, hit.distance, hit.gameObject
        self.groundNormal = hit.normal
    end
end

Collider

A collision shape attached to a GameObject — a sphere, an oriented or axis-aligned box, or a
capsule — plus a layer bitmask and a trigger flag. Enabling a collider registers a static
(mass-0) body in the deterministic FixedXpbdWorld, so dynamic bodies (like
DynamicCharacter) collide with it and Physics queries can hit
it.

Static calls use the type table (Collider.Add(...)); instance methods use colon syntax on a
handle (collider:SetBox(...)).

Types

Collider — an opaque handle (userdata) to a collider component on a GameObject. It may go
stale when its component or GameObject is destroyed; a stale handle is safe to hold and pass
around. Calling a method whose receiver is not a Collider raises a type error — the one exception
is Collider.Exists, which is safe on any value. On a genuine but stale handle nothing raises:
getters log a warning and return nil, shape/config setters silently no-op, and Exists returns
false. tostring(collider) is always the literal string Collider (it never includes the
object’s name).

Known issue: A Collider is effectively static. Its collision body is placed once, at
on_enable, from the GameObject’s world transform, and is not re-posed when the GameObject
moves at runtime (engine/scenegraph/src/collider.rs:60). Moving a collider’s GameObject leaves
its collision surface behind at the enable-time pose. Re-posing happens only as a side effect of
calling a shape or filter setter — each rebuilds the body at the current transform via
sync_collider_shape. Author colliders where they belong, or re-call a setter after moving one.

Creation & Destruction

Collider.Add( GameObject gameObject ) : Collider
Attaches a new collider to gameObject and returns its handle. It starts as a degenerate
zero-extent AABB with layer mask 0xFFFFFFFF (all layers) and is not a trigger — call a shape
setter to give it geometry. Returns nil and logs an error if the component can’t be added (the
GameObject is invalid, it already has a collider, or the pool is exhausted). Raises a type error if
gameObject is not a GameObject.

Collider.Get( GameObject gameObject ) : Collider
Returns the collider on gameObject, or nil (logging a NotFound warning) if it has none.

Collider.Exists( Collider collider ) : boolean
Returns true if the handle refers to a live collider. Safe on any value — a non-collider or
a stale handle returns false and never raises. (The one method that does not type-check its
receiver.)

There is no Destroy binding — a collider is removed with its GameObject; disabling the GameObject
unregisters its collision body, and re-enabling re-registers it.

Functions

Read-only queries.

collider:Active( ) : boolean or nil
The component’s own enabled flag — what Activate()/Deactivate() write. Logs a warning
(NotFound) and returns nil on a stale handle. This is intent, not effect: a collider whose
own flag is enabled but whose GameObject is deactivated still reports true.

collider:ActiveInHierarchy( ) : boolean or nil
true only when the own flag is enabled and the owning GameObject is active in hierarchy —
i.e. the component is actually running. This is the predicate the engine uses to gate update
dispatch. Returns nil on a stale handle.

Properties (get / set)

Setters rebuild the static fixed body so the change reaches the world (the cheap per-frame position
sync does not carry the mask or the sensor flag). Both setters silently no-op on a stale handle.

LayerMask

collider:LayerMask( ) : integer — the collider’s 32-bit layer bitmask (default 0xFFFFFFFF).
Logs a warning and returns nil on a stale handle.
collider:SetLayerMask( integer mask ) : void — sets the bitmask and rebuilds the broadphase
entry so the new mask reaches queries.

Trigger

collider:IsTrigger( ) : boolean — true if the collider is a trigger (sensor) volume. nil

• warning on a stale handle.
  collider:SetTrigger( boolean on ) : void — marks the collider as a trigger (Unity
  isTrigger); overlaps then surface through the deterministic trigger-event pass
  (OnTriggerEnter/Stay/Exit) instead of producing solid contacts.

Methods

Shape setters — bake the collider’s local geometry, then rebuild the static body at the current
transform. Every Vector3 argument must be a native Vector3 value; three loose numbers raise
a type error (unlike the GameObject setters, which accept either). All silently no-op on a stale
handle.

collider:SetSphere( Vector3 center, number radius ) : void
Sphere of radius, centered at local-space center. Orientation-free.

collider:SetAABB( Vector3 center, Vector3 halfExtents ) : void
Axis-aligned box with half-extents halfExtents at center. The body’s orientation is pinned to
identity — it ignores the GameObject’s rotation.

collider:SetBox( Vector3 center, Vector3 halfExtents ) : void
Oriented box — same half-extents as SetAABB, but the body tracks the GameObject’s rotation.

collider:SetCapsule( Vector3 center, number radius, number halfHeight ) : void
Y-axis capsule of radius and halfHeight (center to cap-center) at center. Tracks rotation.

Mesh colliders removed (2026-07-17): SetTriangleMesh and SetConvexMesh are no longer
exposed to Lua. They never produced triangle-mesh or convex-hull collision — both silently
registered an oriented bounding box sized to the vertices’ AABB (FixedShape::Box), ignoring the
triangles/hull entirely (and SetTriangleMesh’s indices outright). The names promised fidelity
the code did not deliver, so the bindings were commented out (lua/venus_lua/src/lua_collider.rs;
scene glue in engine/scenegraph/src/scene.rs) pending a real mesh narrowphase. For non-box
geometry, decompose it into primitive colliders (sphere / box / capsule) yourself.

Lifecycle

Both silently no-op on a stale handle.

collider:Activate( ) : void
Sets the component’s own enabled flag. Its enable callback runs only if the owning GameObject is
also active — and it is that enable callback which registers the collision body.

collider:Deactivate( ) : void
Clears the own enabled flag; the disable callback runs only if the component was actually active.

Example

-- A box trigger zone on layer 3: reports OnTriggerEnter/Stay/Exit instead of blocking.
-- Vector3 args must be native Vector3 values (loose numbers raise a type error).
function Script.OnCreate(self)
    local col = Collider.Add(self.object)
    col:SetBox(Vector3.new(0, 0, 0), Vector3.new(0.5, 0.5, 0.5))  -- a 1-unit cube
    col:SetLayerMask(1 << 3)                                       -- only layer 3
    col:SetTrigger(true)
    -- The static body is seeded here at the object's world pose and is NOT re-posed
    -- if the object later moves — re-call a setter after moving it.
end

KinematicController

A deterministic character-controller component: a capsule that sweeps through the world with
collide-and-slide (auto step-up/down, wall sliding, depenetration, walkable-slope grounding). It
mirrors a conventional controller’s API (Move, IsGrounded, CollisionFlags, GroundNormal,
Radius/SetRadius, …) and adds Rotation/SetRotation for an orientation-aware capsule.

The component owns fixed-point (deterministic) authoritative state and derives its f32
transform each frame — so it must be driven from Script.FixedUpdate at the fixed cadence
(Time.FixedDeltaTime()), not from Update. Render interpolation (stair smoothing over risers
and ledge drops) is handled internally; the authoritative state and every determinism hash stay
untouched.

Static calls use the type table (KinematicController.Add(go)); instance methods use colon syntax
on a handle (kc:Move(...)).

Types

KinematicController — an opaque handle (userdata) to the controller component on a GameObject.
A handle may be stale (its component or GameObject destroyed); it is safe to keep and pass
around. Passing a value that is not a KinematicController raises a type error, but calling a method
on a stale handle never raises — it returns the documented default (nil, false, 0, or
world-up) or no-ops.

Creation & Destruction

KinematicController.Add( GameObject object ) : KinematicController
Attaches a new controller to object and returns its handle, with default capsule tunables
(radius 0.4, half-height 0.9, step 0.3, skin 0.08, slope 46°, no ground plane). Returns
nil and logs an error if the controller can’t be added (the GameObject is invalid, already has
one, or the pool is exhausted).

KinematicController.Get( GameObject object ) : KinematicController
Returns the controller attached to object, or nil if it has none (no warning).

KinematicController.Exists( KinematicController controller ) : boolean
Returns true if the handle refers to a live controller. Safe on stale handles (returns false).

There is no Destroy binding — a controller is removed when its GameObject is destroyed.

Functions

Read-only queries. On a stale handle each returns a default (nil, or the noted fallback) without
raising.

kc:IsGrounded( ) : boolean
true if the controller is resting on a walkable surface (slope ≤ SlopeLimit). false on a
stale handle.

kc:IsWalkable( ) : boolean
Alias of IsGrounded — the slide controller only reports grounded on walkable surfaces, so the
two are identical.

kc:GroundNormal( ) : Vector3
Unit surface normal of the current ground contact ((0, 1, 0) on flat ground). Returns world up
(0, 1, 0) when airborne or on a stale handle.

kc:GroundAngle( ) : number
Slope steepness of the ground under the controller, in degrees from vertical (0 = flat, up
to SlopeLimit when grounded). Derived from the ground normal. 0 on a stale handle.

kc:CollisionFlags( ) : integer
Bitmask (OR) of the COLLISION_* values recording which sides touched during the last Move
(below / sides / above). 0 (COLLISION_NONE) if nothing was hit or on a stale handle. See
Constants.

kc:DidLand( ) : boolean
true if the controller became grounded during the last Move (the EVENT_LANDED transition —
was airborne, now grounded). false on a stale handle.

kc:DidLeaveGround( ) : boolean
true if the controller left the ground during the last Move (the EVENT_LEFT_GROUND
transition). false on a stale handle.

kc:Active( ) : boolean or nil
The component’s own enabled flag — what Activate()/Deactivate() write. nil (+ a logged
NotFound) on a stale handle, so a destroyed controller stays distinguishable from a disabled one.
This is intent, not effect: a controller whose own flag is enabled but whose GameObject is
deactivated still reports true.

kc:ActiveInHierarchy( ) : boolean or nil
true only when the own flag is enabled and the owning GameObject is active in hierarchy —
i.e. the component is actually running. This is the predicate the engine uses to gate update
dispatch. Returns nil on a stale handle.

Properties (get / set)

Getters return nil on a stale handle unless noted; setters no-op. Vector3 / Quaternion
arguments must be native math values (not three loose numbers). Config values are quantized to
fixed-point when the next Move runs.

Velocity

kc:Velocity( ) : Vector3 — current velocity (units/second).
kc:SetVelocity( Vector3 velocity ) : void — sets the velocity directly. Move overwrites it
each call, so this is mainly useful for reading (kc:Velocity().y to integrate gravity) rather
than setting.

Position

kc:Position( ) : Vector3 — current world position (the render-derived f32 value).
kc:SetPosition( Vector3 position ) : void — teleports the controller, setting the
fixed-point authoritative position and clearing stair-smoothing. Use for spawns/respawns, not
per-frame motion (use Move).

Rotation

kc:Rotation( ) : Quaternion — current orientation.
kc:SetRotation( Quaternion rotation ) : void — sets the orientation. The capsule mover is
orientation-aware, so this turns the body (e.g. to face the movement direction).

Radius

kc:Radius( ) : number — capsule radius (default 0.4).
kc:SetRadius( number radius ) : void

Height

kc:Height( ) : number — capsule half-height, center to cap-center (default 0.9). Named
Height for convention, but the value is the half-height.
kc:SetHeight( number halfHeight ) : void — sets the half-height.

SlopeLimit

kc:SlopeLimit( ) : number — max walkable slope in degrees (default 46). Steeper
surfaces are treated as walls and do not ground the controller.
kc:SetSlopeLimit( number degrees ) : void

StepHeight

kc:StepHeight( ) : number — max step height, both directions (default 0.3): auto
step-up over risers up to this height, and step-down snap when descending ledges/slopes.
kc:SetStepHeight( number height ) : void

SkinWidth

kc:SkinWidth( ) : number — contact skin gap held back from surfaces to prevent sticking
(default 0.08).
kc:SetSkinWidth( number width ) : void

GroundPlaneY

kc:GroundPlaneY( ) : number or nil — world y of the optional infinite fallback floor, or
nil if none is set (the default). nil also on a stale handle.
kc:SetGroundPlaneY( number y ) : void — enables an infinite walkable floor at world y,
layered under the voxel terrain (terrain wins where it exists). Catches the character in open
space so it can’t fall through the world. There is no un-set binding — it can only be enabled or
moved.

Methods

kc:Move( Vector3 velocity, number dt ) : void
The core per-step drive. Sets the controller’s velocity to velocity (units/second, with gravity
already folded in by the caller — the controller applies none), then advances it by dt seconds
against the deterministic collision world using collide-and-slide (sweep, step-up/down, wall slide,
depenetration). Refreshes grounded state, ground normal, collision flags, and the land /
leave-ground events. No-op on a stale handle or when no collision world is set. Call once per fixed
step from Script.FixedUpdate with dt = Time.FixedDeltaTime().

kc:Activate( ) : void
Sets the component’s own enabled flag. Its enable callback runs only if the owning GameObject is
also active. Silently no-ops on a stale handle.

kc:Deactivate( ) : void
Clears the own enabled flag; the disable callback runs only if the component was actually active.
Silently no-ops on a stale handle.

Constants

Enum fields on the global KinematicController table (e.g. KinematicController.COLLISION_BELOW)
— not on instances.

Collision flags. CollisionFlags() returns a bitmask (bitwise OR) of these; test a side with
bitwise AND (flags & KinematicController.COLLISION_SIDES ~= 0):

Events. One-step ground transitions, surfaced by the DidLand() / DidLeaveGround() query
methods (you rarely read these constants directly):

Example

-- A deterministic WASD character. Adapted from data/scripts/kinematic_player.lua.
-- Driven from FixedUpdate at the fixed cadence — the controller's state is
-- fixed-point and lockstep-deterministic; render smoothing is handled internally.
local Script = {}

local SPEED, GRAVITY, JUMP = 5.0, 20.0, 8.0

function Script.OnCreate(self)
    KinematicController.Add(self.object)
    local kc = KinematicController.Get(self.object)
    kc:SetStepHeight(0.6)    -- climb 0.5-unit risers
    kc:SetGroundPlaneY(0.0)  -- fallback floor so it can't fall through empty space
end

function Script.FixedUpdate(self)
    local kc = KinematicController.Get(self.object)
    if kc == nil then return end
    local dt = Time.FixedDeltaTime()
    if dt <= 0 then return end

    -- Horizontal input (world axes; forward is -Z).
    local ix, iz = 0, 0
    if Input.Key("move_forward") then iz = iz + 1 end
    if Input.Key("move_back")    then iz = iz - 1 end
    if Input.Key("move_right")   then ix = ix + 1 end
    if Input.Key("move_left")    then ix = ix - 1 end
    local move = Vector3.new(ix, 0, -iz)
    if move:sqrMagnitude() > 1 then move = Vector3.Normalize(move) end
    move = move * SPEED

    -- Script-driven gravity (the controller applies none).
    local vy
    if kc:IsGrounded() then
        vy = -2.0                                -- gentle stick to follow slopes/steps
        if Input.KeyDown("jump") then vy = JUMP end
    else
        vy = kc:Velocity().y - GRAVITY * dt
    end

    kc:Move(Vector3.new(move.x, vy, move.z), dt)

    -- Face the movement direction (orientation-aware capsule).
    if move:sqrMagnitude() > 0.01 then
        local yaw = math.deg(math.atan(move.x, move.z))
        kc:SetRotation(Quaternion.AngleAxis(yaw, Vector3.new(0, 1, 0)))
    end
end

return Script

DynamicCharacter

A dynamic character controller: a real rigid-body capsule in the app-owned FixedXpbdWorld whose
orientation is locked (it cannot tip) and whose horizontal motion is a force-capped velocity
motor — light crates yield to it, heavy crates block it. Gravity and contacts own vertical
motion; Jump is an impulse. It is the two-way, massy counterpart to
KinematicController (which sweeps a shape and never pushes anything).

Because its state is fixed-point and lockstep-deterministic, drive it from Script.FixedUpdate at
the fixed cadence, not from Update. Shape and mass are baked once, at attach time, via Add.
Static calls use the type table (DynamicCharacter.Add(...)); instance methods use colon syntax
(dc:Move(...)).

Types

DynamicCharacter — an opaque handle (userdata) to a dynamic-character component on a GameObject.
Passing a value that is not a DynamicCharacter to any method (including Exists) raises a type
error; a genuine stale handle never raises — it returns the documented default (nil /
false) or no-ops. The handle is safe to hold and pass around. There is no custom __tostring, so
tostring(dc) is Lua’s default userdata string.

The body is registered on on_enable, not on Add. Until it is registered, every
world-touching method — Move, Stop, Jump, IsGrounded, Velocity/SetVelocity,
Position, SetFriction, SetStepOffset — no-ops or returns its default. Guard with
IsRegistered() (the demo script does). Registration is torn down on on_disable, so deactivating
the GameObject removes the body from the simulation; reactivating re-registers it and re-applies
the cached friction and step offset.

The GameObject’s rotation is owned by gameplay: the simulation leaves it alone (the body’s
orientation is locked, and update writes position only), so animate facing/yaw freely — it never
feeds back into physics. There is no SetRotation binding (unlike KinematicController); rotate the
GameObject directly.

Creation & Destruction

DynamicCharacter.Add( GameObject gameObject, number halfHeight, number radius, number mass ) : DynamicCharacter
Attaches a dynamic-character capsule to gameObject. halfHeight, radius, and mass are
optional, defaulting to 0.5, 0.3, and 80 (kg). The push-force budget is not a parameter —
it defaults to 400 N; raise it with SetMaxForce. Shape and mass are baked when the body
registers (on_enable), which seeds it at the GameObject’s world position — so set the spawn
position before Add (as dynamic_player.lua does). Returns nil and logs an error if the
component can’t be added (invalid GameObject, already has one, or the pool is exhausted).

DynamicCharacter.Get( GameObject gameObject ) : DynamicCharacter
Returns the character on gameObject, or nil if it has none (no warning, unlike Collider.Get).

DynamicCharacter.Exists( DynamicCharacter character ) : boolean
Returns true if the handle refers to a live component. Safe on a genuine stale handle (returns
false), but raises a type error if character is not a DynamicCharacter (including nil) — see
Types.

There is no Destroy binding — the character is removed with its GameObject; disabling the
GameObject unregisters its body from the simulation.

Functions

Read-only queries. Each returns its default (false, or nil) when the body is unregistered or no
physics world is wired.

dc:IsGrounded( ) : boolean
true if the body had a ground-like contact (contact normal y ≥ 0.7, ≈ 45°) during the last
fixed step — voxel terrain, a static collider, or standing on a crate all count. false when
unregistered.

dc:Position( ) : Vector3
The body’s current world position — the authoritative fixed-point capsule center converted to
f32, not the interpolated render transform. nil when unregistered.

dc:IsRegistered( ) : boolean
true once the body exists in the world (after on_enable); false on a stale handle. Use it to
gate the other methods (see Types).

The two lifecycle getters below read the scene component, not the world body, so they answer
normally on an attached-but-unregistered character (unlike everything else in this section).

dc:Active( ) : boolean or nil
The component’s own enabled flag — what Activate()/Deactivate() write. nil (+ a logged
NotFound) on a stale handle. This is intent, not effect: a character whose own flag is enabled
but whose GameObject is deactivated still reports true.

dc:ActiveInHierarchy( ) : boolean or nil
true only when the own flag is enabled and the owning GameObject is active in hierarchy —
i.e. the component is actually running. This is the predicate the engine uses to gate update
dispatch. Returns nil on a stale handle.

Properties (get / set)

Velocity

dc:Velocity( ) : Vector3 — the body’s current linear velocity (units/second), or nil when
unregistered.
dc:SetVelocity( Vector3 velocity ) : void — sets the full 3D linear velocity directly.
velocity must be a native Vector3 (loose numbers raise). No-op when unregistered. An active
Move drive re-steers the horizontal velocity every step, so this is mainly for vertical kicks or
teleport-stops.

Methods

Locomotion and tuning.

dc:Move( number vx, number vz ) : void
Sets a persistent, force-capped horizontal velocity motor toward (vx, vz) in units/second.
Note the arguments are two loose numbers (not a Vector3) and there is no delta-time: this
is not a per-step advance — it upserts a drive that the solver re-applies every fixed step until
you change it or call Stop(), so calling it once keeps the character moving. (Contrast
KinematicController:Move, which takes a velocity Vector3 plus dt
and advances a single step.) The force cap is the push budget (SetMaxForce). Vertical motion is
untouched — gravity, contacts, and Jump own it. Idempotent; call each fixed step or on input
change. No-op when unregistered.

dc:Stop( ) : void
Removes the drive entirely — the character then slides freely under friction and contacts.
(Move(0, 0) is different: active braking toward zero under the force budget.) No-op when
unregistered.

dc:Jump( number impulse ) : void
Applies a vertical impulse of impulse = mass·Δv (e.g. mass * 6 for a ~6 units/second take-off).
Does not check grounded — gate on IsGrounded() yourself. No-op when unregistered.

dc:SetMaxForce( number newtons ) : void
Sets the locomotion/push force budget (default 400 N). Stored on the component and applied by the
next Move — it is not pushed to the world immediately. Works before registration; no-op on a
stale handle.

dc:SetFriction( number mu ) : void
Sets the body’s Coulomb friction (characters default a deliberately low 0.05: the drive owns
horizontal control, and a high μ fights it — μ·m·g rivals the force cap). Applied live when
registered and cached on the component so a re-enable keeps it. No-op on a stale handle.

dc:SetStepOffset( number height ) : void
Sets the max auto step-up (stair-climb) height in units; 0 disables (the default, and the
byte-identical off path). Terrain only — the character cannot step onto crates or other dynamic
bodies. Applied live when registered and cached for re-enable. No-op on a stale handle.

Lifecycle

Both silently no-op on a stale handle. Because registration follows the component’s enable state
(see Types), these are the component-level lever on whether the body is in the simulation
at all.

dc:Activate( ) : void
Sets the component’s own enabled flag. Its enable callback runs only if the owning GameObject is
also active — and that callback is what registers the body.

dc:Deactivate( ) : void
Clears the own enabled flag; the disable callback runs only if the component was actually active.

Example

-- A deterministic dynamic (massy) character. Adapted from data/scripts/dynamic_player.lua.
-- Driven from FixedUpdate: Move sets a persistent velocity motor the solver applies each
-- fixed step, so this must run at the fixed cadence for lockstep determinism.
local Script = {}

local SPEED      = 5.0     -- target horizontal speed (units/second)
local JUMP_SPEED = 6.0     -- take-off speed; impulse = mass * this
local MASS       = 80.0    -- must match the DynamicCharacter.Add mass
local MAX_FORCE  = 3000.0  -- push budget (N); the 400 N default is gentle

function Script.OnCreate(self)
    -- Set the spawn position BEFORE Add — the body seeds at the world position on_enable.
    self.object:SetWorldPosition(0, 7, 0)
    DynamicCharacter.Add(self.object, 0.9, 0.4, MASS)  -- half-height, radius, mass
    local dc = DynamicCharacter.Get(self.object)
    if dc then dc:SetMaxForce(MAX_FORCE) end
end

function Script.FixedUpdate(self)
    local dc = DynamicCharacter.Get(self.object)
    if dc == nil or not dc:IsRegistered() then return end

    -- WASD → world-axis direction (forward is -Z).
    local ix, iz = 0, 0
    if Input.Key("move_forward") then iz = iz + 1 end
    if Input.Key("move_back")    then iz = iz - 1 end
    if Input.Key("move_right")   then ix = ix + 1 end
    if Input.Key("move_left")    then ix = ix - 1 end
    local move = Vector3.new(ix, 0, -iz)
    if move:sqrMagnitude() > 1 then move = Vector3.Normalize(move) end
    move = move * SPEED

    -- Horizontal velocity motor (two loose numbers, no dt). (0,0) = active braking.
    -- Vertical is owned by gravity/contacts — we do NOT fold gravity into the drive.
    dc:Move(move.x, move.z)

    -- One impulse per press, only when grounded (Jump itself does not check).
    if Input.KeyDown("jump") and dc:IsGrounded() then
        dc:Jump(MASS * JUMP_SPEED)
    end
end

return Script

FixedRigidBody

A rigid body in the app-owned deterministic FixedXpbdWorld (the lockstep path): box, sphere,
plane, or capsule, driven with conventional rigid-body commands (SetVelocity, AddImpulse,
AddForce, …). Shape and mass are baked once when the body registers (on_enable) — chosen at
attach time via Add / AddBox / AddSphere / AddPlane / AddCapsule, and not mutated live.
Joints between two bodies live on FixedJoint.

Static calls use the type table (FixedRigidBody.AddBox(...)); instance methods use colon syntax
on a handle (rb:AddForce(...)).

Vector arguments come in two flavours. The velocity / force / impulse commands (SetVelocity,
SetAngularVelocity, AddImpulse, AddForce, AddTorque, and the force argument of
AddForceAtPosition) require a native Vector3 — three loose numbers raise a type error. Only the
two world-position overloads, Respawn and the worldPos argument of AddForceAtPosition, accept
either a Vector3 or three loose f64 numbers; the three-number form preserves precision far
from the origin (a Vector3 is f32-backed, ~cm-lossy at range).

Types

FixedRigidBody — an opaque handle (userdata) wrapping a component that holds a generational world
body handle. A handle may be null, stale (its component destroyed), or unregistered
(attached but not yet through on_enable). Every command and query resolves the component and its
world body afresh each call; on a null / stale / unregistered handle, commands no-op and
queries return nil — they never raise. Use IsRegistered() to test readiness.

Creation & Destruction

Each Add* constructor attaches a FixedRigidBody component to gameObject and returns its
handle; the world body is created from the GameObject’s world pose at on_enable, so set the
object’s position before attaching. Returns nil and logs an error if the component cannot be
added (e.g. a null/stale GameObject or an exhausted pool).

FixedRigidBody.Add( GameObject gameObject ) : FixedRigidBody
Attaches a unit-box (half-extent 0.5, mass 1) dynamic body.

FixedRigidBody.AddBox( GameObject gameObject, number hx, number hy, number hz, number mass ) : FixedRigidBody
A box body with half-extents (hx, hy, hz) (all three required). mass is optional (default 1).

FixedRigidBody.AddSphere( GameObject gameObject, number radius, number mass ) : FixedRigidBody
A sphere body of radius (required). mass is optional (default 1).

FixedRigidBody.AddPlane( GameObject gameObject ) : FixedRigidBody
A static infinite ground plane (a half-space; normal = the GameObject’s local +Y). Always
static — it carries no mass and never moves.

FixedRigidBody.AddCapsule( GameObject gameObject, number halfHeight, number radius, number mass ) : FixedRigidBody
A capsule body (axis = local +Y); halfHeight and radius required. mass is optional
(default 1).

FixedRigidBody.Get( GameObject gameObject ) : FixedRigidBody
Returns the FixedRigidBody on gameObject, or nil if it has none. Silent — unlike the
Add* constructors, a miss logs nothing.

FixedRigidBody.Exists( FixedRigidBody body ) : boolean
true if the handle refers to a live component. Safe on any handle (null/stale → false); never
raises.

There is no explicit Destroy. The world body — with its full joint cascade — is torn down
automatically when the GameObject or component is destroyed (on_disable).

Functions

Read-only queries.

rb:Position( ) : Vector3
The body’s current world position. Returns nil if the body is unregistered or the world is
unavailable.

rb:IsRegistered( ) : boolean
true once the world body exists (after on_enable). This is the gate for every command and
query below — before registration they all no-op / return nil.

The two lifecycle getters are the exception: they read the scene component rather than the world
body, so they answer normally on an attached-but-unregistered body.

rb:Active( ) : boolean or nil
The component’s own enabled flag — what Activate()/Deactivate() write. nil (+ a logged
NotFound) on a stale handle. This is intent, not effect: a body whose own flag is enabled but
whose GameObject is deactivated still reports true.

rb:ActiveInHierarchy( ) : boolean or nil
true only when the own flag is enabled and the owning GameObject is active in hierarchy —
i.e. the component is actually running. This is the predicate the engine uses to gate update
dispatch. Returns nil on a stale handle.

Properties (get / set)

Getters return nil on an unregistered / stale handle; setters no-op. Each velocity setter takes a
native Vector3 (not loose numbers).

Velocity

rb:Velocity( ) : Vector3 — current linear velocity, or nil if unregistered.
rb:SetVelocity( Vector3 velocity ) : void

AngularVelocity

rb:AngularVelocity( ) : Vector3 — current angular velocity, or nil if unregistered.
rb:SetAngularVelocity( Vector3 velocity ) : void

Methods

Actions that mutate the body. All no-op on an unregistered / stale handle.

rb:AddImpulse( Vector3 impulse ) : void
An instantaneous linear velocity change (v += j · inv_mass). Takes a native Vector3.

rb:AddForce( Vector3 force, string mode ) : void
Applies a force (Unity Rigidbody.AddForce). force is a native Vector3. mode is the optional
force-mode name — "Force" | "Impulse" | "VelocityChange" | "Acceleration" (Unity’s
names; omitted or nil → "Force"). Any other value raises a Lua error, including a number:
the names are matched exactly, and there is no ForceMode constants table.

rb:AddTorque( Vector3 torque, string mode ) : void
Applies a world-space torque (Unity Rigidbody.AddTorque). torque is a native Vector3. mode
is the optional force-mode name (see AddForce; default "Force").

rb:AddForceAtPosition( Vector3 force, Vector3 worldPos, string mode ) : void
A force plus its induced torque about the application point worldPos. force is a native
Vector3; worldPos may be a Vector3 or three loose f64 numbers (the three-number form
keeps the point precise far from the origin). mode is the optional force-mode name and simply
follows worldPos in either form.

Fixed 2026-07 (was: silent wrong mode). The mode used to fall back to Force on any
unrecognized value, and the global ForceMode.* integer table — a leftover from a retired
binding — coerced through luaL_checkstring to "1"/"2"/"3" and matched nothing. Every
use of those constants silently applied Force, which is wrong by a factor of the fixed step:
Force delivers F·inv_m·dt spread over the next step, Impulse delivers J·inv_m
immediately — so a jump impulse arrived at roughly 1/120 strength, with no diagnostic. The
table is deleted and unrecognized names now raise. Names resolve through
ForceMode::from_yaml_bytes, generated beside the enum in venus-fixed-dynamics, so the
spellings cannot drift from the variants. Note the lowercase form ("impulse") was accepted-
then-ignored before and is now a hard error — spell it as Unity does.

rb:SetRestitution( number e ) : void
Sets bounciness (restitution).

rb:SetFriction( number mu ) : void
Sets the friction coefficient.

rb:SetMaterial( string name ) : void
Resolves a named physics material from the resource registry
(data/core/defs/physics_materials.yaml) and applies its friction, restitution, and combine modes
to the live body, caching it on the component so it survives respawn / re-enable. An unknown name
(or no registry loaded) logs an error and no-ops.

rb:SetCollisionEvents( boolean on ) : void
Opts into OnCollisionEnter / OnCollisionStay / OnCollisionExit on this body’s GameObject
ScriptBehavior. Persists in the authoring params (clones inherit it).

rb:Respawn( Vector3 position ) : void
Teleports to the given world position with zero velocity and identity orientation — a clean
re-drop that resets simulation state (for spawning/respawning, not in-sim motion). Accepts a
Vector3 or three loose f64 numbers; the three-number form keeps the target precise far from
the origin.

Lifecycle

Both act on the component’s enabled flag rather than the world body, so — unlike the commands above
— they are meaningful before registration. Both silently no-op on a stale handle.

rb:Activate( ) : void
Sets the component’s own enabled flag. Its enable callback runs only if the owning GameObject is
also active — and that callback is what creates the world body.

rb:Deactivate( ) : void
Clears the own enabled flag; the disable callback runs only if the component was actually active.

Example

-- A box prop that drops onto the deterministic ground, reports contacts, and
-- re-drops on a timer. (Adapted from data/scripts/fixed_physics_demo.lua.)
function Script.OnCreate(self)
    -- Pose BEFORE Add: on_enable registers the world body from this position.
    -- Three loose f64 numbers keep the drop precise far from the origin.
    self.object:SetWorldPosition(0.0, 9.0, 0.0)
    self.drop = { 0.0, 9.0, 0.0 }

    -- Unit cube → half-extents 0.5, mass 2.
    self.rb = FixedRigidBody.AddBox(self.object, 0.5, 0.5, 0.5, 2.0)
    self.rb:SetMaterial("wood")
    self.rb:SetCollisionEvents(true)   -- enable the OnCollision* callbacks
    self.timer = 0.0
end

function Script.OnCollisionEnter(self, other)
    -- Kick straight up on first contact. Mode is the quoted NAME string;
    -- there is no constants table, and an unrecognized name raises.
    self.rb:AddForce(Vector3.new(0, 5, 0), "Impulse")
end

function Script.Update(self)
    self.timer = self.timer + Time.DeltaTime()
    if self.timer >= 3.0 then
        self.timer = 0.0
        -- f64 overload: teleport back to the drop point and fall again.
        self.rb:Respawn(self.drop[1], self.drop[2], self.drop[3])
    end
end

FixedJoint

A FixedJoint is a scenegraph component that constrains the FixedRigidBody
on its own GameObject — either to a static world anchor (the default) or to another
GameObject’s FixedRigidBody (SetConnected). The constraint is solved in the
deterministic FixedXpbdWorld.

The GameObject must also carry a FixedRigidBody; the joint has nothing to constrain without one.

Static calls use the type table (FixedJoint.Add(...)); instance methods use colon syntax on the
handle (joint:SetRevolute(...)).

Types

FixedJoint — an opaque handle (userdata) to a FixedJoint component, type-id tagged and
generation-checked. The internal FixedJointHandle never crosses the Lua boundary.

The two failure modes differ: