Items and equipment reference

The equipment component, world pickups, the item, rarity, tag and set assets, and the requirement and set-bonus data they carry. For how to use it, see Items and equipment.

VtUnitEquipment

Component. Add it with Add Component → Vantage → Items → VtUnitEquipment. Adds VtUnitModifiers, VtUnitTraits automatically.

Per-unit equipment state — owns the slot map (which item is in which slot) and is the orchestrator for the equip / unequip flow. Drives modifier / attribute-grant / trait-override pushes through the unit’s VtUnitModifiers + VtUnitTraits siblings under the source id "equipment_<slot>".

Inspector fields

Field	Type	Default	Description
Two Hand Rule (`twoHandRule`)	VtTwoHandRule	`OffHandComesOff`	What happens to the off-hand item when a two-handed item goes into the main hand. Off Hand Comes Off puts it in the bag; Off Hand Suspended keeps it worn without its bonuses until the two-hander leaves; Off Hand Blocks Two Hander refuses the two-hander while an off-hand item is worn. Read when gear goes on or comes off; a change during play applies from the next one.

Scripting API

Member	Description
`IReadOnlyDictionary<VtEquipmentSlot, VtItemDefinition> Equipped { get; }`	Read-only view of the slot map. Iterate to render an inventory panel or compute set-piece totals.
`IReadOnlyList<VtActiveSet> ActiveSets { get; }`	Snapshot of all sets with at least one piece equipped. Each entry reports the set definition, equipped piece count, and the highest currently active tier index (or -1 when no tier threshold is met). Allocates a fresh list each call — UI panels typically call this on `OnSetTierChanged`, not every frame.
`bool IsHeldFromInventory { get; }`	True while the main hand shows the selected slot of a `VtUnitHeldSlot` rather than an item worn the usual way. The item then stays in the bag; saves do not list it as worn.
`event Action<VtEquipmentSlot, VtItemDefinition> OnEquipped`	Fired after an item is successfully equipped (incl. via the replication entry point). Args: (slot, item).
`event Action<VtEquipmentSlot, VtItemDefinition> OnUnequipped`	Fired after an item is successfully unequipped. Args: (slot, item).
`event Action<VtEquipmentSlot, int, int> OnDurabilityChanged`	Fired after durability changes on an equipped slot. Args: (slot, current, max), where max is `GetMaxDurability`, which includes copies combined into the item. Fires on equip (initial fill), `ApplyWear`, `RepairItem`, `RepairAll` and when a copy combines into the worn item. Does not fire when an indestructible item is equipped / unequipped.
`event Action<VtEquipmentSlot, VtItemDefinition> OnItemBroken`	Fired exactly once per slot when an item’s durability hits zero. Args: (slot, item). Subscribers can choose whether to repair, replace, or cosmetically handle the broken state. Auto-unequip (when `VtItemDefinition.autoUnequipOnBreak` is true) fires after this event. A main-hand item held from a `VtUnitHeldSlot` is taken from its slot by the held slot’s own handler, so a handler that runs after it may find the main hand already empty.
`event Action<VtItemSetDefinition, int, int> OnSetTierChanged`	Fired when a set’s top active tier index changes — activated, deactivated, or upgraded / downgraded between tiers. Args: (set, oldTopTierIndex, newTopTierIndex). `-1` means “no tier active”. Subscribers update set-bonus UI panels off this; the source-bag mutations have already happened by the time this fires.
`event Action<VtEquipmentSlot, bool> OnSlotSuspended`	Fired when a worn item is suspended or active again, such as the off-hand item while a two-handed item is held under `VtTwoHandRule.OffHandSuspended`. Args: (slot, suspended). Visuals hide it.
`bool IsSuspended(VtEquipmentSlot slot)`	True when the item in `slot` is worn but gives nothing right now. Suspended items do not count toward sets.
`VtItemDefinition GetEquipped(VtEquipmentSlot slot)`	Item currently in the given slot, or null if the slot is empty.
`bool IsEquipped(VtEquipmentSlot slot)`	True if any item occupies the given slot.
`bool IsEquipped(VtItemDefinition item, VtEquipmentSlot slot)`	True if this specific item is in the given slot.
`int GetDurability(VtEquipmentSlot slot)`	Current durability of the item in the given slot. Returns 0 if the slot is empty or the equipped item is indestructible.
`int GetMaxDurability(VtEquipmentSlot slot)`	Maximum durability of the item in the given slot: its authored `VtItemDefinition.maxDurability` plus `GetExtraDurability`. Returns 0 if the slot is empty or the item is indestructible (`maxDurability == 0`).
`int GetExtraDurability(VtEquipmentSlot slot)`	Durability that copies combined into the item in `slot` added (`VtDurabilityMode.Uses`). 0 for a single copy, an empty slot and every other item.
`VtInventoryEntry GetWornEntry(VtEquipmentSlot slot)`	The item in `slot` as a bag entry would hold it, with its wear and extra durability. An empty slot gives an entry without an item.
`int GetWear(VtEquipmentSlot slot)`	Durability the item in `slot` has lost: max minus current. 0 for empty slots and items that do not wear out. Taking the item off into the bag keeps this wear on the bag entry.
`float GetDurabilityFraction(VtEquipmentSlot slot)`	Durability as a 0..1 fraction. Returns 1f for empty slots and indestructible items (so a UI bar can render “full / N/A” uniformly).
`int GetSetPieceCount(VtItemSetDefinition set)`	Number of equipped members of the given set (0 when none). Cheap — reads from a cached map, doesn’t walk slots.
`int GetActiveTierIndex(VtItemSetDefinition set)`	Highest active tier index (into `VtItemSetDefinition.tiers`) for the given set, or `-1` if no tier is currently active.
`bool CanEquip(VtItemDefinition item, VtEquipmentSlot slot, out VtEquipFailureReason reason)`	Pure query — returns whether the item could be equipped right now, ignoring slot occupancy (useful for tooltip “you can equip this” gating). `TryEquip` performs occupancy checks and the actual mutation.
`bool CanEquip(VtItemDefinition item, out VtEquipFailureReason reason)`	Convenience overload that uses the item’s authored slot.
`bool TryEquip(VtItemDefinition item, out VtEquipFailureReason reason)`	Equip the item into its authored slot, picking a family member when applicable (first empty Ring1 / Ring2; first empty Trinket1 / Trinket2; falls back to replacing the first member if both full).
`bool TryEquip(VtItemDefinition item, VtEquipmentSlot slot, out VtEquipFailureReason reason)`	Equip the item into the explicit slot. The slot must match the item’s authored slot (or be in the same Ring / Trinket family).
`bool TryEquipFromInventory(VtItemDefinition item, out VtEquipFailureReason reason)`	Wear `item` from the unit’s `VtUnitInventory`: one is taken out of the bag and whatever it replaces goes back in. Durability carries both ways: the copy put on keeps the wear its bag entry had (the newest copy when several differ), and the replaced items keep theirs. Refused with `VtEquipFailureReason.InventoryFull` when the replaced items would not fit, and with `VtEquipFailureReason.WouldOverflowInventory` when the swap lowers the bag’s capacity below what it holds. On a predicting client the request is forwarded and this returns false with `VtEquipFailureReason.AuthorityNotLocal`.
`bool TryEquipFromInventory(VtItemDefinition item, VtEquipmentSlot slot, out VtEquipFailureReason reason)`	Like `TryEquipFromInventory`, into `slot`, such as the second ring slot. `VtEquipmentSlot.None` picks the item’s own slot.
`bool TryUnequipToInventory(VtEquipmentSlot slot, out VtEquipFailureReason reason)`	Take off the item in `slot` and put it in the unit’s `VtUnitInventory`. Refused with `VtEquipFailureReason.InventoryFull` when the bag has no room, and with `VtEquipFailureReason.WouldOverflowInventory` when the item adds to the bag’s capacity and the bag would no longer hold what it holds. Forwarded like `TryEquipFromInventory`.
`bool Unequip(VtEquipmentSlot slot)`	Unequip the item in the given slot. Returns true if a slot was emptied, false if the slot was already empty, authority refused, or the item adds to the bag’s capacity and the bag would no longer hold what it holds.
`bool TryEquipFromSlot(VtInventorySlotRef from, VtEquipmentSlot slot, out VtEquipFailureReason reason)`	Wear the item in bag slot `from` in `slot` (`VtEquipmentSlot.None` picks the item’s own slot). That exact copy goes on, with its wear, and what it replaces goes back into `from` when that slot takes it, else into the bag. When the slot already wears a copy of the same `VtDurabilityMode.Uses` item, the bag copy combines into the worn one instead: its durability adds to the worn item and the bag slot empties, without taking the worn item off. Refused like `TryEquipFromInventory`. On a predicting client the request is sent and this returns false with `VtEquipFailureReason.AuthorityNotLocal`.
`bool TryUnequipToSlot(VtEquipmentSlot slot, VtInventorySlotRef to, out VtEquipFailureReason reason)`	Take off the item in `slot` into bag slot `to`. When `to` holds an item that can be worn in `slot`, the two swap; when it holds a copy of the same `VtDurabilityMode.Uses` item, the worn copy comes off and combines into it. Refused with `VtEquipFailureReason.TargetSlotRefused` when `to` holds something else, is shut or its rules refuse the item, and otherwise like `TryUnequipToInventory`. On a predicting client the request is sent.
`bool TryMoveWorn(VtEquipmentSlot from, VtEquipmentSlot to, out VtEquipFailureReason reason)`	Move a worn item to another equipment slot it fits, such as a ring from the first ring slot to the second, swapping with what is there. Durability moves with each item. On a predicting client the request is sent.
`VtEquipmentSlot FreeSlotFor(VtItemDefinition item)`	The slot `item` would go into without anything coming off it (the first free ring or trinket slot of a pair), or `VtEquipmentSlot.None` when that slot is taken or the item is not worn.
`bool PassesTwoHandRule(VtItemDefinition item, VtEquipmentSlot slot, out VtEquipFailureReason reason)`	Whether `twoHandRule` lets `item` go into `slot` with what is worn now: an off-hand item while a two-hander is held, or a two-hander while an off-hand item is worn. A drag view asks this with `CanEquip`.
`bool ApplyWear(VtEquipmentSlot slot, int amount)`	Reduce the durability of the item in the given slot by `amount`. Authority-gated. Indestructible items (`maxDurability == 0`) and empty slots are no-ops. When durability hits zero, `OnItemBroken` fires; if the item’s `VtItemDefinition.autoUnequipOnBreak` is true, the slot is also cleared (firing `OnUnequipped`).
`void RepairItem(VtEquipmentSlot slot, int amount)`	Restore `amount` durability on the slot, clamped to `VtItemDefinition.maxDurability`. Authority-gated. No-op on empty slots, indestructible items and `VtDurabilityMode.Uses` items, whose uses are spent, not damaged.
`void RepairAll()`	Restore every equipped slot’s durability to the item’s authored max. Authority-gated. Indestructible and `VtDurabilityMode.Uses` items unaffected. Common pattern: “visit the blacksmith → all gear repaired.”
`void ApplyEquippedFromNet(VtEquipmentSlot slot, VtItemDefinition item)`	Net-replication entry point: mirror an authoritative equip on a replica. Bypasses the authority gate and the requirement / two-hand checks (the authority already validated them); pushes the modifier / attribute / trait sources locally so derived state stays consistent with the host. Durability seeds to the item’s authored max — call the overload to mirror a partial-wear snapshot.
`void ApplyEquippedFromNet(VtEquipmentSlot slot, VtItemDefinition item, int currentDurability)`	Net-replication entry point with a durability snapshot — used when the authoritative side has already taken wear and the replica must mirror the current value (e.g. late-join). `currentDurability` is clamped to `[0, item.maxDurability]`; ignored for indestructible items.
`void ApplyEquippedFromNet(VtEquipmentSlot slot, VtItemDefinition item, int currentDurability, int extraDurability)`	Like `ApplyEquippedFromNet`, for an item that copies were combined into: `extraDurability` is `GetExtraDurability` on the authority, and `currentDurability` is clamped to the item’s maximum with it.
`void ApplyUnequippedFromNet(VtEquipmentSlot slot)`	Net-replication entry point: mirror an authoritative unequip.
`static string SetSourceIdFor(VtItemSetDefinition set, int requiredPieces)`	Source id contract for set-tier rows: `"set_<setId>_<tier>pc"`. Public so consumer net-replication code can mirror or filter on it.
`static string SourceIdFor(VtEquipmentSlot slot)`	Source id for a given slot — convention is `"equipment_<slot>"`.
`static bool SlotsMatch(VtEquipmentSlot itemSlot, VtEquipmentSlot candidate)`	True if the candidate slot is acceptable for an item authored to a specific slot — exact match, or both members of the same family (Ring1/Ring2, Trinket1/Trinket2).

