Engine API

Read this first

Calling Conventions

Every function on this page comes from one table inside the engine, the API registry. A HorizonCode graph, a Lua script, a Python script and C++ game code all call the same row, so a function behaves the same in all four. What differs is how you spell the call and how arguments travel. These rules apply to every row below.

One function, four names

The C++ name listed with every row is the engine's own function behind it. A native GameLogic module does not link against the engine and cannot call it; it reaches a smaller set (save, entity lookup, physics, input, content, networking and anti-cheat) through the he:: service helpers, see Native C++.

Function names are camelCase in Python too: horizon.physics.addImpulse, not add_impulse. Four groups are not reachable as horizon.<group>.* from Lua and Python: transform, material, cursor and log. Scripts use the flat functions for them instead (horizon.setPosition, horizon.setMaterialParam, horizon.showCursor, horizon.log). Rows without a flat twin, such as transform.getWorldPosition, are HorizonCode and C++ only. Each group below says which case it is.

Arguments and results

Arguments are passed flat, in the order the signature lists them. A vector is spread into its numbers, it is not a table or a tuple:

Results spread the same way. One value comes back as that value, several as Lua multiple return values or a Python tuple, none as nil / None. physics.raycast takes two vec3 and a float (seven numbers) and returns a bool, an entity, two vec3, a float and an int (ten values):

local x, y, z = horizon.getPosition(self.entityId)
local hit, other, px, py, pz, nx, ny, nz, dist, layer =
    horizon.physics.raycast(x, y, z,  0, -1, 0,  50)
if hit then
    horizon.log("ground is " .. dist .. " below")
end

x, y, z = horizon.getPosition(self.entity_id)
hit, other, px, py, pz, nx, ny, nz, dist, layer = \
    horizon.physics.raycast(x, y, z,  0, -1, 0,  50)
if hit:
    horizon.log(f"ground is {dist} below")

Too few arguments is an error: Lua raises bad argument #n … (number expected, got no value), Python raises IndexError. The one exception is a missing bool in Lua, which silently reads as false. Extra arguments are ignored in both languages. Optional arguments exist only where a signature shows them in brackets, which is only on the flat functions.

Entity ids and “Self”

An entity is passed as its integer id: self.entityId in Lua, self.entity_id in Python, or whatever a lookup like horizon.entity.findByName returned. Invalid ids are tolerated: getters return a neutral default, setters do nothing.

List results (not yet usable from scripts)

Events in the descriptions

The descriptions come from the editor and name HorizonCode events such as On Timer or On Http Response. A script receives only the events listed under Callbacks; those are linked where they appear. The others (On Http Response, On File Changed, On Menu Item, On Tray Item, On Row Bind, On Window Closed, On Dismissed, On Selection Changed, On Right Clicked) have no Lua or Python callback today. Where a query exists, poll it instead, for example horizon.http.done(ticket) each frame after horizon.http.get. Otherwise handle that part in a HorizonCode graph.

Actions and queries

Every row is either an action (it changes something: moves, spawns, plays, writes) or a query (it only reads and returns). In HorizonCode an action is a node with white execution pins that runs in sequence, a query is a data node without them. In a script both are ordinary calls, but the tag tells you whether a call is safe to repeat freely.

Project permissions

A few rows reach outside the game and only run when the project allows it, under Project Settings ▸ Permissions. Without the permission the call does nothing and returns its “failed” value (false, 0, an empty result), and the log says which permission is missing. The settings travel into the exported app, and they bind play mode in the editor the same way.

Dialogs and the clipboard need no permission. A path the user picked in a file dialog stands in for Files outside the project, but only for the fs.* rows: print.toPdf and db.open need the permission for every path, a relative one inside the project included (build 7d49d44f). The log line about a missing permission is written for the first refused call only; further refusals of any row within the next ten seconds are not logged.

Remote calls take any arguments

horizon.net.callServer(entity, name, …), horizon.net.callClient(player, entity, name, …) and horizon.net.callAllClients(entity, name, …) accept any number of extra arguments after the function name and pass them on. Their types are taken from the values themselves: a boolean, an integer, any other number, a string, or a list/table of those. This is the one place where the registry signature (which has no slot for them) does not describe the script call. The receiving side is a method of that name on the target entity's script, see Callbacks.

Your own enums and structs

Project Types in Scripts

Enums and structs you create as assets in the Content Browser are available to scripts under horizon.enums and horizon.structs, built when the script runtime starts.

A struct value is a plain table / dict: one key per field plus __type, the path of the struct asset. Keep __type when you hand the value back, it is how the engine knows which struct it is. Missing fields keep their defaults, unknown keys are ignored. Inside a struct, fields are single values rather than spread: a vec2 is {x, y} / [x, y], a colour {r, g, b, a}, a transform {pos = {…}, rot = {…}, scl = {…}}, a list a sequence, and a nested struct a nested table. A map field is a Python dict (it keeps its order); in Lua it is a table plus a __keys list that holds the order. Structs go in and out of save.setStruct / save.getStruct this way.

Lua and Python only

Flat horizon.* Functions

Besides the groups, horizon carries 35 functions directly: horizon.setPosition(...) rather than horizon.transform.setPosition(...). They predate the registry, exist only in Lua and Python, and keep a signature of their own: some arguments are optional (in brackets), and raycast returns a table instead of separate values. Where a registry row does the same job it is linked; for transform, material, cursor and log these functions are the only way in from a script.

Log and entities

Transform

Physics

Material

In-game UI elements

These act on entities that carry UI components (a UI canvas in the scene). Widgets built in the Widget Designer are a different thing, see the next table.

Widgets

Widgets are instances of Widget Designer assets. They live outside the entity world and are addressed by the widget id createWidget returns, not by an entity id. The rest of the widget API (lists, animation, popups, children) is horizon.widget.*.

Cursor

What the engine calls on your script

Callbacks

A Lua script returns a table of functions, a Python script defines one subclass of horizon.Behavior. The engine calls the functions below on it by name; every one is optional, and a missing one is simply skipped. Lua names are camelCase, Python names snake_case. Receives says who gets the call: this entity means only the script on the entity concerned, every script means every Lua and Python instance in the session, so check the arguments before reacting. Results of many calls on this page arrive here: timers, input actions, network events, anti-cheat reports.

Lifecycle

Physics contacts

Both entities of a contact get the event, each with the other's id. A contact where either side no longer exists is dropped entirely. A trigger contact fires both pairs: onCollisionEnter and onBeginOverlap, then onCollisionExit and onEndOverlap.

Input actions

Actions are the ones defined in the project's input mapping. These go to every script instance, not only to the player's entity; pick the action by name. For polling instead of events use horizon.input.actionDown and friends.

Timers

Animation notifies

In-game UI pointer

Sent to scripts on entities with an interactive UI element (a button, or any element carrying a script) under the mouse.

Multiplayer session

Every script instance on the machine concerned receives these. Each event happens on one side only: the host hears players come and go, a client hears its own connection. Measured with host and client in Lua and Python.

Replication and remote calls

Anti-cheat

The whole registry at a glance

All Groups

Core and data · 31 functions

Math

Lua / Python: horizon.math.<function> · C++: HE::api::math::<function>

Pure functions over numbers: none of them changes anything, so they can be called anywhere and as often as needed. In a script the language's own math library does most of this too, and with more precision. horizon.math is for the results a HorizonCode graph would get, and for what the languages lack: lerp, clamp, the vector helpers and 32-bit bit operations.

• Angles. sin, cos, tan and atan2 work in radians, while the engine's rotations are in degrees. radians and degrees convert between them; horizon.math.sin(90) is 0.894, not 1.
• Precision. Every float crosses into the engine as a 32-bit number, about seven significant digits: normalize3(3, 0, 4) returns 0.6000000238…, 0, 0.8000000119…. Compare results with a tolerance, not with ==.
• Vectors are spread like every other argument: length(x, y), distance3(ax, ay, az, bx, by, bz). normalize3 and cross return three numbers.
• Bit operations (bitAnd to shiftRight) take and return 32-bit signed integers. Lua accepts an integer or a float with no fraction (6.0); 6.5 raises number has no integer representation. Python accepts only an int; any float raises TypeError. Results wrap at 32 bits: shiftLeft(1, 31) is −2147483648.

Example: math.dot3

local M = {}

-- True when target lies within coneDeg degrees around the direction
-- (fx, fy, fz) this entity faces.
function M.canSee(self, target, fx, fy, fz, coneDeg)
    local x, y, z = horizon.getPosition(self.entityId)
    local tx, ty, tz = horizon.getPosition(target)
    local dx, dy, dz = horizon.math.normalize3(tx - x, ty - y, tz - z)
    local limit = horizon.math.cos(horizon.math.radians(coneDeg / 2))
    return horizon.math.dot3(dx, dy, dz, fx, fy, fz) >= limit
end

return M

import horizon

class ViewCone(horizon.Behavior):
    def can_see(self, target, fx, fy, fz, cone_deg):
        """True when target lies within cone_deg degrees around (fx, fy, fz)."""
        x, y, z = horizon.getPosition(self.entity_id)
        tx, ty, tz = horizon.getPosition(target)
        dx, dy, dz = horizon.math.normalize3(tx - x, ty - y, tz - z)
        limit = horizon.math.cos(horizon.math.radians(cone_deg / 2))
        return horizon.math.dot3(dx, dy, dz, fx, fy, fz) >= limit

Core and data · 12 functions

String

Lua / Python: horizon.string.<function> · C++: HE::api::str::<function>

Text functions with the same results a HorizonCode graph gets. Three rules decide most surprises:

• Positions count from 0, also in Lua, whose own string.sub and string.find count from 1. find returns −1 when the piece is not there.
• Lengths and positions are bytes. Text is UTF-8: letters, digits and punctuation from plain ASCII take one byte, an accented or non-Latin letter two to four. length("ä") is 2, and a substring can cut such a letter in half. toUpper and toLower change only A to Z.
• Comparisons are exact. equals, contains, find, startsWith and endsWith are case-sensitive; lower both sides first when case should not matter.

An empty piece is found everywhere: contains(s, "") is true and find(s, "") is 0, while replace(s, "", x) returns s unchanged. A negative start in substring uses up part of count, so substring("hello", -2, 4) is "he". toNumber reads the number at the start of the text and ignores the rest: "3.5abc" gives 3.5, " 42 " 42, "1e3" 1000 and "0x10" 16. The result is a 32-bit float, exact for whole numbers only up to 16,777,216.

Example: string.find

local M = {}

