Skip to main content
forge-inventory owns containers and the moves between them. Equipment, loot, crafting, and economy all move items through this package rather than holding their own storage.

​
Concepts

  • Container id. A string key. The player bag is inv:<character_id>; the equip container is equip:<character_id>; stashes use their own ids.
  • Container types. player, drop, stash (creators can register more), each with slot and weight caps and a placement policy. Containers lazy-load from the database on first access.
  • Slots. Grid containers have indexed slots; equip-style containers have named slots. Placement validators (registered by other packages) gate what may go where.

​
Exports

​
Items in containers

ExportSignatureReturns
AddItemAddItem(container_id, instance)Result{ data = { slot } }
RemoveItemRemoveItem(container_id, slot, qty?)Result
MoveItemMoveItem(from, to, qty?)Result, from/to are { container_id, slot? }; merges and swaps handled
GetContainerGetContainer(container_id)Result{ data = { slots, caps, ... } } (lazy-loads)
FindItems / CountItemlocate or count an item id in a container
CanFitCanFit(container_id, item, qty)weight + slot + stack aware
UpdateInstanceStateUpdateInstanceState(container_id, slot, patch)persist a durability/meta change
FlushContainerNowFlushContainerNow(container_id)force a write-through

​
Use, drops, stashes

ExportSignature
UseItemUseItem(character_id, container_id, slot), runs the item’s use.outcome
RegisterUseOutcomeRegisterUseOutcome(kind, { pkg, export }), add a custom use-outcome kind
CreateDropCreateDrop(items, position), a world pile
DropItemDropItem(character_id, container_id, slot)
PickupDropPickupDrop(character_id, drop_id), distance-gated
CreateStashCreateStash(stash_id, opts)
OpenContainerOpenContainer(character_id, container_id), open a secondary (stash) on the player’s screen
CloseContainerCloseContainer(character_id, container_id)

​
Container setup

ExportSignature
RegisterContainerTypeRegisterContainerType(typeId, spec), caps + named slots
RegisterPlacementValidatorRegisterPlacementValidator(typeId, pkg, export), gate placement per type
EnsureContainer / EvictContainercreate-on-demand / drop from cache
local fv = exports["forge-inventory"]
local add = fv:AddItem("inv:" .. cid, instance)         -- into the bag
fv:MoveItem({ container_id = "inv:" .. cid, slot = add.data.slot },
            { container_id = "equip:" .. cid, slot = "slot:mainhand" })

​
Events

EventPayload
forge-inventory:server:itemAdded{ container_id, slot, instance }
forge-inventory:server:itemRemoved{ container_id, slot, instance }
forge-inventory:server:used{ character_id, container_id, slot, ... }
forge-inventory:client:dropSpawn / dropDespawnworld-drop visuals
itemAdded/itemRemoved on the equip container are how forge-equipment learns to apply or remove consequences.

​
Status notes

GiveItem (direct player-to-player give) is deferred to a later version. UseItem, drops, stashes, and the combined inventory screen are implemented.