@reldens/items-system Events and Error Codes

Reference of the events, error codes and constants of the @reldens/items-system package, with listener and error handling patterns.

Event Names

All event names are defined in ItemsEvents and start with reldens.items.. Inventory, item and manager events are namespaced when fired: the full name is {eventsPrefix}.{eventName}.

For an ItemsManager, eventsPrefix is the owner event key (owner.eventsPrefix, or items.ownerId.{ownerId} when the owner does not define one) followed by the optional eventsPrefix prop.
For example, the add item event of the owner with ID 15 is fired as items.ownerId.15.reldens.items.addItem.
Items fire their events through their manager, so they share the manager namespace.
Exchange events are fired by the ExchangePlatform with the plain event name (no owner prefix).

Use listenEvent() on the manager (or the item) so the prefix is added for you.

Events

Manager events

reldens.items.setup (MANAGER_INIT) - fired at the start of ItemsManager.setup().
- Payload: {props, manager}
reldens.items.loadedOwnerItems (LOADED_OWNER_ITEMS) - defined for integrations; Reldens fires it after loading an owner items from storage.
- Payload (Reldens): source, itemsInstances, itemsModels

Inventory events

reldens.items.validate (VALIDATE) - item validation.
- Payload: inventory, item, validationResult
reldens.items.addItemBefore (ADD_ITEM_BEFORE) - before a new item entry is added.
- Payload: inventory, item
reldens.items.addItem (ADD_ITEM) - after a new item entry is added.
- Payload: inventory, item
reldens.items.removeItem (REMOVE_ITEM) - fired before the item is deleted from the inventory.
- Payload: inventory, itemKey
reldens.items.modifyItemQty (MODIFY_ITEM_QTY) - quantity modified.
- Payload: item, inventory, operation, key, qty
reldens.items.setItems (SET_ITEMS) - items replaced.
- Payload: {items, manager}
reldens.items.setGroups (SET_GROUPS) - groups replaced.
- Payload: {groups, manager}

A single-instance item added when the key already exists does not fire the add events; it increases the existing quantity and fires the modify quantity event instead.

Equipment events

reldens.items.equipItem (EQUIP_ITEM) - item equipped. Payload: item
reldens.items.unequipItem (UNEQUIP_ITEM) - item unequipped. Payload: item
reldens.items.equipBeforeApplyModifiers - before applying the item modifiers. Payload: item
reldens.items.equipBeforeRevertModifiers - before reverting the item modifiers. Payload: item
reldens.items.equipAppliedModifiers - after applying the item modifiers. Payload: item
reldens.items.equipRevertedModifiers - after reverting the item modifiers. Payload: item

The last four names are built from ItemsEvents.EQUIP_BEFORE and ItemsEvents.EQUIP plus the ApplyModifiers, RevertModifiers, AppliedModifiers and RevertedModifiers suffixes. The modifier events are fired by any item that applies or reverts modifiers, including usable items.

Item execution events

reldens.items.executingItem (EXECUTING_ITEM) - before a usable item is executed. Payload: item
reldens.items.executedItem (EXECUTED_ITEM) - after a usable item is executed. Payload: item

The use target is available as item.target.

Exchange events

Defined under ItemsEvents.EXCHANGE:

reldens.items.initialized (INITIALIZED) - payload: {exchangePlatform, props, inventoryA, inventoryB}
reldens.items.canceled (CANCELED) - payload: {exchangePlatform}
reldens.items.invalidPush (INVALID_PUSH) - payload: {exchangePlatform, itemUid, qty, inventoryKey}
reldens.items.itemPushed (ITEM_PUSHED) - payload: {exchangePlatform, itemUid, qty, inventoryKey}
reldens.items.itemRemove (ITEM_REMOVE) - payload: {exchangePlatform, itemUid, inventoryKey}
reldens.items.confirm (CONFIRM) - payload: {exchangePlatform, inventoryKey}
reldens.items.disconfirm (DISCONFIRM) - payload: {exchangePlatform, inventoryKey}
reldens.items.beforeFinalize (BEFORE_FINALIZE) - payload: {exchangePlatform}
reldens.items.finalized (FINALIZED) - payload: {exchangePlatform}

Error Codes

Error codes are defined in ItemsConst.ERROR_CODES and start with items.. Inventory and equipment errors are stored in the inventory (or manager) lastError; exchange, requirement and reward errors are stored in the ExchangePlatform lastError.

Inventory error codes

items.undefinedItem - item is undefined.
items.undefinedMethodInventoryId - item does not implement getInventoryId().
items.undefinedItemKey - item has no key.
items.invalidItemInstance - item failed validation.
items.lockedForAddItem - inventory locked, cannot add the item.
items.maxTotalReachedForAddItem - total items limit reached.
items.itemExistsForAddItem - item already exists (non-single items).
items.itemLimitExceededForAddItem - item quantity exceeds the per-item limit.
items.addItemsError - error while adding an items array.
items.lockedForSetItem - inventory locked, cannot set the item.
items.lockedForRemoveItem - inventory locked, cannot remove the item.
items.keyNotFound - item key not found in the inventory.
items.lockedForModifyItemQty - inventory locked, cannot modify the quantity.
items.undefinedItemKeyForOperation - item key not found for the quantity operation.
items.qtyNotANumber - quantity is not a number.
items.qtyNegative - negative quantity on increase or decrease.
items.itemQtyLimitExceeded - quantity exceeds the per-item limit.
items.lockedForSetItems - inventory locked, cannot set the items.