-- "volume = 75" -> "volume", 75. Positions count from 0.
local function parse(line)
    local eq = horizon.string.find(line, "=")
    if eq < 0 then return nil end
    local key = horizon.string.trim(horizon.string.substring(line, 0, eq))
    local rest = horizon.string.substring(line, eq + 1, horizon.string.length(line))
    return key, horizon.string.toNumber(rest)
end

function M.onStart(self)
    local key, value = parse("volume = 75")
    if key then horizon.log(key .. " is " .. value) end
end

return M

import horizon

def parse(line):
    """'volume = 75' -> ('volume', 75.0). Positions count from 0."""
    eq = horizon.string.find(line, "=")
    if eq < 0:
        return None
    key = horizon.string.trim(horizon.string.substring(line, 0, eq))
    rest = horizon.string.substring(line, eq + 1, horizon.string.length(line))
    return key, horizon.string.toNumber(rest)

class Settings(horizon.Behavior):
    def on_start(self):
        parsed = parse("volume = 75")
        if parsed:
            key, value = parsed
            horizon.log(f"{key} is {value}")

Core and data · 5 functions

Random

Lua / Python: horizon.random.<function> · C++: HE::api::random::<function>

One random generator for the whole game, shared by every Lua and Python script and every HorizonCode graph. It starts from the same built-in seed at every launch, so a game that never calls seed draws the same numbers every time it starts. Seed it once at start: from the clock when every run should differ, from a constant when a bug should happen again.

Because it is shared, a seed restarts the sequence for everyone, and another script drawing in between changes the numbers you get. A repeated run matches only if the same scripts draw in the same order. Lua's math.random and Python's random module are separate generators and seed does not touch them.

All five are actions, because every call draws a new number (see Actions and queries). range can return min but not max; rangeInt includes both ends. Either one swaps the bounds when max is smaller than min. chance treats anything below 0 as 0 and anything above 1 as 1.

Example: random.seed

local M = {}

function M.onStart(self)
    -- Without this, every launch rolls the same numbers. Seed in one
    -- script only: every seed restarts the sequence for all of them.
    horizon.random.seed(os.time())
end

function M.roll(self)
    local eyes = horizon.random.rangeInt(1, 6)      -- 1 to 6, both included
    local critical = horizon.random.chance(0.05)     -- one in twenty
    return eyes, critical
end

return M

import time
import horizon

class Dice(horizon.Behavior):
    def on_start(self):
        # Without this, every launch rolls the same numbers. Seed in one
        # script only: every seed restarts the sequence for all of them.
        horizon.random.seed(int(time.time()))

    def roll(self):
        eyes = horizon.random.rangeInt(1, 6)     # 1 to 6, both included
        critical = horizon.random.chance(0.05)   # one in twenty
        return eyes, critical

Core and data · 13 functions

Time

Lua / Python: horizon.time.<function> · C++: HE::api::time::<function>

The game clock. It advances once per frame, and every query gives the same answer for the rest of that frame. In the editor it runs only during Play and starts from 0 each time. For the time of day use Date and Time; to be called back later, use a Timer.

deltaTime and elapsed are scaled: they follow the time scale and stand still while the game is paused or in a hit stop. unscaledDeltaTime and unscaledElapsed follow real time, which is what a pause menu or a UI animation needs.

Three separate controls stop or slow the clock, and effectiveScale is their result:

• Time scale (setTimeScale), limited to 0…5. A larger value becomes 5, a negative one 0.
• Pause (pause / resume). It also silences input actions, except the ones with Fires while the game is paused ticked in the Input asset. Tick it on the key that opens the pause menu, or that key cannot close it again. All scripts and graphs share one pause, so a resume anywhere lifts a pause from anywhere. The pause the window sets when it loses focus is separate; resume cannot lift it.
• Hit stop (hitStop): a freeze for a stretch of real time. Input keeps arriving, and isPaused stays false.

Pause and hit stop leave the time scale alone, so the game resumes at the speed it had. When a game loads another scene, the scale goes back to 1 and the script pause and any hit stop are lifted; elapsed and frameCount keep counting.

Example: time.pause

local M = {}

-- "Pause" is an input action with "Fires while the game is paused"
-- ticked; without it the second press would never arrive.
function M.onInputPressed(self, name)
    if name ~= "Pause" then return end
    if horizon.time.isPaused() then
        horizon.time.resume()
    else
        horizon.time.pause()
    end
end

function M.onCollisionEnter(self, other)
    horizon.time.hitStop(0.1)   -- a landed hit freezes for a tenth of a second
end

return M

import horizon

class PauseMenu(horizon.Behavior):
    # "Pause" is an input action with "Fires while the game is paused"
    # ticked; without it the second press would never arrive.
    def on_input_pressed(self, name):
        if name != "Pause":
            return
        if horizon.time.isPaused():
            horizon.time.resume()
        else:
            horizon.time.pause()

    def on_collision_enter(self, other):
        horizon.time.hitStop(0.1)   # a landed hit freezes for a tenth of a second

Core and data · 5 functions

Timer

Lua / Python: horizon.timer.<function> · C++: HE::api::timer::<function>

A timer calls back instead of waiting. after and every return a handle at once and the script carries on; when the time is up the engine calls onTimer(self, handle) (Python on_timer, see Callbacks) on every script instance, and fires the GameInstance's On Timer event. Keep the handle and compare it, because the other scripts' timers arrive too.

• Timers run on real time: pause, slow motion and hit stop do not stretch them. To wait in game time, count horizon.time.deltaTime() in onUpdate.
• Handles count up from 1. 0 means the timer did not start: the interval was shorter than 0.001 seconds or not a number, or 64 timers were already running.
• A timer belongs to the session, not to the script or entity that started it. Destroying the entity or loading another scene does not stop it; stopping Play or quitting the game does. cancelAll stops every timer, other scripts' and the GameInstance's included. To stop only your own, use cancel(handle).

Example: timer.every

local M = {}

function M.onStart(self)
    self.autosave = horizon.timer.every(30)
    self.hint = horizon.timer.after(5)
end

function M.onTimer(self, handle)
    if handle == self.autosave then
        horizon.log("autosave")
    elseif handle == self.hint then
        horizon.log("Press E to open the door")
    end
    -- any other handle belongs to another script
end

return M

import horizon

class Reminders(horizon.Behavior):
    def on_start(self):
        self.autosave = horizon.timer.every(30)
        self.hint = horizon.timer.after(5)

    def on_timer(self, handle):
        if handle == self.autosave:
            horizon.log("autosave")
        elif handle == self.hint:
            horizon.log("Press E to open the door")
        # any other handle belongs to another script

Core and data · 9 functions

Date and Time

Lua / Python: horizon.datetime.<function> · C++: HE::api::datetime::<function>

The wall clock: calendar date and time of day in the time zone of the computer the game runs on. Unlike Time it keeps going through pauses and has nothing to do with frames. A point in time is a number of seconds since 1 January 1970 (the Unix epoch), which is what now returns and every other function takes. format uses strftime patterns: %Y-%m-%d, %H:%M, %A for the weekday name. An empty pattern, or a result longer than 511 bytes, gives an empty string. weekday counts from 0 for Sunday.

Example: datetime.now

local M = {}

local DAYS = { [0] = "Sunday", "Monday", "Tuesday", "Wednesday",
               "Thursday", "Friday", "Saturday" }

function M.onStart(self)
    local now = horizon.datetime.now()
    horizon.log("Today is " .. DAYS[horizon.datetime.weekday(now)] .. ", "
                .. horizon.datetime.format(now, "%d.%m.%Y"))
    -- To the second: from Lua itself until the precision issue is fixed.
    horizon.log("It is " .. os.date("%H:%M:%S"))
end

return M

import time
import horizon

DAYS = ["Sunday", "Monday", "Tuesday", "Wednesday",
        "Thursday", "Friday", "Saturday"]

class ClockLabel(horizon.Behavior):
    def on_start(self):
        now = horizon.datetime.now()
        day = DAYS[horizon.datetime.weekday(now)]
        horizon.log(f"Today is {day}, {horizon.datetime.format(now, '%d.%m.%Y')}")
        # To the second: from Python itself until the precision issue is fixed.
        horizon.log("It is " + time.strftime("%H:%M:%S"))

Core and data · 8 functions

JSON

Lua / Python: horizon.json.<function> · C++: HE::api::json::<function>

Reading and writing JSON text without a parser of your own: a config file from File System, a reply from HTTP. Every call takes the whole document as a string. The setters do not change it in place; they return the new document, so keep the result: doc = horizon.json.setNumber(doc, "volume", 0.8).

A path is a chain of keys separated by dots, with [i] for an array element counted from 0: user.name, items[2].id. The empty path is the document itself, so count(text, "") counts a top-level array. A key that itself contains a dot cannot be reached.

• Getters never fail loudly. A missing path, a value of another type and text that is not JSON all return the fallback. has is true for a key whose value is null.
• Setters create missing objects along the path, and an empty string starts a new document. They cannot add array elements: a path through a missing index, or through a value that is not an object, returns the document unchanged, as does text that is not JSON.
• The returned text is compact and its keys come out in alphabetical order, whatever order they had.
• Numbers pass through a 32-bit float. getNumber is exact for whole numbers up to 16 777 216 and keeps about seven digits otherwise; setNumber writes 3 as 3.0 and 0.1 as 0.10000000149011612. Read ids and other large numbers that the source wrote as strings with getString.

Example: json.getString

local M = {}
local FILE = "settings.json"

-- settings.json in the game's data folder, e.g.
-- {"video": {"width": 1920}, "profiles": [{"name": "Ada"}, {"name": "Lin"}]}
function M.onStart(self)
    local doc = horizon.fs.readText(FILE)   -- "" when the file is missing
    local width = horizon.json.getNumber(doc, "video.width", 1280)
    for i = 0, horizon.json.count(doc, "profiles") - 1 do
        horizon.log(horizon.json.getString(doc, "profiles[" .. i .. "].name", "?"))
    end
    -- Setters return the new text; store it and write it back yourself.
    doc = horizon.json.setNumber(doc, "video.width", width)
    doc = horizon.json.setBool(doc, "video.seen", true)
    horizon.fs.writeText(FILE, doc)
end

return M

import horizon

FILE = "settings.json"

class SettingsFile(horizon.Behavior):
    # settings.json in the game's data folder, e.g.
    # {"video": {"width": 1920}, "profiles": [{"name": "Ada"}, {"name": "Lin"}]}
    def on_start(self):
        doc = horizon.fs.readText(FILE)   # "" when the file is missing
        width = horizon.json.getNumber(doc, "video.width", 1280)
        for i in range(horizon.json.count(doc, "profiles")):
            horizon.log(horizon.json.getString(doc, f"profiles[{i}].name", "?"))
        # Setters return the new text; store it and write it back yourself.
        doc = horizon.json.setNumber(doc, "video.width", width)
        doc = horizon.json.setBool(doc, "video.seen", True)
        horizon.fs.writeText(FILE, doc)

