# new RezInventory()
Holds items in named positions.
An inventory is made up of positions, each declared by a nested @contains
block. The block's id is the position's name and its slot_id names the
@slot that decides what the position accepts. Several positions, in the same
inventory or in different ones, can use the same @slot.
Key features:
- Typed positions: a position only accepts items whose
typeis (or derives from) what its slotaccepts - Capacity: a slot with
has_capacity: truelimits the totalsizeof the items in each position that uses it - Weight: an inventory can have a
max_weight, checked against the totalweightof everything it holds - Exclusion: a slot can
excludeother slots, so filling one position blocks another - Enabled state: positions can be disabled (locked) and enabled at runtime
- Single location: an item is in at most one position at a time. The item
records where it is in its
inventory_idandpositionattributes. Usemove()to move an item from wherever it is. - Effects: items can apply effects to the inventory's owner while they are in it
- Events: adding and removing items runs
insertandremoveevents on the inventory, the slot, and the item
All position state lives in the positions attribute, compiled from the
@contains blocks:
positions: {
left_ring: {slot_id: "ring_slot", enabled: true, contents: ["silver_ring"]}
}
Don't change positions directly; use the methods of this class. They replace
the whole record on every change, so the change is saved and observers (such as
views) are told about it, and on_positions_changed runs.
Define in Rez:
@inventory player_inv {
@contains weapon {
slot_id: #s_weapon
contents: [#item_sword]
}
@contains left_ring {
slot_id: #s_ring
}
@contains right_ring {
slot_id: #s_ring
enabled: false
}
}
Examples
Add an item at runtime
const inv = $("player_inv");
const decision = inv.add("left_ring", "item_gold_ring");
if(decision.wasNo) {
console.log(decision.reason);
}
Move an item from wherever it is
$("player_inv").move("weapon", "item_axe");
Extends
Methods
# static add(name, itemId) → {RezDecision}
Adds an item, that isn't already somewhere, to the position. Runs
insert events on the inventory, the slot, and the item (in that order), and
applies the item's effects to the owner.
Parameters:
| Name | Type | Description |
|---|---|---|
name |
string
|
name of a position |
itemId |
string
|
the decision from canAdd. When it is yes the item has
been added; otherwise nothing has changed and the decision says why.
Example
const d = inv.add("weapon", "item_axe");
if(d.wasNo) showMessage(d.reason);
# static addPosition(name, slotId, enabledopt)
Adds a new, empty position to the inventory at runtime.
Parameters:
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
name |
string
|
name of the new position |
||
slotId |
string
|
id of the |
||
enabled |
boolean
|
<optional> |
true | whether the position starts enabled |
if the position already exists
Error
# static allItems() → {Array.<string>}
ids of every item in every position
Array.<string>
# static applyEffects(name, itemId) → {boolean}
Parameters:
| Name | Type | Description |
|---|---|---|
name |
string
|
name of a position |
itemId |
string
|
whether any effects were applied
boolean
# static canAdd(name, itemId) → {RezDecision}
Checks, in order: the position is enabled; the item isn't
already somewhere (failed_on: "located", use move() instead); the slot
accepts the item's type; the position isn't blocked by an exclusion; the item
fits the slot's capacity; the item fits the inventory's max_weight; and
finally the owner's on_accept_item handler. When the decision is no, its
failed_on data says which check failed.
Parameters:
| Name | Type | Description |
|---|---|---|
name |
string
|
name of a position |
itemId |
string
|
whether the item can be added to the position
# static canMove(name, itemId) → {RezDecision}
Parameters:
| Name | Type | Description |
|---|---|---|
name |
string
|
name of a position in this inventory |
itemId |
string
|
whether the item can be moved from wherever it is now
into the position. Combines canRemove at its current position (if it has one)
with the checks of canAdd.
# static canRemove(name, itemId) → {RezDecision}
Parameters:
| Name | Type | Description |
|---|---|---|
name |
string
|
name of a position |
itemId |
string
|
whether the item can be removed from the position. The
decision is no (failed_on: "missing") if the item isn't in it.
# static clear(name)
Removes every item from the position.
Parameters:
| Name | Type | Description |
|---|---|---|
name |
string
|
name of a position |
# static countItemsIn(name) → {number}
Parameters:
| Name | Type | Description |
|---|---|---|
name |
string
|
name of a position |
number of items in the position
number
# static disable(name)
Disables the position so no further items can be added to it. Items already in it stay there.
Parameters:
| Name | Type | Description |
|---|---|---|
name |
string
|
name of a position |
# static elementInitializer()
Called during the init process. Resolves the owner, then empties
each position and adds its starting contents back through the add path, so
that starting items fire insert events and apply effects like any other.
Starting items are placed even in positions that begin disabled.
if a starting item can't be placed
Error
# static enable(name)
Enables the position so items can be added to it.
Parameters:
| Name | Type | Description |
|---|---|---|
name |
string
|
name of a position |
# static firstItemIn(name) → {string|undefined}
Parameters:
| Name | Type | Description |
|---|---|---|
name |
string
|
name of a position |
id of the first item in the position
string
|
undefined
# static getPositionNames() → {Array.<string>}
the names of this inventory's positions
Array.<string>
# static getPositions() → {Array.<object>}
a {name, slot, enabled, contents} description of each
position, where slot is the RezSlot and contents is an array of item ids
Array.<object>
Example
for(const {name, slot, enabled, contents} of inv.getPositions()) {
const available = inv.isAvailable(name);
// enabled=false → locked; available=false → excluded by another position
}
# static getSlot(name) → {RezSlot}
Parameters:
| Name | Type | Description |
|---|---|---|
name |
string
|
name of a position |
if there is no such position
Error
the slot that the position uses
# static hasItem(itemId) → {boolean}
Parameters:
| Name | Type | Description |
|---|---|---|
itemId |
string
|
true if the item is in any position of this inventory
boolean
# static hasPosition(name) → {boolean}
Parameters:
| Name | Type | Description |
|---|---|---|
name |
string
|
name of a position |
true if this inventory has a position with the given name
boolean
# static isAvailable(name) → {boolean}
Useful for greying out positions in an inventory UI.
Parameters:
| Name | Type | Description |
|---|---|---|
name |
string
|
name of a position |
true if the position is not blocked by an exclusion
boolean
# static isBlockedByExclusion(name) → {boolean}
Parameters:
| Name | Type | Description |
|---|---|---|
name |
string
|
name of a position |
true if another occupied position's slot excludes this position's slot, or this position's slot excludes the slot of another occupied position
boolean
# static isEnabled(name) → {boolean}
Positions start enabled unless their @contains block says
enabled: false. Use enable() at runtime when the player unlocks one.
Parameters:
| Name | Type | Description |
|---|---|---|
name |
string
|
name of a position |
true if the position is enabled
boolean
Examples
Define a locked position in Rez
// @inventory player_equip {
// @contains ring1 {slot_id: #s_ring}
// @contains ring2 {slot_id: #s_ring enabled: false}
// }
Unlock it at runtime
if(player.level >= 5) {
$("player_equip").enable("ring2");
}
# static isOccupied(name) → {boolean}
Parameters:
| Name | Type | Description |
|---|---|---|
name |
string
|
name of a position |
true if there is at least one item in the position
boolean
# static isOverweight() → {boolean}
true if the inventory's total weight exceeds max_weight
boolean
# static itemFits(name, itemId) → {boolean}
If the position's slot has has_capacity: true, items count
towards slot.capacity using their size attribute, defaulting to 1 if
unset. This means capacity: 1 naturally limits a position to a single item
unless an item explicitly opts out with size: 0 or takes up more room with
size: 2+. Slots without has_capacity: true accept any number of items.
Parameters:
| Name | Type | Description |
|---|---|---|
name |
string
|
name of a position |
itemId |
string
|
true if the item fits alongside the position's other contents
boolean
# static itemFitsWeight(itemId) → {boolean}
Parameters:
| Name | Type | Description |
|---|---|---|
itemId |
string
|
true if this inventory can hold the item without exceeding
max_weight. An item already in this inventory is only counted once.
boolean
# static itemsIn(name) → {Array.<string>}
Parameters:
| Name | Type | Description |
|---|---|---|
name |
string
|
name of a position |
a copy of the ids of the items in the position
Array.<string>
# static locationOf(itemId) → {object|null}
Parameters:
| Name | Type | Description |
|---|---|---|
itemId |
string
|
{inventory, position} for the inventory and position
the item is in, or null if it isn't in any inventory
object
|
null
Example
const where = RezInventory.locationOf("item_gold_ring");
if(where) console.log(`In ${where.inventory.id}/${where.position}`);
# static maxWeight() → {number}
the max_weight attribute, or Infinity if not set
number
# static move(name, itemId) → {RezDecision}
Moves an item into the position from wherever it is, which may be another position of this inventory, another inventory, or nowhere.
Parameters:
| Name | Type | Description |
|---|---|---|
name |
string
|
name of a position in this inventory |
itemId |
string
|
the decision from canMove. When it is yes the item has
been removed from where it was (if anywhere) and added to the position.
Example
$("chest").move("contents", "item_gold_ring");
# static positionAccepts(name, itemId) → {boolean}
Parameters:
| Name | Type | Description |
|---|---|---|
name |
string
|
name of a position |
itemId |
string
|
true if the item's type is one that the position's slot accepts
boolean
# static positionOf(itemId) → {string|undefined}
Parameters:
| Name | Type | Description |
|---|---|---|
itemId |
string
|
name of the position holding the item, or undefined if it isn't in this inventory
string
|
undefined
# static remainingWeight() → {number}
how much more weight this inventory can carry before reaching max_weight
number
# static remove(name, itemId) → {RezDecision}
Removes the item from the position. Runs remove events on the
slot, the item, and the inventory (in that order), and removes the item's
effects from the owner.
Parameters:
| Name | Type | Description |
|---|---|---|
name |
string
|
name of a position |
itemId |
string
|
the decision from canRemove. When it is yes the item has
been removed; otherwise nothing has changed and the decision says why.
# static removeEffects(name, itemId) → {boolean}
Parameters:
| Name | Type | Description |
|---|---|---|
name |
string
|
name of a position |
itemId |
string
|
whether any effects were removed
boolean
# static resolveOwner()
If owner_id was not authored directly, find the actor that
declares this inventory as its container_id and record it as owner_id,
so that inventory.owner is reliably available (for the actor veto, effect
application, and insert/remove event handlers). Author ownership in a single
place (actor.container_id); an explicitly authored owner_id still wins.
Safe at init time because all game objects are registered before any object
is initialised.
# static setContents(name, itemIds) → {Array.<RezDecision>}
Empties the position, then adds each item. An item that can't be added is left where it was and its decision says why.
Parameters:
| Name | Type | Description |
|---|---|---|
name |
string
|
name of a position |
itemIds |
string
|
Array.<string>
|
the item or items the position should hold |
a decision for each item added, in order
Array.<RezDecision>
# static shouldApplyEffects(name) → {boolean}
Parameters:
| Name | Type | Description |
|---|---|---|
name |
string
|
name of a position |
true if items in the position apply their effects: the
inventory has an owner and both the inventory and the position's slot have
apply_effects: true
boolean
# static totalWeight() → {number}
sum of the weight attribute of every item in every position
number