Store Page
Uncrewed
All Discussions Screenshots Artwork Broadcasts Videos Workshop News Guides Reviews

Uncrewed

Store Page
Uncrewed > Guides > uncrewedgame's Guides
Not enough ratings
Map Editor: Custom Games & Scripting Guide (Official)
By uncrewedgame
This guide serves as an introduction to custom game making and scripting.
   
Award
Favorite
Favorited
Unfavorite
Created by
uncrewedgame
Online
Category: Maps or Levels, Workshop
Languages: English
Posted
Updated
4 Jul, 2019 @ 1:05pm
10 Jul, 2019 @ 5:18am
136 Unique Visitors
6 Current Favorites
Guide Index
Overview
Introduction 
Getting Started 
Scripting Language Basics 
Statements 
Variables 
Lists 
Strings 
Conditional Statements 
Loops 
Functions 
Lambda Functions 
Comments 
Operator Reference 
Standard Type Constructors 
Standard Functions 
Game Object Constructors 
General Game Functions 
Player Functions 
General Object Functions 
Unit Functions 
AI Functions 
Weapon Functions 
Spawn Functions 
Objective Functions 
Comments
Introduction
This guide assumes at least a basic level of familiarity with the map editor and general script and programming concepts. This guide is meant only as an introduction to custom game making and scripting, and it is not an in-depth technical overview of the language. However it should be sufficiently detailed for the purposes of map making.
Getting Started
When creating a new map in the map editor, the map type is always set to Skirmish. Skirmish maps use the standard game rule-set, and don't allow any scripts. In order to make a custom map with a custom rule-set, the map type should be changed to Custom.

To achieve that, click the Map Settings (located on the top bar), and choose the Custom option, from the map type drop-down.

Player Slots
In addition to being able to run custom scripts, with custom maps it is also possible to modify the player slots. There are four slots in total, and each slot can be set to one of the following settings:
  • Open - open slots are slots that can be chosen from the lobby when starting a game - it can be used by a human player, an AI bot, or set to empty.
  • Closed - closed slots cannot be used by anyone. It's still possible to place units assigned to this slot in the map editor, but they will lack any centralized AI (they will still attack units from other teams when provoked).
  • AI - AI slots cannot be selected from the lobby, but they will have normal AI behavior.

So, for example, if you want to make a PvE map, with two players battling in a team against two AI foes, who are also teamed-up, the slot setup may look like this:
  • Player One (Open) Team (A)
  • Player Two (Open) Team (A)
  • Player Three (AI) Team (B)
  • Player Four (AI) Team (B)

Script Objects
Finally, to customize the rules of the map, scripts objects will be needed. To add a new script object, go to Objects -> Tools, and search for Empty Script.

Script objects have a few properties of their own:
  • Name - the name of the script; note that this name cannot be referenced anywhere in the code, and serves more as a description.
  • Radius - the radius of the script object's detection circle - this is an important property, as it's possible to query what units are currently in the detection by calling the tracked_units function from any of the script objects.
  • Auto-Start - by default all scripts start as soon as the game starts. This can be changed by un-checking this option. Then, to start this particular script, the start_script function will need to be called from some other script.
  • Code - the code of the script object is editable, and this is where it's possible to modify the game behavior.
  • Object Links - this is another important property. By clicking the corresponding button, it's possible to link other objects (units, buildings, scripts, etc.) to this script. Then, in the code it's possible to call the linked_units function to query those objects.
Scripting Language Basics
Every script object can have four clauses, each of which has a distinct purpose:
  • global_init - this clause is always executed at the start of the game, even if the script is not set to auto-start.
  • init - this clause is executed once and only once when the script first starts. It, for example, won't be executed for non auto-starting scripts until the script is explicitly started.
  • condition - this clause is executed on each logic tick, until it evaluates to true. In order for it to evaluate to true, the last statement of the clause must evaluate to true.
  • action - this clause is executed once and only once when the condition clause evaluates to true.
Any of the clauses can be omitted if it is not required by the script.

A clause can be declared and defined as follows:

clause-name { body }

where clause-name is one of the four clause names, and body is a set of code statements.

So that a script object which has all of the four clauses may look like this:

global_init { statements } init { statements } condition { statements } action { statements }

The condition clause differs from all other clauses in that its last statement should evaluate to either true or false.
Statements
A statement is a basic unit of code logic - it carries some action out. For example:

z = x * y

is a statement that multiplies variables x and y together, and the assigns the result to the variable z.

Multiple statements can be separated using the ';' (semi-colon) character:

z = x * y; w = z / 2;

Here, as before, variables x and y are multiplied and assigned to the variable z, and then in the next statement the variable z is divided by two and assigned to variable w.
Variables
Variables are used to store values. Variables are declared, and initialized by assigning values to them for the first time.

x = 3;

A variable can be local, member, or global.

Local variables are only visible within the scope in which they are declared.

x = 7;

Member variables are visible to the entire script object.

member y = "Hello World!";

Global variables are visible to everyone, including other script objects.

global game_score = 1000;

In order to access a global variable from another script object, it must be first imported using the import command.

import game_score;

Variable names are case sensitive. For example the names SomeVariable, someVariable, somevariable will refer to three different variables.
Lists
Lists are used to store collections of values.