Exchange error codes

items.exchange.missingConfirmation - both parties must confirm the exchange.
items.exchange.invalidPushedQuantity - pushed quantity is invalid or exceeds the available quantity.
items.exchange.invalidQuantity - invalid quantity (for example, 0).
items.exchange.invalidExchange - invalid exchange (from and to are the same inventory).
items.exchange.decreaseQuantity - failed to decrease the item quantity.
items.exchange.itemAdd - failed to add the item to the receiving inventory.

Requirements error codes

items.requirements.itemNotPresent - required item not present in the inventory.
items.requirements.quantityNotAvailable - required quantity not available.
items.requirements.itemNotPushed - required item not pushed for exchange.
items.requirements.itemQuantityNotPushed - required quantity not pushed.
items.requirements.itemDoesNotExists - required item does not exist.
items.requirements.itemAdd - failed to add the requirement item.

Rewards error codes

items.reward.doesNotExists - reward does not exist.
items.reward.missingItem - reward item missing.
items.reward.itemNotPresent - reward item not present in the opposite inventory.
items.reward.quantityNotAvailable - reward quantity not available.
items.reward.missingPushed - missing pushed item for the reward.
items.reward.getItemDoesNotExists - item does not exist.
items.reward.processItem - failed to process the reward item.
items.reward.processInventory - failed to process the reward inventory.
items.reward.addItems - failed to add the reward items.
items.reward.quantityOverload - reward quantity exceeds the available quantity.

Equipment error codes

items.equipment.modifiersApply - cannot apply the modifiers, the item is not equipped.
items.equipment.modifiersRevert - cannot revert the modifiers, the item is still equipped.

Error context

Errors are ItemsError instances with message, code, data (context) and withError (a nested error, for example the inventory error that made an exchange fail).

{
    message: 'Cannot add item, item qty limit exceeded.',
    code: 'items.itemLimitExceededForAddItem',
    data: {itemUid: 'sword_abc123', qty: 150},
    withError: false
}

Common data fields:

itemUid - item inventory ID.
qty - quantity involved.
operation - quantity operation (set, increase, decrease).
limitPerItem - limit that was exceeded.
confirmations - confirmation status (exchange).
requiredItemKey, rewardItemKey, inventoryKeyTo - requirement and reward context.

Constants

Action constants

Used in the client / server messages (act property). All start with the rinv prefix.

rinvA - add item (ACTION_ADD).
rinvR - remove item (ACTION_REMOVE).
rinvM - modify quantity (ACTION_MODIFY_QTY).
rinvE - equip item (ACTION_EQUIP).
rinvU - unequip item (ACTION_UNEQUIP).
rinvMa - modifiers applied (ACTION_MOD_APPLIED).
rinvMr - modifiers reverted (ACTION_MOD_REVERTED).
rinvEx - executing item (ACTION_EXECUTING).
rinvAExd - item executed (ACTION_EXECUTED).
rinvMi - manager initialized (ACTION_MANAGER_INIT).
rinvSi - set items (ACTION_SET_ITEMS).
rinvSg - set groups (ACTION_SET_GROUPS).

Item type constants

10 - ITEM_BASE - base item type.
1 - EQUIPMENT - equipment items.
2 - USABLE - usable / consumable items.
3 - SINGLE - single-instance (stackable) items.
4 - SINGLE_EQUIPMENT - single-instance equipment.
5 - SINGLE_USABLE - single-instance usable.

Quantity operations

set, increase, decrease (ItemsConst.SET, INCREASE, DECREASE).

Trade action constants

buy, sell, trade (ItemsConst.TRADE_ACTIONS).

Communication behavior constants

send - send to the owner client only.
broadcast - broadcast to all clients.
both - send and broadcast.

Patterns

Error handling

let result = await inventory.addItem(item);
if(false === result){
    let error = inventory.lastError;
    console.error('Error code:', error.code);
    console.error('Error message:', error.message);
    console.error('Error data:', error.data);
    if(error.withError){
        console.error('Nested error:', error.withError);
    }
}

Listening to inventory events

const { ItemsEvents } = require('@reldens/items-system');

itemsManager.listenEvent(
    ItemsEvents.ADD_ITEM,
    (inventory, item) => {
        console.log('Item added:', item.key);
    },
    itemsManager.getOwnerUniqueEventKey('addItemLogger'),
    itemsManager.getOwnerEventKey()
);

The third argument is a unique remove key and the fourth an optional master key, used later to remove the listeners. Remove keys must be unique: registering a second listener with an existing remove key is ignored.

Listening to exchange events

const { EventsManagerSingleton } = require('@reldens/utils');

EventsManagerSingleton.on(ItemsEvents.EXCHANGE.FINALIZED, async ({exchangePlatform}) => {
    // persist both inventories, notify the players, etc.
});