Leveling reference

The level and XP components every leveling unit and XP-giving enemy carries, and the XP curve asset. For how to use it, see Leveling.

VtUnitLevel

Component. Add it with Add Component → Vantage → Leveling → VtUnitLevel.

Per-unit level and XP tracker. Added automatically when the unit definition has an VtUnitDefinition.xpCurve; add it yourself on a prefab-authored unit. Units that never level (most NPCs) go without it.

Inspector fields

Field	Type	Default	Range	Description
Curve (`curve`)	VtXpCurveDefinition	None		XP curve this unit progresses on. Filled from the unit definition’s XP Curve when the unit spawns; assign it here for prefab-authored units.
Starting Level (`startingLevel`)	`int`	1	≥ 1	Starting level for fresh units. Most games start at 1; some prologues open at higher levels (5, 10) to skip onboarding XP.

Scripting API

Member	Description
`int Level { get; }`	The unit’s current level. Initialized to `startingLevel` on first `Awake`; mutated by `AddXp` / `SetLevel`.
`int CurrentXp { get; }`	Accumulated XP since the last level-up. Always less than the XP needed for the next level (excess is consumed by leveling).
`int XpToNextLevel { get; }`	XP needed to advance from `Level` to the next level. 0 when the unit is at the curve’s max level.
`bool IsMaxLevel { get; }`	True when the unit has reached the curve’s `maxLevel` and further XP gains are dropped.
`event Action<int, int> OnLeveledUp`	Fires once after every `AddXp` call that produces at least one level-up. Args: (oldLevel, newLevel). For multi-level jumps fires once with the full old → new range; subscribe and walk `(oldLevel + 1)..newLevel` if you need per-level work.
`event Action<int, int, int> OnXpChanged`	Fires after any mutation to `CurrentXp` (gain or reset), AFTER any level-ups have been applied. Args: (currentLevel, currentXp, xpToNext). Use for XP-bar UI.
`void Initialize()`	Seed `Level` from `startingLevel` the first time it’s called; subsequent calls are no-ops. Mid-run re-seeds (re-applying the same definition on respawn, swapping definitions) preserve the unit’s current level rather than resetting to 1.
`void SeedFromDefinitionStartingLevel(int startingLevelFromDef)`	Apply a unit definition’s starting level. The first call sets the level to `startingLevelFromDef`; later calls only update `startingLevel`, so respawns and definition swaps keep the current level.
`void AddXp(int amount)`	Credit experience from gameplay (kills, quest turn-ins). Scales `amount` by 1 plus the unit’s XP gain multiplier stat (`VtCoreStats.xpGainMultiplier`), then levels up as often as the total allows, firing `OnLeveledUp` once if any level was crossed. Authority-gated. Negative or zero amounts no-op.
`void AddXp(int amount, bool applyGainMultiplier)`	Credit experience with explicit control over the gain multiplier. Pass `applyGainMultiplier: false` for save-game restore, admin commands, or any flow that must credit exactly `amount`. Otherwise identical to `AddXp`.
`void SetLevel(int level)`	Force-set the unit’s level. Resets `CurrentXp` to 0. Authority-gated. Used by save-game restore, admin commands, mentor systems. Clamps to `[1, curve.maxLevel]`.
`void Reset()`	Wipe XP back to 0 but keep current level. Authority-gated.
`void RemoveXp(int amount)`	Take `amount` XP away within the current level. Never drops a level; stops at zero. A death penalty uses this.
`void ApplyLevelFromNet(int level, int xp)`	Net-replication entry point. Replaces both fields with the authoritative snapshot. Bypasses the authority gate. Fires `OnLeveledUp` if the level changed; always fires `OnXpChanged`.

VtXpAwarder

Component. Add it with Add Component → Vantage → Leveling → VtXpAwarder.

Awards xpAward when this unit dies: the killer, and party members who share the credit, split it through their VtUnitLevel. Added automatically when the unit definition sets an XP award.

Inspector fields

Field	Type	Default	Range	Description
Xp Award (`xpAward`)	`int`	0	≥ 0	XP credited to the killer on this unit’s death. 0 = no XP awarded (equivalent to not having the awarder attached). Filled from the unit definition’s XP Award when the unit spawns; set it here for prefab-authored mobs.

Scripting API

Member	Description
`void Initialize()`	Caches the sibling `VtUnitStats` reference and subscribes to `VtUnitStats.OnDied`. Idempotent — safe to call any number of times.

VtXpCurveDefinition

Asset. Create it with Create → Vantage → Leveling → XP Curve.

Authored XP-to-next-level curve. Designer drops in the per-level XP thresholds; the level component looks up “how much XP does the next level cost” and “what level am I at given a total XP value.”

Inspector fields

Field	Type	Default	Range	Description
Id (`id`)	`string`	Empty		Stable id used in logs and as a stable serialization key. Convention: ‘curve.’ (e.g. ‘curve.standard’, ‘curve.fast’, ‘curve.slow’). Required.
Display Name (`displayName`)	`string`	Empty		Designer-facing name. Shown in inspector dropdowns.
Description (`description`)	`string`	Empty		Designer-facing description (e.g. ‘Standard pacing — capped at 60 with 1.1x extrapolation past the array’).
Max Level (`maxLevel`)	`int`	60	≥ 1	Maximum level reachable on this curve. AddXp on a unit at maxLevel drops the excess silently. Default 60 — typical for most games.
Xp To Next Level (`xpToNextLevel`)	`int`[]	Empty		Per-level XP thresholds. Index 0 = XP to go from level 1 → 2. Index 1 = XP to go from level 2 → 3. Etc. Author 10–60 explicit values; extrapolation handles anything past the array (see extrapolatePercent).
Extrapolate Percent (`extrapolatePercent`)	`float`	0.1	0 to 5	When current level exceeds the array length, the threshold extrapolates as lastThreshold × (1 + extrapolatePercent × levelsPastArray). 0 = hard-cap at the array’s last entry. 0.1 = each level past the array costs 10% more than the previous. Used to soft-cap progression past the explicit values.

Scripting API

Member	Description
`int GetXpToNextLevel(int currentLevel)`	XP required to advance from `currentLevel` to `currentLevel + 1`. Returns 0 when the unit is already at `maxLevel` (no further progression possible).