User Tools

Site Tools


script_syntax

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision
Previous revision
script_syntax [2020/02/06 19:34] justinscript_syntax [2023/11/06 14:13] (current) justin
Line 2: Line 2:
 ---- ----
  
-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 script|quick scripts]] for tiles and objects in the [[Map Editor]] or for script nodes in the [[Dialogue Editor]].+**Bauxite**, the scripting language for RPG in a Boxis designed specifically for the engine. The syntax for Bauxite is useful to know for creating [[quick script|quick scripts]] for tiles and objects in the [[Map Editor]] or for script nodes in the [[Dialogue Editor]].
  
 =====Statement Syntax===== =====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.+Statements are the basic building blocks of Bauxite 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===== =====Function Calls=====
Line 12: Line 12:
 **Examples:** **Examples:**
 <code bauxite> <code bauxite>
-display_message("Hello World!")+display_message("Hello, world!");
 </code> </code>
 <code bauxite> <code bauxite>
 lock_camera(); lock_camera();
 move_camera("cam_position_01"); move_camera("cam_position_01");
-start_dialogue("cutscene_01")+start_dialogue("cutscene_01");
 </code> </code>
  
Line 32: Line 32:
 **Examples:** **Examples:**
 <code bauxite> <code bauxite>
-rand_num = random(1, 20)+$rand_num = random(1, 20);
 </code> </code>
 <code bauxite> <code bauxite>
-entity["sign_01"].property["message"] = "I am a sign!"+entity["sign_01"].property["message"] = "I am a sign!";
 </code> </code>
 <code bauxite> <code bauxite>
-player.stat["max_hp"] += 5+player.stat["max_hp"] += 5;
 </code> </code>
  
Line 50: Line 50:
 <code bauxite> <code bauxite>
 if global.property["gem_count"] > 5 then if global.property["gem_count"] > 5 then
-   display_message("You've collected more than 5 gems!"+   display_message("You've collected more than 5 gems!"); 
-end+end;
 </code> </code>
 <code bauxite> <code bauxite>
Line 57: Line 57:
    remove_item("ITEM_0001");    remove_item("ITEM_0001");
    display_message("The door is now unlocked!");    display_message("The door is now unlocked!");
-   self.property["locked"] = false+   self.property["locked"] = false;
 else else
-   display_message("You need a gold key to unlock this door."+   display_message("You need a gold key to unlock this door."); 
-end+end;
 </code> </code>
 <code bauxite> <code bauxite>
-rand_num = random(1, 20); +$rand_num = random(1, 20); 
-if rand_num > 15 then +if $rand_num > 15 then 
-   give_item("ITEM_0001"+   give_item("ITEM_0001"); 
-elseif rand_num > 10 then +elseif $rand_num > 10 then 
-   give_item("ITEM_0002")+   give_item("ITEM_0002");
 else else
-   give_item("ITEM_0003"+   give_item("ITEM_0003"); 
-end+end;
 </code> </code>
  
Line 82: Line 82:
 while global.property["regen_hp"] do while global.property["regen_hp"] do
    player.stat["hp"] += 1;    player.stat["hp"] += 1;
-   wait(2) +   wait(2); 
-end+end;
 </code> </code>
  
 ====For Loop==== ====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. As [[array]] functionality is still in development, there are currently only a small number of uses cases for "For" loops.+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:**+**Examples:**
 <code bauxite> <code bauxite>
 display_message("The explosion damages all of the enemies!"); display_message("The explosion damages all of the enemies!");
-for slime_entity in group["slimes"] do +for $slime_entity in group["slimes"] do 
-   damage_entity(slime_entity, 5) +   damage_entity($slime_entity, 5); 
-end+end
 +</code> 
 +Deals 5 damage to each [[entity]] in the "slimes" [[groups|group]]. 
 +<code bauxite> 
 +$item_list = array["ITEM_0001", "ITEM_0002", "ITEM_0003"]; 
 +for $item_id in $item_list do 
 +   give_item($item_id); 
 +end; 
 +</code> 
 +Gives one of every item in $item_list to the player by iterating over the entire [[array]]. 
 +<code bauxite> 
 +for $i in range(1, 4) do 
 +   give_item("ITEM_000" + str($i), $i); 
 +end;
 </code> </code>
 +Gives the following items to the player: one of ITEM_0001, two of ITEM_0002, and three of ITEM_0003.
  
 =====Data Types===== =====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]].+There are several data types available in the scripting language used to represent a value or, in the case of an array or codex, 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]].
  
 ^Type^Examples^ ^Type^Examples^
