The scripting language in RPG in a Box is a simple imperative language designed specifically for the engine. The syntax is useful to know for creating quick scripts for tiles and objects in the Map Editor or for script nodes in the Dialogue Editor.

Statements are the basic building blocks of the scripting language and represent a particular action to be taken. A statement can be either a function call, assignment of a value to a variable/property, or control statement (i.e. “If” statement, “While” loop, or “For” loop). Multiple statements must be separated from each other using semicolons (;). Whitespace between statements is ignored, although newlines and indentation are recommended for ease of reading.

Calling a function instructs the game to execute some piece of logic, for example to display a message to the player or to move the camera to a specific location. See Scripting Reference for a comprehensive list of built-in functions that can be called.

Examples:

display_message("Hello World!")

lock_camera();
move_camera("cam_position_01");
start_dialogue("cutscene_01")

Assignment statements allow you to assign values to variables, properties, stats, etc. You can use the “=” operator to place a value directly into a variable or, when working with numeric values, one of the four compound operators to first perform a calculation and then place the resulting value back into variable.

Examples:

rand_num = random(1, 20)

entity["sign_01"].property["message"] = "I am a sign!"

player.stat["max_hp"] += 5

Control statements affect the flow of your script, either by branching or looping through a set of statements multiple times. These include “If” statements, “While” loops, and “For” loops.

If statements allow you to branch your logic according to the results of a condition being evaluated. In the order listed, it consists of the keyword “if”, a condition to check, the “then” keyword, any statements to execute if the condition is true, optionally the “else” keyword followed by any statements to execute if the condition is not true, and lastly the “end” keyword. See Conditional Expression for more information and a list of valid comparison operators that can be used in the condition.

Examples:

if global.property["gem_count"] > 5 then
   display_message("You've collected more than 5 gems!")
end

if player.inventory contains "ITEM_0001" then
   remove_item("ITEM_0001");
   display_message("The door is now unlocked!");
   set_entity_property(self, "locked", false)
else
   display_message("You need a gold key to unlock this door.")
end

While loops allow you to execute a set of statements repeatedly as long as a particular condition evaluates to true. In the order listed, it consists of the keyword “while”, a condition to check, the “do” keyword, any statements to execute if the condition is true, and lastly the “end” keyword. See Conditional Expression for more information and a list of valid comparison operators that can be used in the condition.

Example:

display_message("You entered a pool of regeneration!");
global.property["regen_hp"] = true;
while global.property["regen_hp"] do
   player.stat["hp"] += 1;
   wait(2)
end

For loops allow you execute a set of statements a given number of times based on an iterable expression (e.g. an array of values). In the order listed, it consists of the keyword “for”, a variable name that the current value will be assigned to, the “in” keyword, an expression to iterate though, the “do” keyword, any number of statements to execute, and lastly the “end” keyword. As array functionality is still in development, there are currently only a small number of uses cases for “For” loops.

Example:

display_message("The explosion damages all of the enemies!");
for slime_entity in group["slimes"] do
   damage_entity(slime_entity, 5)
end

There are several data types available in the scripting language used to represent a value or, in the case of arrays, a collection/list of values. These values can be stored in variables or properties (see assignment statements above, or Set Global Property and Set Entity Property), and can be compared to another value of the same type using a conditional expression.