Scripting Language Reference

This is a manual for the kalmar compiler and the scripting language it compiles.

Syntax

Scripts

Scripts are defined using the scr keyword followed by the name of the script and a set of curly brackets containing the contents of the script

scr cool_script {
    Var[0] = 2
    if Var[1] == 4 {
        return
    }
    Var[1] = 6
    return
}

Note that newlines are used to terminate each statement

Comments

Line comments are denoted with // and run to the end of the line. They can be placed at the beginning of a line:

// this is a line comment
Var[0] = 5

or at the end of a line

scr main {
    Var[0] = 5 // this is also a valid comment
}

Block comments are denoted with /* */ where everything in between the delimiters is commented out. They can be used in place of line comments but can additionally be placed in the middle of statements and can span multiple lines:

/*
This entire block
is
a
comment
*/

Var[0] = 2 + /* this is a valid statement */ 5

Types

Constants

All integers are stored as signed 32-bit numbers. They can be written in any of the following forms

Base	Example
Decimal	`523`
Binary	`0b100110`
Octal	`0o1342172`
Hexadecimal	`0x41414141`

Fractional numbers are interpreted as 32-bit floating point numbers. They are converted to fixed-point numbers with a scaling factor of 1024 during compilation.

Variables

Name	Size	Description
Var	0x10	Variables local to the current script
Flag	0x60	Flags local to the current script
MapVar	0x10	Global variables cleared upon map transition
MapFlag	0x60	Global flags cleared upon map transition
AreaByte	0x10	Bytes stored in save file. Cleared upon area transition
AreaFlag	0x100	Flags stored in save file. Cleared upon area transition
GameByte	0x200	Bytes stored in save file. Never cleared
GameFlag	0x800	Flags stored in save file. Never cleared
Array	-	Current script array. Must be assigned before use
FlagArray	-	Current script flag array. Must be assigned before use
Buffer	-	Current script buffer. Must be assigned before use

Expressions

Assignment

Variables may be assigned values using the = operator. They may be assigned integers, floating point numbers, values stored in variables, and references to other variables.

Var[0] = 5
Var[0] = 5.5
Var[0] = Var[1]
Var[0] = &Var[1]

Arithmetic

Arithmetic operators operate on a value stored in a variable and store the result back in the original variable.

// Adds 5 to the value stored in Var[0]
Var[0] += 5

The following operators are provided:

Operator	Operation	Valid operands
+=	Addition	Integers, Floats
-=	Subtraction	Integers, Floats
*=	Multipication	Integers, Floats
/=	Division	Integers, Floats
%=	Modulus	Integers
\|=	Bitwise OR	Integers, Variables
&=	Bitwise AND	Integers, Variables

Constant Expressions

Constant expressions are expressions that can be resolved by the compiler at compile time. They are provided for use in cases when representing a value as an expression may be more clear than using its fully evaluated form. These expressions may only include numbers and the following operators:

arithmetic:
+, -, *, /, %, &

boolean:
==, !=, <, <=, >, >=

Additionally, parentheses may be used to explicitly specify operator precedence

Buffers and Arrays

Script Buffer

The script buffer is a preexisting array that stores 32-bit integers which can be popped off by the current script.

The buffer must be assigned before use. It can be assigned by doing the following:

Buffer = Var[0]

Integers can be retrieved in order from the buffer. Note that this will advance the buffer by however many integers were accessed

Var[1], Var[2], Var[3] <- Buffer

Integers can also be retrieved by index without advancing the buffer

Var[2] = Buffer[1]

Script Array

The script array and flag array are arrays that can either be created within the script or be allocated before the script. They must be assigned before use

An array can be allocated with a specific size using the alloc function. This will return the allocated array pointer and also overwrite the current script's array pointer to match

Var[2] = alloc(5)

If an array already exists, it can be set as the current script array or flag array by assigning either the variable Array or FlagArray

Array = Var[2]
FlagArray = Var[3]

Values in the array can be accessed by index

Var[3] = Array[5]
Var[4] = FlagArray[0]

Control Flow

Wait

The wait function blocks execution of the script for a specified number of frames, while wait_sec blocks execution for a specified number of seconds

