The comms system

Send messages to player consoles and manage the comms-tree route system.

Overview

The comms module provides two related capabilities:

Broadcast messages — comms_broadcast sends a text message to the comms panel of a ship (or all ships). Messages appear as incoming transmissions on the comms console. Use comms_broadcast for NPC dialogue, status updates, and mission narration that the crew hears.

Comms routes — the //comms/<path> route system defines the interactive comms tree that players navigate using the comms console. Use comms_route_to from Python/MAST to programmatically navigate the tree, and comms_select to set which NPC a player is talking to.

Quick example

MAST pyMAST

//comms/alien
    + "Greetings, humans." //comms/alien/greet

//comms/alien/greet
    + "We come in peace.":
        signal_emit("alliance_offered")
    + "Stand down!":
        target(alien_id, player_ship_id)

== patrol ==
    comms_broadcast(ship_id, "Enemy spotted at grid 7-Alpha!", "red")
    ->END

from sbs_utils.procedural.comms import comms_broadcast, comms_route_to

comms_broadcast(ship_id, "Incoming transmission!", "yellow")
comms_route_to(client_id, "alien/greet")

API

`comms(path=None, buttons=None, timeout=None)`

Suspend the current task and present comms buttons, waiting for a choice.

Must be called from a server task (client_id == 0). The task resumes when a comms button is pressed or timeout resolves. The //comms/path route hierarchy controls which buttons appear.

Parameters:

Name	Type	Description	Default
`path`	`str \| None`	Initial comms path. Defaults to `"comms"` (root).	`None`
`buttons`	`dict \| None`	Inline button definitions as `{"button label": label_to_run, ...}`. Buttons are sticky (equivalent to `+` buttons in MAST). Defaults to None.	`None`
`timeout`	`Promise \| None`	A promise that ends the comms interaction when it resolves (e.g. from `delay_promise`). Defaults to None (no timeout).	`None`

Returns:

Name	Type	Description
`CommsPromise`	`CommsPromise`	Resolves when a button is selected or timeout fires.

Example

await comms() await comms(timeout=delay_promise(seconds=30))

`comms_add_button(message, label=None, color=None, data=None, path=None)`

Add a button to the currently active comms panel at runtime.

Injects a sticky button into the comms button list of whichever ButtonPromise is currently navigating. Call this from inside a //comms/ route to add dynamic buttons beyond those defined statically.

Parameters:

Name	Type	Description	Default
`message`	`str`	Button label text.	required
`label`	`label \| None`	MAST label to run when pressed. Defaults to None.	`None`
`color`	`str \| None`	Button text color. Defaults to None (inherits the comms default).	`None`
`data`	`dict \| None`	Variables passed to the button handler. Defaults to None.	`None`
`path`	`str \| None`	Comms sub-path to restrict the button to. Defaults to None (shown at the current path).	`None`

Example

//comms/patrol comms_add_button("Retreat", retreat_label, color="yellow")

`comms_broadcast(ids_or_obj, msg, color=None)`

Send a text message to the text waterfall of one or more targets.

Accepts player ship IDs or client/console IDs. Ship IDs use send_message_to_player_ship; client IDs use send_message_to_client.

Parameters:

Name	Type	Description	Default
`ids_or_obj`		Agent ID, client ID, or set/list of either to send to. Pass `None` to send to the event's `parent_id`.	required
`msg`	`str`	The message text. Supports `{var}` interpolation.	required
`color`	`str`	Text color as a name or hex string, e.g. `"red"` or `"#3ff"`. Defaults to `"#fff"`.	`None`

Example

comms_broadcast(SHIP_ID, "Red alert!", color="red")

`comms_info(name, face=None, color=None)`

Update the comms selection info panel with a name and portrait.

Sets the name and face shown in the comms console's selection panel for the current origin/selected ship pair. Use this from a //comms/ route to customise what the player sees before pressing buttons.

Parameters:

Name	Type	Description	Default
`name`	`str`	Display name to show in the info panel.	required
`face`	`str`	Face asset string for the portrait. Defaults to the face registered for the selected object.	`None`
`color`	`str`	Text color. Defaults to `"white"`.	`None`

Example

comms_info("Commander Karn", face="crew/karn", color="red")

`comms_info_face_override(face=None)`

Override the face portrait shown in the comms panel for this interaction.

Sets a one-time face override on the current ButtonPromise. The override applies until the player selects a different comms target or the interaction ends.

Parameters:

Name	Type	Description	Default
`face`	`str \| None`	Face asset string to show, or `None` to clear any existing override and revert to the default.	`None`

Example

comms_info_face_override("crew/commander")

`comms_message(msg, from_ids_or_obj, to_ids_or_obj, title=None, face=None, color=None, title_color=None, is_receive=True, from_name=None)`

Send a comms message with explicit sender and receiver control.

Lower-level function used by comms_transmit and comms_receive. Handles lifeforms, side colors, CommsOverride, and emits the comms_message signal. Prefer comms_transmit or comms_receive unless you need direct sender/receiver control.

Parameters:

