# Item Authoring Guide

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:

- `damageItemDurability`
- `repairItemDurability`
- `isItemBroken`

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.