VtUnitEquipmentVisuals

Component. Add it with Add Component → Vantage → Items → VtUnitEquipmentVisuals.

Bridges VtUnitEquipment events to per-rig visual prefab spawn / despawn. Holds the slot → attach-point Transform mapping that describes where on the wearer’s model each equipped item should appear (right_hand bone for MainHand, head bone for Head, etc.).

Inspector fields

Field	Type	Default	Description
Attach Points (`attachPoints`)	VtUnitEquipmentVisuals.SlotAttachPoint[]	Empty	Slot → bone/transform map for this rig. Author one entry per slot the character should display equipped visuals for. Slots not in this list silently skip visual spawning — useful for rigs that don’t have a corresponding bone (a wolf has no Ring1 finger).

Scripting API

Member	Description
`void Initialize()`	Cache the sibling `VtUnitEquipment`, subscribe to its events, and re-spawn visuals for items already equipped. Idempotent — safe to call any number of times; call it right after adding the component from code.

VtWorldItem

Component. Add it with Add Component → Vantage → Items → VtWorldItem.

World-space representation of a pickable VtItemDefinition — the dropped sword on the ground, the loot bag the boss left behind, the chest of potions the player walks past. Implements IVtPickable so VtTopDownClickInput can route right-click → walk-to → auto-pickup uniformly with attackables.

