Units and stats reference

The components every unit carries, the assets that define units, stats, attributes and buffs, and the damage and lookup API. For how to use it, see Units and stats.

VtUnit

Component. Add it with Add Component → Vantage → Units → VtUnit. Adds VtUnitModifiers, VtUnitStats, VtUnitTraits, VtUnitBuffs, VtCombatEngagement, VtUnitAbilities, VtCombatTextAutoSubscriber, VtUnitEquipment automatically.

Composition root for a gameplay entity (player, enemy, NPC). Owns identity (name / description / targeting priority / faction / tags), the VtUnitId used by the rest of the system, and the IVtAttackable bridge that plugs into the project’s interaction system.

Inspector fields

Definition

Field	Type	Default	Description
Definition (`definition`)	VtUnitDefinition	None	Baseline stats / identity / traits for this unit. Required.

Scripting API

Member	Description
`VtUnitId Id { get; }`	Stable id valid for the lifetime of this `VtUnit`. Use in `VtDamageInfo.attacker`, logs, and cross-system references.
`string Name { get; }`	Presentational name — pulled from the definition, falling back to the GameObject name.
`string Description { get; }`	Flavor / tooltip description from the definition.
`int TargetingPriority { get; }`	Priority used by enemy AI target selection. Base value from the definition plus any TargetingPriority modifier (taunt / stealth).
`VtFaction VtFaction { get; }`	VtFaction / team of this unit.
`bool HasFactionOverride { get; }`	True while `SetFactionOverride` replaces the definition’s faction.
`VtUnitDefinition Definition { get; }`	Source definition (read-only).
`int Level { get; }`	Current level — the single source of truth for every level gate in the library (item requirements, attribute growth, recipe / quest / buildable prerequisites). Reads the opt-in `VtUnitLevel` sibling when one is attached; otherwise the definition’s `startingLevel` (a level-20 mini-boss that never gains XP still is level 20); otherwise 1.
`IReadOnlyCollection<VtUnitTagDefinition> Tags { get; }`	Live set of tags. Read-only view — mutate via `AddTag` / `RemoveTag`.
`bool IsInvulnerable { get; }`	True when the unit is currently invulnerable to all damage and untargetable. Set by `VtRoaming` during the leash-return (mob runs back home untouchable) and any other consumer flow that needs a temporary “no damage at all” state — cinematics, stealth-vanish, teleport-in invulnerability, post-respawn safety windows.
`event Action<int, int> OnLeveledUp`	Forwarded from the sibling `VtUnitLevel.OnLeveledUp`. Args: (oldLevel, newLevel). Subscribe here rather than on the level component so the subscription survives the sibling being attached after your `OnEnable` ran — `SeedFromDefinition` attaches it late. Never fires for units without a level component.
`static event Action<VtUnit> OnAnyUnitSeeded`	Fires on every instance after a unit was seeded from its definition, on enable and on `SetDefinition`. World-level systems use it to apply their state to units that appear later, such as the active day phase’s modifiers. Subscribers must unsubscribe when they are disabled.
`void SetFactionOverride(VtFaction faction)`	Replace the definition’s faction on this instance, for summons that fight for their owner or charmed units. Not authority-gated: set it on every copy, which replication does.
`void ClearFactionOverride()`	Return to the definition’s faction.
`void RebindLevel()`	Re-discover the sibling `VtUnitLevel` and refresh the `OnLeveledUp` forwarding subscription. Idempotent. Called from `OnEnable`, `SeedFromDefinition`, and from `VtUnitLevel.Initialize` when the component is added after this unit already cached its absence (same late-attach contract as `VtCombatEngagement.RebindThreatTable`).
`bool HasTag(VtUnitTagDefinition tag)`	True if the unit currently has this tag. Compares by asset reference (Unity GUID).
`bool IsImmuneTo(VtCcCategory category)`	True if the unit is immune to the given crowd-control category. Read by `VtApplyBuffEffect` and the taunt effects to refuse application before any state mutates. Source: `VtUnitDefinition.ccImmunities`. Returns false for `VtCcCategory.None` (a non-CC buff is never “immune to nothing”).
`bool IsImmuneTo(VtDamageType type)`	True if the unit is immune to the given damage type. Read by `VtUnitStats.TakeDamage` for an early-exit + Immune combat-text fire. Source: `VtUnitDefinition.damageImmunities`.
`void SetInvulnerable(bool value)`	Toggle the unit’s invulnerability flag. Authority-gated. The damage pipeline (`VtUnitStats.TakeDamage`) and target-selection (`IVtAttackable.CanBeAttacked`) both honor this.
`void AddTag(VtUnitTagDefinition tag)`	Add a tag at runtime (e.g. buff-granted “Cursed” flag). No-op if already present or null.
`void RemoveTag(VtUnitTagDefinition tag)`	Remove a tag at runtime. No-op if missing or null.
`void SetDefinition(VtUnitDefinition def)`	Late-binding entry point for code that spawns a unit with a specific definition (waves, quests). Also triggers a re-seed if called at runtime.
`int TakeDamage(VtDamageInfo info)`	Typed overload — callers that have built a `VtDamageInfo` (weapons with crit/attack-type data, projectiles) should prefer this.

VtUnitDefinition

Asset. Create it with Create → Vantage → Units → Unit Definition.

Designer-authored baseline for a unit’s identity, resources, combat values, and innate modifiers / traits. Used by players, enemies, and NPCs alike — the VtUnit component reads this at enable time and seeds the live VtUnitStats / VtUnitModifiers / VtUnitTraits.

Inspector fields

Identity

Field	Type	Default	Description
Id (`id`)	`string`	Empty	Stable string identifier — the DB / network payload key for this unit archetype. Convention: lowercase dotted, e.g. ‘unit.skeleton_warrior’, ‘unit.player’, ‘unit.boss_lich_king’. Unique across all VtUnitDefinition assets in the project. Saves and network messages refer to units by this id, so changing it breaks existing saves.
Display Name (`displayName`)	`string`	Empty	UI display name shown to players. Falls back to GameObject.name if empty.
Description (`description`)	`string`	Empty	Tooltip / bestiary description.
Portrait (`portrait`)	`Sprite`	None	Portrait shown on a unit frame. Empty: the frame renders the unit’s model through a portrait studio when the scene has one, or shows its initials.
Icon Id (`iconId`)	`string`	Empty	A small icon from the Vantage icon set by name, such as skull or shield, shown next to the level on a unit frame to mark what kind of unit it is.
Faction (`faction`)	VtFaction	`Neutral`	Team / allegiance — drives targeting filters and friendly-fire checks.
Targeting Priority (`targetingPriority`)	`int`	50	Base priority used by enemy AI target selection. Heroes ≈ 100, workers ≈ 20, basic units ≈ 50.
Tags (`tags`)	VtUnitTagDefinition[]	Empty	Categorical labels for this unit — drag in VtUnitTagDefinition assets (Undead.asset, Beast.asset, Humanoid.asset, …). Consumers: quest objectives (‘kill 10 Undead’), vs-type items, targeting filters, bestiary UI. Query at runtime via VtUnit.HasTag(tagAsset). Host-game-specific — author your tag assets in Assets/Data/Units/Tags/.

Resources (HP / MP / Stamina / …)

Field	Type	Default	Range	Description
Pools (`pools`)	VtResourcePoolConfig[]	Empty		Which resource pools this unit has. Most units: HP only. Players: HP + Stamina. RPG classes add MP / Rage / Energy / etc.

Progression

Field	Type	Default	Range	Description
Starting Level (`startingLevel`)	`int`	1	≥ 1	Level the unit spawns at. Players usually start at 1; a lvl-20 mini-boss in a mid-game dungeon can be authored at 20 directly without granting XP. Drives XP rewards on death, level-scaled formulas, and any ‘kill 10 lvl-5+ beasts’-style quest filters.

Primary Attributes (optional — for VtAttributeDerivedStatsBinding)

Field	Type	Default	Range	Description
Base Attributes (`baseAttributes`)	VtAttributeGrant[]	Empty		Baseline values of primary attributes at level 1 (drag in VtAttributeDefinition assets plus a starting value). Used only if VtAttributeDerivedStatsBinding is attached. Items / buffs / level-up grants stack on top via the normal modifier channel.
Attribute Growth Per Level (`attributeGrowthPerLevel`)	VtAttributeGrowth[]	Empty		Per-level attribute gain — ‘+2.5 STR per level’. Each entry adds (currentLevel - 1) * perLevel to the attribute total on top of baseAttributes. Requires VtAttributeDerivedStatsBinding; applied at spawn (honoring startingLevel) and on every level-up.

Basic Attack

Field	Type	Default	Range	Description
Min Damage (`minDamage`)	`int`	1	≥ 0	Minimum damage of the unit’s basic attack (before weapon / modifier scaling).
Max Damage (`maxDamage`)	`int`	2	≥ 0	Maximum damage of the unit’s basic attack.
Damage Type (`damageType`)	VtDamageType	`Physical`		Element of the basic attack — routes through resistance channel.
Attack Type (`attackType`)	VtAttackType	`Normal`		Matrix axis — keyed into VtDamageMatrix against the defender’s armor type. Default flat matrix means this is just a tag; consumers extend VtAttackType + author matrix cells to give it gameplay impact.
Damage Channel (`damageChannel`)	VtDamageChannel	`Melee`		RPG class channel — Melee / Ranged / Magic. Drives power-stat scaling (Magic → spellPower, else physicalPower) and gear / proc filtering. Distinct from attackType: a melee unit typically sets channel = Melee here.
Attack Range (`attackRange`)	`float`	2	≥ 0	Base attack range in world units. Read by the shared basic-attack ability when its ‘sourceRangeFromUnitAttackRange’ flag is on. Lets one ability asset serve many mobs that each have their own reach.
Attack Interval (`attackInterval`)	`float`	1	≥ 0.05	Base seconds between basic attacks. Read by the shared basic-attack ability when its ‘sourceCooldownFromUnitAttackInterval’ flag is on. Stacks multiplicatively with stat.attack_speed via the ability’s ‘scalesWithAttackSpeed’ flag.
Splash (`splash`)	VtSplashSpec	—		Optional: AoE splash around each hit. radius = 0 means single-target.
Projectile (`projectile`)	VtProjectileSpec	—		Optional: travelling projectile config (prefab + speed + arc). Leave prefab empty for melee or hitscan ranged attacks.

Presentation

Field	Type	Default	Description
Emit Combat Text (`emitCombatText`)	`bool`	On	If true, floating damage / heal / dodge text spawns over this unit’s head whenever the damage pipeline fires. Flip off for trash mobs, totems, or chatter-heavy swarms where the numbers would clutter the screen.
Hit Cue (`hitCue`)	VtPresentationCue	—	Animator trigger, sound and effect played when this unit takes damage.
Death Cue (`deathCue`)	VtPresentationCue	—	Played when this unit dies.
Revive Cue (`reviveCue`)	VtPresentationCue	—	Played when this unit is revived.

Movement & AI

Field	Type	Default	Range	Description
Move Speed (`moveSpeed`)	`float`	3	≥ 0	Base locomotion speed in world units / sec. This is how fast the unit walks/runs around the world — NOT missile or animation speed.
Aggro Range (`aggroRange`)	`float`	8	≥ 0	Notice radius in world units. With Use Hostile AI on, the unit attacks hostile units that come inside it; call-for-help also reaches faction-mates within it. Each unit has its own radius. 0 = never engage on sight. Typical melee mob 6-10, ranged mob 14-20, passive unit 0.
Use Hostile Ai (`useHostileAi`)	`bool`	Off		Attack hostile units that come inside Aggro Range, and fight back when something targets this unit through threat or a taunt. Attaches VtHostileAi. Leave off for players, NPCs and passive units.
Takes Orders (`takesOrders`)	`bool`	Off		Players can command this unit with group orders from VtOrderInput: move, attack, attack-move, hold position and stop. While idle it attacks hostile units inside Aggro Range. Attaches VtUnitOrders. Leave Use Hostile AI off.
Ability Rotation (`abilityRotation`)	VtRotationEntry[]	Empty		Abilities this unit casts on its own, highest priority first, each with a target rule, a health window and an interval. Non-empty = VtUnit.SeedFromDefinition attaches VtAbilityRotation. Use it for monsters and bosses.
Vision Radius (`visionRadius`)	`float`	0	≥ 0	How far this unit reveals the fog of war, in world units. 0 = reveals nothing. Attaches VtVisionSource.

