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 revision Previous revision
Next revision
Previous revision
script_syntax [2019/04/18 16:03]
127.0.0.1 external edit
script_syntax [2020/08/05 21:36] (current)
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/end" ​syntax ​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.1555628637.txt.gz · Last modified: 2019/04/18 16:03 by 127.0.0.1