Inspector fields

Field	Type	Default	Range	Description
Item (`item`)	VtItemDefinition	None		Item definition this world pickup represents. Pickup pushes it into the picker’s VtUnitInventory.
Count (`count`)	`int`	1	≥ 1	How many copies are added to the picker’s inventory on pickup. Stackable items merge into a single entry.
Wear (`wear`)	`int`	0	≥ 0	Wear the copies already took, such as a worn axe someone dropped. Picked-up copies keep it.
Extra Durability (`extraDurability`)	`int`	0	≥ 0	Durability added by copies combined into this one (items with Durability Mode Uses). 0 for a single copy.
Pickup Radius (`pickupRadius`)	`float`	1.5	≥ 0	Distance (world units) within which the picker can grab this item. The walk-to-pickup flow stops here.
Destroy On Pickup (`destroyOnPickup`)	`bool`	On		Destroy this GameObject after a successful pickup. Disable for chests / containers that should stay in the scene.

Scripting API

Member	Description
`VtUnit ReservedFor { get; }`	The killer whose party may pick this up while reserved, or null.
`float ReserveRemaining { get; }`	Seconds left on the reservation; 0 when anyone may pick it up.
`event Action<VtUnit> OnPickedUp`	Fired after a successful pickup, before the GameObject is destroyed (if `destroyOnPickup` is true). Subscribers can play VFX, broadcast quest progress, etc.
`event Action<VtUnit, int> OnPartlyPickedUp`	Fired when the picker’s inventory took only part of the stack. Args: (picker, how many it took). The rest stays on the ground in `count`.
`void Reserve(VtUnit owner, float seconds)`	Let only `owner` and its party pick this up for `seconds`. The loot dropper calls this for party kills.
`bool IsReservedAgainst(VtUnit picker)`	True when a reservation keeps `picker` from taking this now.
`void Tick(float deltaTime)`	Count the reservation down.