Core and data · 4 functions

Debug

Lua / Python: horizon.debug.<function> · C++: HE::api::debug::<function>

Lines, spheres and boxes drawn into the 3D view, to see what a script is doing: where a ray went, what an overlap covered. A shape stays for seconds; 0 draws it for one frame, so a shape that follows something moving is drawn again every frame from onUpdate. seconds counts down in real time, so a paused game does not keep a shape alive longer; in the editor the countdown runs only during Play. The color is red, green and blue from 0 to 1; its alpha is ignored. clear removes every shape, including the ones other scripts drew. Debug shapes appear in a packaged game too, so take them out, or put them behind a flag of your own, before you ship.

Example: debug.line

local M = {}

function M.onUpdate(self, dt)
    local x, y, z = horizon.getPosition(self.entityId)
    -- Four numbers per position and color, the fourth is ignored.
    -- 0 seconds: drawn this frame only, so the shapes follow the entity.
    horizon.debug.line(x, y, z, 0,   x, y - 2, z, 0,   1, 0, 0, 1,   0)
    horizon.debug.sphere(x, y - 2, z, 0,   0.25,   0, 1, 0, 1,   0)
end

return M

import horizon

class GroundProbe(horizon.Behavior):
    def on_update(self, dt):
        x, y, z = horizon.getPosition(self.entity_id)
        # Four numbers per position and color, the fourth is ignored.
        # 0 seconds: drawn this frame only, so the shapes follow the entity.
        horizon.debug.line(x, y, z, 0,   x, y - 2, z, 0,   1, 0, 0, 1,   0)
        horizon.debug.sphere(x, y - 2, z, 0,   0.25,   0, 1, 0, 1,   0)

Core and data · 1 function

Log

horizon.log writes one line at Info level to the editor's Console and to HorizonEngine.log, in the editor and in a packaged game alike. In the editor the line is prefixed with the project's script language, for example [Lua]. The message must be text. Lua turns a number into text on its own, and anything else (nil, a table, a boolean) is an error. Python accepts only a str, so pass numbers through an f-string or str(). The language's own print writes to standard output only, which the Console does not show.

World and storage · 18 functions

Entity

Lua / Python: horizon.entity.<function> · C++: HE::api::entity::<function>

Creating, finding and removing entities. An entity is an integer id (see Entity ids). When a destroyed entity's slot is reused, the newcomer gets a different, larger id, so a kept id never points at a stranger; it just stops existing. Guard it with exists. exists(0) is false: 0 is what findByName returns when it finds nothing, even though it is also the scene root.

• destroy takes the entity's children with it.
• spawnClass and spawnClassRotated need the running game or play mode; they return 0 and log the reason when the class path is unknown or not an Entity class. The path is the class asset's content path, as in the Content Browser.
• self, selfObject and the Ref rows (instance, owned, destroyObject) belong to HorizonCode objects. A Lua or Python script is not one, so self() and selfObject() always return 0 there; use self.entityId / self.entity_id.
• Visibility only affects drawing. An entity with nothing to draw always reports getVisible = true, also right after setVisible(e, false).

saveState, hasSavedState and applySavedState store an entity's pose and visibility in the active save, keyed by the entity's stable UUID, so the same entity finds its state again after the scene is loaded anew. Three things must hold, and each missing one logs its own warning and returns false: the game is running (play mode or the packaged game), a save is active (save.create / save.load), and the entity has an enabled Save State component, whose checkboxes choose what is stored. Nothing is on disk until save.write.

Example: entity.exists

local M = {}

-- Opens the gate once the boss is gone. Look the ids up once, not every
-- frame: findByName walks every named entity.
function M.onStart(self)
    self.boss = horizon.entity.findByName("Boss")
    self.gate = horizon.entity.findByName("Gate")
end

function M.onUpdate(self, dt)
    if self.gate ~= 0 and not horizon.entity.exists(self.boss) then
        horizon.entity.destroy(self.gate)   -- takes its children along
        self.gate = 0
    end
end

return M

import horizon

class BossGate(horizon.Behavior):
    # Opens the gate once the boss is gone. Look the ids up once, not every
    # frame: findByName walks every named entity.
    def on_start(self):
        self.boss = horizon.entity.findByName("Boss")
        self.gate = horizon.entity.findByName("Gate")

    def on_update(self, dt):
        if self.gate != 0 and not horizon.entity.exists(self.boss):
            horizon.entity.destroy(self.gate)   # takes its children along
            self.gate = 0

World and storage · 8 functions

Transform

Position, rotation and scale are local: relative to the parent, in metres and Euler degrees (X pitch, Y yaw, Z roll). Without a parent, local and world are the same. On an entity with a rigid body or a character controller, setPosition and setRotation teleport the body as well, so the physics step does not pull it back; nothing checks for walls on the way.

The world-space pair getWorldPosition / setWorldPosition exists only in HorizonCode and C++. A script that needs where a child really stands keeps such entities unparented, or does that part in a HorizonCode graph with Get World Position. Adding up the parents' positions is not enough once a parent is rotated or scaled.

World and storage · 12 functions

Scene

Lua / Python: horizon.scene.<function> · C++: HE::api::scene::<function>

Every call that changes scenes is a request: it is queued and carried out at the start of the next frame, before any script's onUpdate, in the order it was made. So the code after load still runs in the old scene, and a zone you just loaded is not there yet: zonePosition returns 0, 0, 0 and zoneScene an empty string until the next frame. Show, hide and move requests made right after loadAdditive still apply to the new zone, because they queue behind it. Scene paths are relative to the project folder, for example Scenes/Level2.hescene.

• Switching (load) replaces the whole scene. With hidden = true it only preloads the scene and its assets; hasPendingLevel turns true, and activate swaps it in without a loading hitch. A second hidden load replaces the pending one.
• Zones (loadAdditive) add a scene next to the current one, at a world offset, and return a zone id at once. Zone ids count up from 1 and are never reused. A hidden zone is loaded and simulated but not drawn until showZone. A zone gets collision, and in the packaged game its scripts start when it arrives.

Example: scene.loadAdditive

local M = {}

-- This entity is a trigger volume at the start of the corridor. The cave
-- loads hidden, 200 m along X, while the player walks; the door shows it.
function M.onBeginOverlap(self, other)
    if self.zone then return end
    -- The position takes FOUR numbers from a script; the fourth is ignored.
    self.zone = horizon.scene.loadAdditive("Scenes/Cave.hescene", true, 200, 0, 0, 0)
end

-- "Interact" is an input action.
function M.onInputPressed(self, name)
    if name == "Interact" and self.zone then
        horizon.scene.showZone(self.zone)   -- queued behind the load
    end
end

return M

import horizon

class CaveStream(horizon.Behavior):
    # This entity is a trigger volume at the start of the corridor. The cave
    # loads hidden, 200 m along X, while the player walks; the door shows it.
    def on_start(self):
        self.zone = 0

    def on_begin_overlap(self, other):
        if self.zone:
            return
        # The position takes FOUR numbers from a script; the fourth is ignored.
        self.zone = horizon.scene.loadAdditive("Scenes/Cave.hescene", True, 200, 0, 0, 0)

    # "Interact" is an input action.
    def on_input_pressed(self, name):
        if name == "Interact" and self.zone:
            horizon.scene.showZone(self.zone)   # queued behind the load

World and storage · 4 functions

Content

Lua / Python: horizon.content.<function> · C++: HE::api::content::<function>

Loading assets ahead of time. Everything a scene uses is loaded with it, so these calls are for what a scene does not name yet: the level behind a door, a mesh a script will spawn. An asset is named by its path inside the project's Content folder, as the Content Browser shows it, for example Meshes/Crate.hasset. load reads the file right away, in the calling frame, so call it before the moment the asset is needed.

load on an asset that is already in memory returns true without reading it again. A path that does not exist returns false and logs where it looked. unload returns false the second time. typeName answers only for a loaded asset, with names like StaticMesh, Texture or Material, and an empty string otherwise.

World and storage · 17 functions

Save

Lua / Python: horizon.save.<function> · C++: HE::api::save::<function>

Savegames with a fixed shape. A save follows a SaveGame Template asset, which lists its fields and their defaults; the project's default template (Project Settings) is the one create uses. One save is active at a time and every field call works on it, in memory, until write puts it on disk as Saves/<id>.json in the game's data folder (see File System). write replaces the file in one step, so a crash leaves the old save or the new one, never half of each.

• A save id may only contain A–Z a–z 0–9 _ -; anything else (a space, a dot) fails with a warning.
• Each getter takes a default and returns it when there is no active save, the template has no such field, or the field has another type; the matching setter returns false. All three cases log a warning.
• Numbers: a Float, Int or Enum field goes through setNumber / getNumber. An Int field drops the fraction toward zero (2.7 → 2, −2.7 → −2). A Float field keeps about seven digits: 0.1 comes back as 0.10000000149011612.
• A struct field takes a value built with horizon.structs.<Name>() or read with getStruct (see Project Types). A plain table without __type is refused.
• A save remembers its template, and load uses that one, not the project default. It keeps the fields the template still has and fills new ones with their defaults, so a save from an older version of the game still loads.
• delete removes the file only. If it was the active save, it stays active, and the next write creates the file again; call close as well.

Example: save.write

local M = {}
local SLOT = "slot1"

-- "level" (Int) and "stats" (a struct with "kills") are fields of the
-- project's SaveGame Template.
function M.onStart(self)
    -- Continue from the save if there is one, else start a new one.
    if not (horizon.save.exists(SLOT) and horizon.save.load(SLOT)) then
        horizon.save.create(SLOT)
    end
    horizon.log(string.format("Level %d", horizon.save.getNumber("level", 1)))
end

-- This entity is the checkpoint's trigger volume.
function M.onBeginOverlap(self, other)
    horizon.save.setNumber("level", horizon.save.getNumber("level", 1) + 1)
    local stats = horizon.save.getStruct("stats")   -- keeps __type
    stats.kills = stats.kills + 1
    horizon.save.setStruct("stats", stats)
    horizon.save.write()   -- nothing is on disk before this
end

return M

import horizon

SLOT = "slot1"

