t1k:unity:dots-core:time
| Field | Value |
|---|---|
| Module | dots-core |
| Version | 3.56.1 |
| Effort | medium |
| Tools | — |
How to invoke
Section titled “How to invoke”/t1k:unity:dots-core:timeDOTSCore.Time — Wall Clock & Offline Catch-Up
Section titled “DOTSCore.Time — Wall Clock & Offline Catch-Up”Package:
com.the1studio.dots-core— namespaceDOTSCore.Time/DOTSCore.Time.SystemsAssembly:DOTSCore.Time(its own asmdef, not part ofDOTSCore.Runtime) Related skills:t1k-unity-dots-core-farming(the only shipped end-to-end catch-up consumer) ·t1k-unity-dots-core-bridges(AppResumedTag, the session-boundary signal) ·t1k-unity-dots-core-economy(EnergyRegenSystemis the otherWallClockconsumer) ·t1k-unity-dots-core-progression(DOTSProgression.Idle— a different, separately-anchored offline path; see the collision warning below)
Scope — what this skill covers, and what it does not
Section titled “Scope — what this skill covers, and what it does not”Covers WallClock and the offline catch-up chain only.
DOTSCore.Time also ships HitStop*, TickTimer, ScheduledEvent, WorldClock, SimRateControl/GameRateManager/RateDecision, WorkerCatchUpRate, and CooldownTickHelper. CooldownTickHelper is documented in t1k-unity-dots-core-ecs/references/shared-burst-primitives.md; TickTimer (the long-duration, wall-clock-ticked counterpart to DOTSCore.CooldownTimer) is documented in t1k-unity-dots-core-ecs/references/cooldown-timer-guide.md. The rest are not covered here yet — read the source, do not read this skill’s silence as “the package doesn’t have it”.
When This Skill Triggers
Section titled “When This Skill Triggers”- Reading wall-clock time from Burst-compiled code
- Granting progress for time the player spent away (idle income, energy, crop growth, worker output)
- Capping an away window, or reasoning about clock-tamper exposure
- Debugging “offline catch-up only worked once, then never again”
- Wiring the session-boundary hook that re-arms catch-up on app resume
WallClock — the only sanctioned UtcNow reader
Section titled “WallClock — the only sanctioned UtcNow reader”| Type | Kind | Purpose |
|---|---|---|
WallClock | IComponentData (singleton) | long UnixTimestampUtc — UTC seconds since epoch |
WallClockSystem | SystemBase, InitializationSystemGroup | Publishes DateTimeOffset.UtcNow.ToUnixTimeSeconds() once per frame |
System.DateTimeOffset.UtcNow is BC1091 inside Burst — it touches the OS clock and cannot be compiled. WallClockSystem is deliberately managed and is the one place in the library that calls it; every Burst consumer reads the singleton instead. Do not add a second UtcNow caller — publish through this singleton.
It runs in InitializationSystemGroup, so the value is already fresh for any SimulationSystemGroup consumer in the same frame.
A system that needs it must declare state.RequireForUpdate<WallClock>() — otherwise it silently runs against a zero clock. In EditMode tests there is no bootstrap creating the singleton unless you create it: inject WallClock manually or the system never updates (EnergyRegenSystem has the same constraint — see t1k-unity-dots-core-economy).
The offline catch-up chain
Section titled “The offline catch-up chain”Three packages, one chain. Each layer knows strictly less than the one below it:
dots-bridges AppLifecycleBridge → AppResumedTag "the app came back" (genre-neutral) ↓ consumed by a CONSUMER-side system (demo/game), never by the librarydots-core OfflineCatchUp / OfflineElapsedSeconds "N seconds elapsed" (genre-neutral) ↓dots-farming OfflineWorkCatchUpSystem, OfflineClaimState "what that's worth, CropCatchUpSystem, ProducerCatchUpSystem and is it claimable" (genre-specific)dots-core must not depend on MinClaimableSeconds, claim screens, or anything else that knows what a grant is worth — that split is what makes the chain reusable, and it is why the self-retire logic lives in dots-farming rather than upstream.
OfflineCatchUp — persistent anchor + config
Section titled “OfflineCatchUp — persistent anchor + config”| Field | Meaning |
|---|---|
LastOnlineUtc | Anchor for the next delta. 0 = first-ever launch (grants zero, stamps the anchor) |
CatchUpCapSeconds | Max seconds granted in one window. 0 means UNCAPPED, not “capped” |
HighWaterMarkUtc | Highest corrected “now” ever seen. Never decreases |
ServerTimeOffsetSeconds | Signed correction applied to WallClock before any comparison. 0 today |
Evaluated | Session latch — “this system already ran this session” |
OfflineElapsedSeconds — per-window result
Section titled “OfflineElapsedSeconds — per-window result”| Field | Meaning |
|---|---|
ElapsedSeconds | The capped grant. Always ≥ 0 |
RequestedSeconds | The raw pre-cap delta, so a consumer can say “capped at N h”. 0 on a zero grant |
Pending | “A window awaits a consumer’s decision” |
Anchor/config state lives on OfflineCatchUp (meaningful across many sessions); per-window result data lives on OfflineElapsedSeconds (stale the moment the window closes). RequestedSeconds sits beside ElapsedSeconds for exactly that reason — both are written once per evaluation by the same system and both describe one window.
Hard rules
Section titled “Hard rules”Evaluated and Pending are two gates, not one — conflating them is a permanent-silence bug
Section titled “Evaluated and Pending are two gates, not one — conflating them is a permanent-silence bug”This is the single most expensive thing to get wrong in this package, and it has already shipped once as a defect.
Pending= “a window awaits a consumer decision.” Cleared by a player claim acknowledgement — or by a consumer self-retiring a window no claim screen will ever be offered for.Evaluated= “OfflineCatchUpSystemalready ran this session.” Cleared only by a genuine session boundary.
Before the split, Pending alone gated both. The only consumer-side clearer of Pending is a claim ack, and a claim screen is never offered below MinClaimableSeconds — which is trivially true for a zero grant (first-ever launch, a detected rewind, a delta rounding to zero) and also true for a real-but-small absence such as a 30-second app switch. So any non-claimable grant latched Pending forever, silently discarding every later, genuinely claimable absence for the rest of the game’s lifetime. The symptom is “offline catch-up worked the first time and never again”, with no error anywhere.
The split lets a consumer clear Pending alone to self-retire a dead window without re-arming the granter — Evaluated keeps the system quiet for the rest of the session either way.
Evaluated has exactly TWO legitimate writers
Section titled “Evaluated has exactly TWO legitimate writers”OfflineCatchUpSystemsets ittrue, unconditionally, at the top of its evaluation branch — before any of the branch logic runs. That unconditional write is what actually throttles the system to once per session.- The session-boundary hook sets it back to
false.
Anything else clearing it re-creates the original bug in a new costume. In particular: not on claim-ack, and not per-frame while the claim screen is open. OfflineCatchUpSystem lives in SimulationSystemGroup and ticks every frame — a mid-session re-arm means a fresh near-zero window is granted every second and stacked on top of the game’s own per-frame online systems (in dots-farming, PlantGrowthSystem / WaterEvaporationSystem run unconditionally with no awareness of these flags at all). That is a double-apply, and it looks like a balance problem rather than a flag problem.
OfflineWorkCatchUpSystem’s self-retire path deliberately does not touch Evaluated for this reason — it clears Pending only.
The library ships no session-boundary hook — you must write the consumer half
Section titled “The library ships no session-boundary hook — you must write the consumer half”dots-core cannot know what a resume means. dots-bridges publishes the genre-neutral AppResumedTag; a consumer-side system reads it and clears Evaluated. Until you write that system, catch-up evaluates once per process launch and never again mid-process — correct for a cold boot, silent for the common mobile background/foreground case.
Reference implementation (demo-side, ~1 system): Assets/Demos/Farming/TinyTerraces/Runtime/Offline/AppResumeClearsEvaluatedSystem.cs in DOTS-AI. Order it before OfflineCatchUpSystem so a resume observed this frame is visible to this frame’s evaluation.
A near-zero-window resume (a 2-second alt-tab) is safe and needs no special-casing: evaluation re-arms, grants a tiny window, and the consumer’s self-retire path closes it out in the same frame. An outstanding unclaimed window at resume time is also safe — OfflineCatchUpSystem’s if (Pending || Evaluated) continue; guard skips evaluation regardless.
CatchUpCapSeconds = 0 means UNCAPPED
Section titled “CatchUpCapSeconds = 0 means UNCAPPED”The system only clamps when CatchUpCapSeconds > 0. A default-constructed OfflineCatchUp therefore grants unbounded progress — a player who returns after a month gets a month. Whatever authoring/baking path creates this component MUST supply a non-zero value; there is no safe default to fall back on.
Name collision — DOTSCore.Time.Systems.OfflineCatchUpSystem ≠ DOTSProgression.Idle
Section titled “Name collision — DOTSCore.Time.Systems.OfflineCatchUpSystem ≠ DOTSProgression.Idle”Two unrelated offline paths, different anchors, different lifecycles:
DOTSCore.Time.Systems.OfflineCatchUpSystem | DOTSProgression.Idle.OfflineCalculationSystem | |
|---|---|---|
| Anchor | OfflineCatchUp.LastOnlineUtc (UTC seconds) | OfflineProgress.LastLoginTicks (ticks) |
| Cap field | CatchUpCapSeconds (0 = uncapped) | MaxOfflineHours |
| Result | OfflineElapsedSeconds (library-shared scalar) | OfflineProgress (idle-package-specific) |
| Runs | SimulationSystemGroup, OnUpdate, gated by Pending/Evaluated | CoreSystemGroup, OnUpdate, self-advancing anchor |
There is no OfflineCatchUpSystem in dots-progression — the idle one is OfflineCalculationSystem. OfflineElapsedSeconds is the shared scalar any system may read. If you are wiring idle generators, confirm which of the two you actually mean before copying either one’s gating; the units (seconds vs ticks, seconds-cap vs hours-cap) do not interchange.