VtItemDefinition

Asset. Create it with Create → Vantage → Items → Item Definition.

Designer-authored item — equippable gear, consumable, or quest token. Items are pure data: the runtime VtUnitEquipment reads the slot, modifiers, attribute grants, and trait overrides from this asset and pushes them as a single source-bag row keyed "equipment_<slot>".

Inspector fields

Identity

Field	Type	Default	Description
Id (`id`)	`string`	Empty	Stable string identifier for DB / network payloads. Convention: lowercase dotted, e.g. ‘item.sword_of_strength’, ‘item.health_potion’. Unique across all VtItemDefinition assets.
Display Name (`displayName`)	`string`	Empty	UI display name shown to players. Falls back to asset name if empty.
Description (`description`)	`string`	Empty	Tooltip / lore description shown in-inventory and on hover.
Icon (`icon`)	`Sprite`	None	Icon shown in inventory grids and tooltips. Optional — consumer UI may fall back to a placeholder.
Icon Id (`iconId`)	`string`	Empty	Name of an icon from the package’s icon set (VtIcons), used when Icon is empty. Optional.
Equipped Visual Prefab (`equippedVisualPrefab`)	`GameObject`	None	Optional prefab spawned on the wearer’s model when this item is equipped (weapon mesh, helmet visual, glow VFX). Parented under the matching attach-point Transform on the wearer’s VtUnitEquipmentVisuals. Despawned automatically on unequip. Null = no visual (most items — potions, rings, tokens, anything that doesn’t need a 3D representation on the body).
World Item Prefab (`worldItemPrefab`)	`GameObject`	None	Prefab spawned when a unit drops this item from its bag. Must hold a VtWorldItem. Empty uses the Default World Item Prefab on VtTuning.
Rarity (`rarity`)	VtItemRarityDefinition	None	Rarity tier — drives UI tinting, sort order, and any consumer-side gating. Pick from the five shipped Rarities (Common / Uncommon / Rare / Epic / Legendary) or any custom VtItemRarityDefinition you’ve authored. Null = no rarity classification.
Tags (`tags`)	VtItemTagDefinition[]	Empty	Categorical labels for this item — drag in VtItemTagDefinition assets (Cursed.asset, Soulbound.asset, …). Consumers: loot filters, trade restrictions, dismantle UI, sort views. Query at runtime via item.HasTag(tagAsset). Host-game-specific — author your tag assets in Assets/Data/Items/Tags/.
Set (`set`)	VtItemSetDefinition	None	Optional item set this item belongs to. When the wearer has multiple members equipped, the set’s tier bonuses activate. Null = solo item.

