feat(time): the app clock on the engine

src/time/clock.js is the app's own time in ms since the epoch: by default
Date.now exactly (read at each call), with freeze/offset/rate/reset for QA
and tests, and one frame time latched per engine frame (beginFrame). The
contract gains engine.clock { now, frameTime, ticked }, in the fake engine
(a controllable wall clock, fake.advanceTime, fake.appClock), the contract
suite (one frame time for every listener of a frame, latched before
preUpdate, never decreasing), Cesium and Navara.

Cesium latches on the viewer clock's onTick, which CesiumWidget runs right
before scene.render, so scene listeners the app added before the engine
existed read the same frame time; the subscription appears on first use
and destroy removes it. The viewer clock itself is untouched: in the app
it never animates (shouldAnimate false, multiplier 1, its time frozen at
boot), and its time still drives Cesium's lighting as before. Navara
latches in the engine's handler of the view's preUpdate, and the look
reads the engine clock's frame time for the sun, so the app clock is the
one time source on Navara too.

src/time is a portable root in check-import-directions: no engine
packages, no browser globals.
This commit is contained in:
German Khokhlov committed 2026-10-16 15:01:36 +04:00
1 parent 27e28373d0
commit f1a2df5cfe
20 files changed
+771 -13

No files matched your search

+21
View File
@@ -209,6 +209,25 @@
* The source objects on screen, as passed: the base imagery layer on the
* globe and the photoreal tiles shown (null for none).
*
* @typedef {object} GlobeClock
* The app's own time (src/time/clock.js), in milliseconds since the Unix
* epoch: the one time source for layers and the engine's own time-driven
* drawing (Navara's sun). By default it is the wall clock (Date.now); QA
* and tests may freeze, offset or speed it up on the app clock. Cesium's
* viewer.clock is not driven by it (the app never animates that clock).
* @property {() => number} now The current app time.
* @property {() => number} frameTime The app time latched at the start of the
* engine's current frame: every reader in one frame gets the same value; it
* does not decrease from frame to frame while the app clock runs forward.
* Before the first frame, the current time.
* @property {EngineEvent} ticked Raised once per engine frame, with the
* frame time, before that frame's preUpdate (and so before preRender). A
* frame is one turn of the engine's update loop, also when it draws
* nothing: Cesium raises it on the viewer clock's tick, right before
* scene.render (which raises preUpdate on every animation frame, drawn or
* not); Navara on the view's preUpdate, which it emits on every turn of
* its loop.
*
* @typedef {object} GlobeEngine
* @property {'cesium'|'navara'} kind
* @property {{ container: object, canvas: object, size: () => { width: number, height: number } }} host
@@ -228,6 +247,7 @@
* held and one without fires only while no modifier is held.
* @property {{ addStatic: (html: string, options?: { onScreen?: boolean }) => () => void }} credits
* @property {GlobeMaps} maps
* @property {GlobeClock} clock
* @property {() => void} destroy
* @property {() => boolean} isDestroyed True once destroy() has run.
*/
@@ -406,6 +426,7 @@ const SHAPE = {
},
input: { on: isFunction, setCameraInputs: isFunction },
credits: { addStatic: isFunction },
clock: { now: isFunction, frameTime: isFunction, ticked: isEngineEvent },
maps: {
setBaseImagery: isFunction,
setTerrain: isFunction,