Lists are declared and initialized using the list function.

list(1, 2, 3)

Lists themselves are objects and can be assigned to variables, as discussed before:

some_list = list(1, 2, 3)

Two or more lists can be joined together using the + operator:

longer_list = list(1, 2, 3) + list(4, 5)

Individual list elements can be accessed, read, and written to using the [] operator:

some_list = list(1, 2, 3); some_list[0] = 9;

List indexing starts at 0 meaning that the first element of a list has the index of 0.
Strings
Strings are objects that can contain text (currently ASCII only). Declared and initialized using the " (double quotes) character.

text = "Hello World!"

Two or more strings can be joined together using the + operator:

text = "Hello " + "World!"

Strings can be joined with non-string objects, provided those objects are convertible to strings.

score = 1000; text = "Game Score: " + score;

Note that in this case, strings have to be to the left of other objects.

Other objects, such as numbers, can also be converted to strings explicitly by calling string function:

string(20) + " is a positive number"
Conditional Statements
Conditional statements are used to execute code if some condition is met. They can be written using if and else keywords:

if ( condition ) { true-statement } else { false-statement }

If the condition statement is true, then true-statement is executed, otherwise false-statement is executed. The condition statement can be any statement that can be evaluated to either true or false.

For example:

x = 14 if (x < 100) { send_text_message("this statement is true!"); } else { send_text_message("this statement is false!"); }

Results in a message that reads: "this statement is true!"

Likewise,

x = 14 if (x > 100) { send_text_message("this statement is true!"); } else { send_text_message("this statement is false!"); }

Results in a message that reads: "this statement is false!"

The else portion of the conditional statement is not required:

x = 14 if (x < 100) { send_text_message("this statement is true!"); }

It is also possible to chain conditional statements together that will result in sequential checking of conditions; as before the corresponding true-statement will be executed if the relevant condition evaluates to true:

animal = "cow"; if (animal == "cat") { send_text_message("meow!"); } else if (animal == "dog") { send_text_message("bark!"); } else if (animal == "cow") { send_text_message("moo!"); }

Boolean Expressions

The condition statement is a boolean expression - a statement that evaluates to either true or false.

There are several operators provided in the language that can be used to form such statements. They are:
  • Equals: == operator
  • Not Equals: != operator
  • Less Than: < operator
  • Less Than Or Equals: <= operator
  • Greater Than: > operator
  • Greater Than Or Equals: >= operator

There are also logical operators that can be used to combine smaller condition statements into a more complex one:
  • Not: ! operator
  • And: && operator
  • Or: || operator
Loops
A loop is used to execute a statement, or a set of statements until some condition is met. There are three flavours of loops available.

For Range Loop

For Range Loops are designed to be used in conjunction with iterable objects such as lists. It is the simplest way to perform an action for a collection of values.

for (x : iterable_object) { action-statement }

For example:

element_sum = 0; for (x : list(1, 2, 3)) { element_sum = element_sum + x; }

will result in the variable element_sum containing the sum of the list elements, which is 6 in this case.

For Loop

For Loop is a more generalized loop form. It relies on the condition statement to evaluate to true.

for (init-statement; condition-statement; iteration-statement) { action-statement }

First the init-statement is executed in order to perform all the steps required to prepare for the loop. This statement is executed only once.

Then the condition-statement is executed and if it evaluates to true - the action-statement is executed, and finally the iteration statement is executed. After that the loop restarts at the condition-statement. The loop stops when the condition-statement evaluates to false.

For example:

y = 0; for (i = 0; i < 5; i = i + 1) { y = y + 5; }

Here, first the init-statement declares a variable i and initializes it to 0, then the condition-statement checks if the variable i is less than 5, and if so it executes the action statement which simply adds 5 to variable y. Then the iteration-statement increments i by 1, and the loop restarts at the conditional-statement. In total this loop will execute 5 times and result in the variable y having a value of 25.

While Loop

While Loop is similar to the general For Loop, but it does not have an init-statement, nor an iteration-statement.

while (condition-statement) { action-statement }

The condition-statement is executed, and if it evaluates to true - the action-statement is executed. The loop restarts at the condition-statement. The loop stops when the condition-statement evaluates to false.

y = 0; x = 0; while (x < 5) { y = y + 5; x = x + 1; }

In total this loop will execute 5 times and result in variable y having a value of 25.
Functions
Functions are blocks of code. The code of a function can be executed by calling said function. When called, a function can take a number of arguments. That number can also be zero. A function can also return a value.

A function call has the form of:

function-name(argument-0, argument-1, ..., argument-n)

Most functions take a fixed number of arguments. For example the function min takes two arguments and returns the smaller among them:

min(23, 9)

The result of a function can be bound to a variable:

x = min(23, 9)

Results in the variable x containing the value of 9.

There are also functions that take a variable number of arguments. For example the list function that initializes lists.

empty_list = list(); short_list = list(1, 2); longer_list = list("Cat", "Dog", "House", "Car", "Keys");
Lambda Functions
A lambda (also known as an anonymous function) is a function that is not bound to a specific name.

Lambda functions are declared and defined as follows:

[capture-list] (parameter-list) { body }