Slot

Field	Type	Default	Range	Description
Slot (`slot`)	VtEquipmentSlot	`None`		Which slot the item occupies when equipped. None = inventory-only / non-equippable (potions, materials, quest items). Ring1 / Ring2 and Trinket1 / Trinket2 are families; the no-slot equip overload picks the first empty member.
Requires Two Hands (`requiresTwoHands`)	`bool`	Off		Two-handed weapon — when equipped to MainHand, the OffHand slot is auto-unequipped and any subsequent attempt to equip into OffHand is blocked until this 2H is removed. Only meaningful for slot == MainHand items.

Stacking (inventory)

Field	Type	Default	Range	Description
Is Stackable (`isStackable`)	`bool`	Off		Stackable items merge into a single inventory entry up to maxStackSize. Typical for consumables (potions, scrolls), materials, ammo. Equipment items are usually unique.
Max Stack Size (`maxStackSize`)	`int`	1	≥ 1	Maximum stack size. Ignored when isStackable is false. 0 / 1 effectively force individual entries.

Modifiers

Field	Type	Default	Description
Modifiers (`modifiers`)	VtItemModifier[]	Empty	Stat bonuses granted while equipped — same shape as VtBuffDefinition.modifiers. Pushed into VtUnitModifiers under source ‘equipment_’ on equip; removed on unequip.
Attribute Grants (`attributeGrants`)	VtAttributeGrant[]	Empty	Primary attribute grants (STR / DEX / INT / VIT / custom) granted while equipped. Pushed into VtUnitModifiers’ attribute channel under source ‘equipment_’.
Trait Overrides (`traitOverrides`)	VtTraitOverride[]	Empty	Categorical trait overrides granted while equipped — e.g. armor type Heavy at priority 100, movement type Flying. Pushed into VtUnitTraits under source ‘equipment_’.

Requirements

Field	Type	Default	Range	Description
Requirements (`requirements`)	VtItemRequirements	—		Gates checked at CanEquip / TryEquip time — minimum level, attribute minimums, required unit tag. An empty / default Requirements value means ‘no requirements’.

Value

Field	Type	Default	Range	Description
Value (`value`)	VtCurrencyAmount	—		Base price. A vendor sells the item at this times its buy multiplier and pays this times its sell multiplier. Leave the currency empty for an item no vendor trades.

Binding & Restrictions

Field	Type	Default	Description
Is Droppable (`isDroppable`)	`bool`	On	If false, the item cannot be removed from a VtUnitInventory through the drop / trade / sell paths (queried via CanDrop / CanTrade / CanSell). Use for quest items, soulbound rewards, hardcoded loadout items. Does NOT block TryRemoveItem (the primitive) or TryUseItem’s consume — the library doesn’t know which removals are ‘drops’ vs ‘consumes’; only your drop / trade / sell UI does.
Is Tradeable (`isTradeable`)	`bool`	On	If false, consumer trade UI should refuse to include this item in a trade window. Surfaces as VtUnitInventory.CanTrade. Common pattern: bind-on-pickup MMO loot.
Is Sellable (`isSellable`)	`bool`	On	If false, consumer vendor UI should refuse to sell this item. Surfaces as VtUnitInventory.CanSell. Common pattern: quest items, set-piece relics.

Consumable / Active Use

Field	Type	Default	Range	Description
Use Ability (`useAbility`)	VtAbilityDefinition	None		Optional ability fired when the item is ‘used’ from the inventory (potions, scrolls, throwables, charges). Routes through VtUnitAbilities.TryCast so the cast respects cooldowns / GCD / resource cost / interrupts. Self-targeted potions use VtTargetingMode.Self; throwables can use SingleTarget or GroundPoint. Null = item has no active-use behavior (pure stat gear, materials, quest tokens).
Consume On Use (`consumeOnUse`)	`bool`	On		If true, a successful UseItem call decrements the inventory stack by 1 (charge consumed). Set to false for reusable items like a ‘Bandage Kit’ that re-charges over time, or a magic scroll that’s destroyed only when its inner cooldown expires.

Durability