Selection

Field	Type	Default	Range	Description
Selectable (`selectable`)	`bool`	On		Players can select this unit with a click or a box. Turn off for props and scenery.
Selection Radius (`selectionRadius`)	`float`	0	≥ 0	Radius of the selection marker in world units. 0 = from the unit character controller or collider.

Defense

Field	Type	Default	Range	Description
Armor Type (`armorType`)	VtArmorType	`Unarmored`		Defender category — keyed into VtDamageMatrix vs the attacker’s VtAttackType. Overridable by equipped armor items at higher priority.

Abilities

Field	Type	Default	Range	Description
Basic Attack (`basicAttack`)	VtAbilityDefinition	None		The ability used for this unit’s basic attack — granted at spawn and installed in VtUnitAbilities’ auto-fire slot when the unit acquires a target. Most units share a single ‘Basic Attack’ SO whose damage effect sources numbers from minDamage/maxDamage/damageType/attackType/projectile on this definition (see VtUnitBasicAttackDamageEffect). Leave null for non-combatants.
Granted Abilities (`grantedAbilities`)	VtAbilityDefinition[]	Empty		Additional abilities granted to this unit at spawn — active spells, cooldown abilities, passives-as-abilities. Players typically add class abilities here; enemies add boss mechanics. Order does not matter. Null / empty = only the basic attack.

Starting Equipment

Field	Type	Default	Range	Description
Starting Equipment (`startingEquipment`)	VtItemDefinition[]	Empty		Items auto-equipped when this unit spawns. Each entry is fed to VtUnitEquipment.TryEquip in order — so a 2H weapon ahead of an off-hand shield will block the shield. Useful for sample / NPC authoring; players can also set up loadouts here for the level-1 starting kit.

Starting Inventory

Field	Type	Default	Range	Description
Starting Inventory (`startingInventory`)	VtStartingInventoryEntry[]	Empty		Items added to this unit’s VtUnitInventory at spawn (item + count). Only applied if the unit has a VtUnitInventory component (the inventory module is opt-in — not part of VtUnit’s RequireComponent chain). Stackable items merge into a single entry up to maxStackSize; non-stackable items each get their own entry per copy.

Passive Auras

Field	Type	Default	Range	Description
Passive Auras (`passiveAuras`)	VtAuraDefinition[]	Empty		Auras the unit emits as long as it’s alive. VtUnit.SeedFromDefinition attaches one VtAuraEmitter per entry at spawn. Mutually-exclusive auras in the list resolve at attach time — only the last attached one stays enabled.

Threat / Aggro

Field	Type	Default	Range	Description
Use Threat Table (`useThreatTable`)	`bool`	Off		Opt-in: when true, VtUnit.SeedFromDefinition attaches a VtThreatTable + VtThreatAutoSubscriber, and VtCombatEngagement automatically follows the top-threat attacker (MMO-style tank/healer/DPS dynamics). Enable on mobs and bosses; leave off on players (who don’t benefit from a threat ledger). Off: the unit fights the nearest enemy.

Loot

Field	Type	Default	Range	Description
Loot Table (`lootTable`)	VtLootTableDefinition	None		Loot table rolled when this unit dies. Null = no drops (most NPCs — citizens, dummy targets, players). Authoring path: drag a VtLootTableDefinition asset; VtUnit.SeedFromDefinition auto-attaches a VtLootDropper that subscribes to OnDied and spawns VtWorldItems at the corpse on death. Authority-gated.

Roaming / Leash

Field	Type	Default	Range	Description
Roam Radius (`roamRadius`)	`float`	0	≥ 0	Radius around the unit’s spawn position the roaming AI wanders within. 0 = no roaming (most NPCs, players). > 0 = VtUnit.SeedFromDefinition auto-attaches a VtRoaming component that picks random destinations within this radius and walks between them with idle pauses.
Leash Radius (`leashRadius`)	`float`	25	≥ 0	Distance from the spawn position past which the unit gives up chase, drops aggro, and runs back invulnerably (the MMO leash pattern). Should be larger than roamRadius and aggroRange. 0 = no leash break (combat continues regardless of distance — useful for raid bosses with scripted reset triggers instead).
Roam Idle Min Seconds (`roamIdleMinSeconds`)	`float`	2	≥ 0	Lower bound of the roaming idle-pause duration in seconds. The unit waits in place for a random time in [roamIdleMinSeconds, roamIdleMaxSeconds] between walks.
Roam Idle Max Seconds (`roamIdleMaxSeconds`)	`float`	5	≥ 0	Upper bound of the roaming idle-pause duration in seconds.
Roam Speed Multiplier (`roamSpeedMultiplier`)	`float`	0.5	≥ 0.1	Multiplier applied to moveSpeed while roaming (idle wandering). 0.5 = stroll at half combat speed — typical mob feel.
Return Speed Multiplier (`returnSpeedMultiplier`)	`float`	2.5	≥ 0.1	Multiplier applied to moveSpeed while running back to home (leash return). 2.5 = sprint at 2.5x normal speed. Visible signal to the player that the mob is leashing rather than just moving.

Building

Field	Type	Default	Range	Description
Use Builder (`useBuilder`)	`bool`	Off		Opt-in: when true, VtUnit.SeedFromDefinition attaches a VtUnitBuilder component that drives the build / placement loop (ghost preview follows cursor, snap, validate, consume items + currency, spawn prefab). Enable on player units. Default false.

Resource Node

Field	Type	Default	Range	Description
Resource Node (`resourceNode`)	VtResourceNodeDefinition	None		Optional. When set, VtUnit.SeedFromDefinition attaches a VtResourceNode component on this unit, turning it into a tree / ore vein / fishing spot. The referenced VtResourceNodeDefinition drives per-hit yield, tool / skill / damage-type gating, respawn cadence, and visual swap. Null = not a node.

Crafting

Field	Type	Default	Description
Use Recipe Book (`useRecipeBook`)	`bool`	Off	Opt-in: when true, VtUnit.SeedFromDefinition attaches a VtUnitRecipeBook component that tracks explicitly-learned recipes (the rare ones with learnedByDefault = false). Enable on player units. Default false.
Use Crafting Skills (`useCraftingSkills`)	`bool`	Off	Opt-in: when true, VtUnit.SeedFromDefinition attaches a VtUnitCraftingSkills component that tracks per-skill levels and XP (Smithing, Alchemy, etc.). Enable on player units. Default false.
Use Crafter (`useCrafter`)	`bool`	Off	Opt-in: when true, VtUnit.SeedFromDefinition attaches a VtUnitCrafter component that validates / consumes / produces / grants XP for crafting. Enable on player units. Default false.
Use Crafting Station (`useCraftingStation`)	`bool`	Off	Opt-in: when true, VtUnit.SeedFromDefinition attaches a VtCraftingStation component, making this unit right-clickable as an anvil / alchemy table / etc. Pair with stationType. Enable on station NPCs. Default false.
Station Type (`stationType`)	VtRecipeStationDefinition	None	Station type this unit serves (when useCraftingStation is true). Recipes that require this type can be crafted while interacting with this NPC.

Quests

Field	Type	Default	Description
Use Quest Log (`useQuestLog`)	`bool`	Off	Opt-in: when true, VtUnit.SeedFromDefinition attaches a VtUnitQuestLog component that tracks accepted quests, fans out kill/inventory/talk/location events to objectives, and grants rewards on turn-in. Enable on player units. Default false.
Use Quest Giver (`useQuestGiver`)	`bool`	Off	Opt-in: when true, VtUnit.SeedFromDefinition attaches a VtQuestGiver component, making this NPC right-clickable to surface its offered quests AND firing the talk event for talk-to objectives. Enable on quest-giver NPCs and pure talk-target NPCs. Default false.
Offered Quests (`offeredQuests`)	VtQuestDefinition[]	Empty	Quests this NPC offers (when useQuestGiver is true). Empty leaves the giver as a pure talk-target — still fires the talk event for talk-to objectives, just doesn’t surface any quest offers.

Dialogue

Field	Type	Default	Description
Use Dialogue (`useDialogue`)	`bool`	Off	Opt-in: when true, VtUnit.SeedFromDefinition attaches a VtUnitDialogue component that runs conversations with NPCs and remembers dialogue flags. Enable on player units.
Dialogue (`dialogue`)	VtDialogueDefinition	None	Conversation this NPC runs when the player interacts with it (needs Use Quest Giver). Empty = the greeting below is shown with the offered quests as answers.
Greeting (`greeting`)	`string`	Empty	Line shown when this NPC has no dialogue asset. Empty with no quests to offer = no conversation opens.

Vendor

Field	Type	Default	Range	Description
Use Vendor (`useVendor`)	`bool`	Off		Opt-in: when true, VtUnit.SeedFromDefinition attaches a VtVendor component with the vendor definition below, making this NPC right-clickable to open a shop.
Vendor (`vendor`)	VtVendorDefinition	None		What this NPC sells and how it prices (when useVendor is true).

Respawn

Field	Type	Default	Range	Description
Respawn Rules (`respawnRules`)	VtRespawnRules	None		Delay, place, health and penalties after death. Non-null = VtUnit.SeedFromDefinition attaches a VtUnitRespawn component. Set on player units; monsters use spawners.

Progression

Field	Type	Default	Range	Description
Talent Tree (`talentTree`)	VtTalentTreeDefinition	None		Talent tree (class) this unit progresses through. Non-null = VtUnit.SeedFromDefinition attaches a VtUnitProgression component that earns talent and attribute points from the level.

Party

Field	Type	Default	Range	Description
Use Party (`useParty`)	`bool`	Off		Opt-in: when true, VtUnit.SeedFromDefinition attaches a VtUnitParty component so the unit can invite, join and share kill credit. Enable on player units.

Chat

Field	Type	Default	Range	Description
Use Chat (`useChat`)	`bool`	Off		Opt-in: when true, VtUnit.SeedFromDefinition attaches a VtUnitChat component so the unit can send and receive chat. Enable on player units; add a VtPlayerIdentity for whispers and stable names.

Guild

Field	Type	Default	Range	Description
Use Guild (`useGuild`)	`bool`	Off		Opt-in: when true, VtUnit.SeedFromDefinition attaches a VtUnitGuild component so the player can found, join and run guilds. Needs a VtPlayerIdentity on the same object.
Guild Creation Cost (`guildCreationCost`)	VtCurrencyAmount	—		Paid from the player’s wallet to found a guild. Empty currency = free.

Friends

Field	Type	Default	Range	Description
Use Friends (`useFriends`)	`bool`	Off		Opt-in: when true, VtUnit.SeedFromDefinition attaches a VtUnitFriends component for in-game friends, friend requests and presence. Needs a VtPlayerIdentity on the same object.

Mail

Field	Type	Default	Range	Description
Use Mail (`useMail`)	`bool`	Off		Opt-in: when true, VtUnit.SeedFromDefinition attaches a VtUnitMail component for sending and receiving mail with attachments. Needs a VtPlayerIdentity on the same object.
Mail Postage (`mailPostage`)	VtCurrencyAmount	—		Paid from the player’s wallet for every mail sent. Empty currency = free.

Leveling

