Items

Discoverable items collected in space and applied through the upgrade system.

API

Discoverable item registry + pickup spawning.

Items are ordinary prefab labels tagged with metadata: type: item/... and discovered with labels_get_type("item/") -- the same pattern as maps/media. This module is the single source of truth that spawners, collectors, GUI and market read from.

Moved here from the LegendaryMissions items addon so that pickup_spawn and the registry readers are available to any mission on the sbslib alone (the migration a2x layer uses them). It depends only on core sbs_utils; the item definitions (art/keys) are still supplied by whatever addon or mission registers item/ labels. The market/economy layer remains in LegendaryMissions and imports these readers.

Backward compatibility: LegendaryMissions items.py now re-exports these names, so all existing pickup_spawn / terrain_spawn_pickups / item_spawn call sites keep working unchanged.

item_get(key)

Return the item label whose metadata key matches, or None.

item_keys()

Return the list of all registered item keys.

item_meta(item, field, default=None)

Read a metadata field from an item (a label object or a key string).

item_spawn(key, x, y, z, name=None, blink=None, yaw=None, qty=None)

Spawn a collectible pickup for an item key at (x, y, z).

Art comes from the registry; the key is stored on the pickup as the item_key inventory value so the generic collision route can credit it without any per-item code.

qty makes ONE pickup worth several units - a salvage cache, an ore seam. Without it a bulk resource has to spawn one object per unit, which is both object churn and a tedious pickup grind (a job needing 24 salvage would scatter 24 collectibles). The collection route reads it, defaulting to 1, so existing pickups are unaffected.

An UNREGISTERED key is a mission bug, and a silent one: the art it falls back to decides both the mesh and -- via the art's shipData interactionradius -- whether //collision/interactive fires at all, so an unregistered pickup can look like a ? and be uncollectable. Fall back to the key itself (item keys and art keys coincide by convention, so it is the best available guess) and log a warning, rather than quietly spawning the unknown placeholder, which has no interaction radius.

items_get_list()

Return all registered item labels (metadata type: item/...).

items_of_category(category)

Return item labels whose type contains the given category segment.

e.g. items_of_category("upgrade") or items_of_category("resource").

pickup_spawn(x, y, z, roles, blink=None, yaw=None, name=None, art_id=None)

Legacy shim: the old roles arg carried the upgrade key.

terrain_spawn_items(density, center=None, points=None, categories=None)

Scatter tier-weighted item pickups (default categories: upgrade+resource).

density 1-4 controls how many spawn. If points is given they are sampled; otherwise a box scatter around center is used.

terrain_spawn_pickups(upgrade_value, center=None, points=None)

Legacy shim onto the registry-driven spawner.