Docking system

Manage proximity-based docking between player ships and NPCs.

Overview

The docking system runs a background tick task that monitors registered (player, NPC) pairs for proximity. When a player ship comes within the docking distance defined on the label, the system drives the pair through a state machine:

undocked → docking → dock_start → docked → undocking → undocked

Each state transition runs an inline sub-label (defined with ///) on the docking label:

Inline label	Runs when
`///enable`	Player comes within range — return `FAIL_END` to prevent docking
`///docking`	Approach phase — NPC closes in on player
`///docked`	Pair has physically connected — run refit logic here
`///refit`	Called each tick while docked
`///throttle`	Called when player throttle exceeds 0.6 — return `OK_SUCCESS` to undock
`///undocking`	Pair is separating

The DOCKING_PLAYER, DOCKING_PLAYER_ID, DOCKING_NPC, and DOCKING_NPC_ID variables are set in every inline label. The docked signal is emitted when the pair reaches the docked state.

Quick example

MAST pyMAST

== setup ==
    docking_set_docking_logic(player_set, station_set, docking_logic)
    ->END

== docking_logic ==
    ///enable
    OK_SUCCESS   # always allow docking

    ///docked
    set_engineering_value(DOCKING_PLAYER_ID, "energy", 1000)
    OK_SUCCESS

    ///refit
    hp = get_engineering_value(DOCKING_PLAYER_ID, "hullLevel")
    if hp >= 1.0: OK_SUCCESS
    set_engineering_value(DOCKING_PLAYER_ID, "hullLevel", hp + 0.01)
    OK_RUN_AGAIN

//signal/docked
    log(f"Ship {DOCKING_PLAYER.name} has docked.")

from sbs_utils.procedural.docking import docking_set_docking_logic

docking_set_docking_logic(player_set, station_set, docking_logic_label)

API

`docking_run_all(tick_task)`

Process docking state for all registered player/NPC pairs.

Called each tick. Handles undocked proximity detection, docking approach, dock_start handshake, docked refit/throttle, and undocking. Cleans up stale pairs where the player or NPC no longer exists.

Parameters:

Name	Type	Description	Default
`tick_task`	`TickTask \| event`	Tick task or event triggering this run.	required

`docking_schedule()`

Schedule the docking tick task (runs every 1 second) if not already running.

`docking_set_docking_logic(player_set, npc_set, label, data=None)`

Register docking logic between a set of players and a set of NPCs.

For each (player, NPC) pair, associates label as the brain that drives docking state transitions (enable, docking, docked, undocking, refit, throttle inline sections). Automatically schedules the docking tick task.

Parameters:

Name	Type	Description	Default
`player_set`	`int \| set`	Player ship agent ID(s) or object(s).	required
`npc_set`	`int \| set`	NPC agent ID(s) or object(s) to dock with.	required
`label`	`Label`	MAST label with docking inline sub-labels.	required
`data`	`dict`	Variables passed to docking tasks. Defaults to None.	`None`