Scripting API

Attachment & lifecycle

How Scripts Run

A complete reference for the scripting surface: how a script is attached and run, the lifecycle callbacks, and every function the horizon API exposes. Lua and Python share one underlying API, so the same calls are available in both — only the way you package a script differs.

You attach a script to an entity with the Script component, which references a script asset by UUID plus a logical module name. Each script asset is either Lua or Python — the language is stored on the asset and is inferred from the file extension (.py → Python, everything else → Lua). Both languages are hosted side by side; an instance is routed to the right runtime automatically.

The lifecycle is driven by the editor's Play Mode. When you enter play mode, every entity that carries an enabled Script component gets one script instance bound to it. Each instance is bound to its entity: the raw entity id is exposed as self.entityId in Lua and self.entity_id in Python. That id is the first argument to nearly every horizon function.

Every callback is optional — if a script doesn't define one, it's simply skipped. Collision callbacks only fire for entities that also have physics colliders.

Two languages, one API

Lua vs. Python

A Lua script is a module: create a table, add lifecycle functions to it, and return it. Every callback takes self as its first parameter (the per-instance table). A Python script defines a single subclass of horizon.Behavior; the callbacks are ordinary methods, and each instance is one object of that class.

-- Lua: return a table of callbacks
local M = {}
function M.onStart(self) end
function M.onUpdate(self, dt) end
return M

# Python: subclass horizon.Behavior
import horizon
class MyScript(horizon.Behavior):
    def on_start(self): pass
    def on_update(self, dt): pass

Per-instance data

Exposed Properties

You can expose typed fields that appear as editable controls in the Details panel, set per instance. In Lua, add a properties table to your module; in Python, declare typed class attributes (any non-underscore attribute). Supported types are number (int or float), bool and string. The value you set in the editor is injected into the instance before onStart runs, so read it there or in onUpdate.

-- Lua
local M = {}
M.properties = { speed = 4.0, jumpHeight = 2.0, canFly = false }
function M.onUpdate(self, dt)
    -- self.speed is the per-instance value from the editor
end
return M

# Python: typed class attributes become editable properties
class Player(horizon.Behavior):
    speed = 4.0
    jump_height = 2.0
    can_fly = False

Function reference

The horizon API

The same functions are available in Lua (as the global horizon table) and Python (via import horizon). Entity arguments are the raw entity id. Invalid ids are tolerated: getters return neutral defaults, setters are no-ops.

The raycast hit table

A hit is a flat table (Lua) / dict (Python) — the point and normal are spread across individual keys, not nested:

Python subclass

horizon.Behavior (Python)

Python scripts must define exactly one subclass of horizon.Behavior. The base class provides the bound entity_id attribute; every lifecycle method is optional and overridden as needed:

Worked examples

Complete Examples

A minimal starter in each language — these mirror the skeletons the editor generates when you create a new script:

local M = {}

function M.onStart(self)
end

function M.onUpdate(self, dt)
end

return M

import horizon

class NewScript(horizon.Behavior):
    def on_start(self):
        pass

    def on_update(self, dt):
        pass

And a working example in each language — a mover that logs its name, spawns a child, and drives its own transform every frame:

local M = {}

M.properties = { speed = 2.0 }

function M.onStart(self)
    self.t = 0
    horizon.log("Patroller start: " .. horizon.getName(self.entityId))
    -- spawn a marker parented to this entity
    self.marker = horizon.spawn(self.entityId, "Marker")
end

function M.onUpdate(self, dt)
    self.t = self.t + dt
    local x = math.sin(self.t) * self.speed
    horizon.setPosition(self.entityId, x, 0, 0)
end

function M.onCollisionEnter(self, otherId)
    horizon.log("Hit " .. horizon.getName(otherId))
end

return M

import horizon
import math

class Patroller(horizon.Behavior):
    speed = 2.0

    def on_start(self):
        self.t = 0.0
        horizon.log("Patroller start: " + horizon.getName(self.entity_id))
        # spawn a marker parented to this entity
        self.marker = horizon.spawn(self.entity_id, "Marker")

    def on_update(self, dt):
        self.t += dt
        x = math.sin(self.t) * self.speed
        horizon.setPosition(self.entity_id, x, 0, 0)

    def on_collision_enter(self, other_id):
        horizon.log("Hit " + horizon.getName(other_id))