Skip to content

t1k:unity:dots-core:time

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

DOTSCore.Time — Wall Clock & Offline Catch-Up

Section titled “DOTSCore.Time — Wall Clock & Offline Catch-Up”

Package: com.the1studio.dots-core — namespace DOTSCore.Time / DOTSCore.Time.Systems Assembly: DOTSCore.Time (its own asmdef, not part of DOTSCore.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 (EnergyRegenSystem is the other WallClock consumer) · 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”.

  • 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”
TypeKindPurpose
WallClockIComponentData (singleton)long UnixTimestampUtc — UTC seconds since epoch
WallClockSystemSystemBase, InitializationSystemGroupPublishes 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).

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 library
dots-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”
FieldMeaning
LastOnlineUtcAnchor for the next delta. 0 = first-ever launch (grants zero, stamps the anchor)
CatchUpCapSecondsMax seconds granted in one window. 0 means UNCAPPED, not “capped”
HighWaterMarkUtcHighest corrected “now” ever seen. Never decreases
ServerTimeOffsetSecondsSigned correction applied to WallClock before any comparison. 0 today
EvaluatedSession latch — “this system already ran this session”

OfflineElapsedSeconds — per-window result

Section titled “OfflineElapsedSeconds — per-window result”
FieldMeaning
ElapsedSecondsThe capped grant. Always ≥ 0
RequestedSecondsThe 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.

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 = “OfflineCatchUpSystem already 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”
  1. OfflineCatchUpSystem sets it true, 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.
  2. 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.

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.OfflineCatchUpSystemDOTSProgression.Idle.OfflineCalculationSystem
AnchorOfflineCatchUp.LastOnlineUtc (UTC seconds)OfflineProgress.LastLoginTicks (ticks)
Cap fieldCatchUpCapSeconds (0 = uncapped)MaxOfflineHours
ResultOfflineElapsedSeconds (library-shared scalar)OfflineProgress (idle-package-specific)
RunsSimulationSystemGroup, OnUpdate, gated by Pending/EvaluatedCoreSystemGroup, 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.