t1k:unity:dots-core:world
| Field | Value |
|---|---|
| Module | dots-core |
| Version | 3.56.1 |
| Effort | medium |
| Tools | — |
How to invoke
Section titled “How to invoke”/t1k:unity:dots-core:worldDOTS World — Day/Night Clock & Weather
Section titled “DOTS World — Day/Night Clock & Weather”Package:
com.the1studio.dots-core— namespaceDOTSCore.WorldAssembly:DOTSCore.World(its own asmdef, not part ofDOTSCore.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 inAuthoring/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.
When This Skill Triggers
Section titled “When This Skill Triggers”- 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
WeatherTypeenum 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
The Two Systems
Section titled “The Two Systems”| Order | System | Role |
|---|---|---|
| — | WorldTimeSystem | SecondsIntoDay += dt * TimeScale, wraps at RealSecondsPerGameHour * 24, bumps DayCount, derives TimeOfDay + CurrentPhase |
after WorldTimeSystem | WeatherTransitionSystem | Advances 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.CurrentPhaseAdvanceClock(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).
Weather
Section titled “Weather”var w = SystemAPI.GetSingleton<WeatherState>();// CurrentWeather/NextWeather (WeatherType) · Intensity/Precipitation (Current's axes)// NextIntensity/NextPrecipitation (Next's axes) · TransitionProgress · RemainingDurationHours · RngStateSelection 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.
Quick Setup
Section titled “Quick Setup”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.
Hard rules
Section titled “Hard rules”WeatherState.Intensityis set ONCE per selection, not written per frame. Pre-W7.4 it was recomputed every frame asCurrent == Next ? 1f : 1f - TransitionProgress— a second encoding ofTransitionProgress(a derived field). That write is deleted.Intensity/Precipitationare now stable for the whole lifetime ofCurrentWeather. A consumer wanting a crossfaded presentation value must lerp it itself:math.lerp(Intensity, NextIntensity, TransitionProgress). Code that readIntensityexpecting a 1→0 ramp during a transition now reads a constant.- An empty or absent
WeatherVariantbuffer is a legal, tested state, not a misconfiguration. Selection falls back verbatim to the legacyrng % WeatherTypeCountuniform-over-enum roll withIntensity = 1,Precipitation = 0.WeatherTransitionSystem.OnCreatedeliberately does notRequireForUpdate<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, neverCurrentWeather != NextWeather. A Type-equality gate breaks the moment two consecutive selections share an enum value at different axes — twoFogrows (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, default0.5) is normally far shorter than[MinDurationHours, MaxDurationHours](how long a weather lasts before the next is picked, default2–6). The crossfade ordinarily completes long before the next selection fires. SystemAPIis illegal inside astaticmethod (EA0006).WeatherTransitionSystemresolvesTryGetSingletonBuffer<WeatherVariant>in the instanceOnUpdateand threads(bool hasVariants, DynamicBuffer<WeatherVariant> variants)down into the static helpers. The source generator rewritesSystemAPI, and it has no instance to rewrite against in a static.WorldTime.SecondsIntoDayisdoubleon measured evidence, not caution. A seconds-scalefloataccumulator lands onDayCount == 95instead of 96 over a full 24 real hours at 60fps (5,184,000 additions of1/60f):1/60is 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.TimeOfDaystaysfloatdeliberately (it is re-derived every frame and the offline fast-forward never reads it), hence the explicit narrowing cast inAdvanceClock. Guarded byWorldTimeSystemTests.AccumulatedClock_DoesNotDriftOver24Hoursagainst 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 advancesOfflineElapsedSecondsrather than replaying frames. WorldTime.IsPausedcarries[MarshalAs(UnmanagedType.U1)]and it is load-bearing. C#‘s defaultboolmarshalling is the 4-byte Win32BOOL, which makes the enclosing struct non-blittable; Burst then rejects it as a function-pointer parameter withBC1063the momentAdvanceClock(ref WorldTime, ...)is compiled as a direct call. The attribute changes no layout — ECS already stores one byte. Any futurebooladded to a component passed byref/into a[BurstCompile]static needs the same treatment. Full write-up:t1k-unity-dots-core-ecs/references/hard-rules-burst.md§ F8.IsPausedshort-circuits both systems, but at different points.WorldTimeSystemreturns before accumulating;WeatherTransitionSystemreturns before touchingWeatherStateat all — so a paused world freezes the crossfade mid-transition rather than snapping it.TimeScale = 0has the same effect on the clock but still letsWeatherTransitionSystemrun withgameHoursElapsed == 0.- Authoring lives in
Authoring/World/, notRuntime/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. WeatherTypehas 7 values andWorldConstants.WeatherTypeCounthardcodes7. Adding an enum value without bumping the constant makes the legacy fallback roll unable to ever select it. Prefer adding aWeatherVariantrow over adding an enum value.