The upgrades system

Apply MAST-driven ability labels to ships or other agents as activatable upgrades.

Overview

An upgrade is a MAST label that runs as a server task when activated. Upgrades are linked to their agent via the __UPGRADE__ link, so multiple upgrades can be active on the same agent simultaneously. When an upgrade activates, the upgrade_activated signal is emitted with UPGRADE_AGENT, UPGRADE_AGENT_ID, and UPGRADE variables.

Use upgrade_add with activate=False to pre-register upgrades (e.g. at ship setup) and upgrade_add with activate=True to apply them immediately. upgrade_remove_all stops all running upgrade tasks and cleans up their links.

Quick example

MAST pyMAST

== setup ==
    upgrade_add(ship_id, shield_boost_label, activate=True)
    ->END

== shield_boost_label ==
    set_engineering_value(UPGRADE_AGENT_ID, "shieldStrengthFront", 200)
    ->END

from sbs_utils.procedural.upgrades import upgrade_add, upgrade_remove_all

upgrade_add(ship_id, shield_boost_label, activate=True)
upgrade_add(ship_id, {"label": power_label, "multiplier": 2})
upgrade_remove_all(ship_id)

Reacting to upgrade activation

//signal/upgrade_activated
    log(f"Ship {UPGRADE_AGENT.name} received an upgrade!")

API

Manage all objective

`upgrade_add(agent_id_or_set, label, data=None, activate=False)`

Add an upgrade to one or more agents.

Creates an Upgrade object linked to each agent. If activate=True, the upgrade's MAST label is scheduled immediately as a server task and the upgrade_activated signal is emitted.

Parameters:

Name	Type	Description	Default
`agent_id_or_set`	`int \| set \| list \| object`	Agent ID(s) or object(s) to apply the upgrade to.	required
`label`	`label \| str \| dict`	MAST label to run when the upgrade activates. Pass a dict with a `"label"` key to merge extra data: `{"label": my_label, "power": 2}`.	required
`data`	`dict`	Variables passed to the upgrade task. Merged with dict-form `label` data. Defaults to None.	`None`
`activate`	`bool`	Activate the upgrade immediately after adding. Defaults to `False`.	`False`

Returns:

Name	Type	Description
`Upgrade`		The last `Upgrade` object created.

Example

upgrade_add(SHIP_ID, shield_boost_label, activate=True) upgrade_add(SHIP_ID, {"label": power_label, "multiplier": 2})

`upgrade_remove_all(agent)`

Deactivate and remove all upgrades from an agent.

Calls deactivate() and discard() on every Upgrade linked to the agent, stopping their tasks and removing the __UPGRADE__ links.

Parameters:

Name	Type	Description	Default
`agent`		Agent ID or object whose upgrades should be removed.	required

Example

upgrade_remove_all(SHIP_ID)