Currency reference

The wallet component, the currency asset, and the fixed amounts and drop ranges other modules use for prices, costs and loot. For how to use it, see Currency.

VtUnitWallet

Component. Add it with Add Component → Vantage → Currency → VtUnitWallet.

Opt-in per-unit wallet: the balance of every VtCurrencyDefinition the unit holds. Add it to units that earn or spend money, such as players and merchants. Changes are authority-gated, and ApplyWalletFromNet mirrors the authority’s balances on other copies.

Scripting API

Member	Description
`IReadOnlyDictionary<VtCurrencyDefinition, int> Balances { get; }`	Read-only view of every (currency, balance) pair currently tracked. Iteration order is unspecified; sort by `VtCurrencyDefinition.sortWeight` in your UI layer.
`event Action<VtCurrencyDefinition, int> OnChanged`	Fires after any balance change. Args: (currency, newBalance). Subscribe for UI updates / quest tracking (“collect 100 gold”).
`int Get(VtCurrencyDefinition currency)`	Current balance for the given currency. Returns 0 for currencies the wallet has never seen — distinguish “owned 0” from “never owned” via `Balances`.`ContainsKey` if you need the difference.
`bool CanAfford(VtCurrencyDefinition currency, int amount)`	True when the wallet can afford `amount` of `currency`. Use before invoking the spend flow so vendors / repair / training can show “not enough gold” UI without attempting the deduction.
`void Add(VtCurrencyDefinition currency, int amount)`	Credit `amount` of `currency`. Authority-gated. Negative amounts no-op (use `TryRemove` or `Set` for deductions). Fires `OnChanged`.
`bool TryRemove(VtCurrencyDefinition currency, int amount)`	Try to spend `amount` of `currency`. Returns true on success, false (and no mutation) when the wallet can’t afford it. Authority-gated.
`void Set(VtCurrencyDefinition currency, int value)`	Force-set the balance to an absolute value. Authority-gated. Used by save-game restore, admin commands, and net replication’s authoritative-rebroadcast path. Negative values clamp to 0.
`void Clear()`	Wipe every balance — typically for new-character creation / admin reset. Authority-gated. Fires `OnChanged` per cleared currency so UI can update incrementally.
`void ApplyWalletFromNet(IReadOnlyDictionary<VtCurrencyDefinition, int> snapshot)`	Net-replication entry point. Replaces the wallet with the authoritative snapshot. Bypasses the authority gate. Fires `OnChanged` for every currency whose balance differs from before the mirror.

VtCurrencyDefinition

Asset. Create it with Create → Vantage → Currency → Currency.

Authored currency type — the SO that names a currency, gives it an inspector colour, and defines its sort priority. Multi-currency games (gold + honor + marks + premium) author one per type and the wallet tracks each independently.

Inspector fields

Field	Type	Default	Description
Id (`id`)	`string`	Empty	Stable id used in logs and as a stable serialization key. Convention: ‘currency.’ (e.g. ‘currency.gold’, ‘currency.honor’). Required.
Display Name (`displayName`)	`string`	Empty	Designer-facing name. Shown in inspector dropdowns and wallet UI (consumer-side; library exposes the value, consumer renders it).
Description (`description`)	`string`	Empty	Designer-facing description. Doesn’t affect runtime behavior.
Icon (`icon`)	`Sprite`	None	Icon for inspector + wallet UI. Optional.
Icon Id (`iconId`)	`string`	Empty	Name of an icon from the package’s icon set (VtIcons), used when Icon is empty. Optional.
Color (`color`)	`Color`	`#FFFFFFFF`	Inspector tint colour (UI text, drop labels). Default white.
Sort Weight (`sortWeight`)	`int`	0	Sort priority for wallet UI iteration order. Lower = appears first (gold before silver before premium). Authoring convention: 0/100/200/300 tiers leave room to insert intermediate currencies later without renumbering.

VtCurrencyAmount

Serializable struct.

Fixed (currency, amount) pair — for cost / price / fee values that don’t have an RNG range (build costs, vendor prices, repair fees). Distinct from VtCurrencyDropEntry which has min/max for loot rolls.

Inspector fields

Field	Type	Default	Range	Description
Currency (`currency`)	VtCurrencyDefinition	None		Currency type. Required — pair silently no-ops if null.
Amount (`amount`)	`int`	0	≥ 0	Amount. 0 = free / no-op for cost contexts.

VtCurrencyDropEntry

Serializable struct.

One currency-drop row on a VtLootTableDefinition. Always-emit (no weighted competition); the amount rolls between minAmount and maxAmount, both included.

Inspector fields

Field	Type	Default	Range	Description
Currency (`currency`)	VtCurrencyDefinition	None		Currency to credit on death. Required — entry is silently skipped if null.
Min Amount (`minAmount`)	`int`	0	≥ 0	Minimum amount credited. Inclusive. The actual amount rolls in [min, max] per drop.
Max Amount (`maxAmount`)	`int`	0	≥ 0	Maximum amount credited. Inclusive. Equal to minAmount = always credits exactly that amount.