The torpedoes system

Define custom torpedo types and manage ship torpedo loadouts.

Overview

Torpedo types are registered as shared strings on the server using a "key:value;" attribute format. Once registered, they can be added to a ship's loadout with torpedo_make_available. The weapons console reads these shared strings to populate the torpedo selector.

Use torpedo_type for strongly-typed Python registration or torpedo_type_string when building the definition dynamically (e.g. from a data file). torp_update_value lets you tweak individual attributes after registration.

The torpedo system is actively evolving — new warhead and behavior values will be added in future versions. Use the other parameter on torpedo_type to pass attributes not yet exposed as named params.

Quick example

MAST pyMAST

== setup ==
    torpedo_type("emp", gui_text="EMP Pulse", warhead="reduce_shields", damage=10, speed=15)
    torpedo_type("cluster", gui_text="Cluster Bomb", warhead="blast", blast_radius=1500, damage=50)
    torpedo_make_available(ship_id, "emp", count=4)
    torpedo_make_available(ship_id, "cluster", count=2)
    ->END

from sbs_utils.procedural.torpedoes import (
    torpedo_type, torpedo_make_available, torpedo_make_unavailable,
    torpedo_get_count_for_ship, torp_update_value
)

torpedo_type("emp", gui_text="EMP Pulse", warhead="reduce_shields", damage=10)
torpedo_make_available(ship_id, "emp", count=4)

current, max_cap = torpedo_get_count_for_ship(ship_id, "emp")
torp_update_value("emp", "damage", 20)

torpedo_make_unavailable(ship_id, "emp")

Torpedo attributes

Attribute	Default	Notes
`speed`	10	Movement speed
`lifetime`	25	Seconds before expiry
`warhead`	`"standard"`	`"standard"`, `"blast"`, `"reduce_shields"`
`blast_radius`	1000	Used when warhead includes `"blast"`
`damage`	35	Base impact damage
`behavior`	`"homing"`	`"homing"` or `"mine"`
`energy_conversion_value`	100	Energy returned on disassembly

API

`get_torp_string_value_dict(key)`

Return a parsed attribute dictionary for a registered torpedo type.

Parameters:

Name	Type	Description	Default
`key`	`str`	Torpedo type identifier.	required

Returns:

Name	Type	Description
`dict`	`dict`	Attribute → value mapping for the torpedo.

`get_torp_value_string(key)`

Return the raw attribute string for a registered torpedo type.

Parameters:

Name	Type	Description	Default
`key`	`str`	Torpedo type identifier.	required

Returns:

Name	Type	Description
`str`	`str`	The `"attr:value;..."` string, or `None` if not found.

`parse_torp_string(torp_string)`

Parse a torpedo attribute string into a {attr: value} dictionary.

Parameters:

Name	Type	Description	Default
`torp_string`	`str`	Attribute string in `"attr:value;attr:value;"` format.	required

Returns:

Name	Type	Description
`dict`	`dict`	Parsed attribute → value mapping.

`torp_get_attribute_value(key, attribute_name)`

Return the value of a single attribute from a registered torpedo type.

See torpedo_type for valid attribute names (e.g. "damage", "speed", "behavior").

Parameters:

Name	Type	Description	Default
`key`	`str`	Torpedo type identifier.	required
`attribute_name`	`str`	The attribute to read.	required

Returns:

Name	Type	Description
`str`	`str`	The attribute's value, or `None` if the torpedo type or attribute does not exist.

`torp_update_value(key, attribute_name, value)`

Update a single attribute of a registered torpedo type.

See torpedo_type for valid attribute names (e.g. "damage", "speed", "behavior").

Parameters:

Name	Type	Description	Default
`key`	`str`	Torpedo type identifier.	required
`attribute_name`	`str`	The attribute to update.	required
`value`	`str \| int`	The new value.	required

`torpedo_get_available_types_for_ship(id)`

Return the torpedo type keys currently available to a player ship.

Parameters:

Name	Type	Description	Default
`id`	`int \| Agent`	The player ship.	required

