The internal damage system

Manage player ship engineering grid damage, repair, and ship destruction.

Overview

The internal damage system maps 3D world hit positions to grid cells on a player ship's engineering layout. Grid objects are tagged __undamaged__ or __damaged__ as system roles, and damage coefficients (beam, torpedo, impulse, warp, etc.) are recomputed after every change to keep the engine in sync.

A typical damage event flows like this:

//damage/internal route fires with EVENT.source_point
Call grid_take_internal_damage_at(DAMAGE_TARGET_ID, EVENT.source_point) to map the hit to the nearest grid cell and damage it
If all undamaged system nodes are gone, explode_player_ship is called automatically and the player_ship_destroyed signal is emitted

grid_rebuild_grid_objects recreates the entire grid from the ship's art-ID JSON (called at mission start or respawn). grid_restore_damcons resets or creates the three damcon-team crew members.

Quick example

MAST pyMAST

//damage/internal
    grid_take_internal_damage_at(DAMAGE_TARGET_ID, EVENT.source_point)

//signal/player_ship_destroyed
    log("A ship has been destroyed!")
    jump game_over

from sbs_utils.procedural.internal_damage import (
    grid_rebuild_grid_objects,
    grid_damage_system,
    grid_repair_system_damage,
    explode_player_ship,
    respawn_player_ship,
)

# At mission start
grid_rebuild_grid_objects(ship_id)

# Programmatic damage (e.g. random engine hit)
grid_damage_system(ship_id, "engine")

# Repair one node
grid_repair_system_damage(ship_id, "engine")

# Manual destroy / respawn
explode_player_ship(ship_id)
respawn_player_ship(ship_id)

Key signals

Signal	Data keys
`player_ship_destroyed`	`DESTROYED_ID`
`life_form_died`	`SHIP_ID`, `LIFE_FORM_NAME`
`life_form_hp_changed`	`SHIP_ID`, `LIFE_FORM_ID`, `HP`

API

`convert_system_to_string(the_system)`

Convert a ship system enum or integer to its role-name string.

Parameters:

Name	Type	Description	Default
`the_system`	`SHPSYS \| int \| str`	The system enum, integer index, or role-name string.	required

Returns:

Name	Type	Description
`str`		Role name for the system (`"weapon"`, `"engine"`, `"sensor"`, or `"shield"`).

`explode_player_ship(id_or_obj)`

Mark a player ship as destroyed and emit the player_ship_destroyed signal.

The ship is made invisible and tagged "exploded" rather than deleted immediately, allowing scripts to react before removal.

Parameters:

Name	Type	Description	Default
`id_or_obj`	`Agent \| int`	The player ship agent ID or object.	required

`grid_apply_system_damage(id_or_obj)`

Update system-damage counts and coefficients; explode the ship if all nodes are damaged.

Parameters:

Name	Type	Description	Default
`id_or_obj`	`Agent \| int`	The player ship agent ID or object.	required

Returns:

Name	Type	Description
`bool`		`True` if the ship has been destroyed, `False` otherwise.

`grid_count_grid_data(ship_key, role, default=0)`

Count the number of grid items that have a given role in the ship's JSON data.

Parameters:

Name	Type	Description	Default
`ship_key`	`str`	The ship art-ID key to look up in the grid data.	required
`role`	`str`	Role name to match against each grid item's role list.	required
`default`	`int`	Value returned if the ship key is not found in the grid data. Defaults to 0.	`0`

Returns:

Name	Type	Description
`int`		Number of grid items with the specified role.

`grid_damage_grid_object(ship_id, grid_id, damage_color)`

Mark a grid object as damaged and apply a damage color to its icon.

Tools, markers, and rally-point objects are ignored.

Parameters:

Name	Type	Description	Default
`ship_id`	`Agent \| int`	The player ship agent ID or object.	required
`grid_id`	`Agent \| int`	The grid object to damage.	required
`damage_color`	`str`	Color to apply to the damaged grid-object icon.	required

`grid_damage_hallway(id_or_obj, loc_x, loc_y, damage_color)`

Spawn a fire/damage marker at an empty hallway grid cell.

Parameters:

Name	Type	Description	Default
`id_or_obj`	`Agent \| int`	The player ship agent ID or object.	required
`loc_x`	`int`	Grid column of the hallway cell.	required
`loc_y`	`int`	Grid row of the hallway cell.	required
`damage_color`	`str`	Color to apply to the damage marker icon.	required

`grid_damage_pos(id_or_obj, loc_x, loc_y)`

Apply internal damage at a specific grid cell.

If no grid object occupies the cell a hallway-fire marker is placed instead.

Parameters:

Name	Type	Description	Default
`id_or_obj`	`Agent \| int`	The player ship agent ID or object.	required
`loc_x`	`int`	Grid column to damage.	required
`loc_y`	`int`	Grid row to damage.	required