Field	Type	Default	Range	Description
Max Durability (`maxDurability`)	`int`	0	≥ 0	Maximum durability of one copy. 0 = indestructible (the item ignores ApplyWear calls). Wear is tracked per copy: on the worn slot while worn, on the bag entry while carried, and on the world item while on the ground.
Durability Mode (`durabilityMode`)	VtDurabilityMode	`Condition`		Condition: durability is the item’s state, capped at Max Durability and restored by repair. Uses: Max Durability is what one copy gives; moving a copy onto another copy of the same item combines them into one with the uses of both, without a limit, and repair does nothing. Uses only combines items that do not stack.
Auto Unequip On Break (`autoUnequipOnBreak`)	`bool`	On		If true, the item is auto-unequipped when its durability hits 0. If false, the item stays in the slot but its modifiers / grants / overrides remain active — the consumer is then responsible for whatever ‘broken item’ policy the game wants (greyed icon, stat penalty, etc.). Has no effect when maxDurability is 0.

Scripting API

Member	Description
`bool CombinesDurability { get; }`	True when copies of this item combine their durability: it wears out, its `durabilityMode` is `VtDurabilityMode.Uses` and it does not stack.
`bool HasTag(VtItemTagDefinition tag)`	True if this item references the given tag asset.

VtItemRarityDefinition

Asset. Create it with Create → Vantage → Items → Item Rarity Definition.

Designer-authored rarity tier for items — Common, Uncommon, Rare, Epic, Legendary, plus any custom tiers a host game adds (Mythic, Artifact, Set, Heirloom, Soulbound, …). Each item references one rarity asset via VtItemDefinition.rarity; the rarity drives UI tinting, tooltip styling, sort order in inventories, loot-table weighting, and any consumer-side logic that wants to gate features on tier.

Inspector fields

Field	Type	Default	Description
Id (`id`)	`string`	Empty	Stable string identifier for DB / network payloads. Convention: ‘rarity.common’, ‘rarity.legendary’.
Display Name (`displayName`)	`string`	Empty	UI display name. E.g. ‘Common’, ‘Legendary’, ‘Mythic’.
Description (`description`)	`string`	Empty	Tooltip / lore description. E.g. ‘Crafted by master smiths. Uniquely named.’
Sort Weight (`sortWeight`)	`int`	0	Lower weights sort first in lists / loot tables. Convention: Common 0, Uncommon 100, Rare 200, Epic 300, Legendary 400. Leave gaps for inserts.
Color (`color`)	`Color`	`#FFFFFFFF`	Tooltip / inventory text tint for items of this rarity. The shipped rarities use the familiar gray / green / blue / purple / orange palette; change it freely.
Icon Background (`iconBackground`)	`Sprite`	None	Optional sprite shown behind the item icon (rarity frame / glow). Null for no background — the consumer’s tooltip UI then renders just the tint.

VtItemTagDefinition

Asset. Create it with Create → Vantage → Items → Item Tag Definition.

Designer-authored categorical label for an item — e.g. Cursed.asset, Soulbound.asset, Quest.asset, VendorTrash.asset, Crafted.asset. Attach to a VtItemDefinition.tags array to declare what an item is; consumers (loot filters, dismantle UI, trade restrictions, sort views) query via item.HasTag(tag).

Inspector fields

Field	Type	Default	Description
Id (`id`)	`string`	Empty	Stable string identifier for DB / network payloads. Convention: ‘tag.cursed’, ‘tag.soulbound’.
Display Name (`displayName`)	`string`	Empty	UI display name. E.g. ‘Cursed’, ‘Soulbound’, ‘Quest Item’.
Description (`description`)	`string`	Empty	Lore / tooltip description. E.g. ‘Cannot be removed once equipped without a Remove Curse spell.’

VtItemSetDefinition

Asset. Create it with Create → Vantage → Items → Item Set Definition.

Designer-authored item set — a collection of items that grants additional bonuses when several members are equipped together. The classic “Warlord’s Arsenal: 2 pieces grant +5 Strength; 4 pieces grant +50 Max HP; 6 pieces grant +20% damage” pattern from MMO / ARPG itemization.

Inspector fields

Field	Type	Default	Description
Id (`id`)	`string`	Empty	Stable string identifier — the DB / network payload key. Convention: ‘set.warlords_arsenal’.
Display Name (`displayName`)	`string`	Empty	UI display name shown on member tooltips and the set-bonus panel.
Description (`description`)	`string`	Empty	Lore / tooltip description shown in the set-bonus panel.
Members (`members`)	VtItemDefinition[]	Empty	Member items — the items whose ‘set’ field references this definition. Used by the editor for validation + tooltip rendering and as a forward index. Runtime counts pieces by walking equipped items, so this list does NOT need to be authoritative for correctness; keeping it in sync is a UX nicety.
Tiers (`tiers`)	VtItemSetTier[]	Empty	Bonus tiers, sorted ascending by requiredPieces. Each tier independently activates when the wearer has at least requiredPieces members equipped; satisfied tiers stack additively (cumulative model).

