Saving and loading reference

The persistent id component, the save data a scene and a unit are captured into, and the calls that capture, restore and write saves. For how to use it, see Saving and loading.

VtPersistentId

Component. Add it with Add Component → Vantage → Save → VtPersistentId.

A stable id that survives save and load. Put it on every unit that should be saved: the player, NPCs, resource nodes, anything scene-placed you want remembered. The id is generated when the component is added; give the player a readable one such as player so your code can find it.

Inspector fields

Field	Type	Default	Description
Id (`id`)	`string`	Generated	Stable id for save files. Generated when empty; edit it for units you look up by name.

Scripting API

Member	Description
`string Id { get; }`	The id.
`void Assign(string newId)`	Set the id from code, for units spawned at runtime.

VtSaveGame

Serializable class.

A whole save: every persistent unit in a scene.

Inspector fields

Field	Type	Default	Description
Version (`version`)	`int`	1	Format version, for your own migrations.
Scene (`scene`)	`string`	Empty	Scene the save was taken in.
Saved At (`savedAt`)	`string`	Empty	UTC time of the save in ISO 8601, for slot pickers.
Units (`units`)	List of VtUnitSaveData	Empty	Every unit with a VtPersistentId at save time.
Has World Time (`hasWorldTime`)	`bool`	Off	On when the scene had a VtWorldClock at save time.
World Time (`worldTime`)	VtWorldClockState	—	The scene clock at save time: day, time of day, speed and pause state.
Stashes (`stashes`)	List of VtStashState	Empty	What every enabled shared stash held at save time.

VtUnitSaveData

Serializable class.

Everything the package knows about one unit, with definitions referenced by id. Produced by VtUnitSaver.Capture, consumed by VtUnitSaver.Restore, and serializable with JsonUtility. Empty arrays mean the unit has no such component.

Inspector fields

Field	Type	Default	Description
Persistent Id (`persistentId`)	`string`	Empty	Id of the unit’s VtPersistentId, used to find it again on load.
Definition Id (`definitionId`)	`string`	Empty	Id of the unit definition, checked on restore.
Buildable Id (`buildableId`)	`string`	Empty	Id of the buildable this unit was placed from, so a missing building can be spawned again. Empty for other units.
Paid From Stash Id (`paidFromStashId`)	`string`	Empty	Id of the shared stash that paid for the placed piece; empty when none did.
Position (`position`)	`Vector3`	(0, 0, 0)	World position of the unit.
Rotation (`rotation`)	`Quaternion`	—	World rotation of the unit.
Has Level (`hasLevel`)	`bool`	Off	On when the unit has a level component; level and xp are only used then.
Level (`level`)	`int`	0	The unit’s level.
Xp (`xp`)	`int`	0	XP gathered since the last level-up.
Pools (`pools`)	VtPoolSave[]	Empty	Current value of each resource pool.
Equipment (`equipment`)	VtEquipmentSave[]	Empty	Equipped items with their durability.
Inventory (`inventory`)	VtItemStackSave[]	Empty	Backpack stacks with their area and slot.
Inventory Has Slots (`inventoryHasSlots`)	`bool`	Off	On when the inventory entries carry slot positions. Off fills the bag slots in order.
Held Area (`heldArea`)	`string`	Empty	Area of the held slot selection; empty when nothing is selected.
Held Slot (`heldSlot`)	`int`	0	Slot of the held slot selection in the held area.
Wallet (`wallet`)	VtCurrencySave[]	Empty	Currency balances.
Buffs (`buffs`)	VtBuffSave[]	Empty	Active buffs with their remaining time.
Quests (`quests`)	VtQuestSave[]	Empty	Every quest in the log: active, completed, turned in and failed.
Skills (`skills`)	VtSkillSave[]	Empty	Crafting skills with level and XP.
Recipes (`recipes`)	`string`[]	Empty	Ids of the learned recipes.
Dialogue Flags (`dialogueFlags`)	`string`[]	Empty	Dialogue flags the unit has set.
Vendor Stock (`vendorStock`)	VtVendorStockSave[]	Empty	Stock lines of the unit’s vendor.
Respawn Waiting (`respawnWaiting`)	`bool`	Off	On while the unit was dead and waiting to respawn.
Respawn Seconds Remaining (`respawnSecondsRemaining`)	`float`	0	Seconds until the unit may respawn.
Death Position (`deathPosition`)	`Vector3`	(0, 0, 0)	Where the unit died.
Has Checkpoint (`hasCheckpoint`)	`bool`	Off	On once a respawn checkpoint was set.
Checkpoint (`checkpoint`)	`Vector3`	(0, 0, 0)	Position of the last checkpoint.
Talents (`talents`)	VtTalentSave[]	Empty	Learned talents and their ranks.
Attribute Points (`attributePoints`)	VtAttributePointSave[]	Empty	Points spent in each attribute.
Bonus Talent Points (`bonusTalentPoints`)	`int`	0	Talent points granted on top of those from levels.
Bonus Attribute Points (`bonusAttributePoints`)	`int`	0	Attribute points granted on top of those from levels.
Ignored Players (`ignoredPlayers`)	`string`[]	Empty	Player ids on the unit’s chat ignore list.
Hotkeys (`hotkeys`)	`string`[]	Empty	The ability id in each hotkey slot, in slot order; an empty string for an empty slot.
Unlocks (`unlocks`)	`string`[]	Empty	Ids of the unlocks the unit keeps for itself.
Hotbars (`hotbars`)	VtHotbarSave[]	Empty	Every hotbar on the unit, in component order.

VtSaveSystem

Static class.

