Shared stash and costs reference

The shared stash and stash zone components, deposit filters, and the cost-source interface and helpers that building, crafting and unlocks pay through. For how to use it, see Shared stash and costs.

VtSharedStash

Component. Add it with Add Component → Vantage → Economy → VtSharedStash. Adds VtPersistentId automatically.

A pool of items, currency and unlocks that a group of units pays from together: the team’s stone and wood in a co-op survival game, one side’s resources in a strategy game. Place it in the scene; while it is enabled, every unit it serves builds, crafts and buys unlocks with what is in it instead of with its own bag and wallet, and refunds come back to it.

Inspector fields

Field	Type	Default	Description
Scope (`scope`)	VtStashScope	`Faction`	Faction serves every unit of the faction below. Members serves only the units in the member list.
Faction (`faction`)	VtFaction	`Player`	The faction this stash pays for when Scope is Faction.
Members (`members`)	List of VtUnit	Empty	The units this stash pays for when Scope is Members. Add more with AddMember.
Zone Tag (`zoneTag`)	VtUnitTagDefinition	None	Serve only units standing in a VtStashZone whose unit carries this tag, such as a camp around a campfire. Empty serves them anywhere.
Zone Same Faction Only (`zoneSameFactionOnly`)	`bool`	On	Only zones of the served unit’s own faction count.
Starting Items (`startingItems`)	VtRecipeIngredient[]	Empty	Items in the stash when the scene starts.
Starting Currency (`startingCurrency`)	VtCurrencyAmount[]	Empty	Currency in the stash when the scene starts.

Scripting API

Member	Description
`static IReadOnlyList<VtSharedStash> Active { get; }`	Every enabled stash, in the order they were enabled.
`VtStashScope Scope { get; set; }`	Which units the stash serves.
`VtFaction Faction { get; set; }`	The faction served when `Scope` is `VtStashScope.Faction`.
`IReadOnlyList<VtUnit> Members { get; }`	The units served when `Scope` is `VtStashScope.Members`.
`VtUnitTagDefinition ZoneTag { get; set; }`	With a tag, the stash serves units only while they stand in a `VtStashZone` whose unit carries it. Null serves them anywhere.
`bool ZoneSameFactionOnly { get; set; }`	Whether only zones of the served unit’s faction count.
`IReadOnlyDictionary<VtItemDefinition, int> Items { get; }`	Every item and its count.
`IReadOnlyDictionary<VtCurrencyDefinition, int> Currencies { get; }`	Every currency and its balance.
`IReadOnlyCollection<VtUnlockDefinition> Unlocks { get; }`	Every unlock bought with the stash.
`string Id { get; }`	The persistent id the stash is saved under.
`event Action OnChanged`	Fires after anything in the stash changed: items, currency or unlocks.
`static VtSharedStash For(VtUnit unit)`	The first enabled stash that serves `unit`, or null.
`static VtSharedStash Find(string id)`	The enabled stash saved under `id`, or null.
`bool Serves(VtUnit unit)`	Whether the stash pays for `unit`: the unit is in its scope and, with a `ZoneTag`, stands in a matching zone. The authority allows the interact tolerance from `VtTuning` at a zone’s edge, so a client never shows the stash where the server would not use it.
`bool InScope(VtUnit unit)`	Whether `unit` belongs to the stash’s scope (its faction, or its member list), ignoring `ZoneTag`.
`void AddMember(VtUnit unit)`	Serve `unit` while `Scope` is `VtStashScope.Members`. Membership is scene setup, not replicated state: call it on every process.
`void RemoveMember(VtUnit unit)`	Stop serving `unit`.
`void Initialize()`	Start serving units and add the starting contents once. Runs when the stash is enabled; safe to call more than once.
`int GetItemCount(VtItemDefinition item)`	How many of `item` the stash holds.
`int GetCurrency(VtCurrencyDefinition currency)`	How much of `currency` the stash holds.
`void AddItem(VtItemDefinition item, int count)`	Add `count` of `item`. Authority-gated.
`void AddCurrency(VtCurrencyDefinition currency, int amount)`	Add `amount` of `currency`. Authority-gated.
`bool TrySpendItem(VtItemDefinition item, int count)`	Take `count` of `item` from the stash. False, and nothing taken, when there are not enough. Authority-gated.
`bool TrySpendCurrency(VtCurrencyDefinition currency, int amount)`	Take `amount` of `currency` from the stash. False, and nothing taken, when there is not enough. Authority-gated.
`bool GiveItem(VtItemDefinition item, int count)`	Add `count` of `item` to the stash, for refunds and crafted results. The stash has no size limit, so this fails only on a process that is not the authority.
`void GiveCurrency(VtCurrencyDefinition currency, int amount)`	Add `amount` of `currency` to the stash, for refunds. Authority-gated.
`bool Deposit(VtUnit unit, VtItemDefinition item, int count)`	Move `count` of `item` from `unit`’s bag into the stash. False when the unit carries fewer. Refused for a unit the stash does not serve, such as one outside its zone. On the unit’s predicting client the request is forwarded to the authority and this returns false.
`bool DepositCurrency(VtUnit unit, VtCurrencyDefinition currency, int amount)`	Move `amount` of `currency` from `unit`’s wallet into the stash. False when the unit has less. Forwarded like `Deposit`.
`void DepositAll(VtUnit unit)`	Move everything in `unit`’s bag and wallet into the stash, such as when a worker returns to a drop-off point. Items that cannot be traded stay with the unit. Forwarded like `Deposit`.
`void DepositAll(VtUnit unit, VtStashDepositFilter filter)`	Move the part of `unit`’s bag and wallet that `filter` picks into the stash, such as only the items tagged Resource. Items that cannot be traded stay with the unit, and deposited items lose their wear. Forwarded like `Deposit`, as one command.
`bool HasUnlock(VtUnlockDefinition unlock)`	Whether `unlock` was bought with the stash.
`bool GrantUnlock(VtUnlockDefinition unlock)`	Record `unlock` as owned without paying for it, for rewards and admin tools. Authority-gated. `VtUnitUnlocks.TryUnlock` is the paid path.
`VtStashState CaptureState()`	Snapshot the contents by id, for save files and networking.
`void ApplyFromNet(VtStashState state, VtDefinitionCatalog catalog = null)`	Replace the contents with `state`, resolving ids through `catalog` (the shared catalog when null). Bypasses the authority gate: it is the replication and load path. Ids the catalog does not know are skipped with a warning.

