Scripting API

Attachment & lifecycle

How Scripts Run

How a script is attached and run, its lifecycle callbacks and the flat functions on horizon. Lua and Python share one underlying API, so the same calls are available in both — only the way you package a script differs. Every engine function, with its signature, is in the Engine API Reference.

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.

Scripts run in the editor's Play Mode and in the exported game alike. When play mode starts, or when the game loads a scene, every entity that carries an enabled Script component gets one script instance bound to it; entities that arrive later, such as a streamed-in zone, get theirs when they load. 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). They come in two layers: the 35 flat functions below, which sit directly on horizon, and the groups horizon.math.*, horizon.physics.*, horizon.net.* and so on, generated from the engine's API registry. The groups are listed function by function in the Engine API Reference, together with the rules for passing vectors and entity ids.

Entity arguments are the raw entity id. Invalid ids are tolerated: getters return neutral defaults, setters are no-ops. Arguments in brackets are optional.

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:

The other methods a Behavior can define, from on_begin_overlap to on_cheat_detected, are listed under Callbacks.

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