Field	Type	Default	Range	Description
Xp Curve (`xpCurve`)	VtXpCurveDefinition	None		XP curve this unit progresses on. Non-null = VtUnit.SeedFromDefinition auto-attaches a VtUnitLevel component that tracks the unit’s level + current XP and fires OnLeveledUp on threshold crossings. The component seeds its starting level from the existing ‘startingLevel’ field above (under Progression). Null = unit doesn’t level (most mobs).
Xp Award (`xpAward`)	`int`	0	≥ 0	XP credited to the killer on this unit’s death. > 0 = VtUnit.SeedFromDefinition auto-attaches a VtXpAwarder that subscribes to OnDied and credits the killer’s VtUnitLevel. 0 = no awarder attached (most non-combat NPCs).

Immunities

Field	Type	Default	Range	Description
Cc Immunities (`ccImmunities`)	VtCcCategory[]	Empty		Crowd-control categories this unit is innately immune to. Apply-time gate refuses any VtBuffDefinition whose ccCategory matches an entry — the buff silently fails to apply and an Immune combat-text event fires. Use for boss design (Stun + Taunt immunity), boss adds (Fear immunity), racial passives (Undead → Fear/Charm/Sleep immunity).
Damage Immunities (`damageImmunities`)	VtDamageType[]	Empty		Damage types this unit is innately immune to. Damage of an immune type is dropped before any pipeline math (no resist roll, no armor) and an Immune combat-text event fires. Use for elemental boss design (Fire Lord immune to Fire, Frost Wyrm immune to Cold, Lich immune to Shadow).

Innate modifiers / traits

Field	Type	Default	Range	Description
Innate Modifiers (`innateModifiers`)	VtItemModifier[]	Empty		The unit’s racial / class baseline for scalar stats — e.g. a Dwarf starts with +2 Armor and +25% Fire Resistance, a Giant starts with +100 MaxHp. Each entry is a (VtStatDefinition, value, isPercentage) triple, same shape as items and buffs use. Pushed into VtUnitModifiers under the source key “innate” at spawn. Items, buffs, and level-up gains use separate source keys and STACK ON TOP — equipping a +3 Armor ring leaves the Dwarf’s innate +2 intact. Unequipping only removes the item’s source, the baseline is untouched. Leave empty for generic units with no racial quirks.
Innate Traits (`innateTraits`)	VtTraitOverride[]	Empty		The unit’s racial / class baseline for CATEGORICAL traits (not numeric stats) — e.g. a Ghost has VtMovementType = Flying, a Golem has VtArmorType = Heavy, an Undead has CanMove = true but Sleep-immune. Each entry is a (VtTraitKey, value, priority) triple. Written at priority 0 so items and buffs (priority ≥1) naturally override — equip a Levitate Amulet and the Golem’s VtMovementType flips to Flying for as long as it’s worn, then reverts. Leave empty to accept the default trait values (VtMovementType.Ground, CanMove=true, etc.).

On-Kill / Spawn

Field	Type	Default	Range	Description
Xp Reward (`xpReward`)	`int`	0	≥ 0	XP awarded to the killer when this unit dies.
Respawn Time (`respawnTime`)	`float`	0	≥ 0	Seconds before this unit respawns (when used with a respawning spawner). 0 = no respawn.
Model Prefab (`modelPrefab`)	`GameObject`	None		OPTIONAL. Only used by data-driven spawners (e.g. WaveSpawner) that pick a VtUnitDefinition from a table and need to instantiate a GameObject from scratch. Leave EMPTY when the unit is authored as a scene-placed prefab with its VtUnit component and ‘definition’ slot already wired — in that workflow the prefab itself carries the visuals, this field is redundant. Typical use: one SkeletonWarrior.asset points at SkeletonWarrior_Model.prefab; a wave spawner looks up the SO, Instantiates modelPrefab, then attaches VtUnit components and sets the definition. Null with a data-driven spawner → spawner falls back to a debug primitive capsule.

VtUnitStats

Component. Add it with Add Component → Vantage → Units → VtUnitStats. Adds VtUnitModifiers automatically.

Resource pools (HP / MP / Stamina / Rage / Focus / …) for a unit. Owns the TakeDamage pipeline (evade → element resistance → damage matrix → armor → absorb → round → apply) and the pre/post damage hooks.

Scripting API

Member	Description
`IReadOnlyList<VtResourcePool> Pools { get; }`	All resource pools on this unit, in definition order. Do not mutate the list; pool currents mutate via `VtResourcePool.Spend` / `VtResourcePool.Restore`.
`float TimeSinceCombat { get; }`	Simulation seconds since the last incoming or outgoing damage. A unit is considered “in combat” for `VtCombatConstants.OutOfCombatThreshold` seconds after any hit. Advances with `Tick`, not wall-clock time.
`bool InCombat { get; }`	Whether the unit is currently treated as in combat — drives `VtRegenMode.CombatOnly` / `VtRegenMode.OutOfCombatOnly` pools. Threshold is global (`VtCombatConstants.OutOfCombatThreshold`).
`int HP { get; }`	Current health, or 0 without an HP pool.
`int MaxHP { get; }`	Maximum health after modifiers, or 0 without an HP pool.
`bool IsDead { get; }`	True once the HP pool has hit 0. Units without an HP pool are never dead. While dead, every HP-restoring path no-ops — see `Revive`.
`int MP { get; }`	Current mana, or 0 without an MP pool.
`int MaxMP { get; }`	Maximum mana after modifiers, or 0 without an MP pool.
`int Stamina { get; }`	Current stamina, or 0 without a Stamina pool.
`int MaxStamina { get; }`	Maximum stamina after modifiers, or 0 without a Stamina pool.
`VtRegenScheduler RegenScheduler { get; }`	The regeneration scheduler behind this component, for advanced use.
`event Action<VtDamageInfo> OnPreTakeDamage`	Pre-hook, authority-only. Subscribers may mutate the `VtDamageInfo` (convert element, add to absorbed, set cancelled=true).
`event Action<VtDamageInfo> OnPostTakeDamage`	Post-hook, notification. Fires on both authority and replicas after the hit resolves; `VtDamageInfo.appliedDamage` reflects the final value.
`event Action<VtDamageInfo> OnPreDealDamage`	Fired on the attacker before the target pipeline resolves. VtAuthority-only.
`event Action<VtDamageInfo> OnPostDealDamage`	Fired on the attacker after the target pipeline resolves. Drives lifesteal, on-hit procs. Notification (fires on authority; replicas get it from their mirror of the attacker if relevant).
`event Action<VtUnitId> OnDied`	Fired when HP reaches 0. Notification event.
`static event Action<VtUnit, VtUnitId> OnAnyUnitDied`	Static fan-out fired alongside the instance `OnDied` event. Args: (killedUnit, killerId). One subscription covers every unit in the world — used by `VtUnitQuestLog` to advance kill objectives without subscribing to each spawned unit individually.
`event Action<int> OnRevived`	Fired after `Revive` brings a dead unit back above 0 HP. Args: the HP the unit was revived with. Notification — respawn VFX, re-enabling AI, clearing “corpse” UI state. Does not fire for the `Initialize` re-seed path (that’s a fresh spawn, not a revive).
`event Action<VtDamageInfo> OnEvaded`	Fired when an incoming hit was dodged (before HP is touched). Notification; drives “Miss!” floating text.
`event Action<int, bool, bool, VtUnitId> OnHealed`	Fired after a heal lands on this unit. Args: amount actually restored (post-crit, post-clamp), whether it was a crit heal, whether it came from a HoT tick (vs a direct heal), the applier id. Notification only — drives floating-text / healing log. Does not fire for regen; regen is continuous and unimportant to surface as text.
`void MarkInCombat()`	Restart the combat timer. The damage pipeline calls this on both defender and attacker when a hit lands; consumers with their own “enter combat” triggers (a taunt shout, an aggro pull) may call it too.
`void Initialize(VtUnitDefinition def)`	Seed pools from a `VtUnitDefinition`. Rebuilds every pool at its `startingCurrent`, so a dead unit re-seeded this way comes back alive without firing `OnRevived` — this is the respawn path (fresh spawn semantics), not the in-place resurrection path (`Revive`). Safe to call before any child components bind to events — pools fire their `VtResourcePool.OnChanged` on the first mutation.
`VtResourcePool GetPool(VtResourceKind kind)`	Return the pool for `kind`, or null if the unit doesn’t have one. Callers that rely on a specific pool should null-check (a basic mob with only HP returns null for MP).
`bool HasPool(VtResourceKind kind)`	True if the unit has a pool of this kind.
`int TakeDamage(VtDamageInfo info)`	Apply a damage hit through the full pipeline. Returns the final damage dealt (0 on evade / cancel). VtAuthority-only; replicas mirror HP through pool replication and raise the hit events through `ApplyHitFromNet`.
`int TakeDamage(int amount, VtDamageType type = VtDamageType.Physical)`	Deal plain environmental damage, such as a trap or a fall, with no attacker. Builds a minimal `VtDamageInfo` of the given `type` and runs it through the full pipeline.
`void Heal(int amount)`	Restore HP by `amount` with no crit / applier context. VtAuthority-only. Used by lifesteal and any host code that heals without a meaningful caster. No-op while `IsDead`.
`int Heal(int amount, VtUnitId applier, bool canCrit)`	Restore HP with optional crit support. When `canCrit` is true, rolls the applier’s `stat.crit_chance`; on success, multiplies by `VtCombatConstants.DefaultCritMultiplier` + `stat.crit_multiplier`. Returns the actual amount healed (after crit scaling). Used by `VtHealEffect` and HoT ticks. VtAuthority-only. Returns 0 while `IsDead`.
`int TakeTickHeal(int amount, VtUnitId applier, bool canCrit)`	Heal from a heal-over-time tick. Same math as `Heal`, but `OnHealed` reports it as a tick so combat text can style it differently from direct heals. Returns 0 while `IsDead`: a heal over time that outlives its target never revives it.
`bool Revive(int hp)`	Bring a dead unit back with `hp` current HP (clamped to `[1, MaxHP]`). The only way HP rises from 0 short of re-seeding the unit via `Initialize`. Fires `VtResourcePool.OnChanged` on the HP pool, then `OnRevived`. Resets the combat timer so the unit comes back out of combat (regen resumes on the next tick). VtAuthority-only.
`void ApplyHitFromNet(VtDamageInfo info, bool evaded)`	Raise the hit events for a hit the authority applied: `OnEvaded` when `evaded`, then `OnPostTakeDamage`. Changes nothing; HP arrives through pool replication. Used by replication on clients so hit cues, combat text and interrupts follow the server. Refused on the authority, which raised the events itself.
`void ApplyHealFromNet(int amount, bool wasCrit, bool isTick, VtUnitId applier)`	Raise `OnHealed` for a heal the authority applied. Changes nothing. Used by replication on clients; refused on the authority.
`void ApplyDeathFromNet(VtUnitId killer)`	Raise `OnDied` and `OnAnyUnitDied` for a death on the authority. Changes nothing; loot, experience and quest credit stay on the authority. Used by replication on clients; refused on the authority.
`void ApplyReviveFromNet(int hp)`	Raise `OnRevived` for a revive on the authority. Changes nothing. Used by replication on clients; refused on the authority.
`bool SpendResource(VtResourceKind kind, int amount)`	Spend from a specific resource pool. Returns false if the pool doesn’t exist or has insufficient current. Runs on the authority and on the owning client, which predicts the cost; the authority’s value replicates back.
`void RestoreResource(VtResourceKind kind, int amount)`	Restore a specific resource pool. Useful for potions / action-generated rage ticks / etc. VtAuthority-only. HP restores no-op while `IsDead` (a health potion can’t be drunk by a corpse); other pools are unaffected by death.
`void Tick(float deltaTime)`	Advance the combat timer and the regen scheduler by `deltaTime` seconds. The only time input this component consumes: `Update` forwards `Time.deltaTime` here, and a custom tick driver or dedicated server passes its own step.
`VtStatDefinition ResistFor(VtDamageType type)`	Return the `VtStatDefinition` that resists a given `VtDamageType`. Routes through `VtCoreStats.Instance` — returns null when the singleton is missing (damage pipeline treats a null resist stat as zero contribution).