VtItemRequirements

Serializable struct.

Author-facing gate-bag for an item: level minimum, attribute minimums, optional unit-tag requirement. Inspected by VtUnitEquipment.CanEquip before the equip mutation runs.

Inspector fields

Field	Type	Default	Range	Description
Level Min (`levelMin`)	`int`	0	≥ 0	Minimum unit level required to equip. 0 = no level gate.
Attribute Mins (`attributeMins`)	VtAttributeMinimum[]	Empty		Attribute minimums (each entry is a (VtAttributeDefinition, minPoints) pair). Resolved against the wearer’s current post-modifier attribute totals. Empty = no attribute gate.
Required Unit Tag (`requiredUnitTag`)	VtUnitTagDefinition	None		Optional unit-tag gate — the wearer must have this tag to equip. Null = no tag gate. Use cases: ‘Paladin-only’ weapon (tag.paladin), ‘Undead-only’ relic (tag.undead).

VtItemSetTier

Serializable struct.

One tier of a VtItemSetDefinition’s scaling bonuses — e.g. the 2-piece, 4-piece, or 6-piece bonus. Each tier is satisfied independently when the wearer has at least requiredPieces set members equipped; satisfied tiers stack additively (cumulative model — the 4pc bonus is layered on top of the 2pc bonus, not a replacement).

Inspector fields

Field	Type	Default	Range	Description
Required Pieces (`requiredPieces`)	`int`	0	≥ 1	Number of equipped set members required to activate this tier. Convention: 2, 4, 6 — but any positive integer is valid. Author tiers in ascending order; the recompute walks them in array order and accepts every tier whose threshold is satisfied.
Tooltip Name (`tooltipName`)	`string`	Empty		UI label shown in the wearer’s set-bonus panel for this tier. E.g. ‘(2) Set: +5 Strength’. Cosmetic only — the runtime doesn’t read this.
Modifiers (`modifiers`)	VtItemModifier[]	Empty		Stat modifiers granted while this tier is active. Same shape as item modifiers.
Attribute Grants (`attributeGrants`)	VtAttributeGrant[]	Empty		Primary attribute grants (STR / DEX / INT / VIT / custom) granted while this tier is active.
Trait Overrides (`traitOverrides`)	VtTraitOverride[]	Empty		Categorical trait overrides granted while this tier is active.

IVtPickable

Interface. Implemented by VtCraftingStation, VtQuestGiver, VtVendor, VtWorldItem.

Bridge between the input layer and any world-space “thing the player can walk up to and pick up.” The shipped VtWorldItem implements this for dropped item assets; consumers can implement it on quest-pickup orbs, gold piles, lever-pull interactables, gathered resources, etc., and the VtTopDownClickInput right-click flow handles the move-to-then-act chain uniformly.

Scripting API

Member	Description
`Transform Transform { get; }`	The pickable’s world-space anchor — the input layer uses this as the move-to target.
`float PickupRadius { get; }`	Distance (in world units) within which `TryPickUp` can succeed. The picker walks here, then the input layer fires the pickup when its position is inside this radius.
`bool CanBePickedUp { get; }`	Per-pickable gating — false on locked / requires-key / consumed pickables makes the input layer skip them silently.
`void TryPickUp(VtUnit picker)`	Run the actual pickup mutation. Implementations should authority- gate via `VtAuthority.IsAuthoritative` if state changes are involved (item moved into a bag, gold added to wallet, quest flag flipped).

VtUnitEquipmentVisuals.SlotAttachPoint

Serializable struct.

One row in the slot → attach-point map. Authored on the player prefab inspector; one entry per slot the rig supports. Slots without an entry silently skip visual spawning (e.g. ring slots on a character without finger bones).

Inspector fields

Field	Type	Default	Description
Slot (`slot`)	VtEquipmentSlot	`None`	Equipment slot this attach-point serves. Pick the slot the prefab should appear in.
Attach Point (`attachPoint`)	`Transform`	None	Transform under which the visual prefab is parented. Typically a bone on the rig (right_hand_socket, head_socket). Required — entries with null transforms are skipped at spawn time.

VtAttributeMinimum

Serializable struct.

One “attribute ≥ N” gate used in VtItemRequirements. Authors a requirement like “needs 12 Strength to equip” by referencing a VtAttributeDefinition asset and a minimum point total.