VtStashZone

Component. Add it with Add Component → Vantage → Economy → VtStashZone. Adds VtUnit automatically.

Marks a unit as a place where a VtSharedStash with a Zone Tag serves: a campfire, a base, a drop-off point, a guild hall. A stash whose zone tag the unit carries serves units standing within radius of it on the ground plane. Put it on the placed piece’s prefab; a zone counts while its unit is alive and, unless countUnfinished is on, once its build site is finished.

Inspector fields

Field	Type	Default	Range	Description
Radius (`radius`)	`float`	10	≥ 0	How far from this unit the stash serves, on the ground plane, in world units.
Count Unfinished (`countUnfinished`)	`bool`	Off		Serve from here while the build site is still unfinished.

Scripting API

Member	Description
`static IReadOnlyList<VtStashZone> All { get; }`	Every enabled zone in the scene.
`VtUnit Unit { get; }`	The unit this zone is around.
`bool IsActive { get; }`	Whether the zone counts right now: its unit is alive, and its build site is finished unless `countUnfinished` is on.
`void Register()`	Make the zone count. Called from `OnEnable`; safe to call more than once.
`void Unregister()`	Stop the zone counting. Called from `OnDisable`; idempotent.
`bool Contains(Vector3 point, float tolerance)`	Whether `point` lies within `radius` plus `tolerance` on the ground plane, and the zone counts.
`static bool AnyContains(VtUnit unit, VtUnitTagDefinition tag, bool sameFactionOnly, float tolerance)`	Whether `unit` stands in any counting zone whose unit carries `tag`, of the same faction when `sameFactionOnly`.

VtStashDepositFilter

Serializable struct.

Which part of a unit’s bag and wallet VtSharedStash.DepositAll moves: “drop off my resources” keeps the tools and food in the pack. Serializable, so a drop-off point or a button can carry one in the Inspector.

Inspector fields

Field	Type	Default	Description
Tags (`tags`)	VtItemTagDefinition[]	Empty	Only items with at least one of these tags are deposited. Empty = every item that can be traded.
Include Currency (`includeCurrency`)	`bool`	Off	Also move every currency in the wallet.

Scripting API

Member	Description
`static VtStashDepositFilter Everything { get; }`	Every tradeable item and every currency, as `VtSharedStash.DepositAll` does.
`static VtStashDepositFilter ItemsTagged(params VtItemTagDefinition[] itemTags)`	Items that carry at least one of `itemTags`, without currency.
`bool Matches(VtItemDefinition item)`	Whether `item` passes the tag part of the filter.

IVtCostSource

Interface. Implemented by VtSharedStash, VtUnitCostSource.

Where a unit’s costs are paid from and its refunds go to: the unit’s own bag and wallet, a VtSharedStash a whole team draws from, or a pool of your own. Building, crafting and unlocking read and spend through it, so switching a game from “each player pays” to “the team pays” is a scene setup, not a code change.

Scripting API

