Skip to content
AEOWUN
Docs Menu

Syntax

Read and write AeoScript statements.

AeoScript is the scripting language used by Worldkiln. This guide explains how to read and write its statements, expressions, and declarations. Start with the example, then use the sections below as a reference.

A complete first example

// Keep track of collected items.
score: number = 0

fn collect_item(points) {
    score += points
    debug.log("Score:", score)
}

collect_item(10)

The first line is a comment. score stores a number. fn defines a function, and collect_item(10) calls it. When the script runs, Output prints Score: 10.

Lines, spaces, and blocks

Write one statement per line. Indent the statements inside a block so the structure is easy to follow. Curly braces { } enclose function bodies, conditions, loops, and event handlers.

health: number = 100

if health > 0 {
    debug.log("Alive")
}

Whitespace helps readability, but indentation does not replace braces. Semicolons are not needed at the ends of statements.

Comments

Start a comment with //. A comment continues to the end of that line and is ignored when the script runs.

// Set the player's starting health.
health: number = 100

health -= 10 // Damage from one hit

Use comments to explain why code exists or why a choice matters. Clear names usually explain what code does without an extra comment.

Names and punctuation

Names identify variables, functions, parameters, and other declared values. A name starts with a letter or underscore; later characters may also contain numbers.

player_score: number = 0
const item2_found = true

An underscore _ is part of a name, as in player_score. A period . accesses a member of something, as in debug.log. They serve different purposes:

const player_name = "Ada" // One variable name
debug.log(player_name)   // 'log' belongs to 'debug'

Names are case-sensitive, so player_score and Player_Score are different. Use descriptive names consistently. Keywords such as fn, if, while, const, and return have special meanings in the language.

Values and strings

A value may be a number, a string, a Boolean (true or false), nil, a collection, or another supported value.

const health = 100
const speed = 2.5
const player_name = "Ada"
const is_ready = true
const target = nil

Put string text inside double quotes. Escapes let you include special characters:

debug.log("First line\nSecond line")
debug.log("She said \"Hello\"")

The string escapes \n (new line), \r (carriage return), \t (tab), \" (quote), and \\ (backslash) are supported.

See Types for the kinds of values available in AeoScript.

Variables, constants, and types

Use const name = value when the value does not need to change. To declare a variable you plan to reassign, use the supported name: type = value form. A plain name = value changes an existing variable; it does not declare one.

score: number = 0
score += 10

const max_health = 100

Type annotations also appear on function parameters and return values. A question mark after a type name denotes an optional type, for example number?.

A function's parameters and local variables belong to its scope. See Variables for scope and constant behavior.

Operators and expressions

An expression produces a value. You can combine values using operators:

Purpose Operators Example
Arithmetic + - * / % 10 + 5 * 2
Comparison == != < <= > >= score >= 10
Logic && `
Assignment = += -= *= /= score += 5

== compares values; = assigns a value. Parentheses group expressions and control evaluation order:

const first = 10 + 5 * 2    // 20
const second = (10 + 5) * 2 // 30

From higher to lower precedence: member access, calls and indexing; unary ! and -; * / %; + -; comparisons; equality; &&; then ||.

See Operators for more examples.

Functions

Declare a function with fn, followed by its name, parameters in parentheses, and a body in braces. Call it using its name and parentheses.

fn add(a: number, b: number): number {
    return a + b
}

const total = add(10, 20)
debug.log(total) // 30

Parameters receive the arguments passed to the call. return ends the function and optionally gives a result back to its caller. Parameter and return types can be omitted:

fn double(value) {
    return value * 2
}

debug.log(double(5)) // 10

An anonymous function has no declared name. It can be stored in a variable or passed as a callback:

const double = fn(value) {
    return value * 2
}

debug.log(double(6)) // 12

See Functions for closures, callbacks, and return values.

Conditions

Use if to run code when a condition is true. Add else if to test another condition, and else for the remaining case.

health: number = 40

if health <= 0 {
    debug.log("Defeated")
} else if health < 25 {
    debug.log("Low health")
} else {
    debug.log("Ready")
}

Only the first matching branch runs.

Loops

A for loop visits items in a basket:

const items = ["Key", "Map", "Coin"]

for item in items {
    debug.log(item)
}

A while loop continues while its condition is true:

count: number = 0

while count < 3 {
    count += 1
    debug.log(count)
}

Make sure a loop can finish or pause; an endless loop without a pause can exceed script execution limits. See Control flow.

Baskets, maps, and indexing

Square brackets [ ] create a basket and retrieve an item by index. Basket indexes start at zero.

const items = ["Key", "Map", "Coin"]
debug.log(items[0]) // Key

Curly braces with key: value entries create a map. Use an index expression to read or set a map entry:

const settings = {volume: 5, enabled: true}
debug.log(settings["volume"]) // 5
settings["volume"] = 8

An empty basket is []; an empty map is {}. See Baskets and Maps for collection operations.

Calling APIs and accessing objects

Parentheses ( ) supply arguments to a function call. A period . selects a member; square brackets [ ] select an indexed value.

debug.log("Hello")
const limited = math.clamp(15, 0, 10)
debug.log(limited) // 10

Use object.method(arguments) in examples when calling APIs documented with dot notation. AeoScript also accepts object:method(arguments) for method-call expressions, but it is not needed to call ordinary API functions. The API reference shows the names to use.

Events and callbacks

An event lets one part of a game send a message that another part can handle. Declare an event handler using on and fire the event using event.fire().

on score_changed(new_score) {
    debug.log("New score:", new_score)
}

event.fire("score_changed", 25)

The event name in event.fire() matches the name after on. Values supplied when the event is fired are received by the handler's parameters in the same order. Events are queued for handling.

A callback is a function saved for another part of the game to invoke. For example, an object's touch callback can use an anonymous function:

// 'coin' is a previously obtained Cell handle.
coin.on_touch = fn(thing) {
    debug.log("Coin touched")
}

See Events for contact events, custom events, and callback arguments.

Entity declarations

An entity declaration groups fields and functions that belong to that script's entity behavior:

entity Counter {
    count: number = 0

    fn update(dt) {
        count += 1
    }
}

See Entity scripts for attaching this behavior and using lifecycle functions.

Reading syntax errors

When a script fails to parse, check the line named in the error and the line immediately before it. Common mistakes include a missing closing ), ], or }, a missing comma between arguments, an unfinished string, or using = where a comparison needs ==.

// Correct: compare score to 10.
if score == 10 {
    debug.log("Goal reached")
}

Open Output to find script errors. See AeoScript errors for diagnosis and fixes.

Next: Variables, Functions, Control flow, or the API reference.