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
Next revisionBoth sides next revision
script_syntax [2019/04/18 16:03] – external edit 127.0.0.1script_syntax [2020/08/05 21:36] justin
Line 2: Line 2:
 ---- ----
  
-The scripting language in RPG in a Box is a simple imperative language designed specifically for the engine. It is based on the language described [[https://jayconrod.com/posts/37/a-simple-interpreter-from-scratch-in-python-part-1|here]] in the series of articles by Jay Conrod. 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 a simple imperative language 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]].
  
-=====Statements===== +=====Statement Syntax===== 
-Statements are the basic building blocks of the scripting language and represent a particular action to be taken. Currently, a statement can be either a function call or conditional "if/then/else/end" statement. 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. statement can be either a function call, assignment of 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=====
 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. 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:** **Examples:**
-<code lua+<code bauxite
-display_message("Hello World!")+display_message("Hello, world!")
 </code> </code>
-<code lua>+<code bauxite>
 lock_camera(); lock_camera();
 move_camera("cam_position_01"); move_camera("cam_position_01");
Line 20: Line 20:
 </code> </code>
  
-====If/Then/Else/End (Conditional)==== +=====Assignment Statements===== 
-The "if/then/else/endsyntax 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.+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. 
 + 
 +^Operator^Description^ 
 +|=|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:** 
 +<code bauxite> 
 +$rand_num = random(1, 20) 
 +</code> 
 +<code bauxite> 
 +entity["sign_01"].property["message"] = "I am a sign!" 
 +</code> 
 +<code bauxite> 
 +player.stat["max_hp"] += 5 
 +</code> 
 + 
 +=====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:** **Examples:**
-<code lua>+<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 lua+<code bauxite
-if player.inventory contains "Gold Key" then +if player.inventory contains "ITEM_0001" then 
-   remove_item("Gold Key");+   remove_item("ITEM_0001");
    display_message("The door is now unlocked!");    display_message("The door is now unlocked!");
-   set_entity_property(self"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
 +</code>
 +<code bauxite>
 +$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 end
 </code> </code>
  
-=====Literals===== +====While Loop==== 
-A literal represents an explicitfixed value. Literals can be stored in properties (see [[Set Global Property]] and [[Set Entity Property]]) or compared to another value of the same type within a [[conditional expression]].+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:** 
 +<code bauxite> 
 +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 
 +</code> 
 + 
 +====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 listedit 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. 
 + 
 +**Examples:** 
 +<code bauxite> 
 +display_message("The explosion damages all of the enemies!"); 
 +for $slime_entity in group["slimes"] do 
 +   damage_entity($slime_entity, 5) 
 +end 
 +</code> 
 +Deals 5 damage to each [[entity]] in the "slimes" [[groups|group]]. 
 +<code bauxite> 
 +for $i in range(1, 4) do 
 +   give_item("ITEM_000" + "${i}", $i) 
 +end 
 +</code> 
 +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 valuesThese 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| |[[Decimal]]|17, 3.14159|
 |[[Boolean]]|true, false| |[[Boolean]]|true, false|
 +|[[Coordinate]]|coord[1, 2, 3], entity["slime_01"].coord|
 +|[[Color]]|color[255, 0, 255]|
 +|[[Entity]]|player, self, entity["sign"]|
 +|[[Array]]|group["room_01"], self.groups|
 +|Null|null|
  
 +====Arrays====
 +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.
 +^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"]|
 +|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|
 +
 +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_array" is 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:**
 +<code bauxite>
 +for $slime_entity in group["slimes"] do
 +   damage_entity($slime_entity, 2)
 +end
 +</code>
 +Deals 2 damage to all entities in the "slimes" [[groups|group]].
 +<code bauxite>
 +if player.tags contains "human" then
 +   display_message("No humans allowed!")
 +end
 +</code>
 +Displays the message if the player model's tag list contains the "human" tag.
 +<code bauxite>
 +$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)
 +</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.
 +
 +====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>
 +
 +=====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:**
 +<code bauxite>
 +wait(random(1, 5))
 +</code>
 +Waits for a random amount of time between 1 and 5 seconds.
 +
 +<code bauxite>
 +if random(0, 100) <= 25 then
 +  give_item("ITEM_0001")
 +else
 +  give_item("ITEM_0002")
 +end
 +</code>
 +Gives either ITEM_0001 or ITEM_0002 to the player, with a 25% chance that the item will be ITEM_0001.
 +
 +====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).
 +
 +====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.
 +
 +^Type^Example^
 +|[[Number]]|inverse(17) will return -17|
 +|[[Boolean]]|inverse(true) will return false|
 +|[[Coordinate]]|inverse(coord[-3, -4, 5] will return coord[3, 4, -5]|
 +|[[Color]]|inverse(color[128, 255, 0] will return color[127, 0, 255]|
 +|[[Cardinal Direction]]|inverse(NORTH) will return SOUTH|
 +|[[navigation_and_interaction|Navigation Type]]|inverse(WALK_AND_INTERACT) will return PENDING|
 +
 +**Examples:**
 +<code bauxite>
 +rotate_player_to_direction(inverse(entity["goblin"].direction))
 +</code>
 +Rotates the player character to be facing in the opposite direction that the goblin is facing.
  
 ~~NOTOC~~ ~~NOTOC~~
script_syntax.txt · Last modified: 2023/11/06 14:13 by justin