World time reference

The world clock, the day-night cycle and phase assets, the lighting that follows them, and the time-of-day requirement. For how to use it, see World time.

VtWorldClock

Component. Add it with Add Component → Vantage → World Time → VtWorldClock.

The scene’s game clock. Place one per scene and assign a VtDayNightDefinition. It advances the time of day, counts days, raises OnPhaseChanged and OnNewDay, and applies the active phase’s modifiers to every matching unit under the source id ModifierSourceId.

Inspector fields

Field	Type	Default	Description
Definition (`definition`)	VtDayNightDefinition	None	Day length and phases. Required.

Scripting API

Member	Description
`static VtWorldClock Instance { get; }`	The scene’s clock, or null when none is placed.
`static VtDayPhaseDefinition ActivePhase { get; }`	The phase of the scene clock, or null without a clock.
`VtDayNightDefinition Definition { get; }`	Day length and phases.
`VtWorldClockScheduler Scheduler { get; }`	The underlying clock, for reading and for headless hosts.
`int Day { get; }`	Day counter, starting at 1.
`float TimeOfDay { get; }`	Time of day from 0 (midnight) up to 1.
`float Hours { get; }`	Time of day in hours, 0 to 24.
`float TimeScale { get; }`	Speed multiplier. 1 = normal, 0 = stopped.
`bool Paused { get; }`	True while the clock is paused.
`VtDayPhaseDefinition CurrentPhase { get; }`	The active phase, or null when the definition has none.
`static event Action<VtDayPhaseDefinition, VtDayPhaseDefinition> OnPhaseChanged`	Fires when the scene clock’s phase changes. Args: (previous, current).
`static event Action<int> OnNewDay`	Fires when the scene clock starts a new day, with the new day number.
`static event Action<VtWorldClock> OnClockAdjusted`	Fires on the authority after the scene clock was changed by hand through `SetTime`, `AdvanceHours`, `SetTimeScale` or `SetPaused`. Networking sends `CaptureState` to clients here. Normal ticking and `ApplyFromNet` do not raise it.
`const string ModifierSourceId`	Source id the active phase’s modifiers are registered under on each unit.
`static bool IsAnyPhaseActive(VtDayPhaseDefinition[] phases)`	True when `phases` is empty, when the scene has no clock, or when the scene clock’s phase is in the list.
`void Initialize()`	Build the clock from the definition. Idempotent.
`void SetDefinition(VtDayNightDefinition value)`	Swap the day-night definition. Restarts the clock on day 1 at the new definition’s start time.
`void Tick(float deltaTime)`	Advance the clock by `deltaTime` real seconds.
`bool SetTime(int day, float timeOfDay)`	Jump to `timeOfDay` on `day`. Authority only; returns false on a client.
`bool SetTimeOfDay(float timeOfDay)`	Jump to `timeOfDay` on the current day. Authority only.
`bool AdvanceHours(float hours)`	Move forward by `hours` game hours, raising every phase and day change on the way. Use it for sleeping or waiting. Authority only.
`bool SetTimeScale(float scale)`	Set the speed multiplier. Authority only.
`bool SetPaused(bool paused)`	Pause or resume the clock. Authority only.
`VtWorldClockState CaptureState()`	Snapshot to send to clients or store in a save.
`void ApplyFromNet(VtWorldClockState state)`	Adopt the authority’s snapshot on a client, and restore a save.
`void RefreshModifiers(VtUnit unit)`	Apply or remove the active phase’s modifiers on `unit`. The clock does this on every phase change and whenever a unit is seeded; call it after changing a unit’s tags or faction mid-phase.

VtDayNightLighting

Component. Add it with Add Component → Vantage → World Time → VtDayNightLighting.

Moves and tints the sun, and optionally the ambient light and fog, from the scene’s VtWorldClock using a VtDayNightLook. Presentation only: it never changes gameplay, so every client runs it on its own. Swap the look asset to restyle a scene without touching the clock.

Inspector fields

Field	Type	Default	Description
Sun (`sun`)	`Light`	None	Directional light used as the sun. Required.
Look (`look`)	VtDayNightLook	None	Colors, brightness and sun path over the day. Required.
Rotate Sun (`rotateSun`)	`bool`	On	Rotate the sun along the look’s path. Off keeps the light’s own rotation.
Drive Ambient (`driveAmbient`)	`bool`	On	Set the scene’s ambient light color. Needs Environment Lighting Source set to Color.
Drive Fog (`driveFog`)	`bool`	Off	Set the scene’s fog color.

Scripting API

Member	Description
`Light Sun { get; set; }`	Directional light used as the sun.
`VtDayNightLook Look { get; set; }`	Colors, brightness and sun path over the day.
`void Apply(float timeOfDay)`	Show the look at `timeOfDay` right away, for previews and scenes without a clock.

VtDayNightDefinition