Saves and loads every unit that carries a VtPersistentId. On load, units that still exist are restored in place; placed buildings that are gone are spawned again from their buildable’s prefab; anything else missing goes to your spawnMissing callback. The scene’s VtWorldClock, when there is one, and every enabled VtSharedStash are saved and restored with the units. Pair it with VtSaveFile to get JSON on disk.

Scripting API

Member	Description
`static VtSaveGame Capture(string sceneName = null)`	Snapshot every registered unit that has a `VtPersistentId`.
`static int Restore(VtSaveGame save, VtDefinitionCatalog catalog = null, Func<VtUnitSaveData, VtUnit> spawnMissing = null)`	Restore `save` into the current scene. Returns how many units were restored.

VtUnitSaver

Static class.

Captures one unit into VtUnitSaveData and restores it. Every optional component is included when present: pools, level, equipment, backpack, wallet, buffs, quest log, crafting skills and recipe book. Definitions are stored by id and resolved through the VtDefinitionCatalog on restore.

Scripting API

Member	Description
`static VtUnitSaveData Capture(VtUnit unit)`	Snapshot `unit`.
`static void Restore(VtUnit unit, VtUnitSaveData data, VtDefinitionCatalog catalog = null, bool includeTransform = true)`	Write `data` into `unit`. Components the unit lacks are skipped; ids the catalog cannot resolve are skipped with a warning. Pass `includeTransform` false to leave position and rotation alone, for example when the snapshot replicates state to a client that moves itself.

VtSaveFile

Static class.

JSON on disk for VtSaveGame, under the platform’s persistent data path.

Scripting API

Member	Description
`static string PathFor(string slot)`	Path of a named slot: `<persistentDataPath>/<slot>.json`.
`static string ToJson(VtSaveGame save)`	Serialize `save` to JSON.
`static VtSaveGame FromJson(string json)`	Deserialize a save from JSON. Null for empty input.
`static void Write(string path, VtSaveGame save)`	Write `save` to `path`, creating folders as needed.
`static VtSaveGame Read(string path)`	Read a save from `path`. Null when the file does not exist.
`static bool Exists(string path)`	True when a file exists at `path`.
`static void Delete(string path)`	Delete the file at `path` if it exists.

VtPoolSave

Serializable struct.

One resource pool’s current value.

Inspector fields

Field	Type	Default	Description
Kind (`kind`)	VtResourceKind	`HP`	Which resource pool.
Current (`current`)	`int`	0	The pool’s current value.

VtEquipmentSave

Serializable struct.

One equipped item.

Inspector fields

Field	Type	Default	Description
Slot (`slot`)	VtEquipmentSlot	`None`	Equipment slot the item sits in.
Item Id (`itemId`)	`string`	Empty	Id of the item definition.
Durability (`durability`)	`int`	0	The item’s remaining durability.
Extra Durability (`extraDurability`)	`int`	0	Durability that combined copies added to the item. 0 for a single copy.

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.

VtBuffSave

Serializable struct.

One active buff.

Inspector fields

Field	Type	Default	Description
Buff Id (`buffId`)	`string`	Empty	Id of the buff definition.
Remaining (`remaining`)	`float`	0	Seconds the buff had left.

VtQuestSave

Serializable struct.

One quest log entry.

Inspector fields

Field	Type	Default	Description
Quest Id (`questId`)	`string`	Empty	Id of the quest definition.
State (`state`)	VtQuestState	`Available`	Where the quest stands in the log.
Objective Progress (`objectiveProgress`)	`int`[]	Empty	Progress of each objective, in objective order.
Seconds Remaining (`secondsRemaining`)	`float`	0	Seconds left on the quest’s time limit.
Times Turned In (`timesTurnedIn`)	`int`	0	How often the quest was turned in.
Repeat Cooldown Remaining (`repeatCooldownRemaining`)	`float`	0	Seconds until a repeatable quest can be taken again.

VtSkillSave

Serializable struct.

One crafting skill.

Inspector fields

Field	Type	Default	Description
Skill Id (`skillId`)	`string`	Empty	Id of the crafting skill definition.
Level (`level`)	`int`	0	The skill’s level.
Xp (`xp`)	`int`	0	XP toward the next level.

VtVendorStockSave

Serializable class.

One vendor stock line: the item id, units left (-1 unlimited) and seconds until restock.

Inspector fields

Field	Type	Default	Description
Item Id (`itemId`)	`string`	Empty	Id of the item definition.
Remaining (`remaining`)	`int`	0	Units left in stock. -1 is unlimited.
Restock Remaining (`restockRemaining`)	`float`	0	Seconds until the line restocks.

VtTalentSave

Serializable class.

One learned talent and its rank.

Inspector fields

Field	Type	Default	Description
Talent Id (`talentId`)	`string`	Empty	Id of the talent definition.
Rank (`rank`)	`int`	0	Ranks learned.

VtAttributePointSave

Serializable class.

Points spent in one attribute.

Inspector fields

Field	Type	Default	Description
Attribute Id (`attributeId`)	`string`	Empty	Save id of the attribute definition.
Points (`points`)	`int`	0	Points spent in the attribute.

VtHotbarSave

Serializable class.

One VtHotbar’s slots.

Inspector fields

Field	Type	Default	Description
Slots (`slots`)	`string`[]	Empty	What sits in each slot, in slot order, as kind:id; an empty string for an empty slot.

Enums

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`.

VtEquipmentSlot

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

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

VtQuestState

Lifecycle state of a single quest in a VtUnitQuestLog.

Value	Description
`Available`	Not in the log and every prerequisite is met. Computed only.
`Active`	Accepted; objectives in progress.
`Complete`	Every objective satisfied; rewards not yet granted.
`TurnedIn`	Rewards granted. Counts for prerequisites; repeatable quests can be accepted again from here.
`Failed`	Time ran out or a fail condition triggered. Can be accepted again.