User Tools

Site Tools


script_syntax

This is an old revision of the document!


Script Syntax


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.

Statement Syntax

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.

Function Calls

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

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.

OperatorDescription
=Places the value on the right-hand side into the variable on the left-hand side.
+=Adds the value on the right-hand side to the current value of the variable on the left-hand side, then places the resulting value back into the variable.
-=Subtracts the value on the right-hand side from the current value of the variable on the left-hand side, then places the resulting value back into the variable.
*=Multiplies the value on the right-hand side by the current value of the variable on the left-hand side, then places the resulting value back into the variable.
/=Divides the value on the right-hand side by the current value of the variable on the left-hand side, then places the resulting value back into the variable.

Examples:

rand_num = random(1, 20)
entity["sign_01"].property["message"] = "I am a sign!"
player.stat["max_hp"] += 5

Control Statements

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 Statement

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 one or more set of “elseif” conditions, optionally the “else” keyword followed by any statements to execute if none of the previous conditions were 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!");
   self.property["locked"] = false
else
   display_message("You need a gold key to unlock this door.")
end
rand_num = random(1, 20);
if rand_num > 15 then
   give_item("ITEM_0001")
elseif rand_num > 10 then
   give_item("ITEM_0002")
else
   give_item("ITEM_0003")
end

While Loop

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 Loop

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.

Example:

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

Deals 5 damage to each entity in the “slimes” group.

for i in range(1, 4) do
   give_item("ITEM_000" + "${i}", i)
end

Gives the following items to the player: one of “ITEM_0001”, two of “ITEM_0002”, and three of “ITEM_0003”.

Data Types

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.

TypeExamples
String“Hello World!”, “This is a string.”
Decimal17, 3.14159
Booleantrue, false
Coordinatecoord[1, 2, 3], entity[“slime_01”].coord
Colorcolor[255, 0, 255]
Entityplayer, self, entity[“sign”]
Arraygroup[“room_01”], self.groups
Nullnull

Arrays

An array is simply a list of values, such as the entities belonging to a group, the tags assigned to a model, or even a custom set of values defined directly within a script. Refer to the Array documentation for more examples.

TypeDescriptionExample
Entities in a GroupList of all entities assigned to a map group.group[“slimes”], group[“trap_tiles”]
Groups for an EntityList of all group to which an entity belongs.self.groups, entity[“some_id”].groups
Tags for an EntityList of tags assigned to an entity's model (see Model Properties).player.tags, initiator.tags
User-DefinedList of custom values declared with the “array” syntax.array[“A”, “B”, “C”]

The values in an array can be iterated through using a “For” loop. You can also check to see if a particular value exists within an array using the “contains” operator in a conditional expression. See below for some example script usages.

Examples:

for slime_entity in group["slimes"] do
   damage_entity(slime_entity, 2)
end

Deals 2 damage to all entities in the “Slimes” group.

if player.tags contains "human" then
   display_message("No humans allowed!")
end

Displays the message if the player model's tag list contains the “human” tag.

dungeon_map_list = array["room1", "room2", "room3", "room4"];
load_map(dungeon_map_list[random(0, 3)], coord[0, 0, 0]);
item_list = array["ITEM_0001", "ITEM_0005", "ITEM_0008"];
give_item(item_list[random(0, 2)], 5)

Loads a random map from the “dungeon_map_list” array variable (“room1” through “room4”), then gives the player 5 of a random item from the “item_list array variable.

Null

The “null” keyword represents the absence of a value. It can be used to check whether or not a variable has been assigned a value yet, or if a reference to an entity is valid.

Examples:

if x == null then
   print("Variable x is not yet defined or has no value.")
end
if entity["some_id"] != null then
   remove_entity(entity["some_id"])
end
set_player_movement_locked(true);
target_tile = tile[7, 8, 0];
if target_tile == null then
   print("Target tile doesn't exist.")
else
   move_player(target_tile)
end

Functions

Action Functions

Action functions are used to trigger certain actions or events in your game, such as loading a map, playing an animation, or healing a character. These functions allow you to control the flow of your game and help give life to its world! A full list of the available functions can be found on the scripting reference page.

Random Number

The random number function generates an integer value within the given range (inclusive of the minimum and maximum value). It can be used in scripts anywhere a numeric value is expected or allowed.

Examples:

wait(random(1, 5))

Waits for a random amount of time between 1 and 5 seconds.

if random(0, 100) <= 25 then
  give_item("ITEM_0001")
else
  give_item("ITEM_0002")
end

Gives either ITEM_0001 or ITEM_0002 to the player, with a 25% chance that the item will be ITEM_0001.

Inverse

The inverse function returns the inverse, or opposite, of a value. It can be used in scripts anywhere a value of the original type is expected or allowed. Refer to the table below for a list of the supported data types and examples of resulting values.

TypeExample
Numberinverse(17) will return -17
Booleaninverse(true) will return false
Coordinateinverse(coord[-3, -4, 5] will return coord[3, 4, -5]
Colorinverse(color[128, 255, 0] will return color[127, 0, 255]
Cardinal Directioninverse(NORTH) will return SOUTH
Navigation Typeinverse(WALK_AND_INTERACT) will return PENDING

Examples:

rotate_player_to_direction(inverse(entity["goblin"].direction))

Rotates the player character to be facing in the opposite direction that the goblin is facing.

script_syntax.1581915243.txt.gz · Last modified: 2020/02/16 20:54 by justin