Item Entity

The items_item entity represents in-game items with comprehensive inventory management, equipment functionality, and modifier support.

Managing items in the admin panel

Items are in the Items & Inventory section of the admin sidebar, under Items (/reldens-admin/items-item). The same section holds the item Modifiers, Groups, Types and the Players Inventory:

Admin Panel - Items list

To create an item:

  1. Log in to the admin panel at /reldens-admin and open Items & Inventory > Items.
  2. Click Create New (the form opens at /reldens-admin/items-item/edit).
  3. Fill in the Key (required and unique, for example magic_sword) and the Label (required, the name shown to the players).
  4. Select the Type (equipment, usable, single, single_equipment, single_usable or base, see "Item Types" below).
  5. Select the Group ID for equipment: only one item of each group can be equipped at the same time. The groups are managed in Items & Inventory > Groups.
  6. Optionally fill in the Description, Qty Limit, Uses Limit, UseTimeOut and ExecTimeOut (milliseconds) and the CustomData JSON.
  7. Click Save.
  8. Add the stat changes of the item in Items & Inventory > Modifiers: select the item, then fill in the key, the property key (for example stats/atk), the operation and the value (see "Item modifiers" below).
  9. Give the item to the players: directly in Items & Inventory > Players Inventory, as an enemy drop in the Rewards section, or in a trader inventory in Game Objects > Objects Items Inventory.
  10. Restart the server, the items configuration is loaded on startup.
Admin Panel - Create Items form

In the form, r marks a required field and u a field that must be unique. To create a similar item, open an existing one and click Duplicate: the ID is cleared so the next save creates a copy, change the key before saving.

Key Properties

  • key: Unique item identifier
  • type: Item type reference (equipment, usable, single, combinations)
  • group_id: Item group for categorization
  • label: Display name
  • description: Item description
  • qty_limit: Maximum quantity per inventory slot
  • uses_limit: Maximum number of uses
  • useTimeOut: Cooldown between uses (milliseconds)
  • execTimeOut: Execution timeout (milliseconds)
  • customData: JSON custom properties

Item Types

  • ITEM_BASE (10): Base item class
  • EQUIPMENT (1): Equippable items with modifiers
  • USABLE (2): Consumable items
  • SINGLE (3): Stackable items, the quantity is grouped in a single inventory object
  • SINGLE_EQUIPMENT (4): Stackable equipment
  • SINGLE_USABLE (5): Stackable consumables

Related Systems

  • Inventory Management: Add, remove, quantity control with limits
  • Exchange System: Player-to-player trading and NPC shops
  • Modifiers: Stat bonuses and effects via @reldens/modifiers
  • Item Groups: Categorized inventories with separate limits, only one equipped item per group

Database Relations

  • items_types: Item type classification
  • items_group: Item grouping and categorization
  • items_item_modifiers: Stat modifiers applied by item
  • items_inventory: Item instances owned by each player
  • objects_items_inventory: Items in world objects
  • objects_items_requirements: Items required for interactions
  • objects_items_rewards: Items given as rewards

Implementation

Each item can have multiple modifiers that apply when equipped or used. The items system supports complex inventory management with group-based limits, trading between players, and NPC shop interactions.

Item modifiers

Each items_item_modifiers row belongs to one item and changes one property of the item owner:

  • key: Modifier identifier (e.g. atk)
  • property_key: Path to the property to modify (e.g. stats/atk)
  • operation: Operation ID: 1 INC, 2 DEC, 3 DIV, 4 MUL, 5 INC_P (increase by %), 6 DEC_P (decrease by %), 7 SET, 8 METHOD, 9 SET_N
  • value: Value to apply, stored as string and converted to a number for every operation except SET
  • maxProperty: Optional max value property path (e.g. statsBase/hp)

Percentage operations round the result: an INC_P of 5 on atk=100 gives 105, and the revert gives Math.round(105 / 1.05) = 100. The METHOD operation does not work with the default loader, it needs custom code (see Items System Implementation).

How items are loaded and equipped

  1. When the player stats are loaded, the reldens.createPlayerStatsAfter event creates the player inventory (ItemsServer) with a StorageObserver that persists every change.
  2. The items_inventory rows of the player are loaded and ItemsFactory builds each item instance: the class is resolved from server/customClasses/inventory/items by the item key, falling back to the class of the item type.
  3. Equipment items are marked as equipped when items_inventory.is_active is 1, and every modifier targets the player.
  4. When the player equips an item, the equipped item of the same group is unequipped first, is_active is saved, the modifiers are applied to the player stats, the stats are saved and the client receives the updated stats. Unequip follows the same flow reverting the modifiers.

Custom item classes

Extend ItemBase or ItemEquipment from @reldens/items-system and register the class by item key:

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

class MagicWeapon extends ItemEquipment {
    async equip(applyMods){
        await super.equip(applyMods);
        // Post-equip custom logic
    }
}

// server/customClasses/inventory/items:
itemClasses: {
    'magic_sword': MagicWeapon
}

Package

Implemented in the @reldens/items-system package, with the stat changes handled by @reldens/modifiers. The Reldens integration lives in lib/inventory/.

Related Documentation

Go Up