Modifiers system
Modifier
Bases: Agent
A class representing a modifier for a blob value. This is not meant to be used directly by the scripter, but rather as a data structure for storing modifier information.
__eq__(other)
Are the Modifier objects equal?
__init__(target, key, value, source, mod_type=1, timer=None, index=None)
Initialize a Modifier object.
Args:
target (int | set): The id or set of ids of the object(s) for which the modifier is applied.
key (str): The key of the value to be modified.
value (list[float]): The amount by which the value should be modified.
source (string | int): The source of the modifier. Can be named (e.g. "Rested") or the ID of a task.
mod_type (int, optional): The type of modifier (flat, additive, multiplicative). See docs for modifier_add() for more details.
timer (str, optional): The name of the timer. Usually will be key + "__" + source
index (int, optional): The index of the value in a list blob value that is being modified. If None, the modifier is applied to all indices of a list blob value.
expired()
Is the modifier expired?
format_time_remaining()
Get the time remaining on the modifier's timer formatted as a string. Returns None if the modifier has no timer.
get_time_remaining()
Get the time remaining on the modifier's timer. Returns None if the modifier has no timer.
ModifierHandler
This class is just a wrapper for some modifier functions that don't need to be exposed to the scripter.
calculate_modified_value(base_value, modifiers, index=0)
Calculate the modified value of a blob based on the base value and a list of modifiers.
The three types of modifiers are applied in different ways, and in the following order - Flat: All flat modifier values are combined and added directly to the base value of the blob. - Additive: All additive modifier values are added together, then multiplied by the result of the previous step. - Multiplicative: All multiplicative modifier values are multiplied together, then multiplied by the result of the previous step.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
base_value
|
float
|
The base value of the blob before modifiers are applied. |
required |
modifiers
|
list[Modifier]
|
A list of modifiers |
required |
index
|
int
|
The index of the blob value to which the modifiers should be applied if the blob value is a list. Default is 0. |
0
|
Returns: float: The modified value after all modifiers have been applied.
get_blob_max_index(id, key)
Get the maximum valid index for a blob value. If the blob key does not exist, will return -1. Args: id (int | Agent): The ID or object for which to get the blob max index. key (str): The key of the blob for which to get the max index. Returns: int: The maximum valid index for the blob value.
get_default_blob_value(id, key, default=1.0)
Get the default value of a blob for a given object ID and blob key. This is the value of the blob before any modifiers are applied. If the default value is not already stored in the inventory, it will be retrieved from the data set and stored in the inventory for future use. Args: id (int | Agent): The ID or object key (str): The key of the blob for which to get the default value. default (float, optional): The default value for the key. Default is 1.0 Returns: float | list[float]: The default value of the blob for the given object ID and blob key. If it's an inventory key, will return a float. If it's a blob key, will return a list.
get_side_modifiers(side_id_or_key, key)
Get the modifiers for a given side and blob key. If the side id or key provided is invalid, returns an empty string.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
side_id_or_key
|
int or str
|
The ID or key of the side for which to get the modifiers. |
required |
key
|
str
|
The key of the blob for which to get the modifiers. |
required |
Returns: list[Modifier]: A list of modifiers for the given side and blob key.
is_key_for_blob(id, key)
Check if a given key is a blob key for a given object ID. This is used to determine whether we should be looking for the default value in the inventory or in the data set when getting the default value of a blob. Args: id (int | Agent): The ID or object for which to check if the key is a blob key. key (str): The key to check. Returns: bool: True if the key is a blob key for the given object ID, False otherwise.
recalculate_value(id, key)
Recalculate and set the value of a blob for a given object ID and blob key based on the default value and all modifiers currently applied. This should be called after adding or removing a modifier to update the blob value accordingly. If the given object ID is for a side, it will recalculate the blob value for all objects of that side. Args: id (int | Agent): The ID or object for which to recalculate the blob value. key (str): The blob key
remove_expired_modifiers()
Remove all expired modifiers. This should be called regularly to ensure that modifiers are removed after their duration expires.
modifier_add(obj_or_id_or_set, key, value, source, flat_add_or_mult=1, duration=None, index=None)
Add and apply a modifier for a blob value of a given object. The modifier can also apply to all objects of a side by passing a side id or key instead of an object or object id. The source paramter identifies the modifier. Only one modifier with a given source can be active at a time for a given blob. If a modifier with the same source is added again, it will overwrite the previous one. This allows for easy updating of modifiers without needing to remove them first. The duration parameter specifies how long the modifier should be active. If duration is None, the modifier will be permanent until manually removed. If duration is specified, the modifier will be automatically removed after the duration expires.
The three types of modifiers are applied in different ways, and in the following order - Flat: All flat modifier values are combined and added directly to the base value of the blob. - Additive: All additive modifier values are added together, then multiplied by the result of the previous step. - Multiplicative: All multiplicative modifier values are multiplied together, then multiplied by the result of the previous step.
Example usage:
# Assume that for this example, the base scan range is 1000.
# This will increase the ship's scan range by 20% relative to the base range
add_modifier(id, "ship_base_scan_range", 0.2, "Scan Range Efficiency Module", 1) # New value is 1200
# This will add a flat 1000 to the ship's base scan range, and then apply the 20% buff.
# Note that flat modifiers are always applied first when recalculating.
add_modifier(id, "ship_base_scan_range", 1000, "Scan Range Extender", 0) # New value is 2400 (1000 base + 1000 flat from extender, which is then multiplied by the efficiency module modifier.)
# this will add a 10% additive modifier. This stacks with the Scan Range Efficency Module for a total of 30% additive bonus
add_modifier(id, "ship_base_scan_range", 0.1, "AI Scan Enhancement") # New value is 2600
# This will add a multiplicative modifier that reduces the ship's scan range by 50% after the previous modifier types are applied.
# Note that Multipicative modifier are always applied last when recalculating.
add_modifier(id, "ship_base_scan_range", -0.5, "Nebula Interference", 2) # New value is 1300
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
obj_or_id
|
set | int | Agent | key
|
The set, object, ID, or a side key to which the modifier should be added |
required |
key
|
str
|
The key of the blob value which the modifier should affect. |
required |
value
|
float
|
The value of the modifier to be added. |
required |
source
|
str | int
|
The source of the modifier, which can be used to identify and remove the modifier later if needed. Source can be a string or an int. |
required |
flat_add_or_mult
|
float
|
How the modifier should be applied. Default is 1. - If 0, the modifier is a Flat modifier - If 1, the modifier is an Additive modifier - If 2, the modifier is a Multiplicative modifier |
1
|
duration
|
float
|
The duration in seconds for which the modifier should be active. If None, the modifier will be permanent until removed. Defaults to None. |
None
|
index
|
int
|
The index of the blob value to which the modifier should be applied if the blob value is a list. If None, it will apply to all valid indices. Not applicable if the key is for an inventory value. Default is None. |
None
|
Returns: Modifier | set[int]: The modifier object, or a set of the IDs of all the modifiers that were created and added.
modifier_exists(id, source_or_modifier)
Check if the specified modifier exists on the specified object. Args: id (int): The ID of the object for which to check for the modifier. source_or_modifier (str | int | Modifier): The source of the modifier to check for, or the modifier object. Source can be a string or an int. Returns: bool: True if the modifier exists, False otherwise.
modifier_get_formatted_time_remaining(modifier)
Get the formatted time remaining on a modifier's timer. Returns None if the modifier has no timer.
Args:
modifier (Modifier): The modifier for which to get the formatted time remaining.
Returns:
str: The formatted time remaining on the modifier's timer, or None if the modifier has no timer.
modifier_get_time_remaining(modifier)
Get the time remaining on a modifier's timer. Returns None if the modifier has no timer.
Args:
modifier (Modifier): The modifier for which to get the time remaining.
Returns:
float: The time remaining on the modifier's timer in seconds, or None if the modifier has no timer.
modifier_is_expired(modifier)
Check if a modifier is expired based on its timer. Args: modifier (Modifier): The modifier to check for expiration. Returns: bool: True if the modifier is expired, False otherwise.
modifier_remove(obj_or_id_or_set, key_or_modifier, source=None)
Remove a modifier from a blob value of a given object or objects.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
obj_or_id_or_set
|
set | int | Agent | key
|
The set, object, ID, or a side key from which the modifier should be removed. |
required |
key_or_modifier
|
str | Modifier
|
The key of the blob value from which the modifier should be removed, or the modifier object itself. |
required |
source
|
str | int
|
The source of the modifier to be removed. If None, all modifiers for this key are removed. Source can be a string or an int. Defaults to None. |
None
|
modifiers_get_for_object(obj_or_id, key)
Get all modifiers currently applied to a blob value of a given object. This can be used to display the active modifiers for a blob value in a GUI, for example.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
obj_or_id
|
int | Agent
|
The ID or object for which to get the modifiers. |
required |
key
|
str
|
The key of the blob value for which to get the modifiers. |
required |
Returns:
| Type | Description |
|---|---|
list[Modifier]
|
list[Modifier]: A list of modifiers currently applied to the blob value. Source can be a string or an int. |