VtUnitModifiers

Component. Add it with Add Component → Vantage → Units → VtUnitModifiers.

Adds up every stat and attribute bonus on a unit. Items, buffs, auras, level growth and innate bonuses each register as a named source; removing a source removes its bonuses, and every change raises OnModifiersChanged.

Scripting API

Member	Description
`event Action OnModifiersChanged`	Notification event — fires after any mutation on either channel. Bindings subscribing to it recompute derived values. Safe on both authority and replica sides. Fires exactly once per `Set/Remove` call, regardless of which channel was mutated.
`void SetSource(string sourceId, VtItemModifier[] modifiers)`	Register or update a secondary-stat source. Passing null or an empty array removes the source. Triggers `OnModifiersChanged`.
`void RemoveSource(string sourceId)`	Remove a secondary-stat source by id. No-op if not present. Triggers `OnModifiersChanged` only if a source was actually removed.
`bool HasSource(string sourceId)`	True if a secondary-stat source with the given id is currently registered.
`float Get(VtStatDefinition stat)`	Total flat bonus for a secondary stat (sum of all flat entries across all secondary sources). Returns 0 if no flat modifiers are present.
`float GetPercent(VtStatDefinition stat)`	Total percentage bonus for a secondary stat as a fraction (0.15 = +15%). Returns 0 if none present.
`float Apply(VtStatDefinition stat, float baseValue)`	Canonical secondary-stat resolution: `(baseValue + flatSum) * (1 + percentSum)`.
`float Apply(VtStatDefinition stat, float baseValue, IReadOnlyList<VtSourceOverride> overrides)`	What `Apply` would return with the sources in `overrides` replaced or removed. Changes nothing and fires nothing. Only direct modifiers are counted: a stat derived from attributes the overridden sources grant is not.
`float GetModified(VtStatDefinition stat, float baseValue)`	Additive-only form: `baseValue + flatSum`. Kept for callers that have already factored out percent handling.
`float GetMultiplied(VtStatDefinition stat, float baseValue)`	Multiplicative form using only the flat channel: `baseValue * (1 + flatSum)`, for stats that act as a rate multiplier. Prefer `Apply` for new consumers.
`void SetAttributeSource(string sourceId, VtAttributeGrant[] grants)`	Register or update a primary-attribute source. Passing null or an empty array removes the source. Triggers `OnModifiersChanged`.
`void RemoveAttributeSource(string sourceId)`	Remove a primary-attribute source by id. No-op if not present. Triggers `OnModifiersChanged` only if a source was actually removed.
`bool HasAttributeSource(string sourceId)`	True if a primary-attribute source with the given id is currently registered.
`float Get(VtAttributeDefinition attribute)`	Total flat point bonus for a primary attribute (e.g. total Strength contributed by baseline + items + buffs). Returns 0 if no grants present.
`float GetPercent(VtAttributeDefinition attribute)`	Total percentage bonus for a primary attribute as a fraction (0.10 = +10%).
`float Apply(VtAttributeDefinition attribute, float baseValue)`	Canonical primary-attribute resolution: `(baseValue + flatSum) * (1 + percentSum)`. Callers typically use `Mathf.RoundToInt` on the result since primary attributes are int by convention.

VtUnitTraits

Component. Add it with Add Component → Vantage → Units → VtUnitTraits.

Priority-override store for categorical traits on a unit — movement type, armor type, attack type, CC flags. Multiple sources (innate / item / buff) can write the same VtTraitKey at different priorities; the highest priority wins. The innate default sits at priority 0 so any item or buff that cares will take precedence.

Scripting API

Member	Description
`event Action OnTraitsChanged`	Fires when any trait override changes. Notification event; UI / consumers re-query values on receipt.
`void SetTrait<TEnum>(string sourceId, VtTraitKey key, TEnum value, int priority)`	Set an enum-typed trait. Removes any prior entry from the same source for the same key, then appends the new one.
`void SetTraitBool(string sourceId, VtTraitKey key, bool value, int priority)`	Set a bool-typed trait (CanAct / CanMove / CanCast).
`void SetTraitObject(string sourceId, VtTraitKey key, object value, int priority)`	Set a reference-typed trait (VtProjectileSpec, VtSplashSpec boxed, etc.).
`void ClearTrait(string sourceId, VtTraitKey key)`	Remove a single (source, key) override. No-op if missing.
`void ClearSource(string sourceId)`	Remove all overrides from a source (e.g. on unequip). Fires event if any were removed.
`TEnum GetEnum<TEnum>(VtTraitKey key, TEnum fallback)`	Read an enum-typed trait. Returns `fallback` if no override is set.
`bool GetBool(VtTraitKey key, bool defaultValue = true)`	Read a bool-typed trait. Defaults to `defaultValue` (usually `true` for CC flags — no override means “can do it”).
`T GetObject<T>(VtTraitKey key)`	Read a reference-typed trait. Returns null if no override is set.
`bool HasTrait(VtTraitKey key)`	Low-level: returns whether an override exists for the key. For rare consumers that need to distinguish “no override” from “override with default value”.
`void ApplyOverrides(string sourceId, VtTraitOverride[] overrides)`	Applies a batch of inspector-authored overrides under a single source id. Used by `VtUnitDefinition.innateTraits` and `VtBuffDefinition.traitOverrides`.

VtUnitBuffs

Component. Add it with Add Component → Vantage → Units → VtUnitBuffs. Adds VtUnitModifiers automatically.

The buffs and debuffs active on a unit: apply and remove them, ask what is active and for how long, and listen for changes. While a buff is active its stat modifiers, attribute grants and trait overrides apply to the unit, and its tick effects run.

Scripting API

Member	Description
`VtBuffScheduler Scheduler { get; }`	The buff scheduler behind this component, for advanced use. The members on this component cover normal use.
`IReadOnlyList<VtBuffScheduler.Instance> ActiveBuffs { get; }`	The active buff instances, for UI. Do not modify the list.
`event Action<VtBuffScheduler.Instance> OnBuffAdded`	Raised when a new buff instance starts on this unit.
`event Action<VtBuffScheduler.Instance> OnBuffRemoved`	Raised when a buff instance ends: it expired, was removed or was dispelled.
`event Action<VtBuffScheduler.Instance> OnBuffRefreshed`	Raised when re-applying a buff resets or extends an existing instance instead of adding a new one.
`VtBuffScheduler.Instance ApplyBuff(VtBuffDefinition def, float duration, VtUnitId applier, bool fromAura = false)`	Apply a buff to this unit for `duration` seconds and return the instance, or null if it was refused. A crowd-control buff whose `VtBuffDefinition.ccCategory` is in the unit’s `VtUnitDefinition.ccImmunities` is refused and shows Immune combat text; buffs with no crowd-control category always apply. `fromAura` marks the buff as coming from an aura so UI shows it as lasting; leave it false for a normal apply.
`int RemoveBuff(VtBuffDefinition def, bool all = true)`	Remove buff instances by definition. See `VtBuffScheduler.RemoveBuff`.
`VtBuffScheduler.Instance ApplyBuffFromNet(VtBuffDefinition def, float remaining, VtUnitId applier, bool fromAura = false)`	Mirror a buff the authority applied: its modifiers apply here and `OnBuffAdded` fires, but it ticks no effects and never expires on its own. Returns the instance to refresh or remove later. Used by replication on clients; refused on the authority. Pass `fromAura` through from the authority so mirrored aura buffs read the same in the UI on both sides.
`void RefreshBuffFromNet(VtBuffScheduler.Instance instance, float remaining)`	Set a mirrored buff’s remaining time and raise `OnBuffRefreshed`. Used by replication.
`void RemoveBuffFromNet(VtBuffScheduler.Instance instance)`	Remove a mirrored buff and raise `OnBuffRemoved`. Used by replication.
`bool HasBuff(VtBuffDefinition def)`	True if at least one instance of the buff is active.
`float GetRemainingDuration(VtBuffDefinition def)`	Seconds left on the buff, the longest across its stacked instances, or 0 if it is not active.
`void Tick(float deltaTime)`	Advance the buff scheduler by `deltaTime` seconds.

VtCombatEngagement

Component. Add it with Add Component → Vantage → Combat → VtCombatEngagement.

Pure target-engagement mechanics for a unit: hold a target, report in-range state, chase into range via the optional VtTopDownClickToMove sibling, and rotate the unit to face the target. Carries no combat logic of its own — damage, cooldowns, and swing-timing live in the ability system (VtUnitAbilities).

Inspector fields

Field	Type	Default	Range	Description
Range Padding (`rangePadding`)	`float`	0.1	≥ 0	Extra padding (world units) added to the range check when deciding whether the target is in range. Prevents micro-jitter at the edge of range where float noise would oscillate between ‘in’ and ‘out’.
Repath Interval (`repathInterval`)	`float`	0.25	≥ 0.05	How often (seconds) ChaseInto re-issues a MoveTo toward a moving target. Only used when a VtTopDownClickToMove sibling is attached.
Face Rotation Speed (`faceRotationSpeed`)	`float`	720	≥ 0	Degrees/sec the unit rotates to face its target when no movement component provides rotation.

Scripting API

Member	Description
`IVtAttackable Target { get; }`	Currently engaged target, or null if idle.
`bool HasLiveTarget { get; }`	True if a target is held and it still reports `IVtAttackable.CanBeAttacked` plus a live `IVtAttackable.Transform`. Clears the target lazily if the target has been destroyed.
`float DistanceToTargetSqr { get; }`	Planar squared distance to the current target, or +∞ if none. Useful for callers that need the raw distance for sort / priority (consider using `IsInRange` for simple range checks — it is also zero-alloc).
`event Action<IVtAttackable> OnTargetChanged`	Fires when `Target` changes (including to null).
`void RebindMovement()`	Re-discover the sibling `VtTopDownClickToMove`. Call it after adding a mover to a live unit.
`void RebindThreatTable()`	Re-discover the sibling `VtThreatTable` (if any) and refresh the threat-driven retargeting subscription. Idempotent — safe to call any number of times. Called automatically from `Awake`, `OnEnable`, and from `VtThreatTable`’s own `OnEnable` when the table is added after this component already cached its absence.
`void SetTarget(IVtAttackable newTarget)`	Set the current target. Pass null to clear. Fires `OnTargetChanged` iff the reference actually changed.
`void ClearTarget()`	Clear the current target. Equivalent to `SetTarget(null)`.
`bool IsInRange(float range)`	True if the current target is within `range` world units (plus padding) of this unit. False if no target, destroyed target, or out of range. Uses squared distance — zero alloc, zero sqrt.
`void ChaseInto(float range)`	Request movement toward the current target until it is within `range`. No-op if there is no target or no movement sibling (AI-driven units manage their own approach). Throttled by `repathInterval` so a moving target does not flood MoveTo calls.
`void Tick(float deltaTime)`	Drain the `ChaseInto` repath throttle by `deltaTime` seconds. The only time input this component consumes; `Update` forwards `Time.deltaTime`.
`void StopChase()`	Stop any chase this component requested (only meaningful when a `VtTopDownClickToMove` sibling is present). Does not clear the target.
`void FaceTarget(float deltaTime)`	Rotate to face the current target by one `deltaTime` step. Uses `VtTopDownClickToMove.RotationSpeed` when the sibling is present, otherwise the `faceRotationSpeed` field. No-op with no target. Pass the same delta the caller was ticked with.

VtStatDefinition

Asset. Create it with Create → Vantage → Units → Stat Definition.

Designer-authored secondary stat — one ScriptableObject asset per stat (MaxHP.asset, CritChance.asset, ResistFire.asset, …). Carries UI-facing metadata (name + description) and is itself the runtime identity — VtUnitModifiers keys on the asset reference, not on an enum ordinal.

