Fighting Game · Guides & deep dives

V2 Item Authoring Guide

ItemDefinitionSchema_V2_Contract.json

12sections6 minread1table
Markdown source
On this page

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#

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