-|[[String]]|"Hello World!", "This is a string."+|[[String]]|"Hello, world!", "This is a string."
-|[[Decimal]]|17, 3.14159|+|[[Number]]|17, 3.14159|
 |[[Boolean]]|true, false| |[[Boolean]]|true, false|
 |[[Coordinate]]|coord[1, 2, 3], entity["slime_01"].coord| |[[Coordinate]]|coord[1, 2, 3], entity["slime_01"].coord|
 |[[Color]]|color[255, 0, 255]| |[[Color]]|color[255, 0, 255]|
 |[[Entity]]|player, self, entity["sign"]| |[[Entity]]|player, self, entity["sign"]|
-|[[Array]]|group["room_01"], self.groups|+|[[Array]]|array["A", "B", "C"], group["room_01"], self.groups
 +|[[Codex]]|codex["id": "ITEM_0001", "count": 5]| 
 +|Null|null|
  
-====Arrays==== +====Array==== 
-An array is simply a list of values, such as the [[entity|entities]] belonging to a [[groups|group]], the tags assigned to a model, or even a custom set of values defined directly within a [[script]].+An [[array]] is simply a list of values, such as the [[entity|entities]] belonging to a [[groups|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, as well as information about the available functions that can be used to manipulate an [[array|array's]] values.
 ^Type^Description^Example^ ^Type^Description^Example^
 +|User-Defined|List of custom values declared with the "array" syntax.|array["A", "B", "C"]|
 +|Range|List of integers based on a set of parameters.|range(1, 5)|
 |Entities in a Group|List of all [[entity|entities]] assigned to a map [[groups|group]].|group["slimes"], group["trap_tiles"]| |Entities in a Group|List of all [[entity|entities]] assigned to a map [[groups|group]].|group["slimes"], group["trap_tiles"]|
 |Groups for an Entity|List of all [[groups|group]] to which an [[entity]] belongs.|self.groups, entity["some_id"].groups| |Groups for an Entity|List of all [[groups|group]] to which an [[entity]] belongs.|self.groups, entity["some_id"].groups|
 |Tags for an Entity|List of tags assigned to an [[entity|entity's]] model (see [[Model Properties]]).|player.tags, initiator.tags| |Tags for an Entity|List of tags assigned to an [[entity|entity's]] model (see [[Model Properties]]).|player.tags, initiator.tags|
-|User-Defined|List 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 "containsoperator in a [[conditional expression]]. See below for some example script usages.+The values in an [[array]] can be iterated through using a "For" loop, or you can get the value at a specific position within the [[array]] using the index syntax //my_array[x]//, where "my_arrayis an [[array]] variable and "x" is an integer ranging from 0 to one less than the [[array]] size. See below for some example [[script]] usages.
  
-====Examples:====+**Examples:**
 <code bauxite> <code bauxite>
-for slime_entity in group["slimes"] do +for $slime_entity in group["slimes"] do 
-   damage_entity(slime_entity, 2) +   damage_entity($slime_entity, 2); 
-end+end;
 </code> </code>
-Deals 2 damage to all entities in the "Slimes" [[groups|group]].+Deals 2 damage to all entities in the "slimes" [[groups|group]].
 <code bauxite> <code bauxite>
 if player.tags contains "human" then if player.tags contains "human" then
-   display_message("No humans allowed!"+   display_message("No humans allowed!"); 
-end+end;
 </code> </code>
 Displays the message if the player model's tag list contains the "human" tag. Displays the message if the player model's tag list contains the "human" tag.
 <code bauxite> <code bauxite>
-dungeon_map_list = array["room1", "room2", "room3", "room4"]; +$dungeon_map_list = array["room1", "room2", "room3", "room4"]; 
-load_map(dungeon_map_list[random(0, 3)], coord[0, 0, 0]); +load_map($dungeon_map_list[random(0, 3)], coord[0, 0, 0]); 
-item_list = array["ITEM_0001", "ITEM_0005", "ITEM_0008"]; +$item_list = array["ITEM_0001", "ITEM_0005", "ITEM_0008"]; 
-give_item(item_list[random(0, 2)], 5)+give_item($item_list[random(0, 2)], 5)
 +</code> 
 +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. 
 + 
 +====Codex==== 
 +A [[codex]] is a data type with its data stored as key/value pairs. The key is a unique [[string]] and acts as a lookup for its corresponding value within the codex, similar to a dictionary. See [[Codex]] for more information and some scripting examples. 
 + 
 +====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:** 
 +<code bauxite> 
 +if x == null then 
 +   print("Variable x is not yet defined or has no value."); 
 +end; 
 +</code> 
 +<code bauxite> 
 +if entity["some_id"] != null then 
 +   remove_entity(entity["some_id"]); 
 +end; 
 +</code> 
 +<code bauxite> 
 +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;
 </code> </code>
-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. 
  
 =====Functions===== =====Functions=====
Line 148: Line 192:
 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. 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:====+**Examples:**
 <code bauxite> <code bauxite>
-wait(random(1, 5))+wait(random(1, 5));
 </code> </code>
 Waits for a random amount of time between 1 and 5 seconds. Waits for a random amount of time between 1 and 5 seconds.
Line 156: Line 200:
 <code bauxite> <code bauxite>
 if random(0, 100) <= 25 then if random(0, 100) <= 25 then
-  give_item("ITEM_0001")+  give_item("ITEM_0001");
 else else
-  give_item("ITEM_0002"+  give_item("ITEM_0002"); 
-end+end;
 </code> </code>
 Gives either ITEM_0001 or ITEM_0002 to the player, with a 25% chance that the item will be ITEM_0001. Gives either ITEM_0001 or ITEM_0002 to the player, with a 25% chance that the item will be ITEM_0001.
 +
 +====Dice Rolls====
 +Bauxite also supports a dice notation similar to that of Dungeons & Dragons for generating random numbers. Specifically, **XdY**, where **X** is the number of dice to roll and **Y** is how many sides the dice have.
 +
 +**Examples:**
 +<code bauxite>
 +$result = 1d20;
 +</code>
 +Gives the result of rolling a twenty-sided die.
 +
 +<code bauxite>
 +$result = 2d8 + 1d6;
 +</code>
 +Gives the result of rolling two eight-sided dice and one six-sided die.
 +
 +====Range====
 +The **range** function generates an [[array]] of integers based on the supplied parameters. With one parameter, say "a", it generates a list starting with 0 and ending with one less than "a". With two parameters, say "a" and "b", it generates a list starting with "a" and ending with one less than "b". With three parameters, say "a", "b", and "c", it generates a list starting with "a", incrementing by "c", and ending before "b" is reached.  See below for some examples of each scenario.
 +
 +**Examples:**
 +<code bauxite>
 +range(5)
 +</code>
 +List of integers from 0 to, but not including, 5 (i.e. 0, 1, 2, 3, 4).
 +
 +<code bauxite>
 +range(12, 15)
 +</code>
 +List of integers from 12 to, but not including, 15 (i.e. 12, 13, 14).
 +
 +<code bauxite>
 +range(0, 9, 2)
 +</code>
 +List of integers from 0 to, but not including, 9, with an increment of 2 (i.e. 0, 2, 4, 6, 8).
 +
 +<code bauxite>
 +range(5, 0, -1)
 +</code>
 +List of integers from 5 to, but not including, 0, with an increment of -1 (i.e. 5, 4, 3, 2, 1).
 +
 +====Duplicate====
 +The **duplicate** function creates a unique copy of an [[array]] or [[codex]]. Since the copy is unique, you can modify its data without affecting the original [[array]] or [[codex]].
 +
 +With the code below where the value in **$items** is simply stored into another variable, in this case **$items_copy**, the new variable or property will only contain a reference to the original [[codex]], so any changes to one will affect the other (i.e. both "print" statements will display 10).
 +<code bauxite>
 +$items = codex["id": "ITEM_0001", "count": 5];
 +$items_copy = $items;
 +$items_copy["count"] = 10;
 +print($items["count"]);
 +print($items_copy["count"]);
 +</code>
 +
 +In the example below, a copy of **$items** is made using the "Duplicate" function. Since it's now a unique copy of the [[codex]], if the "count" key is changed to 10 for the **$items_copy** variable, the original **$items** [[codex]] will remain unchanged. Therefore, the first "print" statement will display 5, while the second "print" statement will display 10.
 +<code bauxite>
 +$items = codex["id": "ITEM_0001", "count": 5];
 +$items_copy = duplicate($items);
 +$items_copy["count"] = 10;
 +print($items["count"]);
 +print($items_copy["count"]);
 +</code>
  
 ====Inverse==== ====Inverse====
Line 174: Line 277:
 |[[navigation_and_interaction|Navigation Type]]|inverse(WALK_AND_INTERACT) will return PENDING| |[[navigation_and_interaction|Navigation Type]]|inverse(WALK_AND_INTERACT) will return PENDING|
  
-====Examples:====+**Examples:**
 <code bauxite> <code bauxite>
-rotate_player_to_direction(inverse(entity["goblin"].direction))+rotate_player_to_direction(inverse(entity["goblin"].direction));
 </code> </code>
 Rotates the player character to be facing in the opposite direction that the goblin is facing. Rotates the player character to be facing in the opposite direction that the goblin is facing.
  
 +====String/Number Conversion====
 +There are two functions available for converting between a [[string]] and a [[number]]: **str** and **num**. When a variable or property is known to contain a numeric value and you need to concatenate it with a [[string]], you must first convert the [[number]] to a [[string]] using the **str** function. Similarly, if you have a [[string]] and you know it contains a valid numeric value, you can convert it to a [[number]] for use in arithmetic expressions using the **num** function.
 +
 +**Examples:**
 +<code bauxite>
 +$counter += 1;
 +$new_tile_id = "tile" + str($counter);
 +</code>
 +<code bauxite>
 +$string_with_num = "17";
 +$new_value = num($string_with_num) + 1;
 +</code>
 +
 +====Math Functions====
 +^Name^Description^Example^
 +|round(x)|Rounds x to the nearest whole number.|round(16.8) will return 17|
 +|mod(x, y)|Gives the remainder of x divided by y.|mod(8, 3) will return 2|
 +|pow(x, y)|Gives the result of x raised to the power of y.|pow(2, 5) will return 32|
 +|sqrt(x)|Gives the square root of x.|sqrt(16) will return 4|
 +|abs(x)|Gives the absolute value of x.|abs(-17) will return 17|
 +|floor(x)|Rounds x downwards to the nearest whole number.|floor(17.7) will return 17|
 +|ceil(x)|Rounds x upwards to the nearest whole number.|ceil(16.2) will return 17|
 +
 +====Custom Functions====
 +Custom functions provide a way to define reusable logic that can be called later in the same [[script]]. Custom functions can optionally include input arguments that values are passed into (e.g. the way a map name is passed as a [[string]] into the built-in [[Load Map]] function). They can also optionally return a value to the calling code. Refer to the code below for an example of a custom function that takes two input arguments, adds them together, then returns the total.
 +
 +**Example:**
 +<code bauxite>
 +function add_numbers($num1, $num2) begin
 +   $total = $num1 + $num2;
 +   return $total;
 +end;
 +$result = add_numbers(10, 7);
 +display_message("Result: " + str($result));
 +</code>
 ~~NOTOC~~ ~~NOTOC~~
script_syntax.1581046499.txt.gz · Last modified: 2020/02/06 19:34 by justin