Inspector fields

Field	Type	Default	Description
Id (`id`)	`string`	Empty	Stable string identifier, unique across stats. Saves and network messages refer to stats by it. Lowercase snake_case convention: ‘stat.max_hp’, ‘stat.crit_chance’. Changing it breaks existing saves.
Display Name (`displayName`)	`string`	Empty	UI display name. E.g. ‘Max HP’, ‘Critical Hit Chance’, ‘Fire Resistance’.
Description (`description`)	`string`	Empty	Designer / tooltip description. E.g. ‘Maximum health. Damage reduces current HP; when HP reaches 0 the unit dies.’

VtCoreStats

Asset. Create it with Create → Vantage → Setup → Core Stats.

Singleton ScriptableObject holding direct references to every VtStatDefinition that Vantage’s pipeline code hardcodes by id — armor, evade, resistances, crit, lifesteal, and the rest.

Inspector fields

Defense

Field	Type	Default	Description
Armor (`armor`)	VtStatDefinition	`Armor`	Defender’s armor rating. Reduces physical damage via the pipeline’s armor curve. Pipeline id: stat.armor.
Evade Chance (`evadeChance`)	VtStatDefinition	`EvadeChance`	Chance to evade an incoming non-tick non-True hit. 0..1 fraction; clamped by VtCombatConstants.MaxEvadeChance. Pipeline id: stat.evade_chance.
Resist All (`resistAll`)	VtStatDefinition	`ResistAll`	Flat resistance that applies to every damage type. Stacks with the per-type resist channel. Pipeline id: stat.resist_all.
Resist Physical (`resistPhysical`)	VtStatDefinition	`ResistPhysical`	Physical-element resistance. Pipeline id: stat.resist_physical.
Resist Fire (`resistFire`)	VtStatDefinition	`ResistFire`	Fire-element resistance. Pipeline id: stat.resist_fire.
Resist Cold (`resistCold`)	VtStatDefinition	`ResistCold`	Cold-element resistance. Pipeline id: stat.resist_cold.
Resist Poison (`resistPoison`)	VtStatDefinition	`ResistPoison`	Poison-element resistance. Pipeline id: stat.resist_poison.
Resist Lightning (`resistLightning`)	VtStatDefinition	`ResistLightning`	Lightning-element resistance. Pipeline id: stat.resist_lightning.
Resist Holy (`resistHoly`)	VtStatDefinition	`ResistHoly`	Holy-element resistance. Often paired oppositionally with Shadow. Pipeline id: stat.resist_holy.
Resist Shadow (`resistShadow`)	VtStatDefinition	`ResistShadow`	Shadow-element resistance. Often paired oppositionally with Holy. Pipeline id: stat.resist_shadow.
Resist Arcane (`resistArcane`)	VtStatDefinition	`ResistArcane`	Arcane-element resistance — mage’s raw-magic school. Pipeline id: stat.resist_arcane.
Resist Nature (`resistNature`)	VtStatDefinition	`ResistNature`	Nature-element resistance — druid / shaman school. Pipeline id: stat.resist_nature.

Offense

Field	Type	Default	Description
Armor Penetration (`armorPenetration`)	VtStatDefinition	`ArmorPenetration`	Attacker’s armor-penetration fraction (0..1). Reduces the defender’s effective armor before mitigation. Pipeline id: stat.armor_penetration.
Crit Chance (`critChance`)	VtStatDefinition	`CritChance`	Chance to land a critical hit on direct damage. 0..1 fraction; clamped by VtCombatConstants.MaxCritChance. Pipeline id: stat.crit_chance.
Crit Multiplier (`critMultiplier`)	VtStatDefinition	`CritMultiplier`	Additive bonus on top of VtCombatConstants.DefaultCritMultiplier for crit damage scaling. Pipeline id: stat.crit_multiplier.
Lifesteal (`lifesteal`)	VtStatDefinition	`Lifesteal`	Fraction of applied direct damage healed back to the attacker. 0..1. Pipeline id: stat.lifesteal.
Mana Steal (`manaSteal`)	VtStatDefinition	`ManaSteal`	Fraction of applied direct damage restored to the attacker’s MP pool. 0..1. Pipeline id: stat.mana_steal.
Damage Bonus (`damageBonus`)	VtStatDefinition	`DamageBonus`	Flat + percent scaling applied to rolled basic-attack damage when a basic-attack effect references it. Pipeline id: stat.damage_bonus.
Physical Power (`physicalPower`)	VtStatDefinition	`PhysicalPower`	Auto-applied to every Melee + Ranged hit (non-Magic, non-True). Pipeline scales the rolled damage by modifiers.Apply(physicalPower, dmg) between crit and element resistance. Drives warrior / hunter / rogue gear scaling. Pipeline id: stat.physical_power.
Spell Power (`spellPower`)	VtStatDefinition	`SpellPower`	Auto-applied to every Magic-attackType hit (non-True). Same place in the pipeline as physicalPower; drives mage / warlock / cleric gear scaling. Pipeline id: stat.spell_power.
Thorns (`thorns`)	VtStatDefinition	`Thorns`	Fraction (0..1) of applied damage reflected back at the attacker as Physical/Normal. Filtered by VtCombatConstants.ThornsFilter — default PhysicalOnly. Tick damage does not trigger thorns; reflected hits (source=Reflection) don’t chain into another reflection. Pipeline id: stat.thorns.

Timing

Field	Type	Default	Description
Attack Speed (`attackSpeed`)	VtStatDefinition	`AttackSpeed`	Multiplier on basic-attack cadence. 0.20 = +20% faster swings. Read by the ability scheduler when an ability has scalesWithAttackSpeed = true. Pipeline id: stat.attack_speed.
Attack Range Bonus (`attackRangeBonus`)	VtStatDefinition	`AttackRangeBonus`	Flat world-units added to any ability’s effective cast range when its scalesWithRangeBonus flag is on. Pipeline id: stat.attack_range_bonus.
Cooldown Reduction (`cooldownReduction`)	VtStatDefinition	`CooldownReduction`	Cooldown-reduction fraction (0..1). Clamped by VtCombatConstants.MaxCooldownReduction (default 0.80). Applied after attack-speed scaling: a 10s cooldown with 0.5 CDR lands at 5s. Pipeline id: stat.cooldown_reduction.
Move Speed (`moveSpeed`)	VtStatDefinition	`MoveSpeed`	Locomotion top speed bonus. Read by VtTopDownClickToMove as modifiers.Apply(moveSpeed, VtUnitDefinition.moveSpeed) — flat + percent stack on top of the unit’s authored base speed. Pipeline id: stat.move_speed.

World

Field	Type	Default	Description
Vision Radius (`visionRadius`)	VtStatDefinition	`VisionRadius`	Sight bonus. Read by VtVisionSource as modifiers.Apply(visionRadius, radius) — flat world units and percent stack on the source’s authored radius, for fog of war and network interest. Pipeline id: stat.vision_radius.
Gathering Speed (`gatheringSpeed`)	VtStatDefinition	`GatheringSpeed`	Extra attack speed on swings against resource nodes, as a fraction added to stat.attack_speed. 0.25 = gather 25% faster. Applies to abilities with scalesWithAttackSpeed, such as the basic attack. Pipeline id: stat.gathering_speed.

Miscellaneous

Field	Type	Default	Description
Xp Gain Multiplier (`xpGainMultiplier`)	VtStatDefinition	`XpGainMultiplier`	Multiplier on XP gained by this unit on mob kills. 0..∞ fraction added to 1. Pipeline id: stat.xp_gain_multiplier.
Targeting Priority (`targetingPriority`)	VtStatDefinition	`TargetingPriority`	Weighting used by enemy AI target selection. Higher = more attractive to attackers. Pipeline id: stat.targeting_priority.
Threat Multiplier (`threatMultiplier`)	VtStatDefinition	`ThreatMultiplier`	Scalar applied to all threat this unit generates (damage / heal / ability). Read by VtThreatAutoSubscriber + VtTauntEffect + VtThreatOnApplyEffect. Default 1.0; tank items / talents grant + flat / + percent on this stat. Pipeline id: stat.threat_multiplier.

Resource Pool Bindings

Field	Type	Default	Description
Resource Pool Stats (`resourcePoolStats`)	VtResourcePoolStatBinding[]	11 entries	Maps each VtResourceKind to its Max-scaling and Regen-scaling stats. Lets VtResourcePoolConfig infer maxStat / regenStat from the selected kind so consumers don’t wire MaxHp.asset on every unit definition. Add a row when introducing a new VtResourceKind. Run Tools → Vantage → Auto-Fill VtCoreStats Pool Bindings to populate.

Scripting API

Member	Description
`static VtCoreStats Instance { get; }`	The loaded singleton: the one handed to `OverrideInstance`, else your `Assets/Resources/VtCoreStats.asset`, else the package’s. Null only if the shipped asset has been deleted from the package and you have none — which is a configuration error and logs once via the warning below.
`VtStatDefinition GetMaxStat(VtResourceKind kind)`	Look up the `VtStatDefinition` that scales pool Max for `kind`. Returns null when no binding exists (caller treats null as “no modifier scaling — use raw baseMax”). Linear scan over a fixed ~12-row array; called per-pool, not per-frame.
`VtStatDefinition GetRegenStat(VtResourceKind kind)`	Look up the `VtStatDefinition` that scales pool regen rate for `kind`. Returns null when no binding exists or the kind doesn’t passively regen (e.g. Rage / ComboPoints).
`static void ResetCache()`	Forgets the cached core stats so the next `Instance` read loads the asset again. Use it after swapping the asset in the editor, or in test teardown after `OverrideInstance`.
`static void OverrideInstance(VtCoreStats instance)`	Use `instance` as the core stats, such as a copy a boot scene references. Call it before gameplay starts. Pass null to behave like `ResetCache`.

VtAttributeDefinition

Asset. Create it with Create → Vantage → Units → Attribute Definition.

Designer-authored primary attribute — one ScriptableObject asset per attribute (Strength.asset, Dexterity.asset, Intelligence.asset, Vitality.asset, Luck.asset, Agility.asset, …). Carries UI-facing metadata (name + description) and is itself the runtime identity — VtUnitModifiers keys primary-attribute totals on the asset reference. No separate channel / enum / id field is needed.

Inspector fields

Field	Type	Default	Description
Id (`id`)	`string`	Empty	Stable string identifier for save files and network payloads. Empty = the asset name.
Display Name (`displayName`)	`string`	Empty	UI display name. E.g. ‘Strength’, ‘Intelligence’, ‘Luck’.
Description (`description`)	`string`	Empty	Tooltip / codex description shown on the character sheet or allocation UI. E.g. ‘Physical power. Each point grants +1 melee damage and +2 max HP.’

Scripting API

Member	Description
`string SaveId { get; }`	Id for save files and commands: `id`, or the asset name when empty.

VtAttributeFormula

Asset. Create it with Create → Vantage → Units → Attribute Formula.

Designer-tunable mapping from primary attributes (authored as VtAttributeDefinition assets) to any derived StatType. Fully data-driven — each entry is one (source attribute → target stat) row with a per-point coefficient. Add, remove, or reassign rows in the inspector without touching code.

Inspector fields

Field	Type	Default	Description
Mappings (`mappings`)	VtAttributeFormula.Mapping[]	Empty	All attribute→stat contribution rules. One attribute can appear in many rows (multi-effect), and one target stat can appear in many rows (multi-source).

VtAttributeDerivedStatsBinding

Component. Add it with Add Component → Vantage → Units → VtAttributeDerivedStatsBinding. Adds VtUnitModifiers, VtUnit automatically.

Optional binding that reads primary-attribute totals from VtUnitModifiers’ primary channel and projects them into secondary stats (MaxHP, DamageBonus, CritChance, …) under modifier-source id "attr". This is the seam where the two channels meet: sources from the primary side, targets on the secondary side, one-way flow.

