The inventory system

A per-agent key→value store for arbitrary mission data.

Overview

Every Agent (space object, grid object, client, or story agent) has an inventory — a Python dict stored on the agent object itself. Use it to attach mission state to an object: HP values, flags, counters, task references, anything that should follow the object around and be readable by name.

Inventory values survive for the lifetime of the agent. They are not persisted across sessions.

Key functions:

set_inventory_value / get_inventory_value — write and read a single key.
has_inventory — find all agents that have a particular key set.
get_shared_inventory_value — shorthand for Agent.SHARED (the global singleton).
inventory_dict — return the whole inventory dict for inspection.

Quick example

MAST pyMAST

== setup ==
    set_inventory_value(ship_id, "hp", 100)
    set_inventory_value(ship_id, "shield_online", True)

== check_hp ==
    hp = get_inventory_value(ship_id, "hp", 0)
    log(f"Ship HP: {hp}")
    if hp <= 0: jump destroyed

from sbs_utils.procedural.inventory import (
    set_inventory_value, get_inventory_value,
    get_shared_inventory_value, has_inventory,
)

set_inventory_value(ship_id, "hp", 100)
hp = get_inventory_value(ship_id, "hp", default=0)

# Global shared state
get_shared_inventory_value("GAME_STARTED", False)

# Find all agents with a given key
damaged_ships = has_inventory("hp")

Shared inventory

Agent.SHARED is a singleton agent used for global mission state. Use get_shared_inventory_value / set_shared_inventory_value as shorthands:

set_shared_inventory_value("GAME_STARTED", True)
if get_shared_inventory_value("GAME_ENDED"): jump end_screen

In MAST you can also use the shared keyword:

shared GAME_STARTED = True

API

`get_inventory_value(id_or_object, key, default=None)`

Get an inventory value from an agent by key.

Parameters:

Name	Type	Description	Default
`id_or_object`	`Agent \| int`	The agent ID or object.	required
`key`	`str`	The inventory key.	required
`default`	`any`	Value returned when the key is absent. Defaults to None.	`None`

Returns:

Name	Type	Description
`any`		The inventory value, or `default` if the key is not set.

`get_shared_inventory_value(key, default=None)`

Get an inventory value from the global shared agent.

Parameters:

Name	Type	Description	Default
`key`	`str`	The inventory key.	required
`default`	`any`	Value returned when the key is absent. Defaults to None.	`None`

Returns:

Name	Type	Description
`any`		The shared inventory value, or `default` if not set.

`has_inventory(key)`

Return the set of agent IDs that have an inventory entry for the given key.

Parameters:

Name	Type	Description	Default
`key`	`str`	The inventory key to look for.	required

Returns:

Type	Description
	set[int]: IDs of all agents that have this key set.

`has_inventory_value(key, value)`

Return the set of agent IDs whose inventory value for key equals value.

Parameters:

Name	Type	Description	Default
`key`	`str`	The inventory key to look for.	required
`value`		The exact value to match.	required

Returns:

Type	Description
	set[int]: IDs of agents whose `key` inventory entry equals `value`.

`inventory_set(source, key)`

Return the set stored in an agent's inventory under key.

Used to treat an inventory entry as a collection. The value stored under key is expected to be a set; use set_inventory_value to write it.

Parameters:

Name	Type	Description	Default
`source`	`Agent \| int`	The agent ID or object.	required
`key`	`str`	The inventory key.	required

Returns:

Name	Type	Description
`set`		The set stored in inventory, or an empty set if not present.

`inventory_value(id_or_obj, key, default=None)`

Get an inventory value from an agent by key (alias for get_inventory_value).

Parameters:

Name	Type	Description	Default
`id_or_obj`	`Agent \| int`	The agent ID or object.	required
`key`	`str`	The inventory key.	required
`default`	`any`	Value returned when the key is absent. Defaults to None.	`None`

Returns:

Name	Type	Description
`any`		The inventory value, or `default` if the key is not set.

`remove_inventory_value(so, key)`

Remove an inventory key from one or more agents.

If so is a set or collection, the key is removed from every member.

Parameters:

Name	Type	Description	Default
`so`	`Agent \| int \| set[Agent \| int]`	The agent(s) to update.	required
`key`	`str`	The inventory key to remove.	required

`set_inventory_value(so, key, value)`

Set an inventory value on one or more agents.

If so is a set or collection, every member receives the value.

Parameters:

Name	Type	Description	Default
`so`	`Agent \| int \| set[Agent \| int]`	The agent(s) to update.	required
`key`	`str`	The inventory key.	required
`value`	`any`	The value to store.	required

`set_shared_inventory_value(key, value)`

Set an inventory value on the global shared agent.

Parameters:

Name	Type	Description	Default
`key`	`str`	The inventory key.	required
`value`	`any`	The value to store.	required