First, the capture-list portion of the declaration specifies which variables from the scope it was declared in, it is allowed to use.

For example, the following lambda has access to variables x and y, but not z:

x = 5; y = 7; z = 3; do_something = [x, y] () { x = 1; y = -6; }; do_something();

Note that changes made to variables x and y inside the lambda will not affect the outside variables, as they are copied when the lambda is initialized.

In order to be able to modify the original variables, they need to be marked with a ref qualifier in the capture list.

x = 5; y = 7; z = 3; do_something = [ref x, ref y] () { x = 1; y = -6; }; do_something();

A lambda can capture referenced variables automatically, if its capture list contains qualifiers ref, or val by themselves.

x = 5; modify_some_var = [ref] () { x = 1; // Variable x both inside, and outside the lambda now contains 1. }; modify_some_var(); do_not_modify_some_var = [val] () { x = 10; // Variable x inside the lambda now contains 10, // but outside the lambda it remains unmodified as 1. }; do_not_modify_some_var();

Then the parameter-list specifies the names and the amount of parameters the lambda function has. It can also be left empty.

Lastly the function body is a set of statements that represent the function code block. The result of the last statement of the lambda will also be its return value.

Like other functions, in order to be useful, a lambda function needs to be called. There are several ways to do that.

  1. A lambda function can be declared and defined in place of a function argument accepting a function object, and then subsequently executed by that function:

    min_element(list(2, 1, 3), [] (x, y) {x < y})

    The function min_element executes the lambda function [] (x, y) {x < y} in order to find the smallest element in the list and return it.

  2. A lambda function can be bound to a variable, to be called at a later time.

    square_and_add_one = [] (x) { x * x + 1 }; square_and_add_one(5)

  3. A lambda function can also be declared, defined and then called immediately after.

    result = [] (text) { text + " :)"; } ("Hello World");
Comments
Comments are pieces of text that are not interpreted as code, and are completely ignored by the script compiler. They can be useful for explaining or temporarily disabling parts of the code.

There are two types of comments. Single-line and multi-line comments.

A single-line comment is written as // (two slashes), and it instructs to ignore everything until the end of the line.

// This is a comment, and it is ignored by the script compiler x = 2; // This is also a valid comment.

A multi-line comment is written as /* text to be ignored */ meaning that everything between a pair of /* */ will be ignored.

/* This is a multi-line comment and this text is ignored by the script compiler */ x = 2;
Operator Reference
Here's the list of all available operators:

Operator
Description
Example
[]
Subscript
list(1, 2, 3)[0]
()
Function Call
square(4)
unary !
Unary Not
!x
unary -
Unary Minus
-x
unary +
Unary Plus
+x
*
Multiplication
x * y
/
Division
x / y
%
Modulo
x % y
-
Minus
x - y
+
Plus
x + y
<
Less Than
x < y
<=
Less Than Equals
x <= y
>
Greater Than
x > y
>=
Greater Than Equals
x >= y
==
Equals
x == y
!=
Not Equals
x != y
&&
And
x && y
||
Or
x || y
=
Assign
x = y
,
Comma
x, y

Precedence

Precedence
Operators
Associativity
1
[]
()
Left-to-Right
2
unary !
unary -
unary +
Left-to-Right
3
*
/
%
Left-to-Right
4
-
+
Left-to-Right
5
<=
>
>=
==
!=
Left-to-Right
6
&&
Left-to-Right
7
||
Left-to-Right
8
=
Right-to-Left
9
,
Left-to-Right
Standard Type Constructors
Standard type constructors are functions that create, initialize, and return standard type objects.

list
list(argument 0, argument 1, ..., argument n)

Creates, initializes and returns a list object from any number of argument objects.

Parameters
  1. argument 0, argument 1, ..., argument n - the objects to be included in the list in the order they appear in the call
Returns
  • list object
Example
list(1, 2, 3, 4, 5)
  • Returns: (1, 2, 3, 4, 5)

pair
pair(first_object, second_object)

Creates, initializes and returns a pair object which contains two objects.

Parameters
  1. first_object - the first object of the pair
  2. second_object- the second object of the pair
Returns
  • pair object
Example
pair(true, 15)
  • Returns: (true, 15)

map
map(argument 0, argument 1, ..., argument n)

Creates, initializes and returns a map object (associative container) from any number of argument objects (each argument should be a key-value pair object).

Parameters
  1. argument 0, argument 1, ..., argument n - pairs to be included in the map (key-value pairs)
Returns
  • map object
Example
map(pair("apple", "round"), pair("brick", "blocky"))

range
range(a, b)

Creates, initializes and returns an integer range object in the interval of [a, b) which can be iterated over.

Parameters
  1. a - the first endpoint, which is included in the range
  2. b - the second endpoint, which is not included in the range
Returns
  • Range object
Example
result = 0; for (x : range(0, 3)) { result = result + x }; result
  • Returns: 6

There are other constructors, but there is rarely ever a need to explicitly call them (bool, integer, number). One other constructor that is discussed in the String section of this guide, is string, which is useful for converting other types to strings.
Standard Functions
count
count(iterable_object)

Retrieves the size (the number of elements) of an iterable object (such as list).

Parameters
  1. iterable_object - an iterable object (such as list)
Returns
  • The size (the number of elements) of an iterable object
Example
count(list("cat", "dog", "bird"))
  • Returns: 3

min_element
min_element(iterable_object, predicate)

Retrieves the smallest element of an iterable object. The order of the elements is dictated by the supplied predicate.

Parameters
  1. iterable_object - an iterable object (such as list)
  2. predicate - a function object which compares two values and returns true if the first one is less than the second. Can be a lambda function in the form of:
    [] (a, b) { ... }
Returns
  • The smallest element in the iterable object
Example
min_element(list(5, 47, 1, 20), [] (a, b) {a < b})
  • Returns: 1

max_element
max_element(iterable_object, predicate)

Retrieves the largest element of an iterable object. The order of the elements is dictated by the supplied predicate.

Parameters
  1. iterable_object - an iterable object (such as list)
  2. predicate - a function object which compares two values and returns true if the first one is less than the second. Can be a lambda function in the form of:
    [] (a, b) { ... }
Returns
  • The largest element in the iterable object
Example
max_element(list(5, 47, 1, 20), [] (a, b) {a < b})
  • Returns: 47

none_of
none_of(iterable_object, predicate)

Checks if all of the elements of an iterable object do not satisfy the condition of the supplied predicate.

Parameters
  1. iterable_object - an iterable object (such as list)
  2. predicate - a function object that takes an element as an argument and returns true if the condition is satisfied, otherwise returns false. Can be a lambda function in the form of:
    [] (x) { ... }
Returns
  • true if all of the elements do not satisfy the condition of the supplied predicate, false otherwise
Examples
none_of(list(15, 2, 80, 54), [] (x) {x > 100})
  • Returns: true
none_of(list(15, 304, 80, 54), [] (x) {x > 100})
  • Returns: false

any_of
any_of(iterable_object, predicate)

Checks if at least one of the elements of an iterable object satisfies the condition of the supplied predicate.

Parameters
  1. iterable_object - an iterable object (such as list)
  2. predicate - a function object that takes an element as an argument and returns true if the condition is satisfied, otherwise returns false. Can be a lambda function in the form of:
    [] (x) { ... }
Returns
  • true if at least on of the elements satisfies the condition of the supplied predicate, false otherwise
Examples
any_of(list(15, 2, 760, 54), [] (x) {x > 100})
  • Returns: true
any_of(list(15, 2, 80, 54), [] (x) {x > 100})
  • Returns: false

all_of
all_of(iterable_object, predicate)

Checks if all of the elements of an iterable object satisfy the condition of the supplied predicate.

Parameters
  1. iterable_object - an iterable object (such as list)
  2. predicate - a function object that takes an element as an argument and returns true if the condition is satisfied, otherwise returns false. Can be a lambda function in the form of:
    [] (x) { ... }
Returns
  • true if all of the elements of an iterable object satisfy the condition of the supplied predicate, false otherwise
Examples
any_of(list(150, 200, 760, 540), [] (x) {x > 100})
  • Returns: true
any_of(list(150, 200, 14, 540), [] (x) {x > 100})
  • Returns: false

for_each
for_each(iterable_object, action)

Calls the supplied function object for each of the elements in an iterable object.

Parameters
  1. iterable_object - an iterable object (such as list)
  2. action - a function object that takes an element as an argument. Can be a lambda function in the form of:
    [] (x) { ... }
Returns
  • Nothing
Example
for_each(list("Hello World!", "Test Message"), [] (msg) {send_text_message(msg)})
  • Displays two messages: Hello World! Test Message

find
find(iterable_object, predicate)

Finds and returns the first element of an iterable object that satisfies the condition of the supplied predicate.

Parameters
  1. iterable_object - an iterable object (such as list)
  2. predicate - a function object that takes an element as an argument and returns true if the condition is satisfied, otherwise returns false. Can be a lambda function in the form of:
    [] (x) { ... }
Returns
  • Pair object that contains:
    • at index 0: true if an element was found, false otherwise
    • at index 1: the element itself, if it was found
Example
find(list(1, 2, 3), [] (x) {x > 1})
  • Returns: (true, 2)

transform
transform(iterable_object, transformer)

Calls the supplied transformer object function for each of the elements in an iterable object. It then takes the result of that function object and adds it to the result list. In the end, the result list is returned.

Parameters
  1. iterable_object - an iterable object (such as list)
  2. transformer - a function object that takes an element as an argument and returns a new object that is then added to to the result list. If the function object does not return an object, nothing is added to the list. Can be a lambda function in the form of:
    [] (x) { ... }
Returns
    list object of the returned objects
Examples
transform(list(1, 2, 3), [] (x) {x * 2})
  • Returns: (2, 4, 6)
transform(list(1, 2, 3), [] (x) {if (x != 2) {x}})
  • Returns: (1, 3)

random
random(a, b)

Returns random numbers uniformly distributed on the interval of [a, b].

Parameters
  1. a - the first endpoint of the interval
  2. b - the second endpoint of the interval
Returns
  • A random number on the interval of [a, b]
Example
random(0, 5)
  • Returns: 0
  • Returns: 0
  • Returns: 4
  • Returns: 5

min
min(a, b)

Returns the smaller value between a and b.

Parameters
  1. a - the first value
  2. b - the second value
Returns
  • Smaller value between a and b
Example
min(8, 3)
  • Returns: 3

max
max(a, b)

Returns the larget value between a and b.

Parameters
  1. a - the first value
  2. b - the second value
Returns
  • Larget value between a and b
Example
max(8, 3)
  • Returns: 8
Game Object Constructors
resource
resource(resource_name)

Creates, initializes, and returns a game resource object.

Parameters
  1. resource_type_name - type name of the resource ("pellets", "heavypellets", "slots")
Returns
  • resource object
Example
resource("pellets")

player
player(player_name)

Creates, initializes, and returns a player object.

Parameters
  1. player_name - name of the player ("Player One", "Player Two", "Player Three", "Player Four")
Returns
  • player object
Example
player("Player One")

weapon_type
weapon_type(weapon_type_name)

Creates, initializes, and returns a weapon_type object.

Parameters
  1. weapon_type_name - name of the weapon type, which can be one of the following:
    • ""
    • "Plasma Discharger"
    • "Rotary Gun"
    • "Revolver Gun"
    • "Cannon"
    • "Grenade Launcher"
    • "Rocket Launcher"
    • "Laser"
    • "Railgun"
    • "Micro Launcher"
    • "Maintenance Tool"
    • "Pulse Laser"
    • "Ammo Printer"
    • "Artillery Gun"
    • "Fragmentation Launcher"
    • "Large Railgun"
    • "EMP Gun"
    • "Plasma Thrower"
    • "Plasma Launcher"
    • "Large Rotary Gun"
    • "Large Revolver Cannon"
    • "Large Cannon"
    • "Infrared Homing Missile Launcher"
Returns
  • weapon_type object
Example
weapon_type("Rotary Gun")

blueprint
blueprint(unit_name)

Creates, initializes, and returns a unit buleprint object.

Parameters
  1. unit_name - name of the unit; currently supports units from the Map Repository only.
Returns
  • buleprint object
Example
blueprint("Tank")

building_type
building_type(building_type_name)

Creates a building type object.

Parameters
  1. building_type_name - name of the building type, which can be one of the following:
    • "Armory"
    • "Explosives Lab"
    • "Propulsion Lab"
    • "Rocket Lab"
    • "Energy Lab"
    • "Laser Lab"
    • "Reactor"
    • "Repair Pad"
    • "Repair Bay"
    • "Resource Chute"
    • "Field Factory"
    • "Barrier"
    • "Marine Factory"
    • "Mount"
Returns
  • building_type object
Example
building_type("Armory")

weapon_spec
weapon_spec(weapon_spec_name)

Creates a weapon specification object.

Parameters
  1. weapon_spec_name - name of the specification, which can be one of the following:
    • "damage" - damage in points;
    • "cooldown" - cooldown time;
    • "maxrange" - max effective range;
    • "saferange" - safe firing range;
    • "exitspeed" - projectile exit speed (grenade/shell/plasma/rocket launchers only);
    • "ammoperpellet" - cost per ammo unit in pellets;
Returns
  • weapon_spec object
Example
weapon_spec("damage")

order_type
order_type(order_type_name)

Creates a unit order object.

Parameters
  1. order_type_name - name of the order, which can be one of the following:
    • "moveto" - move to a point;
    • "attack" - attack a target;
    • "attack-moveto" - move to a point, and attack encountered units;
    • "takeoff-land" - take off, or land;
    • "ram" - ram a point;
    • "reorient" - reorient an object;
    • "liftup" - lift-up (with a magnet) an object;
    • "drop" - drop the object;
    • "inflate-deflate" - inflate/deflate hover skirts;
    • "extend-retract-beams" - extend/retract support beams;
    • "attach" - attach to the nearest mount;
    • "detach" - detach from the mount;
Returns
  • order_type object
Example
order_type("moveto")
General Game Functions
create_timer
create_timer(interval, function_object)

Creates a timed event that is executed after the set period of time.

Parameters
  1. interval - time period after which the function object is called
  2. function_object - function object to be called
Returns
  • Nothing
Example
create_timer(5.0, [] () {send_text_message("5 seconds have passed in game!"})

set_callback
set_callback(callback_name, function_object)

Sets a global game callback.

Parameters
  1. callback_name - global callback name, which can be one of the following:
    • "destruction" - this callback will called every time any unit has been destroyed; the function object in this case has the signature of:
      callback_function(destroyed_unit)
    • "kill" - this callback will be called every time any unit destroys another unit; the function object in this case has the signature of:
      callback_function(destroyed_unit, killing_unit)
  2. function_object - function object to be called
Returns
  • Nothing
Example
set_callback( "destruction", [] (unit) { send_text_message(get_unit_name(unit) + " has just been destroyed!"); } )

elapsed
elapsed()

Returns the time that has passed since the script started.

Parameters
  • None
Returns
  • time elapsed since the script was first started
Example
five_seconds_passed = elapsed() > 5

start_script
start_script(script_object)

Starts a script.

Parameters
  1. script_object - script object to be started
Returns
  • Nothing
Example
start_script(other_script)

restart
restart()

Instructs the script to restart itself once it finishes executing the action clause (must be called from the action clause).

Parameters
  • None
Returns
  • Nothing
Example
restart()

this_location
this_location()

Gets the location object of the caller.

Parameters
  • None
Returns
  • Location object

tracked_units
Variant 1:
tracked_units()
Variant 2:
tracked_units(location_object)

Retrieves the unit list tracked (units inside the circle) by:

  • Variant 1: this location.
  • Variant 2: another, specified location.

Parameters
Variant 1.
  • None
Variant 2.
  • location_object - location object
Returns
  • Unit object list

linked_units
Variant 1:
linked_units()
Variant 2:
linked_units(location_object)

Retrieves the unit list linked to:

  • Variant 1: this location.
  • Variant 2: another, specified location.

Parameters
Variant 1.
  • None
Variant 2.
  • location_object - location object
Returns
  • Unit object list

send_text_message
send_text_message(message)

Sends a text message directly to the main message roll.

Parameters
  1. message - text message
Returns
  • Nothing

send_transmission
send_transmission(transmission)

Sends a standard game transmission (message), which is displayed on screen.

Parameters
  1. transmission - transmission text
Returns
  • Nothing
Player Functions
get_unit_count
get_unit_count(player)

Returns the current number of units of a player.

Parameters
  1. player - player object
Returns
  • Number of units

fund_player
fund_player(player, resource_list)

Give the set amount of resources to a player.

Parameters
  1. player - target player
  2. resource_list - list of resource object and number pairs
Returns
  • Nothing
Example
fund_player(player("Player One"), list(pair(resource("pellets"), 200), pair(resource("heavypellets"), 50)))

can_charge_player
can_charge_player(player, resource_list)

Checks if a player has enough resources.

Parameters
player - target player
  1. resource_list - list of resource object and number pairs
Returns
  • true if the player has enough resources for the operation, false otherwise
Example
can_charge_player(player("Player One"), list(pair(resource("pellets"), 200), pair(resource("heavypellets"), 50)))

charge_player
charge_player(player, resource_list)

Subtracts resources from a player.

Parameters
  • player - target player
  • resource_list - list of resource object and number pairs e.g.
Returns
  • Nothing
Example
charge_player(player("Player One"), list(pair(resource("pellets"), 200), pair(resource("heavypellets"), 50)))

get_players
get_players()

Retrieves the list of players participating in the game

Parameters
  • None
Returns
  • Player list

get_teams
get_teams()

Retrieves the list of teams participating in the game.

Parameters
  • None
Returns
  • Team list

declare_defeat
declare_defeat(player)

Declare the specified player as defeated.

Notes: Subsequent calls to this function are permitted and will affect no changes.

Parameters
  1. player - defeated player
Returns
  • Nothing

declare_victory
declare_victory(player)

Declare the specfied player as victorious.

Notes: Subsequent calls to this function are permitted and will affect no changes

Parameters
  1. player - victorious player
Returns
  • Nothing

are_allies
are_allies(first_player, second_player)

Checks if the specified players are allies.

Parameters
  1. first_player - first player object
  2. second_player - second player object
Returns
  • true if the players are allies, false otherwise

are_neutral
are_neutral(first_player, second_player)

Checks if the specified players are neutral towards each other.

Parameters
  1. first_player - first player object
  2. second_player - second player object
Returns
  • true if the players are neutral towards each other, false otherwise

are_enemies
are_enemies(first_player, second_player)

Checks if the specified players are enemies.

Parameters
  1. first_player - first player object
  2. second_player - second player object
Returns
  • true if the players are enemies, false otherwise
General Object Functions
General object functions currently work with:
  • Units;
  • Builpads;
  • Weapons;
  • Script Objects.

is_unit
is_unit(object)

Checks if an object is a unit.

Parameters
  1. object - the object to be checked
Returns
  • true if the object is a unit, false otherwise
Example
// Generate a list of units from a list of generic objects. units = list(); for (object : objects) { if (is_units(object)) { units = units + object; } }

is_buildpad
is_buildpad(object)

Checks if an object is a build-pad.

Parameters
  1. object - the object to be checked
Returns
  • true if the object is a unit, false otherwise
Example
// Generate a list of build-pads from a list of generic objects. buildpads = list(); for (object : objects) { if (is_buildpad(object)) { buildpads = buildpads + object; } }

set_user_object
set_user_object(unit, user_object)

Sets the user object of a unit.

Parameters
  1. unit - unit object
  2. user_object - user object, which can be any object
Returns
  • Nothing

get_user_object
get_user_object(unit)

Retrieves the user object of a unit.

Parameters
  1. unit - unit object
Returns
  • User object stored by the unit
Unit Functions
get_unit_name
get_unit_name(unit)

Gets the name of a unit.

Parameters
  1. unit - unit object
Returns
  • The name of the unit

get_unit_player
get_unit_player(unit)

Gets the player to which a unit belongs to.

Parameters
  1. unit - unit object
Returns
  • Player object

get_health
get_health(unit)

Gets the current health of a unit.

Parameters
  1. unit - unit object
Returns
  • The health of the unit

get_max_health
get_max_health(unit)

Gets the maximum health of a unit.

Parameters
  1. unit - unit object
Returns
  • The maximum health of the unit

get_energy
get_energy(unit)

Gets the current energy of a unit.

Parameters
  1. unit - unit object
Returns
  • The energy of the unit

get_max_energy
get_max_energy(unit)

Gets the maximum energy of a unit.

Parameters
  1. unit - unit object
Returns
  • The maximum energy of the unit

is_grounded
is_grounded(unit)

Checks if the unit is grounded.

Parameters
  1. unit - unit object
Returns
  • true if the unit is grounded, false otherwise (flying)

is_submerged
is_submerged(unit)

Checks if the unit is submerged in water.

Parameters
  1. unit - unit object
Returns
    true if the unit is submerged, false otherwise

is_anchored
is_anchored(unit)

Checks if the unit is anchored to an anchor.

Parameters
  1. unit - unit object
Returns
  • true if the unit is anchored, false otherwise

can_drive
can_drive(unit)

Checks if the unit can travel on ground or water. This includes wheeled units, treaded units, walkers, watercraft, and hovercraft.

Parameters
  1. unit - unit object
Returns
  • true if the unit can travel on ground or water, false otherwise

can_fly
can_fly(unit)

Checks if the unit can fly.

Parameters
  1. unit - unit object
Returns
  • true if the unit can fly, false otherwise

has_magnet
has_magnet(unit)

Checks if the unit has a magnet.

Parameters
  1. unit - unit object
Returns
  • true if the unit has a magnet, false otherwise

can_attack
can_attack(unit)

Checks if the unit can attack (in general).

Parameters
  1. unit - unit object
Returns
  • true if the unit can attack, false otherwise

can_heal
can_heal(unit)

Checks if the unit can heal other units.

Parameters
  1. unit - unit object
Returns
  • true if the unit can heal other units, false otherwise

can_restock
can_restock(unit)

Checks if the unit can restock the ammo of other units.

Parameters
  1. unit - unit object
Returns
  • true if the unit can restock the ammo of other units, false otherwise

can_emp
can_emp(unit)

Checks if the unit has at least one EMP weapon.

Parameters
  1. unit - unit object
Returns
  • true if the unit has at least one EMP weapon, false otherwise

has_weapons
has_weapons(unit)

Checks if the unit has weapons.

Parameters
  1. unit - unit object
Returns
  • true if the unit has weapons, false otherwise

get_weapons
get_weapons(unit)

Retrieves the weapon list of a unit.

Parameters
  1. unit - unit object
Returns
  • Weapon list

get_tools
get_tools(unit)

Retrieves the tool list (nano-sprays and ammo-printers) of a unit.

Parameters
  1. unit - unit object
Returns
  • Weapon list

get_cost
get_cost(unit)

Retrieves the cost list of a unit.

Parameters
  1. unit - unit object
Returns
  • Cost list (not including the slots)

set_damageable
set_damageable(unit, damageable)

Retrieves the weapon list of a unit.

Parameters
  1. unit - unit object
  2. damageable - true if the unit is damageable, false otherwise\
Returns
  • Nothing

inflict_damage
inflict_damage(unit, damage)

Inflicts the set amount of damage to the unit.

Parameters
  1. unit - unit object
  2. damage - amount of damage
Returns
  • Nothing

heal
heal(unit, hit_points)

Heals the unit by the set amount of hit points.

Parameters
  1. unit - unit object
  2. hit_points - amount of hit points to restore
Returns
  • Nothing

set_energy
set_energy(unit, energy)

Sets the energy of a unit.

Parameters
  1. unit - unit object
  2. energy - energy level in percentage of the maximum capacity (0-100)
Returns
  • Nothing

move_to
move_to(unit, location)

Instructs the unit to move to the specified location.

Parameters
  1. unit - unit object
  2. location - location object
Returns
  • Nothing


attack_move_to
attack_move_to(unit, location)

Instructs the unit to move to the specified location (while attacking encountered enemy units).

Parameters
  1. unit - unit object
  2. location - location object
Returns
  • Nothing

attack
attack(unit, target)

Instructs the unit to attack a target.

Parameters
  1. unit - unit object
  2. target - target unit
Returns
  • Nothing

transfer_to
transfer_to(unit, player)

Transfers the ownership of a unit to another player.

Parameters
  1. unit - unit object
  2. player - new owner of the unit
Returns
  • Nothing

give_order
give_order(unit, order_type, [optional] target)

Give an order to a unit.

Parameters
  1. unit - unit object
  2. order_type - order type object
  3. target - target object (some orders (like takeoff-land) don't require targets)
Returns
  • Nothing
Examples
give_order(unit, order_type("attack"), enemy_unit);
give_order(flying_unit, order_type("takeoff-land"));
// Lift-up a unit, and drop it off at a location. // NOTE: Orders are put in a queue, so they need to given in reverse order in this case. give_order(unit, order_type("drop"), target_location); give_order(unit, order_type("liftup"), target_unit);

cancel_orders
cancel_orders(unit)

Cancels all orders (active and pending) of a unit.

Parameters
  1. unit - unit object
Returns
  • Nothing
AI Functions
guard_this
guard_this(unit, presence_name)

Orders a unit to guard this location (location of the calling script object).

Guarding units don't retreat from the location (generally stay inside the circle of the location).
Note: only works for AI bot units.

Parameters
  1. unit - unit object
  2. presence_name - name of a presence location maintained by an AI bot. Can be an empty string "" if no presence location is associated with this guard order
Returns
  • Nothing

guard_location
guard_location(unit, location, presence_name)

Orders a unit to guard a location.

Guarding units don't retreat from the location (generally stay inside the circle of the location).
Note: only works for AI bot units.

Parameters
  1. unit - unit object
  2. location - location object (another script object)
  3. presence_name - name of a presence location maintained by an AI bot. Can be an empty string "" if no presence location is associated with this guard order
Returns
  • Nothing
Weapon Functions
get_weapon_type
get_weapon_type(weapon)

Retrieves the weapon type of a weapon.

Parameters
  1. weapon - weapon object
Returns
  • weapon_type object
Examples
// Retrieve the type of the first weapon of a unit. if (has_weapons(unit)) { unit_weapons = get_weapons(unit); get_weapon_type(unit_weapons[0]); }
// Check if a unit has at least one rotary gun. if (any_of(get_weapons(unit), [] (weapon) {get_weapon_type(weapon) == weapon_type("Rotary Gun")})) { send_transmission("This unit has a rotary gun!") }

get_ammo
get_ammo(weapon)

Retrieves the current amount of ammo of a weapon.

Parameters
  1. weapon - weapon object
Returns
  • Ammo amount
Example
// Retrieve the ammo amount of the first weapon of a unit. if (has_weapons(unit)) { unit_weapons = get_weapons(unit); get_ammo(unit_weapons[0]); }

get_max_ammo
get_max_ammo(weapon)

Retrieves the maximum amount of ammo of a weapon.

Parameters
  1. weapon - weapon object
Returns
  • Max ammo amount

set_ammo
set_ammo(weapon, ammo)

Sets the amount of ammo of a weapon.

Parameters
  1. weapon - weapon object
  2. ammo - ammo amount
Returns
  • Nothing
Example
// Restock the ammo of every weapon of a unit. for(weapon : get_weapons(unit)) { set_ammo(weapon, get_max_ammo(weapon)); }

set_max_ammo
set_max_ammo(weapon, max_ammo)

Sets the maximum amount of ammo of a weapon.

Parameters
  1. weapon - weapon object
  2. max_ammo - max ammo amount
Returns
  • Nothing
Example
// Upgrade the maximum ammo capacity of every weapon of a unit. for(weapon : get_weapons(unit)) { set_max_ammo(weapon, get_max_ammo(weapon) + 50); }

set_weapon_spec
set_weapon_spec(weapon, weapon_spec, value)

Sets a weapon specification of a weapon.

Parameters
  1. weapon - weapon object
  2. weapon_spec - weapon_spec object
  3. value - value of the spec
Returns
  • Nothing
Example
// Set the damage output of a weapon to 10. set_weapon_spec(weapon, weapon_spec("damage"), 10);
Spawn Functions
spawn_unit
spawn_unit(blueprint, weapon_type, player, location)

Spawns a new unit.

Parameters
  1. blueprint - blueprint object that describes the unit
  2. weapon_type - weapon type object that is used for primary weapons of the unit
  3. player - player to which the newly spawned unit will belong to
  4. location - spawn location
Returns
  • unit object
Example
spawn_unit( blueprint("Penguin"), weapon_type("Rotary Gun"), player("Player One"), this_location() );

can_spawn_unit
can_spawn_unit(blueprint, player)

Checks if a unit can be spawned.

Parameters
  1. blueprint - blueprint object that describes the unit
  2. player - player to which the newly spawned unit will belong to
Returns
  • true if the unit can be spawned, false otherwise
Example
if (can_spawn_unit(blueprint("Penguin"), player("Player One"))) { ... }

spawn_building
spawn_building(building_type, buildpad)

Spawns a building on the specified build-pad.

Parameters
  1. building_type - building type object that describes the building
  2. buildpad - location of the spawned building
Returns
  • Nothing
Example
buildpad = linked_objects()[0]; spawn_building("Armory", buildpad);

destroy_building
destroy_building(buildpad)

Destroys the building at the specified build-pad.

Parameters
  1. buildpad - location of the spawned building
Returns
  • Nothing

has_building
has_building(buildpad)

Checks if a build-pad has a building deployed.

Parameters
  1. buildpad - location of the spawned building
Returns
  • true if the build-pad has a building deployed, false otherwise
Objective Functions
set_objective_text
set_objective_text(player, objective_name, object_text)

Initializes an objective, and set its text.

Parameters
  1. player - player object
  2. objective_name - name of the objective
  3. object_text - text of the objective
Returns
    Nothing
Example
set_objective_text(player("Player One"), "survive_objective", "Survive for 15 minutes")

set_objective_status
set_objective_status(player, objective_name, status)

Sets the status of an objective.

Parameters
  1. player - player object
  2. objective_name - name of the objective
  3. object_status - status of an objective ("completed")
Returns
    Nothing
Example
set_objective_status(player("Player One"), "survive_objective", "completed")
1 Comments
< >
Ejcreeper 24 Oct, 2020 @ 8:58am 
what do they mean by dynamic