The ship_data module

Load and query the ship-definition JSON database.

Overview

Cosmos ships are defined in a JSON database keyed by art ID (e.g. "tsn_battle_cruiser"). The ship_data module loads this database and provides helpers for looking up ship properties such as display name, base stats, and available systems.

get_ship_data returns the raw dict for a given art ID. get_all_ship_data returns the entire database. get_ship_data_value is a convenience wrapper that reads a single key from a ship's entry with a default fallback.

The database is loaded lazily and cached. Mission scripts do not normally need to interact with this module directly — higher-level spawn functions look up ship data automatically.

Quick example

MAST pyMAST

== pick_ship ==
    ship_db = get_ship_data("tsn_battle_cruiser")
    display_name = ship_db.get("name", "Unknown")
    log(f"Spawning a {display_name}")
    speed = get_ship_data_value("tsn_battle_cruiser", "topSpeed", 10)
    ->END

from sbs_utils.procedural.ship_data import (
    get_ship_data, get_all_ship_data, get_ship_data_value,
)

# Single ship lookup
data = get_ship_data("tsn_battle_cruiser")
name = data.get("name", "Unknown")

# Key with default
speed = get_ship_data_value("tsn_battle_cruiser", "topSpeed", 10)

# Iterate all ships
for art_id, ship in get_all_ship_data().items():
    print(art_id, ship.get("name"))

Common ship data keys

Key	Description
`"name"`	Display name
`"side"`	Default faction side
`"race"`	Race/species string
`"topSpeed"`	Maximum speed
`"shieldStrengthFront"` / `"shieldStrengthBack"`	Shield strength
`"maxEnergy"`	Energy capacity

API

`alien_keys()`

Return all pickup keys containing "alien" (cached).

Returns:

Type	Description
	list[str]: Alien pickup type keys.

`arvonian_ship_keys()`

Return all Arvonian ship keys (cached).

Returns:

Type	Description
	list[str]: Arvonian ship type keys.

`arvonian_starbase_keys()`

Return all Arvonian starbase keys (cached).

Returns:

Type	Description
	list[str]: Arvonian starbase type keys.

`asteroid_keys()`

Return all asteroid ship keys from the ship data (cached).

Returns:

Type	Description
	list[str]: Asteroid type keys.

`container_keys()`

Return all pickup keys containing "container" (cached).

Returns:

Type	Description
	list[str]: Container pickup type keys.

`crystal_asteroid_keys()`

Return all crystal asteroid keys, excluding plain asteroids (cached).

Returns:

Type	Description
	list[str]: Crystal asteroid type keys.

`danger_keys()`

Return all pickup keys containing "danger" (cached).

Returns:

Type	Description
	list[str]: Danger pickup type keys.

`filter_ship_data_by_side(test_ship_key, sides, role=None, ret_key_only=False)`

Return ship data entries matching a key substring, side filter, and optional role.

Parameters:

Name	Type	Description	Default
`test_ship_key`	`str \| None`	Substring that must appear in the ship key, or `None` to match all keys.	required
`sides`	`str`	Comma-separated side names to include (case-insensitive).	required
`role`	`str`	Single role that must be in the ship's role list. Defaults to None (no role filter).	`None`
`ret_key_only`	`bool`	Return a list of key strings instead of full data dicts. Defaults to False.	`False`

Returns:

Type	Description
	list[str \| dict]: Matching ship keys or data entries.

`get_ship_data()`

Load and cache the full ship data, merging extraShipData.json if present.

Results are cached after the first call. The mission-directory extraShipData.json is prepended to the #ship-list so mission ships take priority over built-in data.

Returns:

Name	Type	Description
`dict`		The merged ship data dictionary.

`get_ship_data_for(ship_key)`

Return the full ship data entry for a given key.

Parameters:

Name	Type	Description	Default
`ship_key`	`str`	The ship type key.	required

Returns:

Type	Description
	dict \| None: Ship data dict, or `None` if not found.

`get_ship_index()`

Return ship data indexed by ship key for fast O(1) lookup.

Returns:

Type	Description
	dict[str, dict]: Mapping of ship key → ship data entry.

`get_ship_name(ship_key)`

Return the display name of a ship type by key.

Parameters:

Name	Type	Description	Default
`ship_key`	`str`	The ship type key.	required

Returns:

Type	Description
	str \| None: Ship display name, or `None` if the key is not found.

`kralien_ship_keys()`

Return all Kralien ship keys (cached).

Returns:

Type	Description
	list[str]: Kralien ship type keys.

`kralien_starbase_keys()`

Return all Kralien starbase keys (cached).

Returns:

Type	Description
	list[str]: Kralien starbase type keys.

`merge_mod_ship_data(mod)`

Merge a mod folder's extraShipData.json into the ship data cache.

Parameters:

Name	Type	Description	Default
`mod`	`str`	Mod directory name (resolved via `get_mod_dir`).	required

Returns:

Name	Type	Description
`dict`		The updated ship data cache.

`pirate_ship_keys()`

Return all pirate ship keys (cached).

Returns:

Type	Description
	list[str]: Pirate ship type keys.

`pirate_starbase_keys()`

Return all pirate starbase keys (cached).

As of v1.2.2 no pirate starbases exist in shipData; this returns an empty list.

Returns:

Type	Description
	list[str]: Pirate starbase type keys.

`plain_asteroid_keys()`

Return all plain asteroid keys, excluding crystal asteroids (cached).

Returns:

Type	Description
	list[str]: Plain asteroid type keys.

`reset_ship_data_caches()`

Clear all ship data and key-list caches.

Use when switching missions to ensure stale ship data from a previous mission directory is not used.

`skaraan_ship_keys()`

Return all Skaraan ship keys (cached).

Returns:

Type	Description
	list[str]: Skaraan ship type keys.

`skaraan_starbase_keys()`

Return all Skaraan starbase keys (cached).

Returns:

Type	Description
	list[str]: Skaraan starbase type keys.

`terran_ship_keys()`

Return all TSN ship keys (cached).

Returns:

Type	Description
	list[str]: Terran ship type keys.

`terran_starbase_keys()`

Return all USPF station (Terran starbase) keys (cached).

Returns:

Type	Description
	list[str]: Terran starbase type keys.

`torgoth_ship_keys()`

Return all Torgoth ship keys (cached).

Returns:

Type	Description
	list[str]: Torgoth ship type keys.

`torgoth_starbase_keys()`

Return all Torgoth starbase keys (cached).

Returns:

Type	Description
	list[str]: Torgoth starbase type keys.

`ximni_ship_keys()`

Return all Ximni ship keys (cached).

Returns:

Type	Description
	list[str]: Ximni ship type keys.

`ximni_starbase_keys()`

Return all Ximni starbase keys (cached).

Returns:

Type	Description
	list[str]: Ximni starbase type keys.