class Checkpoint(horizon.Behavior):
    # "level" (Int) and "stats" (a struct with "kills") are fields of the
    # project's SaveGame Template.
    def on_start(self):
        # Continue from the save if there is one, else start a new one.
        if not (horizon.save.exists(SLOT) and horizon.save.load(SLOT)):
            horizon.save.create(SLOT)
        horizon.log(f"Level {horizon.save.getNumber('level', 1):.0f}")

    # This entity is the checkpoint's trigger volume.
    def on_begin_overlap(self, other):
        horizon.save.setNumber("level", horizon.save.getNumber("level", 1) + 1)
        stats = horizon.save.getStruct("stats")   # keeps __type
        stats["kills"] += 1
        horizon.save.setStruct("stats", stats)
        horizon.save.write()   # nothing is on disk before this

World and storage · 13 functions

File System

Lua / Python: horizon.fs.<function> · C++: HE::api::fs::<function>

Relative paths point into the game's own data folder, the sandbox; .. cannot leave it. An absolute path works only for a file or folder the user picked in a file dialog, or when the project allows Files outside the project. Anything else fails with the call's “failed” value and a log line that names the path.

Where the sandbox is: in the editor, the Saved folder next to the project file. In the exported game, a per-user folder named after the project, HorizonCreations/<Project>/Saved under %APPDATA% on Windows, ~/Library/Application Support on macOS and ~/.local/share on Linux. Savegames (Saves/) and Preferences (Prefs.json) live there too, so fs.* can see and delete them.

• writeText creates missing folders on the way. readText returns an empty string for a missing file.
• copy never overwrites: it returns false when the target exists. rename does overwrite an existing file at the target, without asking.
• remove deletes files only, never a folder. makeDir returns true when the folder already exists.
• An empty path means the top of the sandbox for list and watch, and is refused everywhere else.
• size and modified return -1 for anything that is not there, and size also for a folder. Both pass through a 32-bit float: sizes are exact up to 16 MB, and modified is up to 64 seconds off, the same issue as Date and Time. It can even lie a little in the future.

World and storage · 9 functions

Preferences

Lua / Python: horizon.prefs.<function> · C++: HE::api::prefs::<function>

Small settings that outlive the game: volume, the last folder, “don't show this again”. Each value sits under a key of your choosing in Prefs.json in the game's data folder (see File System), shared by every script and graph of the game. Every set and remove writes the file at once. Progress belongs in a save instead.

• A getter returns its fallback when the key was never set or holds another type: getBool on a number gives the fallback, not true. has tells a missing key from one that is set to the default value.
• Numbers are stored with about seven significant digits: setNumber("volume", 0.1) writes 0.10000000149011612, and whole numbers are exact only up to 16 777 216. Keep ids and large counts as strings.

Example: prefs.getBool

local M = {}

function M.onStart(self)
    if not horizon.prefs.getBool("tutorial.skip", false) then
        horizon.log("Tutorial: press Space to jump")
    end
end

-- "SkipTutorial" is an input action, e.g. on the hint's close button.
function M.onInputPressed(self, name)
    if name == "SkipTutorial" then
        horizon.prefs.setBool("tutorial.skip", true)   -- on disk at once
    end
end

return M

import horizon

class TutorialHint(horizon.Behavior):
    def on_start(self):
        if not horizon.prefs.getBool("tutorial.skip", False):
            horizon.log("Tutorial: press Space to jump")

    # "SkipTutorial" is an input action, e.g. on the hint's close button.
    def on_input_pressed(self, name):
        if name == "SkipTutorial":
            horizon.prefs.setBool("tutorial.skip", True)   # on disk at once

Gameplay · 33 functions

Physics

Lua / Python: horizon.physics.<function> · C++: HE::api::physics::<function>

Queries against the physics world and pushes on its bodies. Without a running physics world (edit mode, a world with no bodies built) every query misses, every push returns false and every read is zero. Units are metres, seconds, newtons and kilograms; the one exception is spin, which is in radians per second.

• Hits from Lua/Python. raycast and the four casts return ten values: hit, entity, px, py, pz, nx, ny, nz, distance, layer. On a miss they are false and zeros. The flat horizon.raycast returns a table / dict (entity, x, y, z, nx, ny, nz, distance, no layer) or nil / None. The direction does not have to be normalised.
• A ray started inside a collider hits that collider at distance 0. A ray from a character's own position therefore finds the character. Start it outside the own capsule (a step ahead, see the example below) or give the character its own collision layer and leave that bit out of the mask.
• Shape casts report the centre, not the contact. For sphereCast, boxCast and capsuleCast, point is where the shape's centre stopped (a 0.25 m sphere dropped on a floor at y = 1 reports y = 1.25), which is what a camera boom or a placement check wants. The shape casts ignore trigger volumes; raycast and the overlaps see them.
• Layer masks are bitfields: bit N is collision layer N, 65535 (or -1) is every layer, 0 sees nothing. The layer names are in Project Settings under Collision Layers.
• World and local. Every point a query returns is in world space, and so are the positions of addForceAtPosition / addImpulseAtPosition. setPosition and setPositionAndReset take a local position, like horizon.setPosition: for a child entity the value is relative to its parent. Joint anchors are local to their own entity.
• Forces (addForce, addImpulse, addTorque, the two …AtPosition) need a Dynamic rigid body and return false with a log line on a static or kinematic one, so also on a character. A character moves through Locomotion.
• setVelocity addresses the character controller when there is one, otherwise the rigid body. On a character with a Movement component the next frame overwrites the horizontal part with whatever locomotion.move asked for (nothing = standing still), so use setVelocity on characters only without one.
• setGravity changes gravity for rigid bodies in the whole world. A character falls by its own Character Controller gravity and does not follow it.

Joints tie two rigid bodies together; the entity passed first owns the joint, and only it reports hasJoint. A type outside 0–4 becomes Fixed. setJointMotor works on a Hinge or Slider only and returns false otherwise. A joint made at runtime is written to the owner's Joint component, the same component the editor places, and removeJoint or a break removes it again.

Example: physics.raycast

local M = {}
local REACH = 2.0   -- metres in front of the character
local PUSH  = 4.0   -- impulse, newton-seconds

-- "Interact" is a button action. Pushes whatever dynamic body is in front.
function M.onInputPressed(self, name)
    if name ~= "Interact" then return end
    local e = self.entityId
    local x, y, z = horizon.getPosition(e)
    local _, yaw = horizon.getRotation(e)
    local r = horizon.math.radians(yaw)
    local fx, fz = -horizon.math.sin(r), -horizon.math.cos(r)   -- facing, -Z at yaw 0
    -- Start a step ahead: a ray from inside the own capsule would hit it.
    local ox, oz = x + fx * 0.75, z + fz * 0.75
    local hit, other, px, py, pz = horizon.physics.raycast(ox, y, oz, fx, 0, fz, REACH)
    if hit and horizon.physics.hasPhysics(other) then
        -- The hit point is world space, which is what AtPosition expects.
        horizon.physics.addImpulseAtPosition(other, fx * PUSH, 0, fz * PUSH, px, py, pz)
    end
end

return M

import horizon

REACH = 2.0   # metres in front of the character
PUSH = 4.0    # impulse, newton-seconds

class PushCrate(horizon.Behavior):
    # "Interact" is a button action. Pushes whatever dynamic body is in front.
    def on_input_pressed(self, name):
        if name != "Interact":
            return
        e = self.entity_id
        x, y, z = horizon.getPosition(e)
        _, yaw, _ = horizon.getRotation(e)
        r = horizon.math.radians(yaw)
        fx, fz = -horizon.math.sin(r), -horizon.math.cos(r)   # facing, -Z at yaw 0
        # Start a step ahead: a ray from inside the own capsule would hit it.
        ox, oz = x + fx * 0.75, z + fz * 0.75
        hit, other, px, py, pz, *_ = horizon.physics.raycast(ox, y, oz, fx, 0, fz, REACH)
        if hit and horizon.physics.hasPhysics(other):
            # The hit point is world space, which is what AtPosition expects.
            horizon.physics.addImpulseAtPosition(other, fx * PUSH, 0, fz * PUSH, px, py, pz)

Example: physics.setPositionAndReset

local M = {}
local FLOOR = -20   -- below this height the character has fallen out

function M.onStart(self)
    self.sx, self.sy, self.sz = horizon.getPosition(self.entityId)
end

function M.onUpdate(self, dt)
    local _, y = horizon.getPosition(self.entityId)
    if y < FLOOR then
        -- Back to where the level started it, without the speed of the fall.
        horizon.physics.setPositionAndReset(self.entityId, self.sx, self.sy, self.sz)
    end
end

return M

import horizon

FLOOR = -20   # below this height the character has fallen out

class KillPlane(horizon.Behavior):
    def on_start(self):
        self.spawn = horizon.getPosition(self.entity_id)

    def on_update(self, dt):
        _, y, _ = horizon.getPosition(self.entity_id)
        if y < FLOOR:
            # Back to where the level started it, without the speed of the fall.
            horizon.physics.setPositionAndReset(self.entity_id, *self.spawn)

Gameplay · 6 functions

Navigation

Lua / Python: horizon.nav.<function> · C++: HE::api::nav::<function>

Sends an entity with a Nav Agent component across the scene's baked NavMesh. The agent walks by itself once moveTo has started it; if it has a Character Controller it is steered through it, so it collides and falls like the player. Every call on an entity without a Nav Agent does nothing, returns false / -1 and logs has no NavAgentComponent.

• Destinations are world positions, also for a parented agent, and they have to lie on the walkable surface: a point beside the mesh or a few metres above it is refused. For a target that moves, call moveTo again; each call plans a new route from where the agent stands.
• moveTo plans the route inside the call, so its false is final: no NavMesh, destination off it, or no connection. A refused call also stops an agent that was already walking, and the log line says which of the reasons it was.
• After arrival isMoving and hasPath are false and remainingDistance is -1, the same as after stop or a refusal. It never reads 0, so test "arrived" with isMoving. The agent stops within the Nav Agent's Stopping Distance of the target.
• setSpeed is the agent's own speed (default 3.5 m/s), not the Movement component's Max Speed. A negative value becomes 0, and an agent at speed 0 stands still while isMoving stays true.

Example: nav.moveTo

local M = {}

-- On an entity with a Nav Agent. World positions on the baked NavMesh.
local POINTS = { {6, 0, -6}, {6, 0, 6}, {-6, 0, 6} }

local function goNext(self)
    self.i = self.i % #POINTS + 1
    local p = POINTS[self.i]
    if not horizon.nav.moveTo(self.entityId, p[1], p[2], p[3]) then
        horizon.log("patrol point " .. self.i .. " is not reachable")
    end
end

function M.onStart(self)
    self.i = 0
    goNext(self)
end

function M.onUpdate(self, dt)
    -- isMoving turns false on arrival (and after a refusal).
    if not horizon.nav.isMoving(self.entityId) then goNext(self) end