Inspector fields

Field	Type	Default	Range	Description
Attribute (`attribute`)	VtAttributeDefinition	None		Which primary attribute the wearer must possess at least minPoints of. Pick from the dropdown of every VtAttributeDefinition asset in the project.
Min Points (`minPoints`)	`int`	0	≥ 0	Minimum point total required (resolved post-modifier total — base + items + buffs).

Enums

VtTwoHandRule

What VtUnitEquipment does with the off-hand item when a two-handed item goes into the main hand. Serialized as int; append only.

Value	Description
`OffHandComesOff`	The off-hand item comes off into the bag. Putting an item in the off hand is refused while a two-hander is held.
`OffHandSuspended`	The off-hand item stays worn but gives nothing while the two-hander is held, and counts again when it leaves. A torch or shield comes back when you switch away from a bow.
`OffHandBlocksTwoHander`	A two-handed item cannot go on while an off-hand item is worn; take the off-hand item off first.

VtEquipmentSlot

The set of equipment slots an item can occupy on a unit. Used as the key for the slot map on VtUnitEquipment and as the source-id suffix when equipped items push their modifiers / attributes / traits ("equipment_<slot>").

Value	Description
`None`	Inventory-only / non-equippable. Potions, materials, quest items.
`Head`	Helm / hat / hood.
`Chest`	Chestpiece / robe / breastplate.
`Legs`	Leg armor / pants / greaves.
`Feet`	Boots / sandals / sabatons.
`Hands`	Gloves / gauntlets / bracers.
`MainHand`	Primary weapon. 2H weapons occupy this slot and block `OffHand`.
`OffHand`	Off-hand weapon, shield, or focus. Auto-unequipped when a 2H is equipped to `MainHand`.
`Neck`	Necklace / amulet / pendant.
`Ring1`	First ring slot. Members of the Ring family.
`Ring2`	Second ring slot. Members of the Ring family.
`Trinket1`	First trinket slot. Members of the Trinket family.
`Trinket2`	Second trinket slot. Members of the Trinket family.
`Back`	Worn on the back: backpack, cloak, quiver.

VtEquipFailureReason

Why an attempted VtUnitEquipment.TryEquip / VtUnitEquipment.CanEquip call refused the operation. Returned via the out parameter so callers (UI tooltips, AI, item-pickup handlers) can surface a precise reason without guesswork.

Value	Description
`None`	The operation succeeded — the request would equip cleanly.
`NullItem`	The supplied item was null.
`SlotMismatch`	The slot the caller asked for doesn’t match the item’s authored slot (and isn’t in the same family for ring / trinket items).
`LevelTooLow`	The wearer’s level is below the item’s `VtItemRequirements.levelMin`.
`AttributeTooLow`	The wearer’s resolved attribute totals don’t satisfy one of `VtItemRequirements.attributeMins`.
`MissingRequiredTag`	The wearer doesn’t have `VtItemRequirements.requiredUnitTag`.
`SlotOccupiedBlocked`	A slot conflict that cannot be auto-resolved — typically equipping into `VtEquipmentSlot.OffHand` while a two-handed weapon occupies `VtEquipmentSlot.MainHand`. Caller must unequip the conflicting slot first.
`AuthorityNotLocal`	The caller is not the authoritative owner of this unit. In multiplayer modes `VtUnitEquipment.TryEquip` rejects on replicas; the authoritative side mutates and the net layer mirrors via `VtUnitEquipment.ApplyEquippedFromNet`.
`NotInInventory`	`VtUnitEquipment.TryEquipFromInventory` was asked for an item the unit’s bag does not hold.
`InventoryFull`	The unit’s bag has no room for the item taken off.
`WouldOverflowInventory`	The item adds to the bag’s capacity, and without it the bag could no longer hold what it holds. Empty the bag first.
`TargetSlotRefused`	The bag slot named to take the item holds something that cannot be worn there, is shut, or its rules refuse the item.
`HeldSlotFull`	A `VtUnitHeldSlot` holds the main hand and its area has no free slot for the item.

VtDurabilityMode

How an item’s durability behaves, set on VtItemDefinition.durabilityMode. Only matters for items with a VtItemDefinition.maxDurability above 0. Serialized as int; append only.

Value	Description
`Condition`	Durability is the item’s condition: it wears down to 0, never goes above `VtItemDefinition.maxDurability`, and repair restores it. Copies never combine.
`Uses`	Durability is a number of uses: `VtItemDefinition.maxDurability` is what one copy gives. Moving a copy onto another copy of the same item combines them into one with the uses of both, without a limit. Repair does nothing. Only items that do not stack combine.