Formulas¶
Formulas are at the core of the Stats module; They allow the game designer to elaborate simple or complex systems that intertwine different stat and attribute values.
Math Expressions
Formulas are written using math expressions. For example the following formula:
source.stat[attack] - target.stat[defense]
Can be used to calculate the damage dealt to an enemy. It calculates the output taking into account the attack stat from the player and subtracting the defense stat from the enemy.
It is up to the game designer defining how simple or complex these formulas should be.
Creating a Formula¶
To create a Formula asset, right click on the Project panel folder you want to create it and select Create → Game Creator → Stats → Formula.
The Formula asset has a text field at the top, where the the math expression can be written.
The Help section contains a list of all possible symbols that can be used. For example, to retrieve the final value of a Stat called "strength" from the caller, use the source.stat[strength] symbol.
Each section can be expanded and collapsed to keep the important information at a glance.
Symbols
Check the list of all symbols at the end of this page.
The Table field is an optional one, that can be used to reference a Table asset from within the formula expression.
Symbols¶
A formula expression is composed of a series of symbols, joined together by a math expression, such as the sum, subtraction, product and division.
For example, the attack power of a character could be it's base strength value multiplied by its level. In this case, the expression would be:
source.base[strength] * source.stat[level]
Stats¶
This section covers all values found inside a game object with a Traits component. A stat or attribute can either come from the Source object or the Target object. For example, when calculating the damage dealt to an enemy, Source references the attacker and Target the attacked object.
Source and Target
In some cases, there may be no distinction between source and target. For example, when calculating the level of a character. In this case, we recommend ignoring the Target symbols and use Source.
To get the value of a Stat or Attribute, the target object of the query is first specified, followed by a dot (.) and the value type. Between brackets, the id of the stat or attribute is specified.
Stat Example
For example, to retrieve the attribute "mana" from the source object it's done using:
source.attr[mana]
base: The base stat value of the object.stat: The final stat value of the object.attr: The attribute value of the object.
Circular Formulas
It is up to the game designer to avoid circular dependencies, and Game Creator will not warn about them. A circular dependency happens when a formula requires a value, which must be calculated using the first formula. This locks the process in an infinite loop.
Variables¶
Variables work very similarly to retrieving Stats and Attributes. The targeted object is first specified, followed by a dot (.) and the keyword var. And between brackets, the name of the variable.
Example
For example, if a numeric Local Variable attached to the targetted object with the id "hit-counter" should be accessed, the expression would be:
target.var[hit-counter]
Local Variables
For the moment, a Formula can only access Local Variables by name. In a future update, List Variable access will be supported.
Random¶
Most skill checks use some sort of random values. The Formula analyzer provides three symbols to generate a random value.
-
random[min, max]: Returns a value between min and max, both included.Random[min, max]
Using
random[1, 4]returns a decimal value between these ranges. -
dice[rolls, sides]: For those old-school game designers, you can roll X amount of dices of Y sides and this symbol will return the sum of values.Dice[rolls, sides]
Using
dice[2, 6]returns the result of rolling 2 dices of 6 sides (the most common one). -
chance[value]: Returns 1 if a random value between 0 and 1 is lower or equal than the value specified.Chance[value]
Using
chance[0.2]has a 20% chance of returning a value of 1 and an 80% chance of returning 0.
Arithmetic¶
Number manipulation is also useful and commonly used. For example, to round numbers or choosing between two.
min[a, b]: Returns the lowest value between two.max[a, b]: Returns the greatest value between two.round[value]: Returns the value rounded up or down to the closest integer.floor[value]: Returns the integer part of the value.ceil[value]: Returns the next integer of the input value.
Tables¶
Tables are mostly used for player progression, as they map a certain input value to another value. For more information about Tables see this link.
Table asset
It is required to provide the Formula with a Table asset.
Table symbols start with table followed by a dot (.) and the type of value to retrieve. The value is specified between brackets afterwards.
Level from Experience
For example, let's say we have a stat called experience and we want to calculate the character's level based on that. We can use a Table that transforms the accumulated experience points to a value that represents the level. In this case, the expression would be:
table.level[experience]
level[value]: Returns the level at from the table based on the input cummulative value.value[level]: Returns the cummulative value necessary to reach the input level.increment[level]: Returns the amount left to reach the next level.current[value]: Returns the value gained at the current level.next[value]: Returns the value left to gain to reach the next level.ratio[value]: Returns a unit ratio that represents the progress made at the current level.