Name	Type	Description	Default
`msg`	`str`	The message body text. Supports `{var}` interpolation.	required
`from_ids_or_obj`		Sender agent ID(s) or object(s).	required
`to_ids_or_obj`		Receiver agent ID(s) or object(s). Pass `None` to send the message to the sender (internal communication).	required
`title`	`str`	Title bar text. Defaults to the sender's comms ID.	`None`
`face`	`str`	Face asset string for the sender portrait. Defaults to the face registered for the sender.	`None`
`color`	`str`	Body text color. Defaults to `"#fff"`.	`None`
`title_color`	`str`	Title text color. Defaults to the sender's side color.	`None`
`is_receive`	`bool`	`True` = message is received (`< <` prefix); `False` = message is sent (`> >` prefix). Defaults to `True`.	`True`
`from_name`	`str`	Override the display name of the sender. Defaults to None (uses the sender object's `comms_id`).	`None`

Example

comms_message("Incoming!", ENEMY_ID, SHIP_ID, title="Commander")

`comms_navigate(path, face=None, comms_badge=None)`

Navigate the current comms interaction to a different button path.

Changes which //comms/ route sub-path is active, updating the buttons shown to the player. Call this from inside a comms button handler to implement multi-level comms menus.

Parameters:

Name	Type	Description	Default
`path`	`str`	Target comms sub-path, e.g. `"patrol"` (expanded to `//comms/patrol`). Pass `None` or `""` to reset to the root.	required
`face`	`str \| None`	Face override to apply when navigating. Defaults to None (keep current face).	`None`
`comms_badge`	`object \| None`	Lifeform or ID to associate as the comms badge on the new path. Defaults to None.	`None`

Example

//comms + "Talk to Commander" comms_navigate("commander") //comms/commander + "Order attack" comms_receive("Attack formation!", title="Commander")

`comms_navigate_override(ids_or_obj, sel_ids_or_obj, path=None, path_must_match=True)`

Navigate a comms interaction from outside the comms task.

Refreshes the buttons shown for the specified origin/selected pair. Use this when the story needs to update comms buttons from a non-comms task (e.g. a timer or event handler). If the pair is currently selected, the new buttons appear immediately.

Parameters:

Name	Type	Description	Default
`ids_or_obj`		Player ship ID(s) or object(s) (origin side).	required
`sel_ids_or_obj`		Target ID(s) or object(s) (selected side).	required
`path`	`str \| None`	Comms sub-path to navigate to. Defaults to None (reuses the current path of the active interaction).	`None`
`path_must_match`	`bool`	Only navigate if the active path already matches `path`, avoiding disorienting mid-menu jumps. Defaults to `True`.	`True`

Example

comms_navigate_override(SHIP_ID, ENEMY_ID, "commander/angry")

`comms_override(origin_id=None, selected_id=None, face=None, from_name=None)`

Create a context manager to override comms sender/receiver fields.

Use as a with block to temporarily redirect comms calls (comms_transmit, comms_receive, etc.) to specific IDs or a fixed face/name without changing the underlying event.

Parameters:

Name	Type	Description	Default
`origin_id`	`int \| None`	Override the origin (player ship) ID. Accepts any form accepted by `to_set`. Defaults to None.	`None`
`selected_id`	`int \| None`	Override the selected (target) ID. Defaults to None.	`None`
`face`	`str \| None`	Override the face asset string. Defaults to None.	`None`
`from_name`	`str \| None`	Override the sender display name. Defaults to None.	`None`

Returns:

Name	Type	Description
`CommsOverride`		A context manager; use with `with`.

Example

with comms_override(origin_id=SHIP_ID, selected_id=ENEMY_ID): comms_receive("Surrender or be destroyed.", title="Klingon")

`comms_receive(msg, title=None, face=None, color=None, title_color=None)`

Receive a comms message on a player ship from the selected target.

Reads origin and selected IDs from the current event context (or COMMS_ORIGIN_ID/COMMS_SELECTED_ID task variables). Sends the message with a < < prefix indicating an incoming transmission.

Parameters:

Name	Type	Description	Default
`msg`	`str`	The message body text. Supports `{var}` interpolation.	required
`title`	`str`	Title bar text. Defaults to the sender's comms ID.	`None`
`face`	`str`	Face asset string for the portrait. Defaults to the face registered for the sender.	`None`
`color`	`str`	Body text color. Defaults to `"#fff"`.	`None`
`title_color`	`str`	Title text color. Defaults to the sender's side color.	`None`

Example

comms_receive("Docking clearance granted.", title="Station")

`comms_receive_internal(msg, ids_or_obj=None, from_name=None, title=None, face=None, color=None, title_color=None)`

Receive an internal crew comms message (ship talking to itself).

Sends a message where both sender and receiver are the same ship, used for incoming internal crew messages (e.g. engineering to bridge). The ship is read from the event context or from ids_or_obj.

Parameters:

Name	Type	Description	Default
`msg`	`str`	The message body text. Supports `{var}` interpolation.	required
`ids_or_obj`		Agent ID(s) or object(s) of the receiving ship. Defaults to the origin ship from the current event context.	`None`
`from_name`	`str`	Name of the internal sender (e.g. `"Engineering"`). Used to look up a registered face via `face_Engineering` inventory key. Defaults to the ship's name.	`None`
`title`	`str`	Title bar text. Defaults to None.	`None`
`face`	`str`	Face asset string for the portrait. Defaults to the face registered for `from_name`.	`None`
`color`	`str`	Body text color. Defaults to `"#fff"`.	`None`
`title_color`	`str`	Title text color. Defaults to None.	`None`

Example

comms_receive_internal("Power restored.", from_name="Engineering")

`comms_set_2dview_focus(client_id, focus_id=0, EVENT=None)`

Set the 2D radar view to follow an alternate ship for a comms client.

Stores focus_id as the alternate ship to track on the 2D radar for both the client and its assigned ship. The view only actually updates if the 2d_follow inventory flag is set on the client.

Parameters:

Name	Type	Description	Default
`client_id`	`int`	The client whose radar should be updated.	required
`focus_id`	`int`	ID of the ship to track, or `0` to reset to the client's own ship. Defaults to 0.	`0`
`EVENT`		Unused; present for route-handler compatibility.	`None`

Example

comms_set_2dview_focus(CLIENT_ID, ENEMY_ID)

`comms_speech_bubble(msg, seconds=3, color=None, client_id=None, selected_id=None)`

Display a speech bubble attached to the currently selected space object.

Attaches a timed text bubble to the selected object on the client's 2D radar. The client and selected object are read from the current event context — client_id and selected_id parameters are accepted but currently overridden by the event.

Parameters:

Name	Type	Description	Default
`msg`	`str`	Text to display in the speech bubble.	required
`seconds`	`float`	Duration the bubble is shown. Pass `0` for a permanent bubble. Defaults to 3.	`3`
`color`	`str`	Text color as a name or hex string. Defaults to `"#fff"`.	`None`
`client_id`	`int \| None`	Currently unused; read from event.	`None`
`selected_id`	`int \| None`	Currently unused; read from event.	`None`

Example

comms_speech_bubble("Curse you, Terran!", seconds=5)

`comms_story_buttons(ids, sel_ids, buttons, path, nav_button=None)`

Inject story-controlled buttons into active comms interactions and wait for a choice.

Attaches a CommsChoiceButtonPromise to every active comms task that matches the given origin/selected pairs. The buttons appear at path and disappear when one is pressed. An optional nav_button adds a navigation button at the parent path to enter this sub-menu.

Parameters:

Name	Type	Description	Default
`ids`		Player ship ID(s) or object(s) (origin side).	required
`sel_ids`		Target ID(s) or object(s) (selected side).	required
`buttons`	`list[str]`	Button label strings to present.	required
`path`	`str`	Comms path where the buttons appear, e.g. `"comms/rescue"`.	required
`nav_button`	`str \| None`	Label for a navigation button shown at the parent path that leads to `path`. Defaults to None (no nav button).	`None`

Returns:

Name	Type	Description
`CommsChoiceButtonPromise`	`CommsChoiceButtonPromise`	Resolves with the pressed button label.

Example

result = await comms_story_buttons( SHIP_ID, ENEMY_ID, ["Accept surrender", "Reject"], "comms/surrender", nav_button="Discuss surrender" )

`comms_transmit(msg, title=None, face=None, color=None, title_color=None)`

Transmit a comms message from the player ship to the selected target.

Reads origin and selected IDs from the current event context (or COMMS_ORIGIN_ID/COMMS_SELECTED_ID task variables). Sends the message with a > > prefix indicating an outgoing transmission.

Parameters:

Name	Type	Description	Default
`msg`	`str`	The message body text. Supports `{var}` interpolation.	required
`title`	`str`	Title bar text. Defaults to the sender's comms ID.	`None`
`face`	`str`	Face asset string for the portrait. Defaults to the face registered for the sender.	`None`
`color`	`str`	Body text color. Defaults to `"#fff"`.	`None`
`title_color`	`str`	Title text color. Defaults to the sender's side color.	`None`

Example

comms_transmit("Requesting docking clearance.", title="Artemis")

`comms_transmit_internal(msg, ids_or_obj=None, to_name=None, title=None, face=None, color=None, title_color=None)`

Transmit an internal crew comms message (ship talking to itself).

Sends a message where both sender and receiver are the same ship, used for internal crew communications (e.g. bridge to engineering). The origin ship is read from the current event context.

Parameters:

Name	Type	Description	Default
`msg`	`str`	The message body text. Supports `{var}` interpolation.	required
`ids_or_obj`		Unused — origin ship is always read from the event.	`None`
`to_name`	`str`	Name of the internal recipient (e.g. `"Engineering"`). Used to look up a registered face via `face_Engineering` inventory key. Defaults to the ship's name.	`None`
`title`	`str`	Title bar text. Defaults to None.	`None`
`face`	`str`	Face asset string for the portrait. Defaults to the face registered for `to_name`.	`None`
`color`	`str`	Body text color. Defaults to `"#fff"`.	`None`
`title_color`	`str`	Title text color. Defaults to None.	`None`

Example

comms_transmit_internal("Shields holding.", to_name="Engineering")