The spawn module

Create and delete space objects, NPCs, grid objects, and client agents.

Overview

The spawn module wraps the engine's object-creation calls and registers each new object with the Agent system so it can be queried, linked, and targeted by the rest of the procedural API.

Every spawn function returns either an Agent object or a SpawnData handle you can pass to to_id / to_object. Use delete_object to remove objects when no longer needed — the engine and agent registry are both cleaned up.

Key helpers:

spawn_npc — the most common call; creates an enemy or friendly ship.
spawn_player — creates a player ship for a client console.
grid_spawn — creates an engineering-grid object on a ship.
spawn_nebula / spawn_monster — terrain and special NPC variants.

Quick example

MAST pyMAST

== spawn_enemies ==
e1 = spawn_npc("Hive Emperor", "tsc", 5000, 0, 3000, "Raider 01")
add_role(e1, "enemy")
brain_add(e1, patrol_label)
station = spawn_station("Generic Station", "tsn", 0, 0, 0, "Starbase Alpha")

from sbs_utils.procedural.spawn import spawn_npc, spawn_station, delete_object

enemy = spawn_npc("Hive Emperor", "tsc", 5000, 0, 3000, "Raider 01")
station = spawn_station("Generic Station", "tsn", 0, 0, 0, "Starbase Alpha")

# ... later ...
delete_object(enemy)

Spawn functions overview

Function	Creates
`spawn_npc`	NPC ship (enemy, friendly, neutral)
`spawn_player`	Player-controlled ship
`spawn_station`	Station / base
`spawn_nebula`	Nebula terrain object
`spawn_monster`	Monster / special NPC
`spawn_generic`	Generic space object by art ID
`grid_spawn`	Engineering-grid object on a ship
`delete_object`	Removes any space object

API

`grid_spawn(id, name, tag, x, y, icon_index, color, roles)`

Spawn a grid object (engineering component) onto a ship's grid.

Parameters:

Name	Type	Description	Default
`id`	`Agent \| int`	The ship agent ID or object to attach the grid object to.	required
`name`	`str`	Display name of the grid object.	required
`tag`	`str`	Tag identifying the grid object's side or type.	required
`x`	`int`	Column position on the engineering grid.	required
`y`	`int`	Row position on the engineering grid.	required
`icon_index`	`int`	Icon index for the grid display.	required
`color`	`str`	Display color string.	required
`roles`	`str`	Comma-separated roles to assign to the grid object.	required

Returns:

Name	Type	Description
`GridObject`		The newly created grid object.

`npc_spawn(x, y, z, name, side, ship_key, behave_id)`

Spawn a non-player (NPC) ship into the simulation.

Parameters:

Name	Type	Description	Default
`x`	`float`	X spawn coordinate.	required
`y`	`float`	Y spawn coordinate.	required
`z`	`float`	Z spawn coordinate.	required
`name`	`str`	Display name, or `None`.	required
`side`	`str`	Side the ship belongs to.	required
`ship_key`	`str`	Ship template key from shipData.	required
`behave_id`	`str`	Behavior type identifier.	required

Returns:

Name	Type	Description
`SpawnData`		Spawn data for the new NPC.

`player_spawn(x, y, z, name, side, ship_key)`

Spawn a player ship into the simulation.

Parameters:

Name	Type	Description	Default
`x`	`float`	X spawn coordinate.	required
`y`	`float`	Y spawn coordinate.	required
`z`	`float`	Z spawn coordinate.	required
`name`	`str`	Display name, or `None`.	required
`side`	`str`	Side the ship belongs to.	required
`ship_key`	`str`	Ship template key from shipData.	required

Returns:

Name	Type	Description
`SpawnData`		Spawn data for the new player ship.

`terrain_spawn(x, y, z, name, side, ship_key, behave_id)`

Spawn a passive terrain object into the simulation.

Parameters:

Name	Type	Description	Default
`x`	`float`	X spawn coordinate.	required
`y`	`float`	Y spawn coordinate.	required
`z`	`float`	Z spawn coordinate.	required
`name`	`str`	Display name, or `None`.	required
`side`	`str`	Side the object belongs to, or `None`.	required
`ship_key`	`str`	Object template key from shipData.	required
`behave_id`	`str`	Behavior type identifier.	required

Returns:

Name	Type	Description
`SpawnData`		Spawn data for the new terrain object.