Inspector fields

Field	Type	Default	Description
Formula (`formula`)	VtAttributeFormula	None	Designer formula — rows of (source attribute → target stat, per-point) tuples. Leave null / empty to disable all derived-stat projection.

Scripting API

Member	Description
`void Refresh()`	Re-seed the attribute baseline from the current definition and recompute the derived stats. Call it after swapping the `VtAttributeFormula` or changing the unit’s definition at runtime.

VtBuffDefinition

Asset. Create it with Create → Vantage → Units → Buff Definition.

Designer-authored description of a single buff / debuff. Referenced from code (VtUnitBuffs.ApplyBuff) or from scriptable asset chains (perks, equipped items with “on-hit apply X”). Fully data-driven — creating a new buff is an inspector action, no C#.

Inspector fields

Identity

Field	Type	Default	Description
Id (`id`)	`string`	Empty	Machine id used for stack resolution. Two assets with the same id are treated as the same buff.
Display Name (`displayName`)	`string`	Empty	UI display name.
Description (`description`)	`string`	Empty	Tooltip / codex description.
Icon (`icon`)	`Sprite`	None	Icon for buff bar / tooltip.
Icon Id (`iconId`)	`string`	Empty	An icon from the Vantage icon set by name, such as shield or flame, drawn when Icon is empty, so a buff has art on the buff bar before its own sprite exists.
Harmful (`harmful`)	`bool`	Off	A debuff: it works against the unit that carries it, such as a burn or a slow. Buff bars and unit frames mark it and its tooltip names it a debuff.

Effects

Field	Type	Default	Description
Modifiers (`modifiers`)	VtItemModifier[]	Empty	Secondary-stat modifications applied while the buff is active (HPRegen, CritChance, Armor, ResistFire, …).
Attribute Grants (`attributeGrants`)	VtAttributeGrant[]	Empty	Primary-attribute grants applied while the buff is active (+5 STR, +10% INT, …).
Trait Overrides (`traitOverrides`)	VtTraitOverride[]	Empty	Categorical overrides (movement type, armor type, CC flags, …). Priority is set per-entry; typical buff priority is 200.
Tick Effect (`tickEffect`)	VtTickEffect	—	Optional periodic effect — DoT / HoT. Leave amountPerTick = 0 to disable.

Presentation

Field	Type	Default	Description
Applied Cue (`appliedCue`)	VtPresentationCue	—	Animator trigger, sound and effect played on the target when the buff is applied.
Removed Cue (`removedCue`)	VtPresentationCue	—	Played when the buff expires or is removed.
Loop Vfx Prefab (`loopVfxPrefab`)	`GameObject`	None	Effect prefab kept on the target for as long as the buff lasts. Optional.

Duration

Field	Type	Default	Range	Description
Default Duration (`defaultDuration`)	`float`	5	≥ 0	Seconds the buff lasts if ApplyBuff is called with duration <= 0.
Max Duration (`maxDuration`)	`float`	0	≥ 0	Only used for StackAddDuration policy — the cap on combined duration. 0 = no cap.
Stacking Policy (`stackingPolicy`)	VtStackingPolicy	`Refresh`		How re-application behaves when an instance already exists.

Crowd Control

Field	Type	Default	Range	Description
Cc Category (`ccCategory`)	VtCcCategory	`None`		Categorical CC label. Routes the apply attempt through VtUnit.IsImmuneTo(VtCcCategory) — if the target is immune, the buff is silently rejected (and an Immune combat-text event fires for visible feedback). Pure stat / damage buffs use None and skip the gate entirely.

VtUnitTagDefinition

Asset. Create it with Create → Vantage → Units → Unit Tag Definition.

Designer-authored categorical label for a unit — e.g. Undead.asset, Beast.asset, Humanoid.asset, Construct.asset, Demon.asset. Attach to a VtUnitDefinition.tags array to declare what a unit is; consumers (quest objectives, vs-type items, bestiary UI, targeting filters) query via VtUnit.HasTag(tag).

Inspector fields

Field	Type	Default	Description
Id (`id`)	`string`	Empty	Stable string identifier for DB / network payloads. Convention: ‘tag.undead’, ‘tag.beast’.
Display Name (`displayName`)	`string`	Empty	UI display name. E.g. ‘Undead’, ‘Beast’, ‘Humanoid’.
Description (`description`)	`string`	Empty	Lore / tooltip description. E.g. ‘Reanimated corpses. Vulnerable to Holy damage, immune to Fear.’

VtDefinitionCatalog

Asset. Create it with Create → Vantage → Setup → Definition Catalog.

Turns the string ids that travel in save files and network messages back into definition assets. Create one with Create → Vantage → Setup → Definition Catalog, drag your definitions in, and save it as Assets/Resources/VtDefinitionCatalog.asset so Instance finds it. Both sides of a network connection need the same catalog.

Inspector fields

Field	Type	Default	Description
Abilities (`abilities`)	VtAbilityDefinition[]	Empty	Every ability a client may ask the server to cast.
Buffs (`buffs`)	VtBuffDefinition[]	Empty	Buffs saved or replicated by id.
Items (`items`)	VtItemDefinition[]	Empty	Items saved or replicated by id.
Units (`units`)	VtUnitDefinition[]	Empty	Unit definitions saved or replicated by id.
Quests (`quests`)	VtQuestDefinition[]	Empty	Quests saved or replicated by id.
Currencies (`currencies`)	VtCurrencyDefinition[]	Empty	Currencies saved or replicated by id.
Recipes (`recipes`)	VtRecipeDefinition[]	Empty	Recipes saved or replicated by id.
Crafting Skills (`craftingSkills`)	VtCraftingSkillDefinition[]	Empty	Crafting skills saved or replicated by id.
Buildables (`buildables`)	VtBuildableDefinition[]	Empty	Buildables, so saved buildings can be spawned again from their prefab.
Talents (`talents`)	VtTalentDefinition[]	Empty	Talents saved or replicated by id.
Attributes (`attributes`)	VtAttributeDefinition[]	Empty	Attributes saved or replicated by id (the asset name when the id is empty).
Unlocks (`unlocks`)	VtUnlockDefinition[]	Empty	Unlocks saved or replicated by id.

Scripting API

Member	Description
`static VtDefinitionCatalog Instance { get; }`	The catalog at `Resources/VtDefinitionCatalog`, or null with one warning when there is none.
`static void OverrideInstance(VtDefinitionCatalog catalog)`	Use `catalog` as the instance, such as one a boot scene references. Null restores the Resources lookup.
`void Rebuild()`	Rebuild the lookups after changing the arrays at runtime.
`bool TryGetAbility(string id, out VtAbilityDefinition definition)`	Find an ability by id.
`bool TryGetBuff(string id, out VtBuffDefinition definition)`	Find a buff by id.
`bool TryGetItem(string id, out VtItemDefinition definition)`	Find an item by id.
`bool TryGetUnit(string id, out VtUnitDefinition definition)`	Find a unit definition by id.
`bool TryGetQuest(string id, out VtQuestDefinition definition)`	Find a quest by id.
`bool TryGetCurrency(string id, out VtCurrencyDefinition definition)`	Find a currency by id.
`bool TryGetRecipe(string id, out VtRecipeDefinition definition)`	Find a recipe by id.
`bool TryGetCraftingSkill(string id, out VtCraftingSkillDefinition definition)`	Find a crafting skill by id.
`bool TryGetBuildable(string id, out VtBuildableDefinition definition)`	Find a buildable by id.
`bool TryGetTalent(string id, out VtTalentDefinition definition)`	Find a talent by id.
`bool TryGetAttribute(string id, out VtAttributeDefinition definition)`	Find an attribute by id.
`bool TryGetUnlock(string id, out VtUnlockDefinition definition)`	Find an unlock by id.
`void BuildableCategories(List<VtBuildableCategoryDefinition> results)`	Fill `results` with every category the catalog’s buildables use, lowest `Sort Weight` first, then by name. Buildables without a category are not represented; list them with `BuildablesInCategory` and a null category.
`void BuildablesInCategory(VtBuildableCategoryDefinition category, List<VtBuildableDefinition> results)`	Fill `results` with the catalog’s buildables in `category`, lowest `Sort Weight` first, then in catalog order. A null category lists the buildables that have none.
`void RecipeCategories(List<VtRecipeCategoryDefinition> results)`	Fill `results` with every category the catalog’s recipes use, lowest `Sort Weight` first, then by name.
`void RecipesInCategory(VtRecipeCategoryDefinition category, List<VtRecipeDefinition> results)`	Fill `results` with the catalog’s recipes in `category`, lowest `Sort Weight` first, then in catalog order. A null category lists the recipes that have none.

VtResourcePoolConfig

Serializable struct.

Inspector-authored configuration for one VtResourcePool on a unit. A VtUnitDefinition carries an array of these; at spawn, VtUnitStats instantiates a live VtResourcePool for each entry using these values as seeds.

Inspector fields

Field	Type	Default	Range	Description
Kind (`kind`)	VtResourceKind	`HP`		Kind of resource (HP / MP / Stamina / Rage / …).
Base Max (`baseMax`)	`int`	0	≥ 0	Base max value before modifiers. The live Max resolves as VtUnitModifiers.Apply(maxStat, baseMax).
Starting Current (`startingCurrent`)	`int`	0	≥ 0	Starting current value. Usually equal to baseMax; set lower for units that start wounded.
Regen Mode (`regenMode`)	VtRegenMode	`None`		How and when this pool regenerates.
Base Regen Per Second (`baseRegenPerSecond`)	`float`	0	≥ 0	Starting regen-rate baseline (per second) before modifiers. Final rate = this + VtUnitModifiers.Get(regenStat).

Scripting API

Member	Description
`VtStatDefinition maxStat`	Optional per-pool override for the Max-scaling stat. Leave null and the kind→stat binding on VtCoreStats supplies the right asset (HP → MaxHp, etc.). Hidden by default — set programmatically only when one specific unit needs a custom max-scaling stat (e.g. a boss whose MaxHp scales off a tagged stat).
`VtStatDefinition regenStat`	Optional per-pool override for the Regen-scaling stat. Leave null and the kind→stat binding on VtCoreStats supplies the right asset. Hidden by default; see maxStat for the override use case.

VtItemModifier

Serializable struct.

A single stat modification that an item / buff / perk / innate provides to a unit. Summed into VtUnitModifiers’s two channels (flat and percent) per VtStatDefinition reference, then applied by consumers as (base + flatSum) * (1 + percentSum).

Inspector fields

Field	Type	Default	Description
Stat (`stat`)	VtStatDefinition	None	Which stat this entry modifies. Pick from the dropdown of every VtStatDefinition asset in the project (core + consumer-authored).
Value (`value`)	`float`	0	If isPercentage is false, added flat. If true, treated as a fraction (0.10 = +10%).
Is Percentage (`isPercentage`)	`bool`	Off	Flat (false) → added to base. Percentage (true) → multiplied against (base + flatSum).

VtAttributeGrant

Serializable struct.

One contribution to a unit’s primary-attribute total, flat or percent. Unit definitions use it for the starting attributes, items for “+5 Strength” bonuses, and buffs for temporary grants.

Inspector fields

Field	Type	Default	Description
Attribute (`attribute`)	VtAttributeDefinition	None	Which primary attribute this grant contributes to. Pick from the dropdown of every VtAttributeDefinition asset in the project.
Value (`value`)	`float`	0	If isPercentage is false, added flat. If true, a fraction of the resolved total (0.10 = +10%).
Is Percentage (`isPercentage`)	`bool`	Off	Flat (false) — adds to the attribute’s point total. Percentage (true) — scales the resolved total by (1 + sum of percent grants).

VtAttributeGrowth

Serializable struct.

Per-level growth rate for a single primary attribute — “+2 Strength per level”, “+1.5 Intelligence per level”. Authored on VtUnitDefinition. VtAttributeDerivedStatsBinding reads this on enable and on every level-up, projecting (level - 1) * perLevel into the primary-attribute channel under source id "attr_growth".

