Life form system

Spawn and manage grid-based crew members and lifeforms on the engineering console.

Overview

Lifeforms are grid objects that move autonomously around the engineering grid. They are used for damcon crew members, marines, and other entities that exist inside a ship. Each lifeform has an HP value tracked via inventory, and the life_form_died / life_form_hp_changed signals fire as they take damage.

lifeform_spawn creates a new lifeform grid object on a ship at a given grid position. HP is set via grid_set_hp from the internal_damage module. Lifeforms can be given roles for targeting and filtering ("damcons", "crew", "lifeform").

Damcon crew creation is handled automatically by grid_restore_damcons in the internal_damage module — you normally don't need to spawn damcons manually.

Quick example

MAST pyMAST

== spawn_marine ==
    marine = lifeform_spawn(ship_id, "Marine", "marine_01", 3, 4, 2, "white", "crew,marine")
    grid_set_hp(ship_id, marine, 6)
    ->END

//signal/life_form_died
    log(f"Crew member {LIFE_FORM_NAME} has perished!")

from sbs_utils.procedural.lifeform import lifeform_spawn
from sbs_utils.procedural.internal_damage import grid_set_hp

marine = lifeform_spawn(ship_id, "Marine", "marine_01", 3, 4, icon=2, color="white", roles="crew,marine")
grid_set_hp(ship_id, marine, 6)

API

`lifeform_init(self, name, face, roles, host=None, comms_id=None, path=None, title_color='green', message_color='white')`

Initialise an existing Agent as a lifeform (in-place version of lifeform_spawn).

Parameters:

Name	Type	Description	Default
`self`	`Agent`	The agent to initialise.	required
`name`	`str`	Display name of the lifeform.	required
`face`	`str`	Face image key.	required
`roles`	`str`	Comma-separated roles to assign.	required
`host`	`Agent \| int`	Space object the lifeform boards. Defaults to None.	`None`
`comms_id`	`str`	Unused. Defaults to None.	`None`
`path`	`str`	Comms route path. Defaults to None.	`None`
`title_color`	`str`	Color of the comms title line. Defaults to `"green"`.	`'green'`
`message_color`	`str`	Color of the comms message text. Defaults to `"white"`.	`'white'`

`lifeform_set_path(lifeform, path=None)`

Set the comms route path for a lifeform.

Clears the comms_badge role when path is None, and adds it when a path is set.

Parameters:

Name	Type	Description	Default
`lifeform`	`Agent \| int`	The lifeform agent or its ID.	required
`path`	`str`	The comms route path. Defaults to None (clears).	`None`

`lifeform_spawn(name, face, roles, host=None, comms_id=None, path=None, title_color='green', message_color='white')`

Create a new Agent and initialise it as a lifeform.

Parameters:

Name	Type	Description	Default
`name`	`str`	Display name of the lifeform.	required
`face`	`str`	Face image key.	required
`roles`	`str`	Comma-separated roles to assign (e.g. `"crew,medic"`).	required
`host`	`Agent \| int`	Space object the lifeform boards. Defaults to None.	`None`
`comms_id`	`str`	Unused. Defaults to None.	`None`
`path`	`str`	Comms route path for this lifeform. Defaults to None.	`None`
`title_color`	`str`	Color of the comms title line. Defaults to `"green"`.	`'green'`
`message_color`	`str`	Color of the comms message text. Defaults to `"white"`.	`'white'`

Returns:

Name	Type	Description
`Agent`		The newly created lifeform agent.

`lifeform_transfer(lifeform, new_host)`

Move a lifeform to a new host space object, emitting lifeform_transferred.

Unlinks from the old host (if any) and links to the new one. If new_host is not a space object ID the lifeform gains the "ultra_beam" role instead.

Parameters:

Name	Type	Description	Default
`lifeform`	`Agent \| int`	The lifeform agent or its ID.	required
`new_host`	`Agent \| int`	The new host space object or its ID.	required