wait(5) // blocks script for 5 frames
wait_sec(22) // blocks script for 22 seconds

If statements

An if statement conditionally executes a set of statements if a provided expression evaluates to true

if expr {
    // does something if expr is true
}

An alternate set of statements to be executed if the expression evaluates to false can be specified using an else statement

if expr {
    // does something if expr is true
} else {
    // does something if expr is false
}

Multiple conditions can also be chained together

if expr1 {
    // does something if expr1 is true
} else if expr2 {
    // does something if expr2 is true
} else {
    // does something if neither are true
}

The following conditions are available:


a == b	a is equal to b
a != b	a is not equal to b
a < b	a is less than b
a <= b	a is less than or equal to b
a > b	a is greater than b
a >= b	a is greater than or equal to b
a & b	the bits of b are set on a

The inverse of any condition can be tested by prefixing the condition with a ! character and surrounding it with parentheses

For example: a == b is equivalent to !(a != b)

Labels and Goto statements

A label specifies a statement that can be jumped to using a goto statement. The scope of a label is limited to the script it is defined in.

if Var[0] == 6 {
    goto error
}

error:
return

Loops

A loop executes a set of statements a specified number of times

loop 5 {
    // do something 5 times
}

If the loop count is 0 or is omitted, the loop will run indefinitely unless broken out of

loop {
    // this code will run forever...
    
    if expr { // until this condition is met
        bloop
    }
}

The bloop keyword can be used to break out of any loop whether or not it executes a finite number of times.

Switch statements

A switch statement selects a set of statements to execute based on which condition matches the specified expression.

switch Var[0] {
    3 {
        // do something if Var[0] == 3
    }
    != 5 {
        // do something if Var[0] != 5
    }
}

The following conditions are available:


a	expression is equal to a
== a	expression is equal to a
!= a	expression is not equal to a
< a	expression is less than a
<= a	expression is less than or equal to a
> a	expression is greater than a
>= a	expression is greater than or equal to a
a \| b	expression is equal to a or b
a & b	expression is equal to a and b
a..b	expression is between a and b (inclusive)
& a	the bits of expression are set on a

Additionally, the default keyword can be used to designate a set of statements to execute if none of the previous conditions match.

The bcase keyword can be used to break out of any case statement and jump execution to immediately after the switch statement ends.

Jump statements

A jump statement jumps execution to another script. The script to be jumped to can be defined anywhere in the file containing the script that contains the jump instruction.

scr script1 {
    // script body
}

scr script 2 {
    if Var[5] == 3 {
        jump script1
    }
}

Threads

Regular thread

A thread block creates a temporary script that runs alongside the current script, copying the current script variables to the new script

thread {
    // do stuff
}

Child thread

Similar to a regular thread except the thread is killed when the current script is finished executing

cthread {
    // do stuff
}

Exec/Exec Wait

The family of exec functions allow for launching a new script from inside another

The exec function launches a script without blocking the execution of the current script

exec(cool_script)

The id of the launched script can be stored in a variable

Var[0] = exec(cool_script)

The exec_wait function launches a script and blocks the execution of the current script until the child returns

exec_wait(cool_script)

Misc functions

Function	Arguments	Return value	Description
bind	script pointer, event type: int, collider id: int	trigger pointer	binds a script to run when an event is triggered
bind_lock	script pointer, event type: int, collider id: int, item list: int	trigger pointer	works similar to the `bind` function but displays a list showing selectable items
unbind	-	-	unbinds the current script from a trigger
kill	id: int	-	kills a script with the given id
set_priority	priority: int	-	sets the priority of a script
set_timescale	timescale: float	-	sets the timescale of a script
set_group	group: int	-	sets the group of a script
suspend_group	group: int	-	suspends all scripts in the given group
resume_group	group: int	-	resumes all scripts in the given group
suspend_others	group: int	-	suspends all scripts in the given group excluding the current script
resume_others	group: int	-	resumes all scripts in the given group excluding the current script
suspend_thread	id: int	-	suspends all scripts with the id as well as their children
resume thread	id: int	-	resumes all scripts with the id as well as their children
is_thread_running	id: int	bool	returns whether a script with the given id is in the current script list