end

return M

import horizon

# On an entity with a Nav Agent. World positions on the baked NavMesh.
POINTS = [(6, 0, -6), (6, 0, 6), (-6, 0, 6)]

class Patrol(horizon.Behavior):
    def on_start(self):
        self.i = -1
        self.go_next()

    def go_next(self):
        self.i = (self.i + 1) % len(POINTS)
        if not horizon.nav.moveTo(self.entity_id, *POINTS[self.i]):
            horizon.log(f"patrol point {self.i} is not reachable")

    def on_update(self, dt):
        # isMoving turns false on arrival (and after a refusal).
        if not horizon.nav.isMoving(self.entity_id):
            self.go_next()

Gameplay · 6 functions

Movement

Lua / Python: horizon.movement.<function> · C++: HE::api::movement::<function>

What a character is doing right now, read from its Character Controller. Queries only; to make a character move use Locomotion. An entity without a Character Controller reads 0 and false, without a log line.

• All speeds are metres per second. speed is horizontal only (falling is not running), verticalSpeed is positive while rising.
• forwardAmount and rightAmount are the same horizontal velocity split along the character's facing, also in metres per second, not a fraction: a character strafing right at 5 m/s reads rightAmount 5. Divide by speed for −1…1, and guard against a speed of 0. Forward is the entity's −Z axis turned by its yaw.
• isGrounded is the same answer as physics.isGrounded and the flat horizon.isGrounded, and the one locomotion.jump checks.

Gameplay · 6 functions

Locomotion

Lua / Python: horizon.locomotion.<function> · C++: HE::api::locomotion::<function>

Tells a character what to do this frame. move, look, setMaxSpeed and setOrientToMovement write the entity's Movement component and do nothing, silently, on an entity without one; the jumps need a Character Controller and log when there is none. A Player Character gets both components automatically. The Movement system turns the request into velocity once per frame before physics steps.

• move is an intent for one frame: call it every frame the character should walk. Two calls in the same frame add up, and the sum is cut back to length 1, so move(e, 1, 0, 0) twice still walks at the top speed, not twice it. Length 0.5 walks at half speed.
• The direction is read as the Movement component's Move Direction Is setting says: World (the default) takes it as it is, Camera (the default for a Player Character) turns it by the main camera rig's heading, so (0, 0, -1) is "away from the camera". With an input action from the WASD preset, forward is move(e, x, 0, -y).
• The Y component is dropped, but only after the length is cut to 1: move(e, 0.5, 3, 0) walks at 0.16 of the top speed. Pass 0 for Y.
• look adds its yaw to the character's rotation; several calls in a frame add up. The pitch is accepted and ignored, nothing reads it (build 7d49d44f). Tilt the view through the camera rig with camera.addYawPitch.
• setOrientToMovement(e, true) turns the character towards its travel direction at the component's turn rate (720°/s by default). Leave it off while look or a camera rig owns the facing, or the two fight each other.
• jump uses the Character Controller's Jump Speed, jumpWith a speed of its own. Both return true only when the character left the ground; a second call in the same frame, a call in mid-air or a speed of 0 or less returns false. A jump within 0.12 s of walking off a ledge is still granted.

Example: locomotion.move

local M = {}

-- On a Player Character. "Move" is an Axis2D input action (the WASD
-- preset: W is +y), "Sprint" and "Jump" are button actions.
function M.onUpdate(self, dt)
    local e = self.entityId
    local x, y = horizon.input.actionAxis2D("Move")
    -- Forward is -Z. With "Move Direction Is: Camera" (the Player Character
    -- default) that is away from the camera.
    horizon.locomotion.move(e, x, 0, -y)
    horizon.locomotion.setMaxSpeed(e, horizon.input.actionDown("Sprint") and 8 or 5)
end

function M.onInputPressed(self, name)
    if name == "Jump" and horizon.locomotion.jump(self.entityId) then
        horizon.log("jump")
    end
end

return M

import horizon

class PlayerMove(horizon.Behavior):
    # On a Player Character. "Move" is an Axis2D input action (the WASD
    # preset: W is +y), "Sprint" and "Jump" are button actions.
    def on_update(self, dt):
        e = self.entity_id
        x, y = horizon.input.actionAxis2D("Move")
        # Forward is -Z. With "Move Direction Is: Camera" (the Player Character
        # default) that is away from the camera.
        horizon.locomotion.move(e, x, 0, -y)
        horizon.locomotion.setMaxSpeed(e, 8 if horizon.input.actionDown("Sprint") else 5)

    def on_input_pressed(self, name):
        if name == "Jump" and horizon.locomotion.jump(self.entity_id):
            horizon.log("jump")

Gameplay · 6 functions

Player

Lua / Python: horizon.player.<function> · C++: HE::api::player::<function>

Which player controller drives which character. The references here are HorizonCode object references, not entity ids: a controller is an instance of a PlayerController class, a character an instance of a PlayerCharacter class. In Lua and Python they are plain integers, 0 meaning "none". To get from one to an entity use horizon.entity.owned(ref), the other way horizon.entity.instance(e).

• controller() is the session's first controller, 0 in a project without a PlayerController class; character() is what it possesses. Both are 0 outside a play session.
• A controller drives one character and a character has one controller: possess releases the controller's previous character and takes the new one away from any other controller. possess(0, …) does nothing.
• The table only records numbers and checks none of them, so a wrong reference is stored as it is. Pass what controller() and entity.instance return.

A Lua or Python script is not a controller, so possession does not decide which script hears input: input actions reach every script (see Callbacks). What possession changes is which HorizonCode character graph receives the controller's input events, and which character the camera rig follows.

Gameplay · 17 functions

Input

Lua / Python: horizon.input.<function> · C++: HE::api::input::<function>

Polling the keyboard, mouse, gamepad and the project's input actions. The engine takes one snapshot per frame, so every query gives the same answer for the rest of that frame. Only a running game or play mode fills it; in the editor outside play the values are stale. For one-shot reactions prefer the action callbacks (onInputPressed and friends) over polling.

• Key names are SDL scancode names and case-sensitive: "W", "Space", "Left Shift", "Return", "Escape", "Up". keyDown("w") is always false.
• Mouse buttons: 0 left, 1 right, 2 middle. mousePosition and mouseDelta return two numbers in Lua and a tuple (x, y) in Python.
• Gamepad names are SDL's, not case-sensitive: buttons "a", "b", "x", "y", "leftshoulder", "dpup", "start"; axes "leftx", "lefty", "rightx", "righty", "lefttrigger", "righttrigger". "south" and "cross" are not names and read false. Sticks go −1…1 with Y positive downwards, triggers 0…1, and the deadzone is already applied.
• Actions are looked up by the InputAction asset's name, case-sensitive; an unknown name reads false / 0. onUpdate runs before the actions are updated, so a poll from there sees the previous frame's state; actionPressed is still true for exactly one frame per press. The callbacks always carry the current frame. While the game is paused or the input mode is UI only, an action reads as released unless its asset has Fires while the game is paused ticked.

Input modes decide who receives input. The default is GameAndUI: both do, and a click on a widget is masked out of the game. GameOnly leaves the UI drawn but deaf. UIOnly gives the UI everything: the game then reads no keys, no mouse buttons and no gamepad (it reports disconnected), only mousePosition stays true. The mode does not show or hide the cursor; do that with the flat horizon.showCursor / hideCursor. Play mode starts in GameAndUI.

Example: input.setModeGameAndUI

local M = {}

-- "Inventory" is a button action. While the inventory is open the cursor is
-- visible and clicks go to the UI; the game still reads the keys.
function M.onInputPressed(self, name)
    if name ~= "Inventory" then return end
    self.open = not self.open
    if self.open then
        horizon.input.setModeGameAndUI()
        horizon.showCursor()
    else
        horizon.input.setModeGameOnly()
        horizon.hideCursor()
    end
end

return M

import horizon

class Inventory(horizon.Behavior):
    open = False

    # "Inventory" is a button action. While the inventory is open the cursor
    # is visible and clicks go to the UI; the game still reads the keys.
    def on_input_pressed(self, name):
        if name != "Inventory":
            return
        self.open = not self.open
        if self.open:
            horizon.input.setModeGameAndUI()
            horizon.showCursor()
        else:
            horizon.input.setModeGameOnly()
            horizon.hideCursor()

Presentation · 8 functions

Animator

Lua / Python: horizon.animator.<function> · C++: HE::api::animator::<function>

Steering a character's animation from gameplay: the parameters its animator state machine tests, and the weights of its animation layers. Parameters live on the entity's Animator State Machine component, layers on its Animation Layers component; without the component the setters do nothing and the getters answer 0 or an empty string.

• Parameters are numbers. setParam takes a float. A yes/no parameter is 1 or 0: in Lua setParam(e, "Grounded", true) is an error (number expected, got boolean), Python turns True into 1. A name the state machine asset never declared is created, not rejected, so a typo writes a parameter nothing reads. getParam answers 0 for a name that was never set.
• Layers are found by name, first match. Two layers may share a name; every function then acts on the first of them. setLayerWeight clamps to 0 to 1. playLayer restarts that layer's own playhead and leaves its weight alone.
• notifiesOf and layerNames return lists, which scripts cannot receive yet: from Lua and Python they answer an empty string (see List results). Notifies themselves reach a script as the onAnimationNotify callbacks. notifiesOf loads the clip if it is not in memory.

Example: animator.setParam

local M = {}

-- On a character with Movement and an Animator State Machine whose
-- transitions test "Speed" (m/s) and "Grounded" (1 or 0).
function M.onUpdate(self, dt)
    local e = self.entityId
    horizon.animator.setParam(e, "Speed", horizon.movement.speed(e))
    -- Parameters are numbers: a boolean has to become 1 or 0.
    horizon.animator.setParam(e, "Grounded", horizon.movement.isGrounded(e) and 1 or 0)
end

return M

import horizon

class AnimSpeed(horizon.Behavior):
    # On a character with Movement and an Animator State Machine whose
    # transitions test "Speed" (m/s) and "Grounded" (1 or 0).
    def on_update(self, dt):
        e = self.entity_id
        horizon.animator.setParam(e, "Speed", horizon.movement.speed(e))
        # Parameters are numbers: a boolean has to become 1 or 0.
        horizon.animator.setParam(e, "Grounded", 1 if horizon.movement.isGrounded(e) else 0)

Presentation · 4 functions

Particles

Lua / Python: horizon.particle.<function> · C++: HE::api::particle::<function>

