The item framework stores reusable item definitions separately from runtime item instances. Definitions describe what an item is; instances describe a specific copy owned by a player, container, vendor, or world drop.
Definitions#
Create definitions with createItemDefinition. Required fields are id,
name, description, and category. Optional fields include rarity, icon,
mesh, weight, value, max stack size, tags, stat modifiers, set ID, durability,
sockets, localization, and preview asset references.
Use ItemCategory for weapon, armor, consumable, material, key item, quest
item, cosmetic, and currency. Use ItemRarity for common through legendary item
quality.
Database and Queries#
Use createItemDatabase and registerItemDefinition to build runtime item
databases. Query definitions with queryItemDefinitions by text, category,
rarity, or tags. ItemRegistry wraps the same operations for mutable registry
use.
Instances#
Create runtime copies with createItemInstance. Instances store quantity,
durability, enchantments, socketed item IDs, and custom data. Stack counts are
capped by the definition's maxStackSize.
Durability helpers:
damageItemDurabilityrepairItemDurabilityisItemBroken
Broken durable items contribute no stat modifiers.
Modifiers, Enchantments, and Sockets#
Stat modifiers are flat or percent values keyed by statId. Base item
modifiers, enchantment modifiers, and socketed item modifiers are combined by
computeItemModifiers.
Sockets are constrained by max socket count and allowed item categories.
Sets and Comparison Data#
Define set bonuses with ItemSetDefinition and compute active bonuses with
computeItemSetBonuses.
Use compareItems to create structured comparison data for equipment inspection
surfaces. It returns stat, value, weight, and durability deltas without
rendering any UI.
Save/Load, Localization, and Validation#
Persist item instances with serializeItemInstances and restoreItemInstances.
Use localizeItemDefinition to resolve locale-specific names and descriptions.
Run validateItemDatabase before shipping authored data to catch invalid stack
sizes, negative values, missing icons, invalid set references, and bad
durability thresholds.