Scripts

Scripts are compiled to bytecode and executed by the runtime.

They are currently event-driven. They can live in external files under scripts/ or be embedded directly inside rect and sprite scene nodes.

External example:

1on ready() {2    log("boot")3}

Inline scene example:

1rect Hero {2    on update(dt) {3        self.x = self.x + 10.0 * dt4    }5}

Event handlers

Current handlers are defined as:

1on ready() {2    log("boot")3}4​5on update(dt) {6    self.x = self.x + 10.0 * dt7}

Current language features

Supported today:

• assignments
• numeric expressions
• property reads and writes
• local bindings with let
• persistent per-entity script state with state
• entity-local event dispatch with emit(...)
• if / else
• boolean conditions with &&, ||, !
• top-level reusable functions
• runtime query calls like input_left(), input_action(), and key("Space")
• action builtins like play_sound(...), play_music(...), and stop_music()

Properties

Current readable/writable properties:

• self.x
• self.y
• self.width
• self.height
• self.pos
• self.size
• self.rotation
• self.color
• self.texture for sprites
• self.animation for named sprite animations
• self.flip_x for sprites
• self.flip_y for sprites
• self.vx for platformer sprites
• self.vy for platformer sprites
• self.move_x for platformer sprites
• self.jump for platformer sprites
• self.grounded for platformer sprites
• self.text for text nodes
• self.some_state
• Name.x
• Name.y
• Name.width
• Name.height
• Name.pos
• Name.size
• Name.rotation
• Name.color
• Name.texture for sprites
• Name.animation for named sprite animations
• Name.flip_x
• Name.flip_y
• Name.vx
• Name.vy
• Name.move_x
• Name.jump
• Name.grounded
• Name.text for text nodes
• Name.some_state

Example:

1Accent.color = #7ce0ff2self.pos = Mascot.pos3self.width = 96.04self.rotation = self.rotation + 1.6 * dt

flip_x, flip_y, jump, and grounded are represented as scalar 0 or 1 values in scripts.

Script Events

Scripts can dispatch entity-local events:

1emit("motion", "run")

The same entity can receive them through a generic event handler:

1on event(event, value) {2    if event == "motion" {3        if value == "run" {4            self.animation = "run"5        } else if value == "idle" {6            self.animation = "idle"7        }8    }9}

String equality and inequality are supported in conditions, so event == "motion" and value != "idle" are valid.

Platformer Input

For sprites using physics = platformer, scripts should express input intent and let the runtime handle acceleration, friction, gravity, jumping, and collision:

1on update(dt) {2    if input_left() {3        self.move_x = -14        self.flip_x = 15    } else if input_right() {6        self.move_x = 17        self.flip_x = 08    } else {9        self.move_x = 010    }11​12    if input_action() && self.grounded {13        self.jump = 114    }15}

The runtime updates self.vx, self.vy, and self.grounded.

Collision Events

The runtime emits entity collision events after movement and platformer physics.

collision_enter(other, group) fires once when two visible entities begin overlapping.

collision(other, group) fires every frame while two visible entities overlap.

Both events are sent to both entities. other is the other entity name and group is the other entity group, or an empty string if it has none.

1on collision_enter(other, group) {2    if group == "pickup" {3        destroy(other)4    } else if group == "hazard" && is_stomping(other) {5        destroy(other)6        self.vy = -185.07    } else if group == "hazard" {8        self.vy = -150.09    }10}

is_stomping(other) is a platformer helper for collision handlers. It returns true when the current entity is falling into the top band of other, which is useful for enemy stomp behavior.

Locals

Handler-local values can be introduced with let:

1let next_x = Mascot.x - 12.0 * dt2Mascot.x = next_x

Locals are shared with nested if blocks and with called functions in the same handler execution.

Persistent state

Scripts can declare persistent state that survives across frames on the bound runtime entity:

1state score = 02state lives = 33state invulnerable_until = 0

State values can be read as bare variables inside the same script:

1score = score + 10

They can also be accessed through entity properties:

1self.score = self.score + 102HudState.lives = HudState.lives - 1

Use let for temporary per-handler values and state for data that must persist between updates.

Conditions

Current condition features:

• <
• <=
• >
• >=
• ==
• !=
• &&
• ||
• !
• grouping with parentheses

Example:

1if next_x < 120.0 || (Accent.x < 260.0 && !(self.y < 200.0)) {2    Mascot.x = 520.03} else {4    Accent.color = #7ce0ff5}

Bare query calls are also valid conditions. They are treated as truthy when non-zero:

1if input_left() {2    self.x = self.x - 120.0 * dt3}

Functions

Current functions are top-level, can take parameters, and can return a value:

1fn accent_color(limit) {2    if limit < 120.0 {3        return #ff88994    } else {5        return #7ce0ff6    }7}

Called as a statement:

1call sync_accent(next_x)

Audio actions use the same call ... statement form:

1call play_sound("shot.wav")2call play_music("music-game.ogg")3call stop_music()

play_sound(...) is intended for short one-shot effects.

play_music(...) starts looping background music and replaces any currently playing music.

stop_music() stops the current music track.

These actions work on both native and wasm/web. On the web, browsers may delay music start until the first user interaction because of autoplay rules.

Called as an expression:

1Accent.color = accent_color(next_x)

Runtime queries

Current built-in runtime queries:

• input_left()
• input_right()
• input_up()
• input_down()
• input_action()
• key("Space")
• exists("Name")
• first_overlap("group")
• is_stomping("Name")
• high_score_name(index)
• high_score_value(index)
• format_int(value, digits)
• lerp(a, b, t)
• pulse(period)
• smoothstep(edge0, edge1, x)
• alpha(color, alpha)
• time()
• difficulty()
• every(seconds)
• every(min_seconds, max_seconds)
• rand(min, max)
• screen_width()
• screen_height()

Example:

1if input_action() {2    self.color = #ffbf473}4​5if key("Space") {6    self.color = #ff88997}8​9self.x = clamp(self.x, 80.0, screen_width() - 160.0)10​11if every(1.2, 2.0) {12    spawn("EnemyTemplate", screen_width() + 80.0, rand(48.0, screen_height() - 96.0))13}

input_action() is the generic shoot/confirm/action abstraction. On desktop it currently maps to Space, Enter, Z, and X.

exists("Name") returns whether a live runtime instance with that name currently exists. This is useful for spawn gating:

1if !exists("PlanetTop") && every(10.0, 14.0) {2    spawn("PlanetTopTemplate", "PlanetTop", screen_width() + 96.0, -92.0)3}

first_overlap("group") returns the name of the first overlapping live entity in that group, or an empty string if there is no hit. This is useful for simple projectile collisions:

1let hit = first_overlap("hostile")2if exists(hit) {3    destroy(hit)4    destroy(self)5}

high_score_name(index) and high_score_value(index) read from the runtime high-score table using 1-based indices.

format_int(value, digits) formats a scalar as a zero-padded string. This is useful for HUD text:

1ScoreLabel.text = format_int(score, 3)

lerp(a, b, t) linearly interpolates between two scalar values.

pulse(period) returns a repeating 0..1 pulse over the given period in seconds.

smoothstep(edge0, edge1, x) returns a smoothed 0..1 interpolation factor, useful for eased motion and fades.

alpha(color, alpha) returns the given color with a replaced alpha channel.

difficulty() is currently a simple time-based level that increases as the session runs.

every(seconds) is a per-script-line timer query that returns true when the interval elapses.

every(min_seconds, max_seconds) schedules the next trigger with a randomized interval in that range.

rand(min, max) returns a random scalar inside the given range.

Runtime instancing

Current runtime instance statements:

• spawn("TemplateName", "InstanceName", x, y)
• spawn("TemplateName", x, y)
• destroy("InstanceName")
• destroy(name_expr)
• destroy(self)

Example:

1on ready() {2    spawn("EnemyTemplate", self.x + self.width, rand(self.y, self.y + self.height))3}4​5on update(dt) {6    ScoutOne.x = ScoutOne.x - 180.0 * dt7}

High scores

Scripts can submit scores to the runtime high-score table:

1call submit_score("UNKNOWN", HudState.score)

This updates the internal table used by highscore scene nodes and the high_score_name(...) / high_score_value(...) queries.

Current limitations:

• no closures
• no column-precise diagnostics; warnings/errors currently report file and line

Compatibility helpers

The runtime still supports older helper-style script ops such as:

• move_by(...)
• move_by_dt(...)
• set_pos(...)
• set_color(...)
• copy_pos(...)
• clamp_x(...)
• clamp_y(...)

The direction now is to prefer assignments and expressions instead of adding more one-off built-ins.