Script Overview

Introduction

OpenBOR includes a C-based scripting engine that allows creators to build customized or all new functionality into their games. Scripts may execute in response to a wide range of engine events, including animation-frame updates, engine cycles, timer ticks, collisions, damage, key input, and many others. Creators can implement scripts through native define-file paths, user-defined libraries, or code inserted directly into level files and model sheets.

Alongside its native function library, the OpenBOR scripting engine supports the #include directive. An optional, memory-efficient #import directive is also available when only function references are needed. These directives allow creators to build reusable custom libraries, then call their functions from any appropriate script event.

Scripts can also perform create, read, update, and delete operations on external data files at runtime. This includes working with content such as model sheets, configuration data, and even other script files.

In practical terms, OpenBOR places virtually no limit on the game mechanics creators can implement. If you can imagine it and write the logic, you can build it.

Basics

Syntax

OpenBOR Script uses syntax similar to C, with several notable differences:

Weak typing: OpenBOR Script is weakly typed. Variables are stored as variants, and the engine changes their types as needed. Type prefixes indicate the intended data type, but do not enforce it by default. Functions declared as void may still return values. Strong typing may optionally be enforced with type guards. See Variables and Type Guards for details.

Preprocessor directives: Standard C preprocessor directives such as #include, #define, and #ifdef are available. OpenBOR Script also provides an additional custom memory saving #import directive implementation.

String concatenation: The + operator may be used to combine strings:

void string_a = "Hello "
void string_b = "world!"

void string_c = string_a + string_b;
log(string_c); //"Hello world!"

Assignment: During assignment, both the value and type of the right-hand variant are copied to the left-hand variant. No automatic type validation is performed, so creators should take care when assigning values between variables.

Operators

Category	Operators
Arithmetic	+, -, *, /, %
Increment and decrement	++, --
Assignment	=, +=, -=, *=, /=, %=
Comparison	==, !=, >, <, >=, <=
Logical	!, &&,
Bitwise	&, ^, ~, <<, >>
Bitwise assignment	&=, ^=, <<=, >>=
Conditional	?:
Grouping and access	(), .

Control Flow

• do
• while
• for
• break
• if
• else
• continue
• switch
• case
• return

Caution: There is a known bug in do/while where a continue within the loop disables the exit condition and may cause a runaway. This bug is under investigation. If continue is needed, consider a for loop.

Preprocessor Directives

• #define
• #ifdef
• #ifndef
• #endif
• #include
• #import

#import is an OpenBOR-specific directive. Unlike #include, which copies the contents of a file into the current script, #import imports references to the file's functions without copying its contents. This can significantly reduce memory usage when sharing reusable function libraries across multiple scripts.

Native Functions

In addition to the operators described above, OpenBOR provides a suite of native functions that give scripts direct control over engine primitives and systems. These functions allow creators to inspect, modify, replace, or extend engine behavior while also assisting with game logic, graphics generation, mathematical calculations, data handling, and other common scripting tasks.

Script Entry Points

Every OpenBOR script except for animation contains one required entry-point function, main(), and may also define two optional lifecycle functions, oncreate() and ondestroy().

main()

void main() {
    // Do stuff here.
}

The engine executes main() whenever the script’s associated event fires. Before execution, the engine automatically populates a collection of local variables containing information relevant to that event. Available variables depend on the script type and triggering event. For example, a collision script may receive references to the participating entities, while an input script may receive information about the player and activated controls.

oncreate()

void oncreate() {
    // Do stuff here.
}

The engine executes oncreate() when the script instance is created. This function may be used to initialize variables, allocate resources, or perform other setup required before the script begins responding to events.

ondestroy()

void ondestroy() {
    // Do stuff here.
}

The engine executes ondestroy() when the script instance is destroyed. This function may be used to release resources, save state, or perform other cleanup associated with the script instance.