Stat Modifies

The stat modifiers object represents a collection of modifiers that can be applied to stats.
Return to Index
new ( )
__gc ( )
__eq ( am.stat_modifiers modifiers ) -> ( boolean )
add ( string stat_name , number value , string modifier_type , boolean magical = true ) -> ( integer )
add ( am.stat_modifiers mods ) -> ( integer )
add ( string stat_name , StatModifier mod ) -> ( integer )
remove ( string stat_name , number value , string modifier_type , boolean magical = true ) -> ( integer )
remove ( am.stat_modifiers mods ) -> ( integer )
remove ( string stat_name , StatModifier mod ) -> ( integer )
mods ( ) -> ( table )
calculate_stat ( string stat_name , number baseValue ) -> ( number )
new ( )
Creates a new stat modifier object.
__gc ( )
Deletes the stat modifiers object. TODO Check if it should do this.
__eq ( am.stat_modifiers modifiers ) -> ( boolean )
Compares this stat modifiers object with the given one.
Parameters:
am.stat_modifiers modifiers : The other stat modifiers object to compare with.
Returns:
boolean : True if they are the same stat modifiers object.
add ( string stat_name , number value , string modifier_type , boolean magical = true ) -> ( integer )
Adds a stat modifier to this collection. A modifier is made up the stat it modifiers, the type of modification and a value. This is a list of valid stat names:
  • health
  • maxHealth
  • strength
  • dexterity
  • constitution
  • arcane
  • divine
  • minDamage
  • maxDamage
  • armour
Each modifier type has a different affect and is applied in a specific order. This ensures that a set (=) mod doesn't override other mods, and that a multiply (*) mod doesn't get an unexpected boost because of an add (+) mod.
  • = : Sets the stat to the given value. This mod is applied first.
  • * : Multiplies the stat by the given value. This mod is applied second.
  • + : Adds the given value directly onto the stat, this value can be negative. This mod is applied third.
An example 
 mods = am.stat_modifiers.new()
 
 base_health = 5
 mods:add("health", 4, "+")
 am_log("Calculated Health: " .. mods:calculate_stat("health", base_health)) -- Outputs 9 (5 + 4)
 
 mods:add("health", 3, "*")
 am_log("Calculated Health: " .. mods:calculate_stat("health", base_health)) -- Outputs 19 (5 * 3 + 4)
 
 mods:add("health", 7, "=")
 am_log("Calculated Health: " .. mods:calculate_stat("health", base_health)) -- Outputs 25 (7 * 3 + 4)
Parameters:
string stat_name : The name of the stat this modifier will affect.
number value : The stat modifier value.
string modifier_type : The modifier type name.
boolean magical = true : Defines if the modification is magical in-nature or not. This does not affect how the final stat value is calculated, but it does allow for the UI to categorise how the modification is displayed. This may change in future.
Returns:
integer : Return codes
  • 1: The stat modifier was added successfully.
  • 0: The context object was not a stat modifier collection.
  • -1: The given stat name was invalid.
  • -2: The given value was not a number.
  • -3: The given stat modifier was invalid.
add ( am.stat_modifiers mods ) -> ( integer )
Merges another stat modifiers collection into this one. This behaves as if all the modifiers were taken from the given collection and added through the other add modifier function.
Parameters:
am.stat_modifiers mods : The collection of stat modifiers to combine with this one.
Returns:
integer : Return codes
  • 1: The stat modifiers were successfully merged.
  • 0: The context object was not a stat modifier collection.
  • -1: The given stat modifiers collection was not a StatModifier instance.
add ( string stat_name , StatModifier mod ) -> ( integer )
Adds a StatModifier instance to this collection of modifiers.
Parameters:
string stat_name : The name of the stat this modifier will affect.
StatModifier mod : The stat modifier to add.
Returns:
integer : Return codes
  • 1: The stat modifier was added successfully.
  • 0: The context object was not a stat modifier collection.
  • -1: The given stat name was invalid.
  • -4: The given stat modifier was not a valid stat modifier instance.