Inspector fields

Field	Type	Default	Description
Attribute (`attribute`)	VtAttributeDefinition	None	Which primary attribute grows each level. Drag in an VtAttributeDefinition asset.
Per Level (`perLevel`)	`float`	0	Attribute points gained per level above 1. Typical ranges - primary attribute 2.0-3.0, secondary 1.0-1.5. Zero disables growth for this attribute without removing the row.

VtTraitOverride

Serializable struct.

One categorical trait override — declared on a buff / item / innate so that the VtUnitTraits aggregator can pick the highest-priority non-null value for each VtTraitKey.

Inspector fields

Field	Type	Default	Description
Key (`key`)	VtTraitKey	`VtMovementType`	Which trait this entry sets.
Priority (`priority`)	`int`	0	Priority — highest wins if multiple sources write the same key. Innate defaults = 0, equipped items ≈ 100, buffs ≈ 200.
Movement Value (`movementValue`)	VtMovementType	`Walk`	For VtMovementType trait.
Armor Value (`armorValue`)	VtArmorType	`Unarmored`	For VtArmorType trait.
Attack Value (`attackValue`)	VtAttackType	`Normal`	For VtAttackType trait.
Damage Value (`damageValue`)	VtDamageType	`Physical`	For VtDamageType trait (e.g. convert-to-fire buff).
Bool Value (`boolValue`)	`bool`	Off	For CanAct / CanMove / CanCast bool traits.

VtTickEffect

Serializable struct.

Describes a periodic “tick” that runs while a buff is active — damage-over-time (poison, bleed, burn) or heal-over-time (regeneration aura). VtUnitBuffs schedules the tick and routes the resulting damage through the normal VtUnitStats.TakeDamage pipeline so resistances / armor / hooks all apply naturally.

Inspector fields

Field	Type	Default	Range	Description
Amount Per Tick (`amountPerTick`)	`float`	0	≥ 0	Damage (or heal if isHeal=true) applied per tick. 0 = disabled.
Interval (`interval`)	`float`	0	≥ 0	Seconds between ticks. 0 = disabled.
Damage Type (`damageType`)	VtDamageType	`Physical`		Element routed through the target’s resistance channel. Use True to bypass mitigation.
Attack Type (`attackType`)	VtAttackType	`Normal`		Matrix axis for the tick. Default-flat matrix → no impact unless your game extends VtAttackType + populates matrix cells.
Channel (`channel`)	VtDamageChannel	`Melee`		Class channel for the tick — Magic for spell-class DoTs/HoTs (default), Melee/Ranged for weapon-class bleeds. Drives power-stat scaling.
Is Heal (`isHeal`)	`bool`	Off		When true, ticks call Heal instead of TakeDamage. VtDamageType is still used to tag the heal source for any ‘increased fire healing’ edge cases.
Can Crit (`canCrit`)	`bool`	Off		If true, each tick rolls crit from the applier’s stat.crit_chance and amplifies by stat.crit_multiplier (+ VtCombatConstants.DefaultCritMultiplier). Applies to both DoT ticks (damage) and HoT ticks (heal). Off by default — only buffs whose author explicitly wants per-tick crit variance turn it on.

Scripting API

Member	Description
`bool IsActive { get; }`	Whether this tick effect is effectively enabled.

VtSplashSpec

Serializable struct.

Declarative specification of a splash / AoE effect. Lives on weapons (ItemDefinition.splash), innate attacks (VtUnitDefinition.splash), and projectiles (VtProjectileSpec.splash). A radius of 0 means “no splash (single-target)”.

Inspector fields

Field	Type	Default	Range	Description
Radius (`radius`)	`float`	0	≥ 0	World-space radius around the impact point. 0 = single-target.
Falloff (`falloff`)	`AnimationCurve`	None		Damage-multiplier curve. x axis [0,1] = normalized distance from impact, y axis [0,1] = fraction of primary damage delivered. Default curve = 1→0 linear.
Friendly Fire (`friendlyFire`)	`bool`	Off		If false, units sharing the attacker’s VtFaction are skipped.
Target Mask (`targetMask`)	`LayerMask`	Nothing		Which physics layers to scan for targets. Set to the unit collider layers.
Cone Angle (`coneAngle`)	`float`	0	0 to 360	Full cone angle in degrees. 360 (default) = full circle (bomb / fireball). < 360 = cone in front of attacker (cleave / whirlwind). Candidates whose angle from attacker.forward exceeds coneAngle/2 are skipped. Ignored when the attacker is null (environmental splash — always full circle).

Scripting API

Member	Description
`bool IsActive { get; }`	True if this spec represents an active splash effect.
`float EffectiveConeAngle { get; }`	The cone angle in effect: 0 (unset) and 360 both mean a full circle; any value in between is a cleave cone in front of the attacker.

VtProjectileSpec

Serializable struct.

Declarative config for a ranged attack’s visible projectile. Lives on innate unit attacks (VtUnitDefinition.projectile) and can be overridden per-weapon by items via VtTraitKey.ProjectileKind.

Inspector fields

Field	Type	Default	Range	Description
Prefab (`prefab`)	`GameObject`	None		Visual prefab spawned at the attacker’s muzzle. Must carry a projectile-driver component. Leave null for instant-hit / hitscan attacks.
Speed (`speed`)	`float`	0	≥ 0	Travel speed in world units / second. Final speed = this + VtUnitModifiers.Get(ProjectileSpeed stat).
Arc Height (`arcHeight`)	`float`	0	≥ 0	Parabolic arc peak height in world units. 0 = straight line (arrow / bullet). >0 = ballistic arc (catapult / lobbed spell). Peak occurs at the midpoint of the travel path.
Homing (`homing`)	`bool`	Off		If true, the projectile tracks the target each frame — adjusts direction to follow moving targets (homing missile, guided arrow). If false, it flies straight toward the target’s position at launch (arrow, bullet) — target can dodge by moving. Arcing + homing combo is supported but looks physically odd; prefer one or the other per projectile.

Scripting API

Member	Description
`bool IsActive { get; }`	True if this spec describes a travelling projectile (prefab assigned).

VtDamageInfo

Class.

The per-hit damage payload carried through the damage pipeline. A class, not a struct — so mutation hooks (VtUnitStats.OnPreTakeDamage, VtUnitStats.OnPreDealDamage) can convert element, accumulate absorb, or cancel the hit entirely.

Scripting API

Member	Description
`float rawAmount`	Damage amount after crit multiplication, before mitigation. Mutated in place by the pipeline (resistance, matrix, armor, absorb) and finally rounded to an int for HP subtraction.
`VtDamageType type`	Element of the attack. Routes through the corresponding `ResistX` stat. `VtDamageType.True` bypasses all mitigation.
`VtAttackType attackType`	Matrix axis. Keyed with the defender’s `VtArmorType` into the `VtDamageMatrix` for a multiplier. Default is `VtAttackType.Normal`; consumers extend the enum + populate matrix cells for unit-counter mechanics. Pure RTS-flavor; default flat matrix means this field is a tag with no damage-math impact.
`VtDamageChannel channel`	RPG class channel — Melee, Ranged, or Magic. Hardwired axis that drives power scaling in the pipeline (Magic → spellPower; Melee / Ranged → physicalPower), gear restrictions, animation hooks, and procs that key off “what kind of attack was this.” Independent of `attackType`: a poisoned dagger is `channel = Melee, attackType = Normal`; a fireball is `channel = Magic, attackType = Normal`.
`VtDamageSource source`	How this damage was delivered (melee / ranged / ability / DoT / …). Used by procs and conditional modifiers.
`VtAbilityDefinition ability`	Ability that produced this damage, when one did. Presenters play its impact cue on the target.
`VtUnitId attacker`	Id of the attacking unit, or `VtUnitId.None` for environmental. Resolved via `VtUnitRegistry.Resolve` when a live reference is needed.
`Vector3 hitPoint`	World-space impact point (for VFX / floating-number anchor).
`float absorbed`	Damage pre-consumed by absorb / shield subscribers to `VtUnitStats.OnPreTakeDamage`. The pipeline subtracts this before rounding.
`bool wasCrit`	True if the attacker’s crit roll succeeded. Set by the attacker side before calling `VtUnitStats.TakeDamage`.
`bool ignoreArmor`	If true, the armor-reduction step is skipped. Useful for piercing mechanics that bypass the `Armor` stat but still respect resistance.
`bool isTickDamage`	Flag set by tick effects (DoT/HoT). The pipeline skips the evade roll for tick damage — DoTs always land once they’re applied.
`bool tickCanCrit`	If true, a tick-damage hit is still eligible for the crit roll. Set by `VtBuffScheduler` from `VtTickEffect.canCrit` when the buff’s tick author opted in. Has no effect on non-tick damage, which always rolls crit.
`bool cancelled`	A pre-hook may set this to `true` to drop the hit entirely (block / immunity / phase-out). The pipeline fires `VtUnitStats.OnPostTakeDamage` for accounting and returns 0.
`int appliedDamage`	Final integer damage applied to HP after the pipeline completes. Set by `VtUnitStats.TakeDamage` just before firing `VtUnitStats.OnPostTakeDamage` so UI / log subscribers can read it.

VtUnitId

Serializable struct.

Stable identity for a VtUnit that is safe to store in cross-system data (VtDamageInfo.attacker, event args, log entries). The underlying value has no semantic meaning other than “unique per live unit in this process”.

Scripting API

Member	Description
`bool IsValid { get; }`	True for any id other than `None`.
`static readonly VtUnitId None`	“No unit”: the attacker of environmental damage, or an unknown source.
`readonly int Value`	Raw integer id. Do not derive meaning from its magnitude.

VtUnitRegistry

Static class.

Resolves VtUnitId values to live VtUnit instances. Units register when they are enabled or seeded and unregister when disabled or destroyed; entries whose unit was destroyed without either callback are dropped the next time the registry is read, so All never yields a dead unit.

Scripting API

Member	Description
`static int Count { get; }`	Number of live units.
`static IEnumerable<VtUnit> All { get; }`	Every live unit. Destroyed units are skipped and pruned.
`static VtUnitId Register(VtUnit unit)`	Allocate a fresh id for `unit`.
`static void Unregister(VtUnitId id)`	Remove the mapping for `id`. No-op when unknown.
`static VtUnit Resolve(VtUnitId id)`	The live unit for `id`, or null when unknown or destroyed. Callers must null-check: a stale id from a delayed callback is expected.
`static void Prune()`	Drop entries whose unit has been destroyed.

VtFactionRules

Static class.

The one rule the package uses to decide whether two factions fight: different factions are hostile unless either side is VtFaction.Neutral. Neutral units (resource nodes, vendors, critters) never attack and are never attacked on sight; the player must target them deliberately, which CanAttackOnCommand decides.

Scripting API

Member	Description
`static bool AreHostile(VtFaction a, VtFaction b)`	True when units of faction `a` and `b` attack each other on sight.
`static bool CanAttackOnCommand(VtFaction attacker, VtUnit target)`	True when a unit of faction `attacker` may attack `target` on a deliberate command such as a right-click or an attack order: the factions are hostile, or a component on the target implements `IVtCommandAttackable` and accepts the attacker. Resource nodes accept every attacker until they are depleted.

IVtAttackable

Interface. Implemented by VtUnit.

Marker contract: anything the player / AI can target for damage. Implemented by VtUnit (players, enemies, NPCs) and by non-unit damageables (destructible buildings, training dummies, props). Interaction systems work against this interface rather than concrete unit classes.

Scripting API

Member	Description
`Transform Transform { get; }`	World-space transform used for positioning / distance checks.
`bool CanBeAttacked { get; }`	False to refuse attacks (already dead, phase-invulnerable, owned by same team, etc.).
`int TakeDamage(int damage)`	Apply flat damage. Returns the amount actually dealt (for hit feedback / XP).