Firing and stopping the Particle System component on an entity. An emitter plays on its own from the start (its Playing box is ticked by default); these functions are for effects that have to happen at a moment. Calling play, stop or burst on an entity without a Particle System writes a warning to the log (at most every five seconds) and does nothing; isPlaying answers false without a warning, because asking is how a script finds out.

• One-shots. An emitter whose graph does not loop emits its Max Particles once and finishes. play restarts it from the beginning, however often. isPlaying stays true until the last particle has died, not only until the emitting ends.
• stop is soft. It stops the emitting and lets the particles that are out live their lifetime, so isPlaying is still true right after it and turns false when the last one dies.
• burst(e, count) emits at the emitter's current world position and returns how many it actually made: never more than Max Particles alive at once (with 10 alive and a cap of 30, a burst of 500 makes 20), and 0 for a count of 0 or below. A burst also restarts a stopped or finished emitter.

Example: particle.burst

local M = {}

-- On a crate with a Particle System whose graph does not loop (sparks):
-- every hit fires a handful of sparks and gives the camera a short jolt.
function M.onCollisionEnter(self, other)
    local made = horizon.particle.burst(self.entityId, 24)
    if made > 0 then
        -- 5 cm, 0.5 degrees, 18 shakes per second, a quarter of a second.
        horizon.camera.playShake(0.05, 0.5, 18, 0.25)
    end
end

return M

import horizon

class Impact(horizon.Behavior):
    # On a crate with a Particle System whose graph does not loop (sparks):
    # every hit fires a handful of sparks and gives the camera a short jolt.
    def on_collision_enter(self, other):
        made = horizon.particle.burst(self.entity_id, 24)
        if made > 0:
            # 5 cm, 0.5 degrees, 18 shakes per second, a quarter of a second.
            horizon.camera.playShake(0.05, 0.5, 18, 0.25)

Presentation · 18 functions

Audio

Lua / Python: horizon.audio.<function> · C++: HE::api::audio::<function>

Sounds by asset path, controlled afterwards through the handle play or playAt returns. Handles are whole numbers counting up from 1; 0 means nothing was started: the asset path did not load, or there is no audio engine. The audio engine belongs to a play session, so outside one (the editor while not playing, a tool script) every function here does nothing and the queries answer 0, false, or 1 for the pitch.

• Every argument is required. play(asset, volume, pitch, loop) has no defaults in Python (a missing loop is an IndexError); in Lua a missing loop is read as false. playAt takes the position as three numbers: playAt(asset, x, y, z, volume, pitch, loop, minDist, maxDist).
• Stop what you start. A sound that finishes on its own is no longer playing, but the engine keeps it, with its own copy of the clip, until it is stopped: its handle still answers its volume and pitch, and fifty finished one-shots are fifty held voices (build 7d49d44f). For sounds fired again and again (footsteps, shots) call stop on the previous handle before playing the next, or stopAll at a natural break. A scene change stops everything.
• Transport. isPlaying is false both for a paused and for a finished sound; isPaused tells them apart. seek clamps to the clip (5 s into a 1 s clip lands at 1 s, −2 at 0) and works while paused; getTime stands still while paused.
• Values are not clamped, with one exception: a volume above 1 amplifies and a negative one is stored as it is, while a pitch of 0 or below is ignored and the old pitch stays.
• Spatial sounds are heard from the scene's Audio Listener (the first one). Without a listener the ears stay at the world origin. setSoundPosition only matters for a sound started with playAt.
• setBusVolume creates a bus that does not exist yet, so a misspelled bus name silently becomes a new, empty bus.

Example: audio.playAt

local M = {}
local STEP = "Audio/footstep.hasset"

-- The walk clip carries "FootL" and "FootR" notifies on its timeline.
function M.onAnimationNotify(self, name)
    if name ~= "FootL" and name ~= "FootR" then return end
    -- A finished sound is held until it is stopped, so free the last step.
    if self.step then horizon.audio.stop(self.step) end
    local x, y, z = horizon.getPosition(self.entityId)
    local pitch = horizon.random.range(0.9, 1.1)   -- no two steps alike
    self.step = horizon.audio.playAt(STEP, x, y, z, 0.7, pitch, false, 1, 25)
end

return M

import horizon

STEP = "Audio/footstep.hasset"

class Footsteps(horizon.Behavior):
    step = 0

    # The walk clip carries "FootL" and "FootR" notifies on its timeline.
    def on_animation_notify(self, name):
        if name not in ("FootL", "FootR"):
            return
        # A finished sound is held until it is stopped, so free the last step.
        if self.step:
            horizon.audio.stop(self.step)
        x, y, z = horizon.getPosition(self.entity_id)
        pitch = horizon.random.range(0.9, 1.1)   # no two steps alike
        self.step = horizon.audio.playAt(STEP, x, y, z, 0.7, pitch, False, 1, 25)

Example: audio.setVolume

local M = {}
local MUSIC = "Audio/theme.hasset"
local VOLUME, FADE = 0.6, 2.0   -- fade length in seconds

function M.onStart(self)
    self.music = horizon.audio.play(MUSIC, VOLUME, 1, true)
    self.left = 0
end

-- "EndLevel" is a button action.
function M.onInputPressed(self, name)
    if name == "EndLevel" and self.music ~= 0 then self.left = FADE end
end

function M.onUpdate(self, dt)
    if self.left <= 0 then return end
    self.left = self.left - dt
    if self.left <= 0 then
        horizon.audio.stop(self.music)   -- stop, not volume 0: frees the voice
        self.music = 0
    else
        horizon.audio.setVolume(self.music, VOLUME * self.left / FADE)
    end
end

return M

import horizon

MUSIC = "Audio/theme.hasset"
VOLUME, FADE = 0.6, 2.0   # fade length in seconds

class MusicFade(horizon.Behavior):
    def on_start(self):
        self.music = horizon.audio.play(MUSIC, VOLUME, 1, True)
        self.left = 0.0

    # "EndLevel" is a button action.
    def on_input_pressed(self, name):
        if name == "EndLevel" and self.music != 0:
            self.left = FADE

    def on_update(self, dt):
        if self.left <= 0:
            return
        self.left -= dt
        if self.left <= 0:
            horizon.audio.stop(self.music)   # stop, not volume 0: frees the voice
            self.music = 0
        else:
            horizon.audio.setVolume(self.music, VOLUME * self.left / FADE)

Presentation · 26 functions

Camera

Lua / Python: horizon.camera.<function> · C++: HE::api::camera::<function>

The camera the picture comes from, and the camera rig that moves it. No function here takes an entity: they all act on the active camera, the one marked Main, or the first camera in the scene when none is. The rig functions act on that camera's Camera Rig component; without one they do nothing and read 0.

• Position and rotation are the camera's own transform. getPosition and getRotation read it and the setters write it, relative to the camera's parent. A camera parented under an entity at (10, 0, 0) and sitting 5 m behind it reads 0, 2, 5, not 10, 2, 5. For a camera at the top of the hierarchy that is the world position. While a rig drives the camera it rewrites the transform every frame, so setPosition/setRotation last until the next frame; setFov stays.
• Rig numbers are forgiving, not checked. setRigMode treats anything but 0 as third person. setTargetYawMode treats anything but 0 and 2 as Follow. addYawPitch clamps the pitch to the rig's limits (by default −80° to 75°) but lets the yaw run past 360. setLagSpeeds turns negative speeds into 0. setArmLength takes a negative length as it is, which puts the camera in front of the target.
• Shake moves the transform, the FOV kick does not. The rig writes the shaken pose into the camera's transform, so getPosition and getRotation jitter while a shake runs. A FOV kick is added on top of the field of view and getFov keeps answering the authored value. playShake returns 0 when there is no rig; handles start at 1.
• Blending. blendTo(camera, seconds, curve) makes that camera the main one at once (every other camera loses Main), so from the next call on the other functions act on it. The ease itself needs a Camera Rig on the camera blended to; without one it is a cut and isBlending stays false. Curves outside 0 to 2 become smoothstep.

Example: camera.kickFov

local M = {}

-- "Sprint" is a button action. The kick widens the view for a moment and
-- falls back by itself; getFov keeps answering the authored value.
function M.onInputPressed(self, name)
    if name == "Sprint" then
        horizon.camera.kickFov(8, 0.15, 0.6, 0.4)   -- degrees, attack, hold, decay
        horizon.camera.setLagEnabled(true)           -- the camera trails a little
    end
end

function M.onInputReleased(self, name)
    if name == "Sprint" then horizon.camera.setLagEnabled(false) end
end

return M

import horizon

class SprintFov(horizon.Behavior):
    # "Sprint" is a button action. The kick widens the view for a moment and
    # falls back by itself; getFov keeps answering the authored value.
    def on_input_pressed(self, name):
        if name == "Sprint":
            horizon.camera.kickFov(8, 0.15, 0.6, 0.4)   # degrees, attack, hold, decay
            horizon.camera.setLagEnabled(True)           # the camera trails a little

    def on_input_released(self, name):
        if name == "Sprint":
            horizon.camera.setLagEnabled(False)

Presentation · 2 functions

Material

The named parameters of a node-graph material, the ones its Param nodes declare, read and written at runtime. Every parameter holds four numbers whatever the shader reads, so a scalar parameter is its first number. From Lua and Python, horizon.setMaterialParam(e, name, x [, y, z, w]) fills missing numbers with 0 and returns false when the entity has no Material component or the material declares no such parameter; horizon.getMaterialParam returns four zeros then.

Presentation · 116 functions

Environment

Lua / Python: horizon.env.<function> · C++: HE::api::env::<function>

The sky, the day-night cycle and the weather look of the scene: every field of the Environment component on the Sky entity, which the Environment window adds. If a scene carries more than one Sky, these functions and the renderer both use the first. The table below is generated from the engine's own field list, so it always has every field there is.

• Colours take four numbers. A color field is set from Lua and Python with r, g, b, a: horizon.env.setSunColor(1, 0.8, 0.6, 1). The fourth number is ignored, but it has to be there: with three, Lua raises bad argument #4 and Python IndexError. The getters return four numbers with alpha always 1. int fields need a whole number (1.7 is an error in both languages); bool fields accept true/false or, in Python, 1/0.
• Nothing is clamped. A setter stores exactly what it is given: a time of day of 1.7, a negative fog density or a cloud quality of 9 read back unchanged. Stay inside the ranges the descriptions give. Time of day is wrapped into 0 to 1 only when Auto Advance moves it on.
• Time of day needs the cycle switched on. setTimeOfDay only moves the sun while DayNightCycle is true; the Details panel switches that on for you when you drag the slider, a script does not. For a clock that runs by itself set AutoAdvance as well: with a CycleSeconds of 10, one second moves the time by 0.1, and with MoonPhaseAuto the moon phase moves one cycle per MoonCycleDays days.
• Weather. A Weather component writes six of these fields (cloud coverage, fog density, wind speed, rain, snow, wetness) toward its preset, blending over its transition time. It backs off a field as soon as its value differs from the last value Weather wrote, so a value a script sets stays until a new preset is selected, which takes all six back. The lightning Flash is rewritten every tick. Every other field is never touched by Weather.
• No Sky entity (removed in the Environment window): every getter answers 0, false or black, and every setter does nothing. A time of day of 0 then does not mean midnight.