remove ( string stat_name , number value , string modifier_type , boolean magical = true ) -> ( integer )
Removes a stat modifier from the collection. See the add function for a list of valid stat names and modifier types. Each modifier does not contain any identification information about it, as such to remove a modifier you need to specify the same stats which you want to remove. So if you previous added a + 5 to Health, to remove it you remove a + 5 to Health.

Note: Internally the values are stored as 32-bit floats, as such two different modifier values are considered the same if their different is less than 0.00001. 

 mods = am.stat_modifiers.new()
 
 base_health = 5
 mods:add("health", 4, "+")
 am_log("Calculated Health: " .. mods:calculate_stat("health", base_health)) -- Outputs 9 (5 + 4)
 
 mods:add("health", 3, "*")
 am_log("Calculated Health: " .. mods:calculate_stat("health", base_health)) -- Outputs 19 (5 * 3 + 4)
 
 mods:add("health", 7, "=")
 am_log("Calculated Health: " .. mods:calculate_stat("health", base_health)) -- Outputs 25 (7 * 3 + 4)
 
 -- Remove them all again but in a different order.
 mods:remove("health", 3, "*")
 am_log("Calculated Health: " .. mods:calculate_stat("health", base_health)) -- Outputs 11 (7 + 4)
 
 mods:remove("health", 4, "+")
 am_log("Calculated Health: " .. mods:calculate_stat("health", base_health)) -- Outputs 7 (7)
 
 mods:remove("health", 7, "=")
 am_log("Calculated Health: " .. mods:calculate_stat("health", base_health)) -- Outputs 5 (5)
Parameters:
string stat_name : The name of the stat to remove this modifier from.
number value : The stat modifier value.
string modifier_type : The modifier type name.
boolean magical = true : If the added modifier was magical, it has be removed as magical.
Returns:
integer : Return codes
  • 1: The stat modifier was removed.
  • 0: The context object was not a stat modifier collection.
  • -1: The given stat name was invalid.
  • -2: The given value was not a number.
  • -3: The given stat modifier was invalid.
remove ( am.stat_modifiers mods ) -> ( integer )
Removes all the stat modifiers from the given collection from this collection. This behaves as if all the modifiers were taken from the given collection and removed through the other remove modifier function.
Parameters:
am.stat_modifiers mods : The collection of stat modifiers to remove.
Returns:
integer : Return codes
  • 1: The stat modifiers were successfully removed.
  • 0: The context object was not a stat modifier collection.
  • -1: The given stat modifiers collection was not a StatModifier instance.
remove ( string stat_name , StatModifier mod ) -> ( integer )
Removes a stat modifier from this collection.
Parameters:
string stat_name : The name of the stat to remove this modifier from.
StatModifier mod : The modifier to remove.
Returns:
integer : Return codes
  • 1: The stat modifier was removed.
  • 0: The context object was not a stat modifier collection.
  • -1: The given stat name was invalid.
  • -4: The given stat modifier was not a valid StatModifier instance.
mods ( ) -> ( table )
Returns a map of stat name keys and arrays of all the modifcations values. This is a copy of the internal mods map, changing values on this table will have no affect on the internal values. 
 statMods = am.stat_modifiers.new()
 statMods:add("health", 5, "+", false)
 statMods:add("health", 8, "=")
 statMods:add("health", 2, "*")
 
 mods = statMods:mods()
 am_log("Magical: " .. tostring(mods["health"][1].magical)) -- Outputs "Magical: false"
 am_log("Type: " .. mods["health"][2].type)                 -- Outputs "Type: ="
 am_log("Value: " .. mods["health"][1].value)               -- Outputs "Value: 2"
Returns:
table : All the modifications as a Lua table.
calculate_stat ( string stat_name , number baseValue ) -> ( number )
Calculates the final value for a given stat with the given base value. Stats with no modifications will simply return the base value.
Parameters:
string stat_name : The stat name, nil will be returned if this is invalid.
number baseValue : The base value for the stat.
Returns:
number : The calculated stat value.