`grid_damage_system(id_or_obj, the_system=None)`

Damage a random undamaged grid node for the specified ship system.

Parameters:

Name	Type	Description	Default
`id_or_obj`	`Agent \| int \| CloseData \| SpawnData`	The player ship.	required
`the_system`	`SHPSYS \| int \| str`	The system to damage. If `None`, a system is chosen at random. Defaults to None.	`None`

Returns:

Name	Type	Description
`bool`		`True` if a node was damaged; `False` if no undamaged nodes remain or the ship has already exploded.

`grid_get_max_hp()`

Return the current global maximum HP value for damcon-team grid objects.

Returns:

Name	Type	Description
`int`		The max HP setting (default 6).

`grid_rebuild_grid_objects(id_or_obj, grid_data=None)`

Rebuild all engineering-grid objects on a ship from shipData JSON.

Deletes all existing grid objects for the ship, then re-creates them from the grid layout defined in the ship's art-ID entry in grid_data. Also re-creates the damcon teams, the position marker, and the EPad.

Parameters:

Name	Type	Description	Default
`id_or_obj`	`Agent \| int`	The player ship agent ID or object.	required
`grid_data`	`dict`	Pre-loaded grid data. If `None`, loaded via `grid_get_grid_data()`.	`None`

`grid_repair_grid_objects(player_ship, id_or_set, who_repaired=None)`

Repair one or more grid objects and update the ship's damage state.

Hallway-fire markers are deleted; system nodes have their icon color restored and the system-damage count decremented. Recomputes damage coefficients if any system node was healed.

Parameters:

Name	Type	Description	Default
`player_ship`	`Agent \| int`	The player ship agent ID or object.	required
`id_or_set`	`Agent \| int \| set[Agent \| int]`	Grid object(s) to repair.	required
`who_repaired`	`Agent \| int`	The damcon-team agent that performed the repair (used to remove work-order links). Defaults to None.	`None`

`grid_repair_system_damage(id_or_obj, the_system=None)`

Repair a single damaged grid node for the specified system.

Parameters:

Name	Type	Description	Default
`id_or_obj`	`Agent \| int`	The player ship agent ID or object.	required
`the_system`	`SHPSYS \| int \| str`	The system to repair. If `None`, a system is chosen at random. Defaults to None.	`None`

Returns:

Name	Type	Description
`bool`		`True` if a node was repaired; `False` if no damaged nodes remain for that system.

`grid_restore_damcons(id_or_obj)`

Restore all damcon teams on a ship to full health, creating them if missing.

Parameters:

Name	Type	Description	Default
`id_or_obj`	`Agent \| int`	The player ship agent ID or object.	required

`grid_set_hp(ship_id, GRID_OBJECT_ID, hp)`

Set the HP of a damcon-team grid object and emit the life_form_hp_changed signal.

Parameters:

Name	Type	Description	Default
`ship_id`	`Agent \| int`	The player ship agent ID or object.	required
`GRID_OBJECT_ID`	`Agent \| int`	The damcon-team grid object ID or agent.	required
`hp`	`int`	The new HP value to assign.	required

`grid_set_max_hp(max_hp)`

Set the global maximum hit-point value for damcon-team grid objects.

Parameters:

Name	Type	Description	Default
`max_hp`	`int`	New maximum HP value. Defaults to 6 at module load.	required

`grid_take_internal_damage_at(id_or_obj, source_point, system_hit=None, damage_amount=None)`

Apply internal damage to a ship at a 3D world position.

Maps the 3D position to the nearest grid cell, then damages the grid objects at that cell (or a hallway marker if the cell is empty). Also injures any damcon-team lifeforms at the impact location.

Parameters:

Name	Type	Description	Default
`id_or_obj`	`Agent \| int`	The player ship agent ID or object.	required
`source_point`	`Vec3`	3D position of the hit.	required
`system_hit`	`SHPSYS \| int \| str`	Unused. Defaults to None.	`None`
`damage_amount`	`int`	Unused. Defaults to None.	`None`

Returns:

Name	Type	Description
`bool`		`True` if the ship was destroyed by this damage.

`respawn_player_ship(id_or_obj)`

Respawn a previously destroyed player ship at its original spawn position.

Restores the ship's art ID, repositions it to the spawn point, and removes the "exploded" role.

Parameters:

Name	Type	Description	Default
`id_or_obj`	`Agent \| int`	The player ship agent ID or object.	required

`set_damage_coefficients(id_or_obj)`

Recalculate and write the damage coefficients for all ship systems.

For each system (beam, torpedo, impulse, warp, maneuver, sensors, shields) computes the ratio of undamaged to total nodes and writes it to the blob.

Parameters:

Name	Type	Description	Default
`id_or_obj`	`Agent \| int`	The player ship agent ID or object.	required