Asset. Create it with Create → Vantage → World Time → Day Night Cycle.

The length of a game day and the phases it is split into. Assign it to the scene’s VtWorldClock. Phases may be listed in any order; each one lasts until the next phase’s start time, and the last phase of the day runs through midnight into the first.

Inspector fields

Field	Type	Default	Range	Description
Day Length Seconds (`dayLengthSeconds`)	`float`	1200	≥ 1	Real seconds one full game day takes at time scale 1. 1200 = a 20-minute day.
Start Time (`startTime`)	`float`	0.3	0 to 1	Time of day a new game starts at. 0 = midnight, 0.25 = 6:00, 0.5 = noon.
Phases (`phases`)	VtDayPhaseDefinition[]	Empty		The phases of the day, such as Dawn, Day, Dusk and Night.

VtDayPhaseDefinition

Asset. Create it with Create → Vantage → World Time → Day Phase.

One part of the day, such as Dawn, Day, Dusk or Night. A phase starts at startTime and lasts until the next phase of its VtDayNightDefinition begins. Gameplay refers to phases by asset: spawners list the phases they are active in, quests and dialogue gate on them through VtTimeOfDayRequirement.

Inspector fields

Field	Type	Default	Range	Description
Display Name (`displayName`)	`string`	Empty		Name shown in the UI, or a localization key.
Start Time (`startTime`)	`float`	0	0 to 1	Where the phase starts in the day. 0 = midnight, 0.25 = 6:00, 0.5 = noon, 0.75 = 18:00.
Modifiers (`modifiers`)	VtItemModifier[]	Empty		Stat changes every matching unit has while this phase is active.
Affected Tags (`affectedTags`)	VtUnitTagDefinition[]	Empty		Only units with at least one of these tags get the modifiers. Empty = no tag filter.
Affected Factions (`affectedFactions`)	VtFaction[]	Empty		Only units of these factions get the modifiers. Empty = no faction filter.

Scripting API

Member	Description
`bool Affects(VtUnit unit)`	True when this phase’s `modifiers` apply to `unit`. A unit must pass both the tag and the faction filter; an empty filter passes everyone.

VtDayNightLook

Asset. Create it with Create → Vantage → World Time → Day Night Look.

How the scene looks over one day: sun color and brightness, ambient light and fog color, all sampled by time of day from 0 (midnight) to 1. Read by VtDayNightLighting. A new asset starts with a plain warm-day, blue-night look.

Inspector fields

Field	Type	Default	Range	Description
Sun Color (`sunColor`)	`Gradient`	Gradient		Sun color over the day.
Sun Intensity (`sunIntensity`)	`AnimationCurve`	Curve		Sun intensity over the day. The time runs along X from 0 to 1.
Ambient Color (`ambientColor`)	`Gradient`	Gradient		Ambient light over the day. Needs Environment Lighting Source set to Color.
Fog Color (`fogColor`)	`Gradient`	Gradient		Fog color over the day. Used when the lighting component drives fog.
Sun Yaw (`sunYaw`)	`float`	-30	-180 to 180	Compass direction the sun travels along, in degrees.
Noon Elevation (`noonElevation`)	`float`	70	0 to 90	Highest sun angle above the horizon at noon, in degrees. 90 = straight down.

Scripting API

Member	Description
`Quaternion SunRotation(float timeOfDay)`	Sun rotation at `timeOfDay`: rising at 6:00, highest at noon, setting at 18:00, below the horizon at night.

VtTimeOfDayRequirement

Asset. Create it with Create → Vantage → Quests → Requirements → Time Of Day. Inherits VtQuestRequirement.

Quest and dialogue requirement: the scene clock is in one of phases and has reached minimumDay. Use it for “only offered at night” quests or answers a guard only gives after dark. Without a VtWorldClock in the scene it never passes.

Inspector fields

Field	Type	Default	Range	Description
Phases (`phases`)	VtDayPhaseDefinition[]	Empty		The clock must be in one of these phases. Empty = any phase.
Minimum Day (`minimumDay`)	`int`	1	≥ 1	The clock must have reached at least this day.

Scripting API

Member	Description
`override bool IsMet(VtUnit holder)`	True when the scene clock has reached `minimumDay` and is in one of `phases`. False without a `VtWorldClock` in the scene.

VtWorldClockState

Serializable struct.

Everything needed to reproduce a VtWorldClock on another machine or after a load. Send it from the authority to clients, and store it in saves.

Inspector fields

Field	Type	Default	Description
Day (`day`)	`int`	0	Day counter, starting at 1.
Time Of Day (`timeOfDay`)	`float`	0	Time of day from 0 (midnight) up to 1.
Time Scale (`timeScale`)	`float`	0	Speed multiplier. 1 = normal, 0 = stopped.
Paused (`paused`)	`bool`	Off	True while the clock is paused.

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.