# V2 Item Authoring Guide

This guide is the author-facing workflow for Phase 72 item content. It connects
the V2 Unreal item definition schema, item database, runtime instances,
modifiers, sets, durability, sockets, preview data, localization, serialization,
and validation gates that protect shipped item catalogs.

## Source Of Truth

- Definition schema contract:
  [ItemDefinitionSchema_V2_Contract.json](../../ue/Content/V2/Gameplay/Items/ItemDefinitionSchema_V2_Contract.json)
- Database contract:
  [ItemDatabase_V2_Contract.json](../../ue/Content/V2/Gameplay/Items/ItemDatabase_V2_Contract.json)
- Instance contract:
  [ItemInstanceSystem_V2_Contract.json](../../ue/Content/V2/Gameplay/Items/ItemInstanceSystem_V2_Contract.json)
- Rarity tier contract:
  [ItemRarityTiers_V2_Contract.json](../../ue/Content/V2/Gameplay/Items/ItemRarityTiers_V2_Contract.json)
- Category contract:
  [ItemCategories_V2_Contract.json](../../ue/Content/V2/Gameplay/Items/ItemCategories_V2_Contract.json)
- Stat modifier contract:
  [ItemStatModifiers_V2_Contract.json](../../ue/Content/V2/Gameplay/Items/ItemStatModifiers_V2_Contract.json)
- Set bonus contract:
  [ItemSetBonuses_V2_Contract.json](../../ue/Content/V2/Gameplay/Items/ItemSetBonuses_V2_Contract.json)
- Durability contract:
  [ItemDurability_V2_Contract.json](../../ue/Content/V2/Gameplay/Items/ItemDurability_V2_Contract.json)
- Enchantment and socket contract:
  [ItemEnchantmentSockets_V2_Contract.json](../../ue/Content/V2/Gameplay/Items/ItemEnchantmentSockets_V2_Contract.json)
- Comparison tooltip contract:
  [ItemComparisonTooltip_V2_Contract.json](../../ue/Content/V2/Gameplay/Items/ItemComparisonTooltip_V2_Contract.json)
- Preview contract:
  [ItemPreview_V2_Contract.json](../../ue/Content/V2/Gameplay/Items/ItemPreview_V2_Contract.json)
- Serialization contract:
  [ItemSerialization_V2_Contract.json](../../ue/Content/V2/Gameplay/Items/ItemSerialization_V2_Contract.json)
- Validation tool contract:
  [ItemValidationTool_V2_Contract.json](../../ue/Content/V2/Gameplay/Items/ItemValidationTool_V2_Contract.json)
- Localization contract:
  [ItemLocalization_V2_Contract.json](../../ue/Content/V2/Gameplay/Items/ItemLocalization_V2_Contract.json)
- Authoring guide contract:
  [ItemAuthoringGuide_V2_Contract.json](../../ue/Content/V2/Gameplay/Items/ItemAuthoringGuide_V2_Contract.json)
- Runtime definition header:
  [V2ItemDefinition.h](../../ue/Source/V2Gameplay/Public/V2ItemDefinition.h)
- Catalog validation header:
  [V2ItemValidationTool.h](../../ue/Source/V2Gameplay/Public/V2ItemValidationTool.h)

## Item Identity And Definitions

Every authored item starts as an `FV2ItemDefinition`. The definition is the
stable catalog row used by the database, runtime instances, preview surfaces,
serialization, and localization.

Required definition fields:

| Field               | Authoring rule                                               |
| ------------------- | ------------------------------------------------------------ |
| `ItemId`            | Stable `item.` id. Do not reuse after shipping.              |
| `NameTextId`        | Stable `loc.item.*` string id for the display name.          |
| `DescriptionTextId` | Stable `loc.item.*` string id for the description.           |
| `IconAsset`         | Soft object path for inventory and tooltip icon rendering.   |
| `MeshAsset`         | Soft object path for preview and equipped visual references. |
| `Weight`            | Non-negative encumbrance value.                              |
| `Value`             | Non-negative economy value used by shops and loot balancing. |
| `MaxStackSize`      | At least `1`; use `1` for non-stackable equipment.           |
| `Categories`        | At least one `EV2ItemCategory` value.                        |
| `Tags`              | At least one stable gameplay or content tag.                 |
| `Rarity`            | One `EV2ItemRarity` value from `Common` through `Legendary`. |

Run `ValidateItemDefinition` on every new or edited definition before the row
enters the catalog.

## Categories, Rarity, And Tags

Use `EV2ItemCategory` to express broad item behavior. Supported category values
are `Weapon`, `Armor`, `Consumable`, `Material`, `KeyItem`, `QuestItem`,
`Cosmetic`, and `Currency`.

