//-----------------------------------------------------------------------------
// Inventory
//-----------------------------------------------------------------------------
/**
* @class RezInventory
* @extends RezBasicObject
* @category Elements
* @description 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 `type` is (or derives
* from) what its slot `accepts`
* - **Capacity**: a slot with `has_capacity: true` limits the total `size` of the
* items in each position that uses it
* - **Weight**: an inventory can have a `max_weight`, checked against the total
* `weight` of everything it holds
* - **Exclusion**: a slot can `exclude` other 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_id` and `position` attributes. Use
* `move()` 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 `insert` and `remove` events on the
* inventory, the slot, and the item
*
* All position state lives in the `positions` attribute, compiled from the
* `@contains` blocks:
*
* <pre><code>
* positions: {
* left_ring: {slot_id: "ring_slot", enabled: true, contents: ["silver_ring"]}
* }
* </code></pre>
*
* 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:**
* <pre><code>
* @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
* }
* }
* </code></pre>
*
* @example <caption>Add an item at runtime</caption>
* const inv = $("player_inv");
* const decision = inv.add("left_ring", "item_gold_ring");
* if(decision.wasNo) {
* console.log(decision.reason);
* }
* @example <caption>Move an item from wherever it is</caption>
* $("player_inv").move("weapon", "item_axe");
*/
class RezInventory extends RezBasicObject {
constructor(id, attributes) {
super("inventory", id, attributes);
}
/**
* @function elementInitializer
* @memberof RezInventory
* @description 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.
* @throws {Error} if a starting item can't be placed
*/
elementInitializer() {
this.resolveOwner();
const positions = this.getAttributeValue("positions");
const startingContents = Object.entries(positions).map(([name, pos]) => [name, pos.contents]);
this.#writePositions(Object.fromEntries(
Object.entries(positions).map(([name, pos]) => [name, {...pos, contents: []}])
));
for(const [name, itemIds] of startingContents) {
for(const itemId of itemIds) {
const decision = this.#checkAdd(name, itemId, {initializing: true});
if(!decision.result) {
throw new Error(`Inventory |${this.id}|: cannot place starting item |${itemId}| in position |${name}|: ${decision.reason}`);
}
this.#insertItem(name, itemId);
}
}
}
/**
* @function resolveOwner
* @memberof RezInventory
* @description 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.
*/
resolveOwner() {
if(this.hasValue("owner_id")) return;
const owner = this.game.filterObjects(
(o) => o.element === "actor" && o.getAttributeValue("container_id", null) === this.id
)[0];
if(owner) {
this.setAttribute("owner_id", owner.id);
}
}
//---------------------------------------------------------------------------
// Position state
//---------------------------------------------------------------------------
#positions() {
return this.getAttributeValue("positions");
}
#position(name) {
const pos = this.#positions()[name];
if(!pos) {
throw new Error(`Inventory |${this.id}| does not have a position |${name}|!`);
}
return pos;
}
#writePositions(positions) {
this.setAttribute("positions", positions);
}
// Replaces the record for one position with the result of fn(record). The
// record is never changed in place, which is what makes the change visible to
// saving and observers, and lets copies of an inventory share a record safely.
#updatePosition(name, fn) {
const positions = this.#positions();
this.#writePositions({...positions, [name]: fn(this.#position(name))});
}
/**
* @function locationOf
* @memberof RezInventory
* @static
* @param {string} itemId
* @returns {object|null} `{inventory, position}` for the inventory and position
* the item is in, or `null` if it isn't in any inventory
* @example
* const where = RezInventory.locationOf("item_gold_ring");
* if(where) console.log(`In ${where.inventory.id}/${where.position}`);
*/
static locationOf(itemId) {
// An item that isn't anywhere has a null inventory_id, or a placeholder if
// it has never been placed.
const item = $(itemId);
const inventoryId = item.getAttributeValue("inventory_id", null);
if(inventoryId == null || Rez.isPlaceholder(inventoryId)) return null;
return {inventory: $(inventoryId), position: item.getAttributeValue("position")};
}
#ownerParams() {
const owner = this.owner ?? null;
return {owner_id: owner?.id ?? null, owner};
}
/**
* @function hasPosition
* @memberof RezInventory
* @param {string} name name of a position
* @returns {boolean} true if this inventory has a position with the given name
*/
hasPosition(name) {
return Object.hasOwn(this.#positions(), name);
}
/**
* @function getPositionNames
* @memberof RezInventory
* @returns {string[]} the names of this inventory's positions
*/
getPositionNames() {
return Object.keys(this.#positions());
}
/**
* @function getPositions
* @memberof RezInventory
* @returns {object[]} a `{name, slot, enabled, contents}` description of each
* position, where `slot` is the RezSlot and `contents` is an array of item ids
* @example
* for(const {name, slot, enabled, contents} of inv.getPositions()) {
* const available = inv.isAvailable(name);
* // enabled=false → locked; available=false → excluded by another position
* }
*/
getPositions() {
return Object.entries(this.#positions()).map(([name, pos]) => ({
name,
slot: $t(pos.slot_id, "slot", true),
enabled: pos.enabled,
contents: [...pos.contents]
}));
}
/**
* @function getSlot
* @memberof RezInventory
* @param {string} name name of a position
* @returns {RezSlot} the slot that the position uses
* @throws {Error} if there is no such position
*/
getSlot(name) {
return $t(this.#position(name).slot_id, "slot", true);
}
/**
* @function addPosition
* @memberof RezInventory
* @param {string} name name of the new position
* @param {string} slotId id of the `@slot` the position uses
* @param {boolean} [enabled=true] whether the position starts enabled
* @description Adds a new, empty position to the inventory at runtime.
* @throws {Error} if the position already exists
*/
addPosition(name, slotId, enabled = true) {
if(this.hasPosition(name)) {
throw new Error(`Inventory |${this.id}| already has a position |${name}|!`);
}
$t(slotId, "slot", true);
this.#writePositions({...this.#positions(), [name]: {slot_id: slotId, enabled, contents: []}});
}
//---------------------------------------------------------------------------
// Contents
//---------------------------------------------------------------------------
/**
* @function itemsIn
* @memberof RezInventory
* @param {string} name name of a position
* @returns {string[]} a copy of the ids of the items in the position
*/
itemsIn(name) {
return [...this.#position(name).contents];
}
/**
* @function firstItemIn
* @memberof RezInventory
* @param {string} name name of a position
* @returns {string|undefined} id of the first item in the position
*/
firstItemIn(name) {
return this.#position(name).contents[0];
}
/**
* @function countItemsIn
* @memberof RezInventory
* @param {string} name name of a position
* @returns {number} number of items in the position
*/
countItemsIn(name) {
return this.#position(name).contents.length;
}
/**
* @function isOccupied
* @memberof RezInventory
* @param {string} name name of a position
* @returns {boolean} true if there is at least one item in the position
*/
isOccupied(name) {
return this.countItemsIn(name) > 0;
}
/**
* @function allItems
* @memberof RezInventory
* @returns {string[]} ids of every item in every position
*/
allItems() {
return Object.values(this.#positions()).flatMap((pos) => pos.contents);
}
/**
* @function positionOf
* @memberof RezInventory
* @param {string} itemId
* @returns {string|undefined} name of the position holding the item, or undefined
* if it isn't in this inventory
*/
positionOf(itemId) {
return Object.entries(this.#positions()).find(([, pos]) => pos.contents.includes(itemId))?.[0];
}
/**
* @function hasItem
* @memberof RezInventory
* @param {string} itemId
* @returns {boolean} true if the item is in any position of this inventory
*/
hasItem(itemId) {
return this.positionOf(itemId) !== undefined;
}
//---------------------------------------------------------------------------
// Enabled & available
//---------------------------------------------------------------------------
/**
* @function isEnabled
* @memberof RezInventory
* @param {string} name name of a position
* @returns {boolean} true if the position is enabled
* @description Positions start enabled unless their `@contains` block says
* `enabled: false`. Use `enable()` at runtime when the player unlocks one.
* @example <caption>Define a locked position in Rez</caption>
* // @inventory player_equip {
* // @contains ring1 {slot_id: #s_ring}
* // @contains ring2 {slot_id: #s_ring enabled: false}
* // }
* @example <caption>Unlock it at runtime</caption>
* if(player.level >= 5) {
* $("player_equip").enable("ring2");
* }
*/
isEnabled(name) {
return this.#position(name).enabled;
}
/**
* @function enable
* @memberof RezInventory
* @param {string} name name of a position
* @description Enables the position so items can be added to it.
*/
enable(name) {
this.#updatePosition(name, (pos) => ({...pos, enabled: true}));
}
/**
* @function disable
* @memberof RezInventory
* @param {string} name name of a position
* @description Disables the position so no further items can be added to it.
* Items already in it stay there.
*/
disable(name) {
this.#updatePosition(name, (pos) => ({...pos, enabled: false}));
}
/**
* @function isAvailable
* @memberof RezInventory
* @param {string} name name of a position
* @returns {boolean} true if the position is not blocked by an exclusion
* @description Useful for greying out positions in an inventory UI.
*/
isAvailable(name) {
return !this.isBlockedByExclusion(name);
}
/**
* @function isBlockedByExclusion
* @memberof RezInventory
* @param {string} name name of a position
* @returns {boolean} true if another occupied position's slot excludes this
* position's slot, or this position's slot excludes the slot of another occupied
* position
*/
isBlockedByExclusion(name) {
// `excludes` holds slot ids; accept {$ref} objects too in case a ref has
// not been resolved.
const excludedBy = (slotId) => new Set(
[...$t(slotId, "slot", true).getAttributeValue("excludes", new Set())].map((ref) => ref?.$ref ?? ref)
);
const targetSlotId = this.#position(name).slot_id;
const targetExcludes = excludedBy(targetSlotId);
for(const [otherName, other] of Object.entries(this.#positions())) {
if(otherName === name || other.contents.length === 0) continue;
if(targetExcludes.has(other.slot_id) || excludedBy(other.slot_id).has(targetSlotId)) {
return true;
}
}
return false;
}
//---------------------------------------------------------------------------
// Fit
//---------------------------------------------------------------------------
/**
* @function positionAccepts
* @memberof RezInventory
* @param {string} name name of a position
* @param {string} itemId
* @returns {boolean} true if the item's type is one that the position's slot accepts
*/
positionAccepts(name, itemId) {
const accepts = this.getSlot(name).getAttributeValue("accepts");
return Rez.isTypeOf($(itemId).getAttributeValue("type"), accepts);
}
/**
* @function itemFits
* @memberof RezInventory
* @param {string} name name of a position
* @param {string} itemId
* @returns {boolean} true if the item fits alongside the position's other contents
* @description 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.
*/
itemFits(name, itemId) {
const slot = this.getSlot(name);
if(!slot.has_capacity) return true;
const sizeOf = (id) => $(id).getAttributeValue("size", 1);
const used = this.#position(name).contents
.filter((id) => id !== itemId)
.reduce((amount, id) => amount + sizeOf(id), 0);
return used + sizeOf(itemId) <= slot.capacity;
}
/**
* @function totalWeight
* @memberof RezInventory
* @returns {number} sum of the `weight` attribute of every item in every position
*/
totalWeight() {
return this.allItems().reduce((total, itemId) => {
return total + $(itemId).getAttributeValue("weight", 0);
}, 0);
}
/**
* @function maxWeight
* @memberof RezInventory
* @returns {number} the `max_weight` attribute, or `Infinity` if not set
*/
maxWeight() {
return this.getAttributeValue("max_weight", Infinity);
}
/**
* @function remainingWeight
* @memberof RezInventory
* @returns {number} how much more weight this inventory can carry before reaching `max_weight`
*/
remainingWeight() {
return this.maxWeight() - this.totalWeight();
}
/**
* @function isOverweight
* @memberof RezInventory
* @returns {boolean} true if the inventory's total weight exceeds `max_weight`
*/
isOverweight() {
return this.totalWeight() > this.maxWeight();
}
/**
* @function itemFitsWeight
* @memberof RezInventory
* @param {string} itemId
* @returns {boolean} true if this inventory can hold the item without exceeding
* `max_weight`. An item already in this inventory is only counted once.
*/
itemFitsWeight(itemId) {
const alreadyHere = this.hasItem(itemId) ? $(itemId).getAttributeValue("weight", 0) : 0;
return this.totalWeight() - alreadyHere + $(itemId).getAttributeValue("weight", 0) <= this.maxWeight();
}
//---------------------------------------------------------------------------
// Adding, removing & moving
//---------------------------------------------------------------------------
/**
* @function canAdd
* @memberof RezInventory
* @param {string} name name of a position
* @param {string} itemId
* @returns {RezDecision} whether the item can be added to the position
* @description 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.
*/
canAdd(name, itemId) {
return this.#checkAdd(name, itemId);
}
#checkAdd(name, itemId, {initializing = false, moving = false} = {}) {
const decision = new RezDecision("canAdd");
decision.setData("inventory_id", this.id);
decision.setData("position", name);
decision.setData("item_id", itemId);
const item = $(itemId);
if(!initializing && !this.isEnabled(name)) {
decision.no("position is not enabled").setData("failed_on", "enabled");
} else if(!moving && RezInventory.locationOf(itemId)) {
const {inventory, position} = RezInventory.locationOf(itemId);
decision
.no(`item is already in |${inventory.id}/${position}|`)
.setData("failed_on", "located");
} else if(!this.positionAccepts(name, itemId)) {
decision.no("position doesn't take this kind of item").setData("failed_on", "accepts");
} else if(this.isBlockedByExclusion(name)) {
decision.no("position is blocked by exclusion").setData("failed_on", "excludes");
} else if(!this.itemFits(name, itemId)) {
decision.no("does not fit").setData("failed_on", "capacity");
} else if(!this.itemFitsWeight(itemId)) {
decision.no("too heavy").setData("failed_on", "weight");
} else if(this.owner != null) {
const actorDecision = this.owner.checkItem(this.id, this.getSlot(name).id, name, itemId);
if(actorDecision.result) {
decision.yes();
} else {
decision.no(actorDecision.reason).setData("failed_on", "actor");
}
} else {
decision.yes();
}
return decision;
}
/**
* @function add
* @memberof RezInventory
* @param {string} name name of a position
* @param {string} itemId
* @returns {RezDecision} the decision from `canAdd`. When it is yes the item has
* been added; otherwise nothing has changed and the decision says why.
* @description 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.
* @example
* const d = inv.add("weapon", "item_axe");
* if(d.wasNo) showMessage(d.reason);
*/
add(name, itemId) {
const decision = this.canAdd(name, itemId);
if(decision.result) {
this.#insertItem(name, itemId);
}
return decision;
}
/**
* @function canRemove
* @memberof RezInventory
* @param {string} name name of a position
* @param {string} itemId
* @returns {RezDecision} whether the item can be removed from the position. The
* decision is no (`failed_on: "missing"`) if the item isn't in it.
*/
canRemove(name, itemId) {
const decision = new RezDecision("canRemove");
decision.setData("inventory_id", this.id);
decision.setData("position", name);
decision.setData("item_id", itemId);
if(!this.#position(name).contents.includes(itemId)) {
return decision
.no(`No item |${itemId}| in position |${name}| of inventory |${this.id}|!`)
.setData("failed_on", "missing");
}
decision.defaultYes();
return decision;
}
/**
* @function remove
* @memberof RezInventory
* @param {string} name name of a position
* @param {string} itemId
* @returns {RezDecision} the decision from `canRemove`. When it is yes the item has
* been removed; otherwise nothing has changed and the decision says why.
* @description 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.
*/
remove(name, itemId) {
const decision = this.canRemove(name, itemId);
if(decision.result) {
this.#removeItem(name, itemId);
}
return decision;
}
/**
* @function clear
* @memberof RezInventory
* @param {string} name name of a position
* @description Removes every item from the position.
*/
clear(name) {
for(const itemId of this.itemsIn(name)) {
this.remove(name, itemId);
}
}
/**
* @function setContents
* @memberof RezInventory
* @param {string} name name of a position
* @param {string|string[]} itemIds the item or items the position should hold
* @returns {RezDecision[]} a decision for each item added, in order
* @description Empties the position, then adds each item. An item that can't
* be added is left where it was and its decision says why.
*/
setContents(name, itemIds) {
this.clear(name);
return ensureArray(itemIds).map((itemId) => this.add(name, itemId));
}
/**
* @function canMove
* @memberof RezInventory
* @param {string} name name of a position in this inventory
* @param {string} itemId
* @returns {RezDecision} 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`.
*/
canMove(name, itemId) {
const location = RezInventory.locationOf(itemId);
if(location) {
if(location.inventory === this && location.position === name) {
const decision = new RezDecision("canMove");
decision.yes();
return decision;
}
const removal = location.inventory.canRemove(location.position, itemId);
if(!removal.result) {
return removal;
}
}
return this.#checkAdd(name, itemId, {moving: true});
}
/**
* @function move
* @memberof RezInventory
* @param {string} name name of a position in this inventory
* @param {string} itemId
* @returns {RezDecision} the decision from `canMove`. When it is yes the item has
* been removed from where it was (if anywhere) and added to the position.
* @description Moves an item into the position from wherever it is, which may be
* another position of this inventory, another inventory, or nowhere.
* @example
* $("chest").move("contents", "item_gold_ring");
*/
move(name, itemId) {
const decision = this.canMove(name, itemId);
if(!decision.result) {
return decision;
}
const location = RezInventory.locationOf(itemId);
if(location?.inventory === this && location.position === name) {
return decision;
}
if(location) {
location.inventory.#removeItem(location.position, itemId);
}
this.#insertItem(name, itemId);
return decision;
}
#insertItem(name, itemId) {
const item = $(itemId);
if(!item.hasAttribute("type")) {
throw new Error(`Attempt to add |${itemId}| to inventory |${this.id}|, but it does not define a 'type'!`);
}
this.#updatePosition(name, (pos) => ({...pos, contents: [...pos.contents, itemId]}));
item.setAttribute("inventory_id", this.id);
item.setAttribute("position", name);
const slot = this.getSlot(name);
const params = {inventory_id: this.id, slot_id: slot.id, position: name, item_id: itemId, ...this.#ownerParams()};
this.runEvent("insert", params);
slot.runEvent("insert", params);
item.runEvent("insert", params);
this.applyEffects(name, itemId);
}
#removeItem(name, itemId) {
const item = $(itemId);
this.#updatePosition(name, (pos) => ({...pos, contents: pos.contents.filter((id) => id !== itemId)}));
item.setAttribute("inventory_id", null);
item.setAttribute("position", null);
const slot = this.getSlot(name);
const params = {inventory_id: this.id, slot_id: slot.id, position: name, item_id: itemId, ...this.#ownerParams()};
slot.runEvent("remove", params);
item.runEvent("remove", params);
this.runEvent("remove", params);
this.removeEffects(name, itemId);
}
//---------------------------------------------------------------------------
// Effects
//---------------------------------------------------------------------------
/**
* @function shouldApplyEffects
* @memberof RezInventory
* @param {string} name name of a position
* @returns {boolean} 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`
*/
shouldApplyEffects(name) {
return this.owner != null && this.apply_effects && this.getSlot(name).apply_effects;
}
/**
* @function applyEffects
* @memberof RezInventory
* @param {string} name name of a position
* @param {string} itemId
* @returns {boolean} whether any effects were applied
*/
applyEffects(name, itemId) {
if(!this.shouldApplyEffects(name)) return false;
const effectIds = $(itemId).getAttributeValue("effect_ids", null);
if(!effectIds) return false;
const location = {inventory_id: this.id, slot_id: this.getSlot(name).id, position: name};
for(const effectId of effectIds) {
$t(effectId, "effect").apply(this.owner_id, itemId, location);
}
return true;
}
/**
* @function removeEffects
* @memberof RezInventory
* @param {string} name name of a position
* @param {string} itemId
* @returns {boolean} whether any effects were removed
*/
removeEffects(name, itemId) {
if(!this.shouldApplyEffects(name)) return false;
const effectIds = $(itemId).getAttributeValue("effect_ids", null);
if(!effectIds) return false;
const location = {inventory_id: this.id, slot_id: this.getSlot(name).id, position: name};
for(const effectId of effectIds) {
$t(effectId, "effect").remove(this.owner_id, itemId, location);
}
return true;
}
}
window.Rez.RezInventory = RezInventory;
Source