Example: env.setTimeOfDay

local M = {}

-- "Sleep" is a button action: skip to the next morning.
function M.onInputPressed(self, name)
    if name ~= "Sleep" then return end
    horizon.env.setDayNightCycle(true)   -- without it the sun ignores the clock
    horizon.env.setTimeOfDay(0.3)        -- a little after sunrise
    -- Colours are four numbers; the fourth is ignored but required.
    horizon.env.setSunColor(1.0, 0.85, 0.7, 1)
    -- Weather lets go of a field a script changed, until the next preset.
    horizon.env.setFogDensity(0.02)
end

return M

import horizon

class Sleep(horizon.Behavior):
    # "Sleep" is a button action: skip to the next morning.
    def on_input_pressed(self, name):
        if name != "Sleep":
            return
        horizon.env.setDayNightCycle(True)   # without it the sun ignores the clock
        horizon.env.setTimeOfDay(0.3)        # a little after sunrise
        # Colours are four numbers; the fourth is ignored but required.
        horizon.env.setSunColor(1.0, 0.85, 0.7, 1)
        # Weather lets go of a field a script changed, until the next preset.
        horizon.env.setFogDensity(0.02)

All 58 fields as one table, 116 functions: for a field Name, horizon.env.getName() reads it and horizon.env.setName(value) writes it; in HorizonCode they are Get … and Set … nodes, in C++ HE::api::env::getName(ctx) / setName(ctx, value). Setters are actions, getters queries. Each field is the value of the same name on the Sky entity's Environment component, which its Details panel shows. The Weather column says what a Weather component in the scene does to the field.

Interface and app · 12 functions

UI Elements

Lua / Python: horizon.ui.<function> · C++: HE::api::ui::<function>

These rows work on entities that carry UI components: an element on a UI canvas in the scene, addressed by its entity id like any other entity. Widgets built in the Widget Designer are a different thing with their own ids, see Widget. From a script, pass the id: the element the script sits on is self.entityId (Python self.entity_id), another one is found once with horizon.entity.findByName.

• Which component answers. The text rows need a UI Text component: setText on anything else does nothing and getText answers "". The colour is the Image tint, else the Text colour, else a Button's normal colour, in that order. An element with none of the three ignores setColor and reads as white (1, 1, 1, 1). Visibility, position and size belong to every element; an entity without UI answers false and 0, 0.
• A colour is four numbers and a position or size two: setColor(e, 1, 0.5, 0, 1), setPosition(e, x, y). With three colour numbers Lua throws bad argument #5 and Python an IndexError. A missing visible reads as false in Lua, so the element disappears; Python throws.
• Nothing is clamped or checked: a negative size is stored as it is.
• pointerOverUI asks the widget layer: it is true while the pointer is over a widget, and while a widget dialog (widget.showModal) is open, wherever the pointer is. UI elements on a scene canvas do not count.

Example: ui.setText

local M = {}
local LIMIT = 90   -- seconds for the level

-- This script sits on the HUD's UI Text entity.
function M.onStart(self)
    self.left = LIMIT
end

