Skip to content

t1k:unity:dots-core:world

FieldValue
Moduledots-core
Version3.56.1
Effortmedium
Tools—
/t1k:unity:dots-core:world

Package: com.the1studio.dots-core — namespace DOTSCore.World Assembly: DOTSCore.World (its own asmdef, not part of DOTSCore.Runtime) Group: WorldSystemGroup — [UpdateInGroup(SimulationSystemGroup, OrderFirst = true)], [UpdateBefore(CoreSystemGroup)], so clock and weather are settled before any downstream system reads them Sources: Runtime/World/ (components, systems, utilities) · authoring lives OUTSIDE it in Authoring/World/ Tests: Tests/EditMode/World/{WorldTimeSystemTests,WeatherTransitionSystemTests}.cs

Two independent singletons, two systems. WorldTimeSystem accumulates a clock; WeatherTransitionSystem runs after it and crossfades weather in game-hours derived from that clock.

  • Building a day/night cycle, or anything that must survive an offline fast-forward
  • Authoring a weather distribution — especially more GDD weather states than the seven-value WeatherType enum has
  • Reading weather modifiers (move speed / visibility / damage) on gameplay entities
  • Gating behaviour on “is it raining right now” across packages that must not reference each other
  • Debugging weather that never changes, or a clock that drifts over a long session
OrderSystemRole
—WorldTimeSystemSecondsIntoDay += dt * TimeScale, wraps at RealSecondsPerGameHour * 24, bumps DayCount, derives TimeOfDay + CurrentPhase
after WorldTimeSystemWeatherTransitionSystemAdvances the crossfade, selects the next weather when the duration expires, writes WeatherEffect on every entity holding that buffer

Both call state.RequireForUpdate<T>() on every singleton they read — [RequireMatchingQueriesForUpdate] does not protect SystemAPI.GetSingleton.

var t = SystemAPI.GetSingleton<WorldTime>();
// t.TimeOfDay (0-24, float) · t.SecondsIntoDay (double, the real accumulator)
// t.DayCount · t.TimeScale · t.IsPaused · t.CurrentPhase

AdvanceClock(ref WorldTime, in WorldTimeConfig, float secondsElapsed) is public static [BurstCompile] — extracted from OnUpdate precisely so tests can drive millions of iterations with no ECS/World overhead. It is the single writer of SecondsIntoDay/TimeOfDay in production.

Phase thresholds are all config, not constants: DawnHour → MorningHour → AfternoonHour → DuskHour → NightHour, with Night wrapping midnight. Defaults live in WorldConstants (5 / 7 / 12 / 17 / 19, RealSecondsPerGameHour = 60).

var w = SystemAPI.GetSingleton<WeatherState>();
// CurrentWeather/NextWeather (WeatherType) · Intensity/Precipitation (Current's axes)
// NextIntensity/NextPrecipitation (Next's axes) · TransitionProgress · RemainingDurationHours · RngState

Selection is weighted over the singleton’s WeatherVariant buffer via DOTSCore.WeightedSampler:

// Authored on WeatherAuthoring.Variants (List<WeatherVariant>), baked onto the singleton.
new WeatherVariant { Type = WeatherType.Fog, Intensity = 0.3f, Precipitation = 0f, Weight = 2f },
new WeatherVariant { Type = WeatherType.Fog, Intensity = 1.0f, Precipitation = 0f, Weight = 1f },

Two rows sharing one enum Type at different axes is the point — it is how a consumer expresses light-vs-dense fog, or wet-vs-dry thunder, without the library growing enum values for game-specific states. No game-specific state name belongs in WeatherVariant — only the numeric mapping.

WeatherEffect (buffer, InternalBufferCapacity(2)) is rewritten each frame on every entity that has one, holding the crossfaded MoveSpeedMultiplier / VisibilityMultiplier / DamageMultiplier. Per-type modifier values are WorldConstants (e.g. StormVisibilityMultiplier = 0.4f, SandstormVisibilityMultiplier = 0.2f) — the mapping itself is a hardcoded switch in GetWeatherModifiers, not data.

WeatherRules — the cross-package predicate

Section titled “WeatherRules — the cross-package predicate”
if (WeatherRules.IsPrecipitating(in weatherState)) { /* skip manual watering */ }

Pure, Burst-safe, no SystemAPI. Formula: CurrentWeather == Rain || (CurrentWeather == Storm && Precipitation > 0f). It exists so dots-ai (WorkAssignmentSystem) and dots-farming (WeatherWateringSystem) can agree on “it is raining” without referencing each other — both already reference dots-core. Do not re-derive this formula in a consumer, and do not cache its result into a component.