Use `EV2ItemRarity` for tuning, presentation, and loot table expectations:
`Common`, `Uncommon`, `Rare`, `Epic`, and `Legendary`.

Tags should describe systems that need stable lookup behavior, for example:

- `slot.weapon.main_hand`
- `slot.armor.chest`
- `craft.material.ore`
- `socket.gem`
- `rune.fire`
- `quest.market_routes`

Avoid using prose labels as tags. Tags are consumed by stat profiles, socket
rules, filters, validation reports, and analytics.

## Stat Modifiers And Sets

Use `FV2ItemStatModifier` for authored stat changes. Each modifier needs a
stable `ModifierId`, `StatTag`, `Operation`, `Magnitude`, `SourceItemId`,
`SourceTag`, and an explicit `bRequiresEquipped` setting.

Supported operations are `AddFlat`, `AddPercent`, `Multiply`, and `Override`.
Use `ValidateItemStatModifiers` before a stat profile is reviewed. Use
`ApplyItemStatModifiers` to verify the final value for target stats during
balance review.

Set content is authored with `FV2ItemSetDefinition` and
`FV2ItemSetBonusThreshold`. Each set needs a stable `SetId`, display and
description text ids, `PieceItemIds`, and increasing bonus thresholds. Validate
sets with `ValidateItemSetDefinitions`, then review active bonuses with
`EvaluateAllItemSetBonuses` and `GetActiveItemSetStatModifiers`.

## Durability, Sockets, And Enchantments

Durable items use `FV2ItemDurabilityProfile`. Profiles define `ProfileId`,
`MaxDurability`, `WearPerUse`, low durability threshold, broken effectiveness,
repair cost, break-at-zero behavior, and repair permissions. Use
`InitializeItemDurability` for new instances, `ApplyItemDurabilityUse` for wear,
and `RepairItemDurability` for repair flows. Use
`ValidateItemDurabilityProfiles` before changing durability tuning.

Socket layouts use `FV2ItemSocketDefinition`. Socket occupants use
`FV2ItemSocketOccupant`, and active socket state is stored in
`FV2ItemSocketState`. Author accepted item tags, gem/rune permissions, and sort
order before content review. Use `InitializeItemSocketStates`,
`SocketItemIntoItemSocket`, `RemoveItemFromItemSocket`, and
`GetActiveItemSocketStatModifiers` to test socket behavior.

Enchantments use `FV2ItemEnchantmentRecipe` with a stable `RecipeId`,
`EnchantmentId`, display and description text ids, required rune tag/count,
crafting cost, and granted modifiers. Use `ApplyItemEnchantmentRecipe`,
`GetActiveItemEnchantmentStatModifiers`, and
`GetCombinedItemEnhancementStatModifiers` to verify authored results. Run
`ValidateItemEnchantmentSocketData` for every socket or enchantment data change.

## Runtime Instances And Serialization

Definitions are reusable catalog rows. Player-owned or world-owned copies are
`FV2ItemInstance` values with `InstanceId`, `ItemId`, `StackCount`,
`Durability`, `MaxDurability`, `Enchantments`, and `CustomData`.

Use `CreateItemInstanceFromDefinition` when spawning a new item. Use
`ValidateItemInstance` before storing, trading, equipping, or serializing an
instance. Use `AreItemInstanceIdsUnique` for container or save-game batches.

Save data uses `FV2SerializedItemInstance` and `FV2ItemSaveState`. Run
`SerializeItemInstance`, `MakeItemSaveState`, `RestoreSerializedItemInstance`,
`RestoreItemSaveState`, `ValidateSerializedItemInstance`, and
`ValidateItemSaveState` when testing persistence changes.

## Preview, Comparison, And UI Text

Item previews are authored from the same definition data used by inventory and
equipment systems. Preview rows must preserve `PreviewSurfaceTag`, `ItemId`,
`NameTextId`, `DescriptionTextId`, `IconAsset`, `MeshAsset`, `Rarity`,
`PreviewContext`, `CameraRig`, `LightingRig`, action state, purchase data,
stable dimensions, and `AccessibilitySummaryTextId`.

Comparison tooltips use structured delta data instead of prose-only output. Run
the comparison tooltip validation when changing item stat, value, weight,
durability, or equip-state behavior.

Player-facing UI text must be referenced by stable text ids, not hard-coded
strings. Names and descriptions resolve through item localization before they
reach preview, tooltip, shop, equip, or save-restore surfaces.

## Localization

Item localization rows are stored in `FV2ItemLocalizationTable`. Each
`FV2ItemLocalizedTextEntry` is keyed by `ItemId` and `Locale`, and it repeats
the definition's `NameTextId` and `DescriptionTextId` so mismatches are caught
by validation.

