The science module

Control and respond to science console scanning and intel display.

Overview

The science module provides helpers for the science console: setting what information is shown when an object is scanned, controlling scan-data visibility, and emitting the scan event programmatically.

science_add_scan_data attaches key→value intel entries to an object that appear on the science console when the player scans it. science_clear_scan_data removes them.

The //focus/science route fires when the science console focuses on an object. The selected object's ID is in EVENT.selected_id.

Quick example

MAST pyMAST

== setup ==
    science_add_scan_data(enemy_id, "Ship Class", "Battlecruiser")
    science_add_scan_data(enemy_id, "Threat Level", "High")
    science_add_scan_data(enemy_id, "Shields", "Online")
    ->END

//focus/science
    if EVENT.selected_id == enemy_id: jump enemy_scanned

== enemy_scanned ==
    comms_broadcast(ship_id, "Science: Enemy battlecruiser detected!", "red")
    ->END

from sbs_utils.procedural.science import science_add_scan_data, science_clear_scan_data

science_add_scan_data(enemy_id, "Ship Class", "Battlecruiser")
science_add_scan_data(enemy_id, "Threat Level", "High")
science_clear_scan_data(enemy_id)

API

scan(path=None, buttons=None, timeout=None, auto_side=True)

Start a science scan and return a promise that resolves when scanning is complete.

Parameters:

Name	Type	Description	Default
path	str	Route path prefix for scan button labels. Defaults to None.	None
buttons	dict	Extra buttons as {label_text: label} pairs. Defaults to None.	None
timeout	Promise	A timeout promise (e.g. from timeout()). Defaults to None.	None
auto_side	bool	Instantly complete scanning for same-side objects. Defaults to True.	True

Returns:

Name	Type	Description
ScanPromise		A promise to await; resolves when all tabs are scanned.

scan_results(message, target=None, tab=None)

Set the scan results for the current scan. This should be called when the scan is completed. This is typically called as part of a scan() This could also be called in response to a routed science message. When paired with a scan() the target and tab are not needed. Tab is the variable SCAN_TAB, target is track

Parameters:

Name	Type	Description	Default
message	str	Scan text for a scan that is in progress.	required
target	Any	Not currently used. Default is None.	None
tab	str	Scan tab for a scan that is in progress. Default is None.	None

science_add_scan(message, label=None, data=None, path=None)

Add a scan button to the current science scan promise.

Parameters:

Name	Type	Description	Default
message	str	Button text shown in the science UI.	required
label	str | Label	Label to run when the button is pressed.	None
data	dict	Variables passed to the button's label.	None
path	str	Route path to navigate to when pressed.	None

science_ensure_scan(ids_or_objs, target_ids_or_objs, tabs='scan')

Force a completed scan result onto all (scanner, target) pairs.

Useful for scripted encounters where objects should appear pre-scanned without waiting for player interaction. Pass tabs="*" to populate every tab the target exposes.

Parameters:

Name	Type	Description	Default
ids_or_objs	set[Agent | int]	The scanning player ship(s).	required
target_ids_or_objs	set[Agent | int]	The object(s) to mark as scanned.	required
tabs	str	Comma-separated tab names, or "*" for all tabs. Defaults to "scan".	'scan'

science_get_scan_data(origin, target, tab='scan')

Return the scan text on a tab as seen by the scanning ship.

Parameters:

Name	Type	Description	Default
origin	int | Agent	The scanning player ship.	required
target	int | Agent	The object being scanned.	required
tab	str	Science tab to read. Defaults to "scan".	'scan'

Returns:

Name	Type	Description
str	str	The scan text, or None if not yet scanned.

science_has_scan_data(origin, target, tab='scan')

Return True if the target has real scan data on the given tab.

Parameters:

Name	Type	Description	Default
origin	int | Agent	The scanning player ship.	required
target	int | Agent	The object to check.	required
tab	str	Science tab to check. Defaults to "scan".	'scan'

Returns:

Name	Type	Description
bool	bool	True if scan data exists and is not empty or default.

science_is_unknown(origin, target)

Return True if the target has not been scanned by the scanning ship.

Checks the "scan" tab. Use science_has_scan_data to check a different tab.

Parameters:

Name	Type	Description	Default
origin	int | Agent	The scanning player ship.	required
target	int | Agent	The object to check.	required

Returns:

Name	Type	Description
bool	bool	True if the target is unscanned or shows default/empty data.

science_navigate(path)

Navigate the current science GUI task to a new button path.

Parameters:

Name	Type	Description	Default
path	str	The science route path to navigate to.	required

science_set_2dview_focus(client_id, focus_id=0)

Focus the science 2D view of a client console on a specific object.

Parameters:

Name	Type	Description	Default
client_id	int	The client console ID.	required
focus_id	int	ID of the object to focus on. 0 clears the focus. Defaults to 0.	0

science_set_scan_data(player_id_or_obj, scan_target_id_or_obj, tabs)

Set science scan data for a target immediately, bypassing the normal scan delay.

Parameters:

Name	Type	Description	Default
player_id_or_obj	Agent | int	The scanning player ship.	required
scan_target_id_or_obj	Agent | int	The object being scanned.	required
tabs	dict | str	Tab-name → scan-text mapping. A bare string is treated as {"scan": string}.	required

science_update_scan_data(origin, target, info, tab='scan')

Update (or forcibly set) the scan text on a specific tab for a scanning ship.

Use when the target has already been scanned and the text needs to change, or to inject scan data without requiring the player to scan first.

Parameters:

Name	Type	Description	Default
origin	int | Agent	The scanning player ship.	required
target	int | Agent	The object being scanned.	required
info	str	The new scan text.	required
tab	str	The science tab to update (e.g. "scan", "intel"). Defaults to "scan".	'scan'

show_warning(t)

Print a warning message to the F7 debug screen.

Parameters:

Name	Type	Description	Default
t	str	The message to display.	required

start_science_message(event)

Handle a science message event, emitting a science_auto_scan signal.

This is the mechanism behind the auto-scan feature. Called automatically by ConsoleDispatcher for science_target_UID message events.

Parameters:

Name	Type	Description	Default
event		Engine message event carrying the auto-scan trigger.	required

start_science_selected(event)

Start or resume a science scan for the given selection event.

Creates a new ScanPromise for the (origin, selected) pair if none exists; otherwise returns the existing one. Called automatically by ConsoleDispatcher for science_target_UID select events.

Parameters:

Name	Type	Description	Default
event		Engine selection event that triggered the scan.	required

Returns:

Type	Description
	ScanPromise | None: The active scan promise, or None if the origin or target no longer exists.