Links
Uni-directional named associations between agents.
Overview
Links are a lightweight way to associate one agent with another under a named relationship. Unlike inventory values, a single agent can have many outgoing links under the same name, making links ideal for one-to-many relationships: a ship linked to all its console clients, a brain linked to all its child nodes, a ship linked to all its active upgrades.
Key functions:
link(from_id, name, to_id)— add a link.unlink(from_id, name, to_id)— remove a specific link.linked_to(from_id, name)— get the set of agents linked undername.has_link_to(from_id, name, to_id)— check whether a specific link exists.
Links are uni-directional. linked_to(ship_id, "consoles") returns the consoles; nothing automatically tells a console which ships it belongs to.
Quick example
== setup ==
link(ship_id, "escort_targets", freighter_id)
link(ship_id, "escort_targets", transport_id)
== check ==
targets = linked_to(ship_id, "escort_targets")
alive = [t for t in targets if object_exists(t)]
if len(alive) == 0: jump mission_complete
from sbs_utils.procedural.links import link, unlink, linked_to, has_link_to
link(ship_id, "escort_targets", freighter_id)
link(ship_id, "escort_targets", transport_id)
targets = linked_to(ship_id, "escort_targets")
unlink(ship_id, "escort_targets", freighter_id)
if has_link_to(ship_id, "escort_targets", freighter_id):
log("still escorting the freighter")
System link names
Several library modules use reserved link names:
| Link name | Used by |
|---|---|
"__UPGRADE__" |
Upgrade system |
"__BRAIN__" (inventory, not link) |
Brain system |
"consoles" |
Client console associations |
"grid_objects" |
Grid objects on a ship |
"damage" |
Damaged grid objects |
"work-order" |
Damcon repair assignments |
API
clear_dedicated_link(so, link_name)
Clear a dedicated (1-to-1) link, leaving the source linked to nothing.
After this get_dedicated_link(so, link_name) returns None and the
source no longer appears in has_link(link_name).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
so
|
Agent | int
|
The source agent ID or object. |
required |
link_name
|
str
|
The link key name. |
required |
get_dedicated_link(so, link_name)
Return the single agent ID linked under a dedicated (1-to-1) link.
A dedicated link stores exactly one target per source. Use link /
set_dedicated_link for many-to-many or 1-to-1 links respectively.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
so
|
Agent | int
|
The source agent ID or object. |
required |
link_name
|
str
|
The link key name. |
required |
Returns:
| Type | Description |
|---|---|
|
int | None: The linked agent ID, or |
has_link(link_name)
Return the set of agent IDs that have at least one link under a given name.
Despite the has_ prefix this returns a set, not a bool. Use the result
to iterate or test membership.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
link_name
|
str
|
The link key name. |
required |
Returns:
| Type | Description |
|---|---|
|
set[int]: IDs of all agents that own a link entry with this name. |
has_link_to(link_source, link_name, link_target)
Return whether a source agent has a specific link to a target.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
link_source
|
Agent | int
|
The agent ID or object hosting the link. |
required |
link_name
|
str
|
The link key name. |
required |
link_target
|
Agent | int
|
The target agent ID or object to check. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
bool |
bool
|
|
link(set_holder, link_name, set_to)
Create a named link from one or more source agents to one or more targets.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
set_holder
|
Agent | int | set[Agent | int]
|
Source agent(s). |
required |
link_name
|
str
|
The link key name. |
required |
set_to
|
Agent | int | set[Agent | int]
|
Target agent(s) to link to. |
required |
linked_to(link_source, link_name)
Return the set of IDs that an agent links to under a given name.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
link_source
|
Agent | int
|
The source agent ID or object. |
required |
link_name
|
str
|
The link key name. |
required |
Returns:
| Type | Description |
|---|---|
|
set[int]: IDs of all linked targets, or an empty set if none. |
set_dedicated_link(so, link_name, to)
Set a dedicated (1-to-1) link from a source agent to a single target.
Replaces any existing link under link_name with the new target. Pass
to=None to clear the link entirely, so that get_dedicated_link
returns None again.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
so
|
Agent | int
|
The source agent ID or object. |
required |
link_name
|
str
|
The link key name. |
required |
to
|
Agent | int | None
|
The target agent ID or object, or |
required |
unlink(set_holder, link_name, set_to)
Remove a named link from one or more source agents to one or more targets.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
set_holder
|
Agent | int | set[Agent | int]
|
Source agent(s). |
required |
link_name
|
str
|
The link key name. |
required |
set_to
|
Agent | int | set[Agent | int]
|
Target agent(s) to unlink. |
required |