Returns:

Type	Description
`list[str]`	list[str]: Torpedo type key strings, or an empty list if none.

`torpedo_get_count_for_ship(id, key)`

Return the current count and maximum capacity of a torpedo type on a ship.

Parameters:

Name	Type	Description	Default
`id`	`int \| Agent`	The player ship.	required
`key`	`str`	Torpedo type identifier.	required

Returns:

Type	Description
`tuple[int, int]`	tuple[int, int]: `(current_count, max_capacity)`, or `(0, 0)` if the torpedo type is not available on the ship.

`torpedo_make_available(id, key, count=0, fill=True)`

Add a torpedo type to a player ship's loadout.

The torpedo type must first be registered with torpedo_type or torpedo_type_string.

Parameters:

Name	Type	Description	Default
`id`	`int \| Agent`	The player ship.	required
`key`	`str`	Torpedo type identifier.	required
`count`	`int`	Maximum capacity and initial count. Defaults to 0.	`0`
`fill`	`bool`	If `True`, set the current count to `count` (fill to max). Defaults to True.	`True`

`torpedo_make_unavailable(id, key)`

Remove a torpedo type from a player ship's loadout and zero its count.

Parameters:

Name	Type	Description	Default
`id`	`int \| Agent`	The player ship.	required
`key`	`str`	Torpedo type identifier to remove.	required

`torpedo_type(key, gui_text=None, speed=10, lifetime=25, flare_color='white', trail_color='white', warhead='standard', blast_radius=1000, damage=35, explosion_size=10, explosion_color='fire', behavior='homing', energy_conversion_value=100, other=None)`

Define and register a torpedo type on the server.

The torpedo system is actively evolving; new behaviors and warheads will be added in future versions. Use other to pass attributes not yet exposed as named params in the format "key1:value1;key2:value2;".

Parameters:

Name	Type	Description	Default
`key`	`str`	Unique identifier for this torpedo type.	required
`gui_text`	`str`	Player-visible name. Defaults to `key`.	`None`
`speed`	`int`	Movement speed. Defaults to 10.	`10`
`lifetime`	`int`	Seconds before the torpedo expires. Defaults to 25.	`25`
`flare_color`	`str`	Exhaust flare color. Defaults to `"white"`.	`'white'`
`trail_color`	`str`	Exhaust trail color. Defaults to `"white"`.	`'white'`
`warhead`	`str`	Comma-separated warhead behaviors. `"standard"` damages a single target; `"blast"` creates an area-of-effect; `"reduce_shields"` acts as an EMP. Defaults to `"standard"`.	`'standard'`
`blast_radius`	`int`	AoE radius when `warhead` includes `"blast"`. Defaults to 1000.	`1000`
`damage`	`int`	Base damage on impact. Defaults to 35.	`35`
`explosion_size`	`int`	Visual explosion size. Defaults to 10.	`10`
`explosion_color`	`str`	Visual explosion color. Defaults to `"fire"`.	`'fire'`
`behavior`	`str`	Guidance behavior. `"homing"` tracks the target; `"mine"` stays in place and detonates on proximity. Defaults to `"homing"`.	`'homing'`
`energy_conversion_value`	`int`	Energy returned when the torpedo is disassembled. Defaults to 100.	`100`
`other`	`str`	Additional key-value pairs not yet in the API, e.g. `"key1:value1;key2:value2;"`. Defaults to None.	`None`

`torpedo_type_string(key, string)`

Define a torpedo type from a CSS-style attribute string, filling missing values with defaults.

Useful when the torpedo definition originates from a data file or dynamic string rather than explicit Python parameters. Any attribute omitted from string inherits its default from torp_keys.

Parameters:

Name	Type	Description	Default
`key`	`str`	Unique identifier for this torpedo type.	required
`string`	`str`	Attribute string in `"attr:value;attr:value;"` format. See `torpedo_type` for valid attribute names.	required

Example

torpedo_type_string("Type42", "gui_text:Type 42;damage:12")