Skip to content

Modifiers system

Apply temporary or persistent stat modifications to agents.

Overview

Modifiers are named adjustments to an agent's engineering or inventory values. Each modifier has a key (the attribute being changed), a value (the amount of change), and a source tag (who applied it — used for selective removal). Multiple modifiers with different sources can stack on the same key.

modifier_add registers a modifier and applies it immediately. modifier_remove removes the modifier and reverts its contribution. modifier_clear removes all modifiers from an agent.

Modifiers are used internally by the upgrade system to track stat changes applied by upgrades — when upgrade_remove_all is called, the upgrade's modifiers are removed cleanly.

Quick example

== apply_speed_boost ==
    modifier_add(ship_id, "topSpeed", 5, "speed_upgrade")
    ->END

== remove_speed_boost ==
    modifier_remove(ship_id, "topSpeed", "speed_upgrade")
    ->END

from sbs_utils.procedural.modifiers import modifier_add, modifier_remove, modifier_clear

modifier_add(ship_id, "topSpeed", 5, "speed_upgrade")
modifier_remove(ship_id, "topSpeed", "speed_upgrade")
modifier_clear(ship_id)

API

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 to a blob value on one or more objects.

obj_or_id_or_set may be an agent, an ID, a set of IDs, or a side key (str) — in which case the modifier is applied to every object on that side.

source identifies the modifier. Only one modifier per source can be active for a given key on a given object. Adding a modifier with an existing source overwrites the previous one, making updates easy without an explicit remove.

Modifiers are applied in this order: Flat (0) — all flat values are summed and added to the base. Additive (1) — all additive values are summed, then multiplied by the result of the Flat step. Multiplicative (2) — all multiplicative values are multiplied together, then applied to the result of the Additive step.

Parameters:

Name Type Description Default
obj_or_id_or_set set | int | Agent | str

Object, ID, set of IDs, or side key to apply the modifier to.

 required
key str

The blob key the modifier should affect.

 required
value float

The modifier amount.

 required
source str | int

Identifier for this modifier — used to overwrite or remove it later.

 required
flat_add_or_mult int

Modifier type: 0 = Flat, 1 = Additive (default), 2 = Multiplicative.

 1
duration float

Seconds before the modifier expires automatically. Defaults to None (permanent).

 None
index int

Index into a list blob value. None applies to all indices. Ignored for inventory keys. Defaults to None.

 None

Returns:

Type Description
Modifier

Modifier | set[int]: The created Modifier when exactly one is added; otherwise a set of all created modifier IDs.
Example

Base scan range is 1000.

modifier_add(id, "ship_base_scan_range", 0.2, "Efficiency Module") # 1200 modifier_add(id, "ship_base_scan_range", 1000, "Range Extender", 0) # 2400 modifier_add(id, "ship_base_scan_range", 0.1, "AI Enhancement") # 2600 modifier_add(id, "ship_base_scan_range", -0.5, "Nebula", 2) # 1300

modifier_exists(id, source_or_modifier)

Return True if a modifier matching source_or_modifier is active on the object.

Parameters:

Name Type Description Default
id int

ID of the object to check.

 required
source_or_modifier str | int | Modifier

Source identifier or a Modifier object to look for.

 required

Returns:

Name Type Description
bool bool

True if the modifier exists, False otherwise.

modifier_get_formatted_time_remaining(modifier)

Return the time remaining on a modifier's timer as a human-readable string.

Parameters:

Name Type Description Default
modifier Modifier

The modifier to query.

 required

Returns:

Name Type Description
str str

Formatted time remaining (e.g. "1:23"), or None if the modifier is permanent.

modifier_get_time_remaining(modifier)

Return the seconds remaining until a modifier expires.

Parameters:

Name Type Description Default
modifier Modifier

The modifier to query.

 required

Returns:

Name Type Description
float float

Seconds remaining, or None if the modifier is permanent.

modifier_is_expired(modifier)

Return True if the modifier's timer has elapsed.

Parameters:

Name Type Description Default
modifier Modifier

The modifier to check.

 required

Returns:

Name Type Description
bool bool

True if expired, False if still active or permanent.

modifier_remove(obj_or_id_or_set, key_or_modifier, source=None)

Remove a modifier (or all modifiers for a key) from one or more objects.

If key_or_modifier is a Modifier object, that specific modifier is removed directly and obj_or_id_or_set is ignored. Otherwise key_or_modifier is treated as a blob key: if source is given only that source's modifier is removed; if source is None all modifiers for that key are cleared.

Parameters:

Name Type Description Default
obj_or_id_or_set set | int | Agent | str

Object, ID, set of IDs, or side key to remove modifiers from.

 required
key_or_modifier str | Modifier

Blob key, or a Modifier object to remove directly.

 required
source str | int

Source identifier to remove. None removes all modifiers for the key. Defaults to None.

 None

modifiers_get_for_object(obj_or_id, key)

Return all modifiers currently applied to a blob key on an object.

Combines per-object modifiers stored in inventory with any side-level modifiers. Useful for displaying active buffs/debuffs in a GUI.

Parameters:

Name Type Description Default
obj_or_id int | Agent

The object or its ID.

 required
key str

The blob key whose modifiers should be retrieved.

 required

Returns:

Type Description
list[Modifier]

list[Modifier]: All active Modifier objects for that key.