Member	Description
`int GetItemCount(VtItemDefinition item)`	How many of `item` the source holds.
`int GetCurrency(VtCurrencyDefinition currency)`	How much of `currency` the source holds.
`bool TrySpendItem(VtItemDefinition item, int count)`	Take `count` of `item`. False, and nothing taken, when there are not enough.
`bool TrySpendCurrency(VtCurrencyDefinition currency, int amount)`	Take `amount` of `currency`. False, and nothing taken, when there is not enough.
`bool GiveItem(VtItemDefinition item, int count)`	Add `count` of `item`, for refunds and crafted results. False when it did not fit.
`void GiveCurrency(VtCurrencyDefinition currency, int amount)`	Add `amount` of `currency`, for refunds.

VtUnitCostSource

Class.

The default IVtCostSource: a unit pays from its own VtUnitInventory and VtUnitWallet. A missing inventory holds no items and a missing wallet holds no money.

Scripting API

Member	Description
`VtUnitInventory Inventory { get; }`	The bag items are paid from, or null.
`VtUnitWallet Wallet { get; }`	The wallet money is paid from, or null.
`int GetItemCount(VtItemDefinition item)`	How many of `item` the unit’s bag holds; 0 without a bag.
`int GetCurrency(VtCurrencyDefinition currency)`	How much of `currency` the unit’s wallet holds; 0 without a wallet.
`bool TrySpendItem(VtItemDefinition item, int count)`	Take `count` of `item` from the unit’s bag. False, and nothing taken, when there are not enough.
`bool TrySpendCurrency(VtCurrencyDefinition currency, int amount)`	Take `amount` of `currency` from the unit’s wallet. False, and nothing taken, when there is not enough.
`bool GiveItem(VtItemDefinition item, int count)`	Add `count` of `item` to the unit’s bag, for refunds and crafted results. False when they did not all fit.
`void GiveCurrency(VtCurrencyDefinition currency, int amount)`	Add `amount` of `currency` to the unit’s wallet, for refunds.

VtCostSources

Static class.

Picks the IVtCostSource a unit pays from, and checks, spends and refunds item and currency cost lists against any source.

Scripting API

Member	Description
`static IVtCostSource Resolve(VtUnit unit)`	The source `unit` pays from: the stash that serves it, or its own bag and wallet. Null for a null unit.
`static bool HasItems(IVtCostSource source, VtRecipeIngredient[] items)`	Whether `source` holds every item in `items`. Empty entries are skipped.
`static bool HasCurrency(IVtCostSource source, VtCurrencyAmount[] currencies)`	Whether `source` holds every amount in `currencies`. Empty entries are skipped.
`static void SpendItems(IVtCostSource source, VtRecipeIngredient[] items)`	Take every item in `items` from `source`. Check `HasItems` first.
`static void SpendCurrency(IVtCostSource source, VtCurrencyAmount[] currencies)`	Take every amount in `currencies` from `source`. Check `HasCurrency` first.
`static void Refund(IVtCostSource source, VtRecipeIngredient[] items, VtCurrencyAmount[] currencies, float fraction)`	Give back `fraction` of each item and amount, rounded down.

VtStashState

Serializable class.

What a VtSharedStash holds, by id, for save files and networking.

Inspector fields

Field	Type	Default	Description
Stash Id (`stashId`)	`string`	Empty	The persistent id of the stash this state belongs to.
Items (`items`)	VtItemStackSave[]	Empty	Items in the stash, by item id and count.
Currencies (`currencies`)	VtCurrencySave[]	Empty	Currency balances in the stash, by currency id.
Unlocks (`unlocks`)	`string`[]	Empty	Ids of the unlocks bought with the stash.

VtItemStackSave

Serializable struct.

One backpack stack.

Inspector fields

Field	Type	Default	Description
Item Id (`itemId`)	`string`	Empty	Id of the item definition.
Count (`count`)	`int`	0	Number of items in the stack.
Wear (`wear`)	`int`	0	Durability the stack’s items have lost. 0 for new items.
Extra Durability (`extraDurability`)	`int`	0	Durability that combined copies added to the stack’s item. 0 for a single copy.
Area (`area`)	`string`	Empty	Id of the inventory area the stack sits in. Empty for the default bag.
Slot (`slot`)	`int`	0	Position of the stack in its area.

VtCurrencySave

Serializable struct.

One currency balance.

Inspector fields

Field	Type	Default	Description
Currency Id (`currencyId`)	`string`	Empty	Id of the currency definition.
Amount (`amount`)	`int`	0	The balance.

Enums

VtStashScope

Which units a VtSharedStash pays for.

Value	Description
`Faction`	Every unit of the stash’s faction: all players in a co-op game, one side in a strategy game.
`Members`	Only the units added to the stash’s member list, from the Inspector or with `VtSharedStash.AddMember`.

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.