@reldens/items-system

# Events and Error Codes Reference Quick reference for all events and error codes in the items system. ## Events All events are prefixed with `reldens.items.` by default. ### Manager Events - `reldens.items.setup` - ItemsManager initialization complete - Payload: `{props, manager}` ### Inventory Events - `reldens.items.validate` - Item validation - Payload: `inventory, item, validationResult` - `reldens.items.addItemBefore` - Before adding item - Payload: `inventory, item` - `reldens.items.addItem` - After adding item - Payload: `inventory, item` - `reldens.items.removeItem` - Removing item - Payload: `inventory, itemKey` - `reldens.items.modifyItemQty` - Quantity modified - Payload: `item, inventory, operation, key, qty` - `reldens.items.setItems` - Items set - Payload: `{items, manager}` - `reldens.items.setGroups` - Groups set - Payload: `{groups, manager}` - `reldens.items.loadedOwnerItems` - Owner items loaded - Payload: varies ### Equipment Events - `reldens.items.equipItem` - Item equipped - Payload: `item, target` - `reldens.items.unequipItem` - Item unequipped - Payload: `item, target` - `reldens.items.equipBeforeApplyModifiers` - Before applying modifiers - Payload: `item` - `reldens.items.equipBeforeRevertModifiers` - Before reverting modifiers - Payload: `item` - `reldens.items.equipAppliedModifiers` - After applying modifiers - Payload: `item` - `reldens.items.equipRevertedModifiers` - After reverting modifiers - Payload: `item` ### Item Execution Events - `reldens.items.executingItem` - Before item execution - Payload: `item, target` - `reldens.items.executedItem` - After item execution - Payload: `item, target` ### Exchange Events - `reldens.items.initialized` - Exchange initialized - Payload: `{exchangePlatform, props, inventoryA, inventoryB}` - `reldens.items.canceled` - Exchange canceled - Payload: `{exchangePlatform}` - `reldens.items.invalidPush` - Invalid item push attempt - Payload: `{exchangePlatform, itemUid, qty, inventoryKey}` - `reldens.items.itemPushed` - Item successfully pushed - Payload: `{exchangePlatform, itemUid, qty, inventoryKey}` - `reldens.items.itemRemove` - Item removed from exchange - Payload: `{exchangePlatform, itemUid, inventoryKey}` - `reldens.items.confirm` - Exchange confirmed - Payload: `{exchangePlatform, inventoryKey}` - `reldens.items.disconfirm` - Exchange disconfirmed - Payload: `{exchangePlatform, inventoryKey}` - `reldens.items.beforeFinalize` - Before exchange finalization - Payload: `{exchangePlatform}` - `reldens.items.finalized` - Exchange finalized - Payload: `{exchangePlatform}` ## Error Codes All error codes are prefixed with `items.` by default. ### Inventory Error Codes - `items.undefinedItem` - Item is undefined - `items.undefinedMethodInventoryId` - Item missing getInventoryId() method - `items.undefinedItemKey` - Item missing key property - `items.invalidItemInstance` - Item instance failed validation - `items.lockedForAddItem` - Inventory locked, cannot add item - `items.maxTotalReachedForAddItem` - Maximum total items reached - `items.itemExistsForAddItem` - Item already exists (non-single items) - `items.itemLimitExceededForAddItem` - Item quantity exceeds limit - `items.addItemsError` - Error adding items array - `items.lockedForSetItem` - Inventory locked, cannot set item - `items.lockedForRemoveItem` - Inventory locked, cannot remove item - `items.keyNotFound` - Item key not found in inventory - `items.lockedForModifyItemQty` - Inventory locked, cannot modify quantity - `items.undefinedItemKeyForOperation` - Item key undefined for operation - `items.qtyNotANumber` - Quantity is not a number - `items.itemQtyLimitExceeded` - Item quantity limit exceeded - `items.lockedForSetItems` - Inventory locked, cannot set items ### Exchange Error Codes - `items.exchange.missingConfirmation` - Both parties must confirm exchange - `items.exchange.invalidPushedQuantity` - Pushed quantity exceeds available quantity - `items.exchange.invalidQuantity` - Invalid quantity (e.g., 0) - `items.exchange.invalidExchange` - Invalid exchange (FROM and TO are same) - `items.exchange.decreaseQuantity` - Failed to decrease item quantity - `items.exchange.itemAdd` - Failed to add item to inventory ### Requirements Error Codes - `items.requirements.itemNotPresent` - Required item not present in 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 doesn't exist - `items.requirements.itemAdd` - Failed to add requirement item ### Rewards Error Codes - `items.reward.doesNotExists` - Reward doesn't exist - `items.reward.missingItem` - Reward item missing - `items.reward.itemNotPresent` - Reward item not present - `items.reward.quantityNotAvailable` - Reward quantity not available - `items.reward.missingPushed` - Missing pushed items for reward - `items.reward.getItemDoesNotExists` - Get item doesn't exist - `items.reward.processItem` - Failed to process reward item - `items.reward.processInventory` - Failed to process reward inventory - `items.reward.addItems` - Failed to add reward items - `items.reward.quantityOverload` - Reward quantity exceeds limits ### Equipment Error Codes - `items.equipment.modifiersApply` - Failed to apply equipment modifiers - `items.equipment.modifiersRevert` - Failed to revert equipment modifiers ## Action Constants Used for client/server communication. - `rinvA` - Add item action - `rinvR` - Remove item action - `rinvM` - Modify quantity action - `rinvE` - Equip item action - `rinvU` - Unequip item action - `rinvMa` - Modifier applied action - `rinvMr` - Modifier reverted action - `rinvEx` - Executing item action - `rinvAExd` - Item executed action - `rinvMi` - Manager initialized action - `rinvSi` - Set items action - `rinvSg` - Set groups action ## Item Type Constants - `10` - ITEM_BASE - Base item type - `1` - EQUIPMENT - Equipment items - `2` - USABLE - Usable/consumable items - `3` - SINGLE - Single-instance items (stackable) - `4` - SINGLE_EQUIPMENT - Single-instance equipment - `5` - SINGLE_USABLE - Single-instance usable ## Trade Action Constants - `buy` - Buy action - `sell` - Sell action - `trade` - Trade action ## Communication Behavior Constants - `send` - Send to specific client - `broadcast` - Broadcast to all clients - `both` - Both send and broadcast ## Common Error Handling Pattern ```javascript 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.error){ console.error('Nested Error:', error.error); } } ``` ## Event Listening Pattern ```javascript itemsManager.listenEvent( ItemsEvents.ADD_ITEM, (inventory, item) => { console.log('Item added:', item.key); }, 'unique-listener-key' ); ``` ## Custom Events with Prefix When creating ItemGroup or using custom eventsPrefix: ```javascript let group = new ItemGroup({ id: 1, key: 'equipment', eventsPrefix: 'player123.' }); // Events will be: player123.g.equipment.reldens.items.addItem // Format: {playerPrefix}.g.{groupKey}.{eventName} ``` ## Event Propagation 1. Item events bubble up through manager 2. Manager events can be global or owner-specific 3. Exchange events are platform-specific 4. All events go through EventsManager (from @reldens/utils) ## Error Context Errors include contextual data in the `data` property: ```javascript { code: 'items.itemLimitExceededForAddItem', message: 'Cannot add item, item qty limit exceeded.', data: { itemUid: 'sword_abc123', qty: 150 } } ``` Common data fields: - `itemUid` - Item unique ID - `qty` - Quantity involved - `operation` - Operation type (set, increase, decrease) - `limitPerItem` - Limit that was exceeded - `confirmations` - Confirmation status (exchange)