function M.onUpdate(self, dt)
    if self.left <= 0 then return end
    self.left = math.max(0, self.left - dt)
    local e = self.entityId
    horizon.ui.setText(e, string.format("%d:%02d", self.left // 60, math.floor(self.left) % 60))
    if self.left < 10 then
        horizon.ui.setColor(e, 1, 0.25, 0.2, 1)   -- a colour is four numbers
    end
    if self.left == 0 then
        horizon.ui.setVisible(e, false)
    end
end

return M

import horizon

LIMIT = 90  # seconds for the level

# This script sits on the HUD's UI Text entity.
class LevelClock(horizon.Behavior):
    def on_start(self):
        self.left = LIMIT

    def on_update(self, dt):
        if self.left <= 0:
            return
        self.left = max(0.0, self.left - dt)
        e = self.entity_id
        horizon.ui.setText(e, "%d:%02d" % (self.left // 60, int(self.left) % 60))
        if self.left < 10:
            horizon.ui.setColor(e, 1, 0.25, 0.2, 1)   # a colour is four numbers
        if self.left == 0:
            horizon.ui.setVisible(e, False)

Interface and app · 28 functions

Widget

Lua / Python: horizon.widget.<function> · C++: HE::api::widget::<function>

Live instances of Widget Designer assets. A widget is addressed by the id that horizon.createWidget(path) returns (0 when the asset does not load); showing, hiding and destroying it are the flat showWidget, hideWidget and destroyWidget. A new widget starts hidden until showWidget (or showModal, openPopup, window.show) puts it on screen. Widgets live outside the entity world, so a widget id is not an entity id, and in an exported game a script and a HorizonCode graph share the same widgets.

• Always pass the widget. Several descriptions say “leave Widget unwired” for the calling widget's own. That is a HorizonCode graph living in the widget; a script has no widget of its own, and 0 answers false or 0.
• Scripts receive none of the widget events. On Row Bind, On Selection Changed, On Dismissed, On Right Clicked, On Animation Finished and On Clip Finished go to the widget's own HorizonCode graph only. Neither are there Set External, Call External or Bind Event for scripts. In practice: a script can size, select and scroll a ListView, but its rows are filled by the row widget's own graph; a script notices a closed dialog by asking isVisible each frame (see the example under showModal).
• References are not widget ids. addChild, listRow and childRef return object references for those HorizonCode nodes; isVisible on one answers false. From a script a child reference is good for removeChild.
• Animation ok checks less than it seems. It is false for a missing widget or element, but a property name the element does not have is accepted and animates nothing, and an unknown easing name runs as "Linear". The easings are "Linear", "In Quad", "Out Quad", "In Out Quad", "In Cubic", "Out Cubic", "In Out Cubic" and "Out Back"; directions for the clip rows are "Forward", "Backward" and "Ping Pong" (anything else is Forward). Colours are four numbers, points two: animateColor(w, "Card", "Color", 1, 0, 0, 1, 0.5, "Linear").
• Lists are named by the element's name in the designer. A negative count becomes 0; an index at or past the count leaves the selection as it was, and still answers true. listRow is 0 for an item that is scrolled out of view.
• Closing is hiding. After closeTopLayer, Escape or Back, a dialog or popup widget answers isVisible false; show it again to reopen it.

Example: widget.showModal

local M = {}
local MENU = "UI/pause_menu.hasset"   -- a widget with an element called "Panel"

function M.onStart(self)
    self.menu = horizon.createWidget(MENU)   -- starts hidden; 0 if the asset is missing
end

function M.onInputPressed(self, name)
    if name ~= "Pause" or self.paused or self.menu == 0 then return end
    self.paused = true
    horizon.time.pause()
    horizon.showCursor()
    -- A dialog: dims the game, takes the input, closes on Escape or Back.
    horizon.widget.showModal(self.menu)
    horizon.widget.animate(self.menu, "Panel", "Render Opacity", 0, 0, "Linear")
    horizon.widget.animate(self.menu, "Panel", "Render Opacity", 1, 0.2, "Out Quad")
end

function M.onUpdate(self, dt)
    -- A script gets no On Dismissed: notice the close by asking.
    if self.paused and not horizon.widget.isVisible(self.menu) then
        self.paused = false
        horizon.time.resume()
        horizon.hideCursor()
    end
end

return M

import horizon

MENU = "UI/pause_menu.hasset"   # a widget with an element called "Panel"

class PauseMenu(horizon.Behavior):
    paused = False

    def on_start(self):
        self.menu = horizon.createWidget(MENU)   # starts hidden; 0 if the asset is missing

    def on_input_pressed(self, name):
        if name != "Pause" or self.paused or self.menu == 0:
            return
        self.paused = True
        horizon.time.pause()
        horizon.showCursor()
        # A dialog: dims the game, takes the input, closes on Escape or Back.
        horizon.widget.showModal(self.menu)
        horizon.widget.animate(self.menu, "Panel", "Render Opacity", 0, 0, "Linear")
        horizon.widget.animate(self.menu, "Panel", "Render Opacity", 1, 0.2, "Out Quad")

    def on_update(self, dt):
        # A script gets no On Dismissed: notice the close by asking.
        if self.paused and not horizon.widget.isVisible(self.menu):
            self.paused = False
            horizon.time.resume()
            horizon.hideCursor()

Interface and app · 1 function

Cursor

One row, and no horizon.cursor.* group: from a script use the flat horizon.showCursor() and horizon.hideCursor(). Hiding the cursor also captures the mouse for camera control, showing it releases the mouse. In the editor this applies to play mode only.

Interface and app · 6 functions

Theme

Lua / Python: horizon.theme.<function> · C++: HE::api::theme::<function>

The colours and text size of every widget. A Theme asset carries a light and a dark set of colour roles; set switches the asset, setMode picks between its two sets. Widgets that name their own theme in the designer keep it.

• Mode names are exact: "Light", "Dark" or "System". Anything else, including "dark", is ignored with a log line.
• Preference and mode are two answers. getPreference returns what was asked for, including "System"; getMode returns what is on screen, only ever Light or Dark. Store the preference, show the mode (see the example under setMode). Where the desktop reports nothing, System resolves to Dark.
• Font scale is clamped to 0.5 … 3: setFontScale(5) reads back 3, 0.1 reads back 0.5.
• set answers false for a path that does not load and for a Theme asset whose JSON cannot be read; the current theme stays.

Example: theme.setMode

local M = {}
-- Store the PREFERENCE, not the mode: System is a rule that follows the desktop.
local NEXT = { System = "Light", Light = "Dark", Dark = "System" }

function M.onStart(self)
    horizon.theme.setMode(horizon.prefs.getString("theme", "System"))
    horizon.theme.setFontScale(horizon.prefs.getNumber("textScale", 1))
end

function M.onInputPressed(self, name)
    if name == "CycleTheme" then
        local pref = NEXT[horizon.theme.getPreference()]
        horizon.theme.setMode(pref)
        horizon.prefs.setString("theme", pref)
        horizon.log("theme " .. pref .. ", showing " .. horizon.theme.getMode())
    elseif name == "BiggerText" or name == "SmallerText" then
        local step = name == "BiggerText" and 0.25 or -0.25
        horizon.theme.setFontScale(horizon.theme.getFontScale() + step)   -- kept in 0.5..3
        horizon.prefs.setNumber("textScale", horizon.theme.getFontScale())
    end
end

return M

import horizon

# Store the PREFERENCE, not the mode: System is a rule that follows the desktop.
NEXT = {"System": "Light", "Light": "Dark", "Dark": "System"}

class ThemeToggle(horizon.Behavior):
    def on_start(self):
        horizon.theme.setMode(horizon.prefs.getString("theme", "System"))
        horizon.theme.setFontScale(horizon.prefs.getNumber("textScale", 1))

    def on_input_pressed(self, name):
        if name == "CycleTheme":
            pref = NEXT[horizon.theme.getPreference()]
            horizon.theme.setMode(pref)
            horizon.prefs.setString("theme", pref)
            horizon.log("theme %s, showing %s" % (pref, horizon.theme.getMode()))
        elif name in ("BiggerText", "SmallerText"):
            step = 0.25 if name == "BiggerText" else -0.25
            horizon.theme.setFontScale(horizon.theme.getFontScale() + step)   # kept in 0.5..3
            horizon.prefs.setNumber("textScale", horizon.theme.getFontScale())

Interface and app · 5 functions

Window

Lua / Python: horizon.window.<function> · C++: HE::api::window::<function>

Second windows for a desktop application: a tool window beside the main one, a document per window. Window 0 is the main window; window.setTitle(0, …) and window.setSize(0, …) are app.setTitle and app.setSize, and close(0) is refused with a pointer to app.quit. Only an exported application has windows to give: in the editor open answers 0, and so it does on a renderer without a path into a second window (Software and Metal have one). A width or height of 0 or less opens at 640 × 480.

Interface and app · 5 functions

Dialog

Lua / Python: horizon.dialog.<function> · C++: HE::api::dialog::<function>

The operating system's own message boxes and file pickers. Every one of them blocks: the frame stops until the person answers, so a game keeps them for what really has to be read or chosen first. No permission is needed.

• Choosing is the permission for the fs rows: a path returned by openFile or saveFile, and everything inside a folder from pickFolder, may be read and written with an absolute path from then on, even when the project does not allow files outside the project. It does not open db.open or print.toPdf, see Database.
• An empty path means cancelled, and it is also the answer when the picker fails. A picker left open for five minutes is given up on and answers empty as well.
• message kind 1 is a warning, 2 an error, anything else information. confirm returns true for the first button; empty labels become "OK" and "Cancel", Return takes the first button and Escape the second.
• Hidden runs (HE_HIDDEN_WINDOW, headless exports and tests) show no box: message writes its text to the log and confirm answers false. The three pickers do not check for a hidden run, so keep them out of one.

Interface and app · 3 functions

Clipboard

Lua / Python: horizon.clipboard.<function> · C++: HE::api::clipboard::<function>

The system clipboard, shared with every other application. Text only, and no permission is needed. Reading an empty clipboard gives "", as does a clipboard holding something that is not text; hasText is the cheap check for greying out a Paste button. A process without a window (a headless tool) has no clipboard: setText fails with a log line and getText answers "".

Interface and app · 24 functions

App

Lua / Python: horizon.app.<function> · C++: HE::api::app::<function>

The application around the game: its window, menu bar, tray icon, notifications and login item. These rows exist for desktop applications built with the engine and need a host that provides each piece. The exported application provides all of them. Play mode in the editor provides only quit (it stops play mode), size and requestRedraw; everything else logs “no … bound by the host” and does nothing.

• Ids and labels. A menu, menu entry or tray entry without an id is refused with a log line; an empty label shows the id. Adding a menu id twice is one menu. A shortcut that does not parse is dropped with a log line and the entry arrives without it; "Ctrl" means Command on a Mac.
• Refused values. setSize with a side of 0 or less is ignored; notify with neither title nor text answers false. On macOS notify needs the packaged app.
• setAutostart needs the project permission Run other programs; reading autostart needs none.

Interface and app · 3 functions

Process

Lua / Python: horizon.process.<function> · C++: HE::api::process::<function>

Other programs on the machine. run and openUrl need the project permission Run other programs; which needs none, so a script can find out what is installed before anyone decides to allow it.

• run blocks the frame until the program ends or the timeout kills it; a timeout of 0 means 30 seconds. It returns four values, ok, exitCode, out, err: ok is true for exit code 0, out and err are the complete output. A program that could not be started gives exit code −1. Nothing goes through a shell.
• openUrl hands the address to the desktop (browser, mail client, file manager) and answers false for an empty one or when the desktop refuses it. which answers the full path, or "".

Example: process.openUrl

local M = {}
local MANUAL = "https://example.com/manual/"

function M.onInputPressed(self, name)
    if name ~= "Help" then return end
    -- openUrl needs "Run other programs". Without it, hand the address over.
    if horizon.process.openUrl(MANUAL) then return end
    horizon.clipboard.setText(MANUAL)
    horizon.dialog.message("Manual", "The manual's address is on your clipboard:\n" .. MANUAL, 0)
end

return M

import horizon

MANUAL = "https://example.com/manual/"

class OpenManual(horizon.Behavior):
    def on_input_pressed(self, name):
        if name != "Help":
            return
        # openUrl needs "Run other programs". Without it, hand the address over.
        if horizon.process.openUrl(MANUAL):
            return
        horizon.clipboard.setText(MANUAL)
        horizon.dialog.message("Manual", "The manual's address is on your clipboard:\n" + MANUAL, 0)

Interface and app · 3 functions

Print

Lua / Python: horizon.print.<function> · C++: HE::api::print::<function>

Paper and PDF. toPdf writes a plain page of text itself; file hands an existing file to the system's print queue.

• The PDF layout is fixed: A4, Courier 10 pt, 80 characters by 60 lines per page. Lines break at your newlines and at the last space that fits, pages when they are full. title becomes the document title in its properties. Characters of Latin-1 come through (ä, é); every other one, the euro sign included, prints as ?. Missing folders on the way to the path are created.
• toPdf always needs the permission Files outside the project, even for a relative path, which lands in the project's Saved folder like the fs rows. A path the user picked in a file dialog does not stand in for it (build 7d49d44f).
• file and available use the system's lp, on macOS and Linux. On Windows both answer false. file needs Run other programs and answers true once the queue took the file, which says nothing about paper; a missing file is false.

Interface and app · 7 functions

Database

Lua / Python: horizon.db.<function> · C++: HE::api::db::<function>

SQLite databases, as files. open returns a handle for the other rows, 0 when it failed; at most 16 are open at once, and all close when the application ends. The path follows the fs rules: relative lands in the project's Saved folder, .. is refused, an absolute path needs the permission. There is no in-memory database: ":memory:" is an ordinary file name.

• Values go behind ?, as a JSON array in params: '["Ada", 36.5]'. Strings, numbers, true/false (stored as 1/0) and null; a nested array or object is stored as its JSON text. Placeholders the array does not reach are NULL, and a params that is not an array is ignored. Python builds it with json.dumps. Lua has no JSON writer, and horizon.json.set* can overwrite array slots but not add them: start from a template such as '["", 0]' (see the example under query).
• exec runs one statement. Of "INSERT …; INSERT …" only the first runs, and the answer is still true. exec on a SELECT runs it and throws the rows away.
• query answers JSON text: an array with one object per row, keyed by column name. Integers come back as integers, REAL as floats (12.0), NULL and BLOB as null. An empty result and a failed query both give "[]"; lastError tells them apart. More than 10 000 rows are cut off, with a note in lastError.
• lastError is SQLite's own message and empty after a call that worked. On a handle that is not open, exec is false, query "[]" and lastError empty. lastInsertId reads back ids above 2 147 483 647 as 2 147 483 647.
• SQL cannot reach other files: ATTACH, VACUUM INTO and the pragmas that move SQLite's own files fail with “not authorized”.

Example: db.query

local M = {}
local PLAYER = "Player 1"

function M.onStart(self)
    -- Lands in the project's Saved folder, but needs the "Files outside the
    -- project" permission all the same (see the group notes).
    self.db = horizon.db.open("scores.db")
    if self.db ~= 0 then
        horizon.db.exec(self.db, "CREATE TABLE IF NOT EXISTS scores(name TEXT, points INTEGER)", "")
    end
end

function M.onInputPressed(self, name)
    if name ~= "LevelDone" or self.db == 0 then return end
    local points = math.max(0, 1000 - math.floor(horizon.time.elapsed() * 10))
    -- Values travel as a JSON array behind the ?s, never pasted into the SQL.
    -- json.set* can overwrite array slots but not add them, so start from two.
    local params = horizon.json.setNumber(horizon.json.setString('["", 0]', "[0]", PLAYER), "[1]", points)
    if not horizon.db.exec(self.db, "INSERT INTO scores(name, points) VALUES(?, ?)", params) then
        horizon.log("scores: " .. horizon.db.lastError(self.db))
        return
    end
    local rows = horizon.db.query(self.db,
        "SELECT name, points FROM scores ORDER BY points DESC LIMIT 5", "")
    for i = 0, horizon.json.count(rows, "") - 1 do
        horizon.log(string.format("%d. %s  %d", i + 1,
            horizon.json.getString(rows, "[" .. i .. "].name", "?"),
            horizon.json.getNumber(rows, "[" .. i .. "].points", 0)))
    end
end

return M

import horizon
import json

PLAYER = "Player 1"

class Highscores(horizon.Behavior):
    def on_start(self):
        # Lands in the project's Saved folder, but needs the "Files outside the
        # project" permission all the same (see the group notes).
        self.db = horizon.db.open("scores.db")
        if self.db:
            horizon.db.exec(self.db, "CREATE TABLE IF NOT EXISTS scores(name TEXT, points INTEGER)", "")

    def on_input_pressed(self, name):
        if name != "LevelDone" or not self.db:
            return
        points = max(0, 1000 - int(horizon.time.elapsed() * 10))
        # Values travel as a JSON array behind the ?s, never pasted into the SQL.
        if not horizon.db.exec(self.db, "INSERT INTO scores(name, points) VALUES(?, ?)",
                               json.dumps([PLAYER, points])):
            horizon.log("scores: " + horizon.db.lastError(self.db))
            return
        rows = json.loads(horizon.db.query(
            self.db, "SELECT name, points FROM scores ORDER BY points DESC LIMIT 5", ""))
        for i, row in enumerate(rows, 1):
            horizon.log("%d. %s  %d" % (i, row["name"], row["points"]))