One GameObject in the SubScene carrying WorldTimeAuthoring and WeatherAuthoring (they may share it). WeatherBaker always adds the WeatherEffect and WeatherVariant buffers — even when Variants is empty — so the system’s query matches and empty-table fallback works.

  • WeatherState.Intensity is set ONCE per selection, not written per frame. Pre-W7.4 it was recomputed every frame as Current == Next ? 1f : 1f - TransitionProgress — a second encoding of TransitionProgress (a derived field). That write is deleted. Intensity/Precipitation are now stable for the whole lifetime of CurrentWeather. A consumer wanting a crossfaded presentation value must lerp it itself: math.lerp(Intensity, NextIntensity, TransitionProgress). Code that read Intensity expecting a 1→0 ramp during a transition now reads a constant.
  • An empty or absent WeatherVariant buffer is a legal, tested state, not a misconfiguration. Selection falls back verbatim to the legacy rng % WeatherTypeCount uniform-over-enum roll with Intensity = 1, Precipitation = 0. WeatherTransitionSystem.OnCreate deliberately does not RequireForUpdate<WeatherVariant> — doing so would silently stop weather in every scene baked before W7.4 (e.g. BattleDemo2D). An all-zero-weight table falls through to the same legacy path.
  • The transition gate is TransitionProgress < 1f, never CurrentWeather != NextWeather. A Type-equality gate breaks the moment two consecutive selections share an enum value at different axes — two Fog rows (light vs dense) would be treated as “no transition in flight” and the new axes would never land. This is the specific bug the variant table makes reachable.
  • The crossfade clock and the selection clock are separate and must stay separate. TransitionDurationHours (how long a crossfade takes, default 0.5) is normally far shorter than [MinDurationHours, MaxDurationHours] (how long a weather lasts before the next is picked, default 2–6). The crossfade ordinarily completes long before the next selection fires.
  • SystemAPI is illegal inside a static method (EA0006). WeatherTransitionSystem resolves TryGetSingletonBuffer<WeatherVariant> in the instance OnUpdate and threads (bool hasVariants, DynamicBuffer<WeatherVariant> variants) down into the static helpers. The source generator rewrites SystemAPI, and it has no instance to rewrite against in a static.
  • WorldTime.SecondsIntoDay is double on measured evidence, not caution. A seconds-scale float accumulator lands on DayCount == 95 instead of 96 over a full 24 real hours at 60fps (5,184,000 additions of 1/60f): 1/60 is not exactly representable in binary32, and re-quantizing the already-rounded running total every frame makes the error compound directionally rather than average out — ~16.9s of deficit. TimeOfDay stays float deliberately (it is re-derived every frame and the offline fast-forward never reads it), hence the explicit narrowing cast in AdvanceClock. Guarded by WorldTimeSystemTests.AccumulatedClock_DoesNotDriftOver24Hours against an independent double-precision reference.
  • The day/night cycle must remain an accumulated clock — never an Animator. That is the sole precondition for offline fast-forward, which advances OfflineElapsedSeconds rather than replaying frames.
  • WorldTime.IsPaused carries [MarshalAs(UnmanagedType.U1)] and it is load-bearing. C#‘s default bool marshalling is the 4-byte Win32 BOOL, which makes the enclosing struct non-blittable; Burst then rejects it as a function-pointer parameter with BC1063 the moment AdvanceClock(ref WorldTime, ...) is compiled as a direct call. The attribute changes no layout — ECS already stores one byte. Any future bool added to a component passed by ref/in to a [BurstCompile] static needs the same treatment. Full write-up: t1k-unity-dots-core-ecs/references/hard-rules-burst.md § F8.
  • IsPaused short-circuits both systems, but at different points. WorldTimeSystem returns before accumulating; WeatherTransitionSystem returns before touching WeatherState at all — so a paused world freezes the crossfade mid-transition rather than snapping it. TimeScale = 0 has the same effect on the clock but still lets WeatherTransitionSystem run with gameHoursElapsed == 0.
  • Authoring lives in Authoring/World/, not Runtime/World/Authoring/. Both authoring types carry [MovedFrom(true, sourceAssembly: "DOTSCore.World")] from that relocation — do not strip it, or every already-baked scene loses its component bindings.
  • WeatherType has 7 values and WorldConstants.WeatherTypeCount hardcodes 7. Adding an enum value without bumping the constant makes the legacy fallback roll unable to ever select it. Prefer adding a WeatherVariant row over adding an enum value.