Variables
Introduction
Variables are used to acess data from objects and more. Basically, every time you see a parameter in a command that looks like this [VALUE] or pretty much any other [...] with CAPS LOCK, you can use a variable instead of it.
A variable consists of the base and any amount of modifiers behind the base. An example:
{player|name}.toUppercase().endsWith(AN)
They can even contain multiple layers of variables:
{player|name}.indexOf({lastInput}.substring(0|2))
To easily find out the value of a variable, you can use the print command to get the first value or the evaluate command to get all values.
Everytime you see something enclosed in [...] it means that you need to replace it with a value and a <...> means that whatever is in them optional. If the text inside the [...] is lowercase it means you need to choose one of the options.
If you need to write something in {} without them being seen as a variable, you will need to escape them \{\}.
Variable base
It is important to know that a variable can not only store a single value but can contain a whole list of values. Some of the variables will return only one, but others will return a whole array. A great example for this is the {selector|[SELECTOR]} variable that can transform the result of a selector into a variable. Meaning this {selector|#type:location#} can return this:
453521874aec4192fa353d3a33ef4d54
To acess the individual results you would need to specify which one you want using modifiers, but more on those later. Parameters inside of variable bases and modifiers are split by |. You can escape this by using \|.
Time for a list of all possible variable bases:
| Variable | Description |
|---|---|
{{VARIABLENAME]} |
Will return the value of a variable object |
{player|[SETTING]} |
Will return the value of the setting specified in the player settings |
{project|[SETTING]} |
Will return the value of the setting specified in the project settings |
{random|[MIN]|[MAX]} |
Returns a random number |
{value|[VALUE 1];[VALUE 2];...} |
Creates a variable based on the given value(s). Each value is a new line in the variable |
{selector|[SELECTOR]} |
Creates a variable based on the result of the selector |
{event|[SELECTOR(object)]|[VALUE(eventname)]} |
Used for the execute command. [SELECTOR] specifies the object where the event is stored and [VALUE] the name of the event that will be executed (all will execute all events) |
{amount|[SELECTOR(item)]|[SELECTOR(inventory)]} |
Gives the amount of an item in a specific inventory |
{currentbattle} |
Returns the UID of the battleMap that is currently active |
{this} |
Returns the UID of the object evaluating the variable |
{inBattle} |
Returns true or false whether a battleMap is active |
{input|dice|[VALUE(text)]|[VALUE(sides)]|[VALUE(duration)]|[VALUE(autoroll;boolean)]} |
Opens a popup with a dice and returns the value rolled |
{input|button|[VALUE(text)]|[VALUE(button1)];[VALUE(button2)];...} |
Opens a popup with a text and multiple buttons and returns the ID of the one selected |
{input|button|[VALUE(button1)];[VALUE(button2)];...} |
Opens a smaller popup with multiple buttons and returns the ID of the one selected |
{input|buttonlist|[VALUE(text)]|[VARIABLE(without{})]} |
Opens a popup with a text and multiple buttons based on the entries of the given variable (without {}, cannot have modifiers) and returns the ID of the one selected |
{input|buttonlist|[VARIABLE(without{})]} |
Opens a smaller popup with multiple buttons based on the entries of the given variable (without {}, cannot have modifiers) and returns the ID of the one selected |
{input|dropDown|[VALUE(text)]|[VALUE(option1)];[VALUE(option2)];...} |
Opens a popup with a drop down menu and returns the value of the selected option |
{input|text|[VALUE(text)]|[VALUE(pretext)]} |
Opens a popup with a text input and returns what the player typed |
{input|line} |
Waits for the player to type something and returns the value |
{talent|[VALUE(talentname)]|[VALUE(dc)]|[true;false(visible)]|[true;false(autoroll)]|[VALUE(message);none]} |
Rolls a talent and returns true or false |
{lastInput} |
Returns the last thing the player typed or selected in a popup |
{empty} |
Creates an empty variable |
{[parameter]} |
Returns a parameter that came with the event call |
{web|[VALUE(url)]} |
Returns an entire website or file via the URL with each line being a new entry in the variable (requires web permission) |
{file|[VALUE(path)]} |
Returns the selected file in the res/advfiles/ folder with each line being a new entry in the variable (requires fileread/filereadanywhere permission) |
{file|[SELECTOR(fileObject)]} |
Reads content of fileObject as if it was text with each line being a new entry in the variable |
{popup|[uids;names]} |
Returns all of the currently open popup uids or the individually defined names |
{inventory|[VALUE(inventory]} |
Returns the uids of the items contained inside of the given inventory |
There are also object specific variables:
| Object Type | Variable | Description |
|---|---|---|
| item | armor | Reduces the amount of damage taken when equipped as armor item |
| item | color | hex color value that determines the color of the item name in the inventory |
| item | weight | How much the item adds to the inventory weight |
| item | damage | How much damage the item deals (see below for more infos) |
| item | range | The range of the item on the battle map |
| item | value | How much the item is worth (unused) |
| item | hands | Can be either 1, 2 or armor and describes the slots the item takes |
| npc | health | The health of the NPC |
| npc | courage | The object with the highest courage comes first on a battle map |
| npc | speed | How many tiles the NPC can walk on a battle map in one turn |
| npc | dmgNoWeapon | The damage if the NPC has no item equipped |
| npc | equippedWeapon | The item the NPC has currently equipped |
| npc | armor | How much damage is being absorbed |
Some of the variables, such as {this} or {[parameter]} cannot have modifiers. You will have to use the value variable {value|{this}}.toUppercase().
Modifiers
Modifiers can change the values of a variable in different ways.
- Modify the individual elements of the variable
- Create a whole new variable
Let's start with the ones that only modify the values of the variable. They get applied on every entry separately.
| Modifier | Description |
|---|---|
charAt([VALUE(index)]) |
Returns the character at the given index |
toUppercase() |
Turns all lowercase characters to their uppercase counterpart |
toLowercase() |
Turns all uppercase characters to their lowercase counterpart |
contains([VALUE]) |
Sets to true or false depending on if the variable contains the value |
equals([VALUE]) |
Sets to true or false depending on if the variable is equals to the value |
endsWith([VALUE]) |
Sets to true or false depending on if the variable is ends with the value |
matches([VALUE]) |
Sets to true or false depending on if the variable matches a regular expression |
isType([VALUE(type)]) |
Sets to true or false depending on if the variable is a UID and if the corresponding object is the given type |
isUID() |
Sets to true or false depending on if the variable is a UID |
replace([VALUE(find)]|[VALUE(replace)]) |
Replaces all occurrences of a value with another one |
replaceAll([VALUE(find)]|[VALUE(replace)]) |
Replaces all occurrences of a regular expression with another value |
indexOf([VALUE]) |
Sets to the index of the first time the value appears in the string |
substring([VALUE(int)]|[VALUE(int)]) |
Sets to a substring from the beginning index to the end index |
length() |
Sets to the length of the value |
round() |
Rounds the value to the next whole number |
math([VALUE(math. expression)]) |
Performs a mathematical operation on the value. See 'Using variable values in modifiers' |
evalMath() |
Treats entry as mathematical expression and returns result |
string([VALUE]) |
Just like math() but does not perform any further operations on it |
sort() |
Sorts the variable entries based on the alphabet |
invert() |
Inverts the order of the entries |
set([VALUE(index)]|[VALUE]) |
Sets an entry to a value |
battleInfo([npc; item; extragroundtiles; obstacles; player; groundtiles]<|[x; y; uid; image]>) |
Returns information on the battleMap with the UID of the variable entry. Specify what information you need with the parameters |
You can also use this to get object data:
| Modifier | Description |
|---|---|
name() |
Grabs the UID of the variable entry and if the according object exists returns the name of it |
description() |
Grabs the UID of the variable entry and if the according object exists returns the description of it |
location() |
Grabs the UID of the variable entry and if the according object exists returns the location UID of it |
image() |
Grabs the UID of the variable entry and if the according object exists returns the image UID of it |
type() |
Grabs the UID of the variable entry and if the according object exists returns the type of it |
inventory() |
Grabs the UID of the variable entry and if the according object exists returns the inventory UID of it |
variable([VARIABLENAME]) |
Grabs the UID of the variable entry and if the according object exists returns the variable with the given name |
These modifiers create a new results-list:
| Modifier | Description |
|---|---|
get([equals;contains;matches]|[VALUE]) |
Returns only the entries that match the given criteria |
get(index|[VALUE(index)]) |
Return only the entry with the given index |
get(random<|[VALUE(fromIndex)]|[VALUE(toIndex)]>) |
Returns a random entry with the option to specify in what range the index can be |
remove([equals;contains;matches]|[VALUE]) |
Removes the entries that match the given criteria |
remove(index|[VALUE(index)]) |
Removes the entry with the given index |
remove(random<|[VALUE(fromIndex)]|[VALUE(toIndex)]>) |
Removes a random entry with the option to specify in what range the index can be |
append([VALUE]) |
Appends either another variable list or simply a single value. If you want to append a variable, leave away the {} |
indexOfInList([VALUE]) |
Looks for the value inside of the list and returns the index of the first match |
average([round;float]) |
Returns the average value of the entire list |
sum([round;float]) |
Returns the sum of the entire list |
min([round;float]) |
Returns the smallest value of the entire list |
max([round;float]) |
Returns the largest value of the entire list |
count() |
Returns the amount of entries |
split([VALUE]) |
Splits first entry at given value and creates for each element a new emtry in the new result list |
size() |
Returns the amount of entries in the variable |
Using variable values in modifiers
Using the strings %1 and %2 inside of the modifier parameters will replace them with:
%1- current element%2- current element index
Meaning the variable {value|Line 0}.append(Line 1).string(%1 - %2) will return:
Line 0 - 0
Line 1 - 1
Setting variables
It wouldn't be too useful if you could only read variables. Setting them is pretty easy luckily:
[VARIABLE] = [VALUE/VARIABLE]
for example: {test} = {test}.toUppercase()
If you need to perform one/multiple mathematical operation(s), you need to use two ==:
[VARIABLE] == [MATHEMATICAL EXPRESSION WITH VALUES/VARIABLES]
for example: {test} = {test} + 23
One more thing: You cannot use more than one modifier on the left variable, meaning this would not work:
{selector|#type:npc#}.sort().remove(index|3).name() = {test}.name()
Examples / Exercises
Now that you know how the variables work, try creating variables that return values that match these descriptions:
- A variable that returns the playername with only uppercase
- A variable that reads the file
test.txtin the advfiles folder and returns the rounded average length of all lines (what permissions are required here?) - A variable that reads the file
foo.txtone folder above the advfiles folder and returns a list in which no entry contains the wordhmm(what permissions are required here?) - A variable that returns the name of the location the player is at
- A variable that returns all of the location image UIDs of all NPCs
-
A variable that returns the amount of bread in a random NPC inventory
Now set the these variables to the values:
-
Set the player name to the name of a random location
- Set the amount of
Breadin the players inventory to the result of the product of{bar}and 6 - Set the description of all locations to the value a player rolls with a 20 sided dice
- Set the
healthof all NPCs to 10
Here are the solutions:
{player|name}.toUppercase(){file|test.txt}.length().average(round)
requiresfilereadpermission{file|../foo.txt}.remove(contains|hmm)
requiresfilereadanywherepermission{player|location}.name(){selector|#type:npc#}.location().image()-
{amount|#name:Brot#|{selector|#type:npc;sort:random;limit:1#}.inventory()} -
{player|name} = {selector|#type:location;sort:random;limit:1#}.name() {amount|#name:Brot#|#uid:{player|inventory}#} == {bar} * 6{selector|#type:location#}.description() = {input|dice|Roll a dice!|20|8|false}{selector|#type:npc#}.variable(health) = 10