The source locale is `en-US`. Use `MakeItemLocalizedTextEntry` for new rows,
`ResolveItemLocalizedText` for runtime display, and source-locale fallback only
when a requested locale is missing during development. Before content review,
run `BuildItemLocalizationCoverage` and `ValidateItemLocalizationTable` for all
required locales.

## Catalog Validation

Catalog signoff uses `ValidateItemCatalog` and produces an
`FV2ItemValidationReport`. Provide:

- The complete `FV2ItemDefinition` list.
- One `FV2ItemValidationStatProfile` for each equippable or balance-relevant
  item.
- The balance rules from `GetDefaultItemValidationBalanceRules`, extended only
  when a design owner has approved new stat bounds.

The report must have `bValid: true`, `MissingReferenceCount: 0`,
`VisualReferenceIssueCount: 0`, `BalanceIssueCount: 0`,
`DuplicateItemIdCount: 0`, and no blocking `FV2ItemValidationIssue` rows before
content can ship.

## Authoring Workflow

1. Create or edit the `FV2ItemDefinition` row with stable ids, icon, mesh,
   economy, stack, category, tag, and rarity data.
2. Register the row in the item database and verify lookup by item id, category,
   tag, rarity, and search text.
3. Add stat modifiers, set membership, durability profile, socket layout, and
   enchantment recipes only when the item needs those systems.
4. Create preview data for inspect, equip, and purchase contexts.
5. Add `FV2ItemLocalizedTextEntry` rows for `en-US` and every required locale.
6. Spawn at least one `FV2ItemInstance` fixture and validate stack, durability,
   enchantment, socket, and custom data behavior.
7. Serialize and restore the instance fixture.
8. Run the catalog validation report with visual references and balance rules.
9. Run the validation commands in this guide and attach results to the content
   review.

## Review Checklist

Before item content review, confirm:

- `ItemId`, `NameTextId`, and `DescriptionTextId` are stable and unique.
- Icon and mesh soft object paths resolve for the target platform.
- Weight, value, and `MaxStackSize` match economy and inventory expectations.
- Categories and tags are specific enough for filtering, sockets, loot, and QA.
- Rarity is consistent with drop rate, price, stats, VFX, and preview lighting.
- Stat modifiers have stable ids, approved operations, and balanced magnitudes.
- Set bonuses have ordered thresholds and valid piece item ids.
- Durability profiles cannot generate negative durability or invalid repair
  costs.
- Socket definitions and enchantment recipes use accepted tags consistently.
- Preview data includes stable dimensions and accessibility summary text.
- Localization covers every required locale or explicitly reports a source
  fallback during development.
- Serialized instances restore without losing enchantments, socket state,
  durability, stack count, or custom data.
- `ValidateItemCatalog` reports no duplicate item ids, missing references, or
  blocking balance issues.

## Validation Commands

Run these commands after changing item authoring docs, item catalog data, item
runtime behavior, validation rules, localization rows, or CI wiring:

```bash
python3 V2/ue/Tools/check-v2-item-authoring-guide.py
python3 V2/ue/Tools/check-v2-item-localization.py
python3 V2/ue/Tools/check-v2-item-validation-tool.py
python3 V2/ue/Tools/check-v2-item-serialization.py
python3 V2/ue/Tools/check-v2-item-preview.py
python3 V2/ue/Tools/check-v2-item-comparison-tooltip.py
python3 V2/ue/Tools/check-v2-item-enchantment-sockets.py
python3 V2/ue/Tools/check-v2-item-durability.py
python3 V2/ue/Tools/check-v2-item-set-bonuses.py
python3 V2/ue/Tools/check-v2-item-stat-modifiers.py
python3 V2/ue/Tools/check-v2-item-categories.py
python3 V2/ue/Tools/check-v2-item-rarity-tiers.py
python3 V2/ue/Tools/check-v2-item-instance-system.py
python3 V2/ue/Tools/check-v2-item-database.py
python3 V2/ue/Tools/check-v2-item-definition-schema.py
python3 V2/ue/Tools/check-v2-ci-workflow.py
python3 -m json.tool V2/ue/Content/V2/Gameplay/Items/ItemAuthoringGuide_V2_Contract.json
python3 -m json.tool V2/ue/Build/Horde/v2-buildgraph-job.json
python3 V2/tools/validate-v2-docs.py
pnpm exec prettier --check V2/docs/modes/item-authoring-guide.md V2/ue/Content/V2/Gameplay/Items/ItemAuthoringGuide_V2_Contract.json V2/ue/Build/Horde/v2-buildgraph-job.json
```