Skip to content

The prefab system

Reusable MAST labels that spawn entities and configure them in one call.

Overview

A prefab is a MAST label treated as a self-contained spawn template. prefab_spawn runs the label as an independent task (not a child of the caller) and injects START_X, START_Y, START_Z, and NAME from the data dict so the label can position and name its object without needing arguments. The OFFSET_* params shift the spawn position without modifying the original data.

prefab_extends is the sub-task variant — it attaches to the calling task instead of running independently. Both set self and prefab variables so the prefab label can call back to its own task.

prefab_autoname is applied automatically when NAME contains a # placeholder — it replaces # with an auto-incrementing zero-padded integer, making it easy to produce unique names like "Enemy 01", "Enemy 02".

A PrefabAll promise (returned from grouping multiple prefab_spawn calls via task_all) collects the spawned agent IDs into a set once all tasks complete.

Quick example

== spawn_enemy_wave ==
prefab_spawn(enemy_prefab, {"START_X": 5000, "START_Z": 3000, "NAME": "Raider #"})
prefab_spawn(enemy_prefab, {"START_X": 5500, "START_Z": 3000, "NAME": "Raider #"})
== enemy_prefab ==
id = spawn_enemy(START_X, START_Y, START_Z, NAME)
add_role(id, "enemy")

from sbs_utils.procedural.prefab import prefab_spawn, prefab_extends, prefab_autoname

# Spawn at position with auto-numbered name
task = prefab_spawn(enemy_prefab, {
    "START_X": 5000, "START_Z": 3000, "NAME": "Raider #"
})

# Spawn with position offset
prefab_spawn(station_prefab, {"START_X": 0, "START_Z": 0}, OFFSET_X=2000, OFFSET_Z=1000)

# Run as sub-task of current label
prefab_extends(setup_subsection, data={"color": "red"})

NAME auto-numbering

If data["NAME"] contains #, the # is replaced with a sequential counter:

"Fighter #"  →  "Fighter 01", "Fighter 02", ...
"Drone ###"  →  "Drone 001", "Drone 002", ...

API

PrefabAll

Bases: PromiseAllAny

result()

Get a set of the results of all of the promises. Returns: set[Promise]: The set of promise results

prefab_autoname(name)

Return name with the # placeholder replaced by an auto-incrementing number.

If name contains #, the prefix before # is used as a counter key and the # (plus any trailing characters) is replaced with a zero-padded incrementing integer. Names without # are returned unchanged.

Parameters:

Name Type Description Default
name str

Name template, optionally containing #.

 required

Returns:

Name Type Description
str

The name with # replaced by a unique number, or the original name if no # was found.

prefab_extends(label, data=None)

Run a prefab label as a sub-task of the current task.

Unlike prefab_spawn, which creates an independent task, this attaches the prefab as a child of the calling task and sets self/prefab variables so the sub-task can refer back to its parent.

Parameters:

Name Type Description Default
label str | Label

The label to run as a sub-task.

 required
data dict

Variables passed into the sub-task. Defaults to None.

 None

Returns:

Name Type Description
MastAsyncTask

The running sub-task.

prefab_spawn(label, data=None, OFFSET_X=None, OFFSET_Y=None, OFFSET_Z=None)

Spawn a prefab label as an independent task and return it.

Positional keys START_X, START_Y, START_Z inside data set the spawn origin (default 0). The OFFSET_* params shift that origin without modifying the original data dict. If data contains a NAME key with a # placeholder, prefab_autoname is applied to generate a unique name.

Parameters:

Name Type Description Default
label str | Label

The label to spawn.

 required
data dict

Variables passed into the prefab task. May include START_X, START_Y, START_Z, and NAME. Defaults to None.

 None
OFFSET_X float

X offset added to START_X. Defaults to None (no offset).

 None
OFFSET_Y float

Y offset added to START_Y. Defaults to None (no offset).

 None
OFFSET_Z float

Z offset added to START_Z. Defaults to None (no offset).

 None

Returns:

Name Type Description
MastAsyncTask

The running prefab task, or None if the label is invalid.