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

+54
View File
@@ -0,0 +1,54 @@
// The engine clock on a Cesium viewer: the app clock (src/time/clock.js),
// with one frame time latched per turn of CesiumWidget's loop. The latch
// listens to the viewer clock's tick, which the widget runs right before
// scene.render, so every preUpdate/preRender/postRender listener of the frame
// (including those the app added to the scene before the engine existed)
// reads the same frame time. The viewer clock itself is never changed: the
// app does not animate it (shouldAnimate stays false), and its time still
// drives Cesium's own lighting as before. The tick subscription appears on
// first use (a ticked listener or a frameTime read) and destroy removes it.
import { createEngineEvent } from '../contract.js';
import { appClock as pageClock } from '../../time/clock.js';
/**
* @param {Cesium.Viewer} viewer
* @param {{ appClock?: import('../../time/clock.js').AppClock }} [options]
* `appClock` defaults to the page's app clock.
* @returns {{ clock: import('../contract.js').GlobeClock, destroy: () => void }}
*/
export function createCesiumClock(viewer, { appClock = pageClock } = {}) {
// A viewer-shaped object without a clock (tests, a bare scene): the
// scene's preUpdate opens the frame instead.
const tickSource = viewer.clock?.onTick ?? viewer.scene.preUpdate;
const ticked = createEngineEvent();
let removeTick = null;
let destroyed = false;
const onTick = () => ticked.raiseValue(appClock.beginFrame());
const attach = () => {
if (!removeTick && !destroyed)
removeTick = tickSource.addEventListener(onTick);
};
const add = ticked.addEventListener;
ticked.addEventListener = (listener) => {
const remove = add(listener);
attach();
return remove;
};
return {
clock: {
now: () => appClock.now(),
frameTime() {
attach();
return appClock.frameTime();
},
ticked,
},
destroy() {
destroyed = true;
const remove = removeTick;
removeTick = null;
remove?.();
},
};
}
+116
View File
@@ -0,0 +1,116 @@
import test from 'node:test';
import assert from 'node:assert/strict';
import * as Cesium from 'cesium';
import { isEngineEvent } from '../contract.js';
import { createAppClock } from '../../time/clock.js';
import { createCesiumClock } from './clock.js';
import { createFakeViewer } from './testing/fakeViewer.mjs';
function manualAppClock(start = Date.UTC(2026, 9, 16)) {
let wall = start;
const appClock = createAppClock({ now: () => wall });
return {
appClock,
advance(ms) {
wall += ms;
},
};
}
// One turn of CesiumWidget's loop: the clock ticks, then scene.render
// raises preUpdate (and preRender/postRender when it draws).
function cesiumFrame(viewer, { draw = true } = {}) {
const time = Cesium.JulianDate.now();
viewer.clock.onTick.raiseEvent(viewer.clock);
viewer.scene.preUpdate.raiseEvent(viewer.scene, time);
if (!draw) return;
viewer.scene.preRender.raiseEvent(viewer.scene, time);
viewer.scene.postRender.raiseEvent(viewer.scene, time);
}
test('the clock reads the app clock and subscribes to nothing at creation', () => {
const viewer = createFakeViewer();
const wall = manualAppClock();
const { clock } = createCesiumClock(viewer, { appClock: wall.appClock });
assert.ok(isEngineEvent(clock.ticked));
assert.equal(viewer.clock.onTick.numberOfListeners, 0);
assert.equal(clock.now(), wall.appClock.now());
wall.advance(5);
assert.equal(clock.now(), wall.appClock.now());
});
test('frameTime is latched on the viewer clock tick, before preUpdate', () => {
const viewer = createFakeViewer();
const wall = manualAppClock();
const { clock } = createCesiumClock(viewer, { appClock: wall.appClock });
const seen = [];
clock.ticked.addEventListener((time) => seen.push(['ticked', time]));
// A preUpdate listener the app added before the engine existed still
// reads this frame's time: the latch is on the tick, not on preUpdate.
viewer.scene.preUpdate.addEventListener(() =>
seen.push(['preUpdate', clock.frameTime()]),
);
viewer.scene.preRender.addEventListener(() => {
wall.advance(3);
seen.push(['preRender', clock.frameTime()]);
});
const t0 = wall.appClock.now();
cesiumFrame(viewer);
wall.advance(16);
cesiumFrame(viewer, { draw: false });
assert.deepEqual(seen, [
['ticked', t0],
['preUpdate', t0],
['preRender', t0],
['ticked', t0 + 19],
['preUpdate', t0 + 19],
]);
});
test('frameTime alone starts the latch; destroy removes it', () => {
const viewer = createFakeViewer();
const wall = manualAppClock();
const { clock, destroy } = createCesiumClock(viewer, {
appClock: wall.appClock,
});
const before = clock.frameTime();
assert.equal(before, wall.appClock.now());
assert.equal(viewer.clock.onTick.numberOfListeners, 1);
wall.advance(40);
cesiumFrame(viewer);
assert.equal(clock.frameTime(), before + 40);
wall.advance(10);
assert.equal(clock.frameTime(), before + 40);
destroy();
assert.equal(viewer.clock.onTick.numberOfListeners, 0);
});
test('a viewer without a clock latches on preUpdate', () => {
const viewer = createFakeViewer();
delete viewer.clock;
const wall = manualAppClock();
const { clock, destroy } = createCesiumClock(viewer, {
appClock: wall.appClock,
});
const seen = [];
clock.ticked.addEventListener((time) => seen.push(time));
wall.advance(7);
viewer.scene.preUpdate.raiseEvent(viewer.scene);
assert.deepEqual(seen, [wall.appClock.now()]);
destroy();
assert.equal(viewer.scene.preUpdate.numberOfListeners, 0);
});
test('the viewer clock itself is left alone', () => {
const viewer = createFakeViewer();
viewer.clock.shouldAnimate = false;
viewer.clock.multiplier = 1;
const { clock } = createCesiumClock(viewer, {
appClock: manualAppClock().appClock,
});
clock.ticked.addEventListener(() => {});
cesiumFrame(viewer);
assert.equal(viewer.clock.shouldAnimate, false);
assert.equal(viewer.clock.multiplier, 1);
assert.equal(viewer.clock.currentTime, undefined);
});
+5 -2
View File
@@ -4,6 +4,7 @@
// (the viewer itself stays owned by the app).
import { createCesiumCamera } from './camera.js';
import { createCesiumClock } from './clock.js';
import { createCesiumCredits } from './credits.js';
import { createCesiumFrames } from './frames.js';
import { createCesiumInput } from './input.js';
@@ -21,8 +22,9 @@ import { createCesiumSurface } from './surface.js';
* createEventHandler?: Function,
* createImageryLayer?: Function,
* loadPhotorealTileset?: Function,
* }} [options] `requestRender` defaults to the render governor; the
* `create*`/`load*` options are test seams.
* appClock?: import('../../time/clock.js').AppClock,
* }} [options] `requestRender` defaults to the render governor; `appClock`
* to the page's app clock; the `create*`/`load*` options are test seams.
*
* `render.setContinuous` takes a hold on the app's singleton renderGovernor
* (src/renderGovernor.js), which governs the one viewer it was installed on;
@@ -40,6 +42,7 @@ export function createCesiumEngine(viewer, options = {}) {
picker: createCesiumPicker(viewer),
projector: createCesiumProjector(viewer),
frames: createCesiumFrames(viewer),
clock: createCesiumClock(viewer, options),
render,
surface: createCesiumSurface(viewer),
input: createCesiumInput(viewer, options),
@@ -138,3 +138,21 @@ test('the engine reads the Viewer aliases and builds on a minimal viewer', () =>
assert.equal(renders, 1);
engine.destroy();
});
test('the engine clock is the app clock given, latched on the viewer clock tick', async () => {
const { createAppClock } = await import('../../time/clock.js');
let wall = 1_000_000;
const appClock = createAppClock({ now: () => wall });
const viewer = createFakeViewer();
const engine = createCesiumEngine(viewer, { appClock });
assert.equal(engine.clock.now(), 1_000_000);
const seen = [];
engine.clock.ticked.addEventListener((time) => seen.push(time));
assert.equal(viewer.clock.onTick.numberOfListeners, 1);
wall += 16;
viewer.clock.onTick.raiseEvent(viewer.clock);
assert.deepEqual(seen, [1_000_016]);
assert.equal(engine.clock.frameTime(), 1_000_016);
engine.destroy();
assert.equal(viewer.clock.onTick.numberOfListeners, 0);
});
+3
View File
@@ -165,6 +165,9 @@ export function createFakeViewer({ width = 1024, height = 768 } = {}) {
staticCredits,
primitiveList,
trackedEntityChanged: new Cesium.Event(),
// The viewer clock: only its tick event (CesiumWidget ticks it right
// before scene.render on every animation frame).
clock: { onTick: new Cesium.Event() },
imageryList,
terrainProvider: undefined,
imageryLayers: {