rules
The rules every inventory change passes, as pure functions over an inventory state, built on the engine's own slot inventory (`@builtin::modules.extras.inventory`): stacking up to an item's maxStack, swapping, splitting, equipping only into the slot an item is made for, and refus…
rules
The rules every inventory change passes, as pure functions over an inventory state, built on the engine's own slot inventory (@builtin::modules.extras.inventory): stacking up to an item's maxStack, swapping, splitting, equipping only into the slot an item is made for, and refusing any move of an item you do not have. Every operation returns (ok, why, newState) and never changes the state it was given. Used by inventoryKit itself and by tests.
Interface
What this asset declares: the schema it conforms to, what it exposes, and the rendered structured payload.
conforms to
zero/source-extract/v2strict
new(opts: { bag: number?, hotbar: number? }?) → State
A new, empty inventory. opts: { bag = 24, hotbar = 8 }.
| arg | type | description |
|---|---|---|
| opts | { bag: number?, hotbar: number? }? |
copy(state: State) → State
A deep copy of a state.
| arg | type | description |
|---|---|---|
| state | State |
maxOf(defs: Defs, id: string) → number
| arg | type | description |
|---|---|---|
| defs | Defs | |
| id | string |
toSave(state: State) → any
The form an inventory is saved in: { v, items = { { at, id, count } }, hotbarSelected }. JSON-safe (no sparse arrays); `sanitize` reads it back.
| arg | type | description |
|---|---|---|
| state | State |
sanitize(raw: any, defs: Defs, opts: { bag: number?, hotbar: number? }?) → void
Bring any stored or received table into a valid state: unknown items are dropped (and returned in `dropped`), counts are clamped to 1..maxStack, equipment that does not fit its slot is moved to the bag (or dropped when there is no room). Never errors.
| arg | type | description |
|---|---|---|
| raw | any | |
| defs | Defs | |
| opts | { bag: number?, hotbar: number? }? |
clean(x: any) → Slot
| arg | type | description |
|---|---|---|
| x | any |
parse(state: State, address: string) → void
Parse "hotbar:3" / "bag:12" / "equip:head" into (area, key) or nil, why.
| arg | type | description |
|---|---|---|
| state | State | |
| address | string |
addressOf(state: State, index: number) → string
The address of a raw slot index ("hotbar:i" or "bag:i").
| arg | type | description |
|---|---|---|
| state | State | |
| index | number |
at(state: State, address: string) → Slot
What is at an address: { id, count } or nil.
| arg | type | description |
|---|---|---|
| state | State | |
| address | string |
count(state: State, id: string) → number
How many of an item the inventory holds (bag, hotbar and equipment).
| arg | type | description |
|---|---|---|
| state | State | |
| id | string |
room(state: State, id: string, defs: Defs) → number
How many more of an item fit (in stacks and empty slots, not equipment).
| arg | type | description |
|---|---|---|
| state | State | |
| id | string | |
| defs | Defs |
firstEmpty(state: State, bagFirst: boolean?) → number
The first empty slot index (hotbar first unless bagFirst), or nil.
| arg | type | description |
|---|---|---|
| state | State | |
| bagFirst | boolean? |
add(state: State, id: string, count: number, defs: Defs) → void
Add `count` of an item: tops up existing stacks, then fills empty slots (hotbar first). Returns (added, leftover, newState); newState is nil when nothing was added.
| arg | type | description |
|---|---|---|
| state | State | |
| id | string | |
| count | number | |
| defs | Defs |
removeItem(state: State, id: string, count: number) → void
Take `count` of an item from anywhere (stacks in the bag first, then the hotbar, then equipment). Refused when the inventory holds fewer.
| arg | type | description |
|---|---|---|
| state | State | |
| id | string | |
| count | number |
removeAt(state: State, address: string, count: number?) → void
Take `count` (default all) from one address. Refused when that slot holds less, or nothing.
| arg | type | description |
|---|---|---|
| state | State | |
| address | string | |
| count | number? |
fitsEquip(defs: Defs, item: Slot?, name: string) → void
| arg | type | description |
|---|---|---|
| defs | Defs | |
| item | Slot? | |
| name | string |
move(state: State, from: string, to: string, defs: Defs) → void
Move what is at `from` to `to`: into an empty slot, onto a stack of the same item (up to maxStack, the rest stays), or swapping with what is there. Equipment slots take only the items made for them, and a swap out of an equipment slot is refused unless the item coming back fits it.
| arg | type | description |
|---|---|---|
| state | State | |
| from | string | |
| to | string | |
| defs | Defs |
split(state: State, from: string, to: string?, amount: number?) → void
Split a stack: move `amount` (default half, rounded down) from `from` into `to` (default the first empty bag slot). `to` must be empty.
| arg | type | description |
|---|---|---|
| state | State | |
| from | string | |
| to | string? | |
| amount | number? |
equip(state: State, from: string, defs: Defs) → void
Equip the item at an address into the slot its item names (swapping out what was there).
| arg | type | description |
|---|---|---|
| state | State | |
| from | string | |
| defs | Defs |
unequip(state: State, name: string) → void
Take off what is in an equipment slot, into the first empty bag slot (or hotbar).
| arg | type | description |
|---|---|---|
| state | State | |
| name | string |
select(state: State, index: number) → void
Select a hotbar slot.
| arg | type | description |
|---|---|---|
| state | State | |
| index | number |
check(state: any, defs: Defs) → void
Check a whole state against the rules (used on states received from the network and on saves). Returns ok, why.
| arg | type | description |
|---|---|---|
| state | any | |
| defs | Defs |
hotbarView(state: State, defs: { [string]: any }) → void
The hotbar as the engine's UI-ready view ({ icon, count, tooltip } per slot), straight from `@builtin::modules.extras.inventory`.
| arg | type | description |
|---|---|---|
| state | State | |
| defs | { [string]: any } |
toWire(state: State) → any
The state as it travels between engines: slots keyed by their number as text. A numbered list with gaps (an empty slot before a full one) loses everything after the first gap on the way, so the wire form never has one.
| arg | type | description |
|---|---|---|
| state | State |
fromWire(raw: any) → State
A state back from its wire form (also accepts a plain state). Returns nil for anything that is not a state.
| arg | type | description |
|---|---|---|
| raw | any |
Def = { id: string, slot: string?, maxStack: number? }Defs = { [string]: Def }Slot = { id: string, count: number }State = {Pure inventory rules (stack, swap, split, equip, refuse impossible moves) over the engine slot inventory, returning a new state or a reason.Sub-parts
Everything contained inside this part. Assets are composite children (clickable cards). Files are leaf payloads. Expand any row to view its source.
Problems
Everything affecting this asset right now: its own problems, anything wrong inside it, and problems on its direct dependencies.
agent_score is exposed.+ quality × 0.35
+ performance × 0.25
± compat factor
Usability ratings
Did the part work as advertised when consumers tried to drop it in. Separate from upvotes: those are taste; this is "did it function".
Scoped to this part · feeds back into the world's score.