IVtCommandAttackable

Interface. Implemented by VtResourceNode.

A component on a unit that lets players attack the unit on purpose although its faction is not hostile to them. Resource nodes implement it so a right-click or an attack order chops a Neutral tree; implement it on props, doors or practice targets that should take deliberate attacks. It changes nothing about attacks on sight: idle units and AI still fight only hostile factions, see VtFactionRules.CanAttackOnCommand.

Scripting API

Member	Description
`bool CanBeAttackedOnCommand(VtFaction attacker)`	True when a unit of faction `attacker` may attack this unit on a deliberate command.

VtResourcePoolStatBinding

Serializable struct.

Maps a VtResourceKind to the VtStatDefinition assets that scale its pool’s Max and Regen values. Authored on VtCoreStats as the canonical kind→stat lookup so consumers don’t have to wire VtResourcePoolConfig.maxStat / VtResourcePoolConfig.regenStat on every VtUnitDefinition — selecting kind = HP already implies “use MaxHp / HpRegen.”

Inspector fields

Field	Type	Default	Description
Kind (`kind`)	VtResourceKind	`HP`	Resource kind this row applies to (HP / MP / Stamina / …).
Max Stat (`maxStat`)	VtStatDefinition	None	VtStatDefinition asset that scales the pool’s max value (e.g. MaxHp.asset). Leave empty if this kind has no max-scaling stat.
Regen Stat (`regenStat`)	VtStatDefinition	None	VtStatDefinition asset that scales the pool’s regen rate (e.g. HpRegen.asset). Leave empty if this kind doesn’t passively regen (Rage, ComboPoints, etc.).

VtAttributeFormula.Mapping

Serializable struct.

One contribution row — a single attribute’s per-point effect on a single derived stat.

Inspector fields

Field	Type	Default	Description
Source Attribute (`sourceAttribute`)	VtAttributeDefinition	None	Source primary attribute. Drag in an VtAttributeDefinition asset (Strength / Dexterity / Intelligence / …).
Target Stat (`targetStat`)	VtStatDefinition	None	Derived stat this row contributes to (drag in a VtStatDefinition asset: MaxHp.asset, DamageBonus.asset, CritChance.asset, …).
Per Point (`perPoint`)	`float`	0	Per-point contribution. Example: 10 means each source-attribute point grants 10 of the target stat.
Is Percentage (`isPercentage`)	`bool`	Off	If false, contribution is flat (adds to target). If true, contribution is a percentage fraction (0.01 = +1%).

Enums

VtFaction

Team or allegiance of a VtUnit. Units of different factions fight each other unless either is Neutral; AI targeting, splash damage and projectiles all respect it.

Value	Description
`Neutral`	Unaffiliated or ambient — not targeted, not hostile.
`Player`	The local player and their summons / pets.
`Enemy`	Scripted hostile units (waves, bosses).
`Wildlife`	Passive NPCs (deer, rabbits) — flee when attacked, don’t aggro.

VtCcCategory

Categorical label for crowd-control buffs. Authored on VtBuffDefinition.ccCategory; read by the apply-time immunity gate (VtUnit.IsImmuneTo) and by per-game UX systems (CC bar, breaking-CC procs, diminishing returns).

Value	Description
`None`	Not crowd control. Pure stat / damage buffs use this.
`Stun`	Cannot act (no movement, no cast, no attack). Bash / Hammer of Justice.
`Root`	Cannot move; can still attack and cast. Frost Trap / Entangling Roots.
`Silence`	Cannot cast spells / abilities; can move and auto-attack. Counterspell.
`Disarm`	Cannot use weapon / auto-attack; can still cast spells. Disarm shout.
`Fear`	Forced random / fleeing movement, no player input. Howl of Terror.
`Charm`	Faction temporarily flipped — unit fights on the caster’s side. Mind Control.
`Sleep`	Cannot act until damage breaks the effect. Sleep / Hibernate.
`Polymorph`	Visual transform + cannot act / cast (often heals while polymorphed). Polymorph.
`Slow`	Movement speed reduced. Slow / Frostbolt’s debuff. NOT a hard CC.
`Knockback`	Forced horizontal displacement. Shockwave / Death Grip-source.
`Knockup`	Forced vertical displacement (lifted off ground). Knockup.
`Taunt`	Forced target swap on AI controllers. Taunt / Mocking Blow.

VtDamageType

The element of an attack — routed through the corresponding resistX stat on VtCoreStats in VtUnitStats.TakeDamage.

Value	Description
`Physical`	Weapons, claws and falling rocks. Reduced by armor; resisted by stat.resist_physical.
`Fire`	Fire and burning. Resisted by stat.resist_fire.
`Cold`	Frost and ice. Resisted by stat.resist_cold.
`Poison`	Poison and venom, often dealt over time. Resisted by stat.resist_poison.
`True`	Bypasses all mitigation (resistance, armor, matrix). Use sparingly.
`Lightning`	Electricity / chain-lightning / EMP-flavor. Resisted by stat.resist_lightning.
`Holy`	Paladin / priest school. Strong vs undead in many genres. Resisted by stat.resist_holy.
`Shadow`	Warlock / necromancer school — corruption, agony, void. Resisted by stat.resist_shadow. Often paired oppositionally with Holy.
`Arcane`	Mage’s “raw magic” school — distinct from elemental. Magic missile, polymorph. Resisted by stat.resist_arcane. Conventionally hardest to resist.
`Nature`	Druid / shaman school — earth, plant, weather, wildlife. Resisted by stat.resist_nature.

VtAttackType

The matrix / unit-counter axis of a hit — paired with the defender’s VtArmorType in VtDamageMatrix to produce a multiplier. Pure RTS-flavor mechanic; default matrix is flat (every cell 1.0) for MMO/ARPG scope.

Value	Description
`Normal`	Default attack type. The matrix lookup against any armor type returns 1.0 (no multiplier) when the matrix is flat. Use as the catch-all when your game doesn’t care about unit-counter mechanics.

VtDamageChannel

The class / source channel of a hit — i.e. how it was delivered from the character-fantasy point of view. Hardwired and stable: the pipeline, gear procs, tooltips, and animation systems all key off these three values.

Value	Description
`Melee`	Touch-range weapon strikes — swords, daggers, fists, staves, hammers.
`Ranged`	Projectile / thrown weapons — bows, guns, throwing knives, javelins.
`Magic`	Casted spells — bolts, novas, missiles, channels, curses.

VtArmorType

The defender-side armor classification — paired with the attacker’s VtAttackType in the VtDamageMatrix for a multiplier. Default matrix is flat (MMO scope), so these values mainly serve as categorical tags (gear tiers, loot filters, encounter design) that content systems can read without the matrix affecting damage math.

Value	Description
`Unarmored`	No armor — naked, cloth-less. Mage robe / clothwearer default.
`Light`	Leather, padded — light caster / rogue armor.
`Medium`	Chainmail, scale — mid-tier hunter / shaman armor.
`Heavy`	Plate — warrior / paladin armor.

VtResourceKind

The kind of a resource pool on a unit, such as health, mana, stamina or rage. A unit definition lists the pools it has; read one with VtUnitStats.GetPool.

Value	Description
`HP`	Health. The unit dies when it reaches 0.
`MP`	Mana, spent by spells.
`Stamina`	Stamina, spent by physical actions such as sprinting or dodging.
`Rage`	Rage, built by dealing and taking damage rather than regenerating.
`Focus`	Focus, a small fast-refilling pool for ranged or precise actions.
`Energy`	Energy, a fixed-size pool that refills quickly.
`ComboPoints`	Combo points, built by some abilities and spent by finishers.
`Charges`	Charges, discrete uses that refill one at a time.
`Hunger`	Food pool: decreases over time, damages HP when empty.
`Thirst`	Water pool: decreases over time, damages HP when empty.
`Shield`	Secondary HP layer — sci-fi / mage-barrier style. Regenerates out of combat (per the configured `VtRegenMode`); takes damage before HP only when consumer code wires that interception (typically via an `VtUnitStats.OnPreTakeDamage` hook). Pair with `stat.max_shield` / `stat.shield_regen`.

VtTraitKey

Keys used by VtUnitTraits to identify which categorical trait a VtTraitOverride is setting. Each key corresponds to a specific value type that consumers expect back when reading; mismatching types is a programmer error.

Value	Description
`VtMovementType`	How the unit moves; the value is a `global::VtMovementType`.
`VtArmorType`	The unit’s armor type; the value is a `global::VtArmorType`.
`VtAttackType`	The unit’s attack type; the value is a `global::VtAttackType`.
`VtDamageType`	The element of the unit’s attacks, for “your attacks deal Fire” buffs; the value is a `global::VtDamageType`.
`ProjectileKind`	The projectile the unit’s basic attack fires; the value is a `VtProjectileSpec`.
`Splash`	Splash damage on the unit’s attacks; the value is a `VtSplashSpec`.
`CanAct`	Can the unit take ANY action (attack, cast, move)? Stun = false.
`CanMove`	Can the unit move? Root = false (but can still attack/cast).
`CanCast`	Can the unit cast spells / abilities? Silence = false.

VtStackingPolicy

How a new application of a buff interacts with an existing instance of the same VtBuffDefinition. Resolved inside VtUnitBuffs.ApplyBuff.

Value	Description
`Unique`	If already present, do nothing. The existing buff keeps its remaining duration.
`Refresh`	If already present, reset the duration to the new value but don’t add a second instance. Most common policy for re-applied DoTs.
`StackIndependent`	Always add another independent instance. Each instance ticks and expires separately. Used when a DoT from two different attackers should stack.
`StackAddDuration`	If already present, add the new duration to the remaining duration (capped by the buff’s `maxDuration` if set). Classic RPG “stack duration” rule.

VtRegenMode

Describes how a VtResourcePool refills over time. Picked per-pool per-unit in the VtResourcePoolConfig so e.g. HP trickles passively, Rage generates on attack, and Stamina refills only when out of combat.

Value	Description
`None`	No automatic regen. Only external calls (potions, abilities) restore it.
`Passive`	Always regenerates at the `regenStat` rate (per second).
`CombatOnly`	Regenerates only while the unit is in combat — used for resources like Rage / Energy that build up while fighting.
`OutOfCombatOnly`	Regenerates only while the unit is OUT of combat — classic resting-heals rule for Stamina / HP in many RPGs.
`OnActionGenerated`	Does not passively tick — instead is generated by specific actions (landing an attack, dodging, spending another resource). Callers push into it via `VtResourcePool.Restore` at the action site.

VtMovementType

Categorical movement capability — resolved via VtUnitTraits under VtTraitKey.VtMovementType. A binding component (e.g. MovementTypeBinding) reads the current value and configures the pathfinder accordingly (flyers ignore cliffs, swimmers navigate water, etc.).

Value	Description
`Walk`	Moves on the ground and is blocked by cliffs and obstacles.
`Fly`	Flies over terrain and obstacles.
`Swim`	Moves through water.
`Hover`	Floats just above the ground, over water and low obstacles.

VtDamageSource

Classifies how a piece of damage was delivered: a melee or ranged attack, an ability, damage over time, reflection or the environment. Carried on every VtDamageInfo so procs, conditional bonuses and UI can tell hits apart.

Value	Description
`None`	Unknown / unset. Treat as generic damage.
`MeleeAttack`	Basic melee attack from a weapon or unarmed.
`RangedAttack`	Basic ranged attack (bow, thrown weapon).
`Ability`	Active spell / skill / ability damage (usually consumes MP or a charge).
`DoT`	Periodic damage tick from a `VtBuffDefinition.tickEffect`.
`Reflection`	Damage reflected back at the attacker (thorns, retaliation, reactive spells).
`Environmental`	World damage — lava, spikes, fall damage, starvation.
`Splash`	A secondary hit from an AoE / splash resolution.