refactor(flights): Cesium rendering behind a renderer interface

Task 10a. The flights logic no longer imports Cesium: every Cesium object it
built moved one for one into the shared aircraft renderer
(src/layers/aircraft/render/cesium.js; contract in render/contract.js), with
the flights' parameters in src/layers/flights/render/cesium.js, registered
for 'cesium' in the renderer registry and created at init(viewer, {engine}).

- Fleet: BillboardCollection + sprite-order slot; sprites stay Billboard
  handles (field vocabulary documented for the Navara renderer).
- Models: fleet/tracked/preload glTF loads (asynchronous:false, MIX tint, IR
  boost as `unlit` → the UNLIT CustomShader), the model collection, setPose
  (same HPR frame with airplane.glb's 180° offset).
- Tracked: the ENU billboard Entity with its position/colour/rotation
  callbacks, viewFrom, followed through viewer.trackedEntity + the one exact
  tracked frame (kept as is; engine.camera.follow on Cesium would also end
  the follow on any camera command, a behaviour change).
- Trail: the entity trail (data/trailRenderer, unchanged: its Primitive
  predecessor failed below the mesh) and the live head segment.
- View: camera/scene reads, frame number, frustum and horizon tests,
  projection, render requests, frame events, evidence render-loop hold.
- Clicks and Escape go through the engine's selection dispatcher (the
  ScreenSpaceEventHandler and keydown listener are gone); the cross-layer
  untrack watches the renderer's follow.
- Colours are engine-neutral Rgba (src/layers/shared/color.js), bit-equal to
  the Cesium.Color constants they replace; NearFarScalar → nearFarScale.
- Cesium math in the logic → src/geo.
- check-import-directions: cesium only in render/cesium*.js and three/Navara
  only in render/navara*.js for flights, aircraft and shared; a layer's
  Navara renderer only through navaraMode's import().

Source-text tests updated with the moved code, same meaning:
- readLayerSource reads a layer's render/*.js and, for the aircraft layers,
  aircraft/render/*.js (GLB-load, tracked-entity, CallbackProperty checks).
- modelScale.test: _normalBillboardScaleByDistance reads nearFarScale(...).
- spriteOrder.test: flights' enable calls fleet.restoreOrderOnEnable(); the
  renderer wires it to restoreSpriteOrderOnEnable('flights', viewer).
- trackingClickGesture.test: the flights gesture rules are the dispatcher's
  (selection gesture before select, click classifier before the empty-space
  clear); flights answers the empty click with a user-origin clear.
- militaryAwareness.test: flights' hasContact guard reads fleet.visible().
- ownership.test: the services fixture names selection and renderer.

New tests: color, the Cesium aircraft renderer (contract, collections, pose,
loads, frustum/horizon, tracked entity, follow, trail head, adopted
collections), the flights logic over a plain-data renderer and a fake engine
(fleet, click-select, no-op on the tracked visual, empty-click release), the
boundary rule.

W1 replay vs 7c7422e2: counts, known objects, screen points (0 px), tracking
poses (0 m), requests and shots (same sha256) identical. Main chunk
2,890,982 B (+6.2 KB, +0.21 %: the renderer indirection).
This commit is contained in:
German Khokhlov committed 2026-10-17 01:04:25 +04:00
1 parent 8e702f0c3b
commit 7f13ef4a87
33 files changed
+1974 -748

No files matched your search

+52 -96
View File
@@ -1,4 +1,3 @@
import * as Cesium from 'cesium';
import { PLANE_MODEL_URL } from './policy.js';
export function createLifecycle({
@@ -9,11 +8,6 @@ export function createLifecycle({
resolveAsset,
}) {
const { clearFocusTarget } = services.focus;
const {
registerSpriteCollection,
restoreSpriteOrder,
restoreSpriteOrderOnEnable,
} = services.sprites;
const { onMilitaryLayerActiveChange } = services.militaryRegistry;
const { holdContinuousRender, releaseContinuousRender } = services.render;
const { ensureGeoidReady } = services.geoid;
@@ -22,7 +16,7 @@ export function createLifecycle({
const methods = {
/** Configure the source before initialization; an active layer keeps its owner. */
setSource(source) {
if (flightState._viewer)
if (flightState._renderer)
throw new Error('Configure the source before layer initialization');
if (typeof source?.getSnapshot !== 'function')
throw new TypeError('A snapshot source is required');
@@ -34,12 +28,14 @@ export function createLifecycle({
/**
* Initialize the flights layer.
* Creates the BillboardCollection, resets all state, and installs the
* click-to-track handler on the scene canvas.
* @param {Cesium.Viewer} viewer - The CesiumJS viewer instance.
* Creates the engine's aircraft renderer (fleet sprites, models), resets
* all state, and joins the engine's selection dispatcher.
* @param {object|null} viewer - The Cesium viewer (null on an engine
* without one).
* @param {{ engine?: object }} [context] - LayerLifecycle's context.
*/
init(viewer) {
if (flightState._viewer)
init(viewer, { engine = null } = {}) {
if (flightState._renderer)
throw new Error('Flight layer is already initialized');
if (typeof flightState.feed._source?.getSnapshot !== 'function')
throw new TypeError('A snapshot source is required');
@@ -47,31 +43,22 @@ export function createLifecycle({
flightState.lifetime = new AbortController();
clearFocusTarget('flights');
flightState._focusEvidenceIds.clear();
flightState._viewer = viewer;
flightState._billboardCollection = new Cesium.BillboardCollection();
viewer.scene.primitives.add(flightState._billboardCollection);
registerSpriteCollection('flights', flightState._billboardCollection);
flightState._modelCollection = new Cesium.PrimitiveCollection();
viewer.scene.primitives.add(flightState._modelCollection);
const renderer = services.renderer.create({ viewer, engine });
flightState._renderer = renderer;
renderer.fleet.attach();
// Warm the glTF cache so the tracked plane's model instantiates instantly when first needed
// (keeps the retained instance referenced; never rendered). Captured against this epoch so a
// destroy/re-init mid-load doesn't flip the flag for a torn-down lifecycle.
if (!flightState._preloadModel) {
const epoch = flightState._modelEpoch;
Cesium.Model.fromGltfAsync({
url: resolveAsset(PLANE_MODEL_URL),
asynchronous: false,
})
renderer.models
.preload(resolveAsset(PLANE_MODEL_URL))
.then((m) => {
if (epoch === flightState._modelEpoch) {
flightState._preloadModel = m;
flightState._planeModelLoaded = true;
} else {
try {
m.destroy();
} catch {
/* gone */
}
renderer.models.destroy(m);
}
})
.catch(() => {
@@ -114,7 +101,7 @@ export function createLifecycle({
parts.enrichment._ambientBudgetKnobs().ceil;
flightState._enrichAmbientRefillAnchorMs = 0;
parts.tracking._installClickHandler(viewer);
parts.tracking._installClickHandler();
// React to Military-layer toggles IMMEDIATELY (suppress/restore sweep)
// instead of waiting out the 30 s poll (M2).
@@ -124,21 +111,19 @@ export function createLifecycle({
);
}
restoreSpriteOrder(viewer);
renderer.fleet.restoreOrder();
console.log('[Data:Flights] Initialized with billboard icons');
},
/**
* Show the billboard collection and re-install the click handler.
* @param {Cesium.Viewer} viewer
* Show the fleet and re-join the selection dispatcher.
*/
enable(viewer) {
if (flightState._billboardCollection)
flightState._billboardCollection.show = true;
enable() {
const renderer = flightState._renderer;
renderer?.fleet.setVisible(true);
holdContinuousRender('flights'); // per-frame animator (perf wave 2)
if (flightState._modelCollection)
flightState._modelCollection.show = true;
renderer?.models.setVisible(true);
parts.tracking._setCockpitContactMode(
document.body.classList.contains('cockpit-mode'),
);
@@ -155,24 +140,25 @@ export function createLifecycle({
/* geoid grid failed to load — baro path stays un-geoid-corrected until retried */
});
}
parts.tracking._installClickHandler(viewer);
parts.tracking._installClickHandler();
registerPickOwner('flights', (pickedId) =>
flightState._billboards.has(pickedId),
);
// Force a fresh rotation pass on the first tick after re-enable
flightState._lastCamPoseSig = '';
if (!flightState._preRenderRemove && viewer?.scene) {
flightState._preRenderRemove = viewer.scene.preRender.addEventListener(
if (!flightState._preRenderRemove && renderer) {
flightState._preRenderRemove = renderer.view.on(
'preRender',
parts.rendering._fleetTick,
);
}
if (!flightState._trackedModelPreUpdateRemove && viewer?.scene) {
flightState._trackedModelPreUpdateRemove =
viewer.scene.preUpdate.addEventListener(
parts.rendering._updateTrackedModel,
);
if (!flightState._trackedModelPreUpdateRemove && renderer) {
flightState._trackedModelPreUpdateRemove = renderer.view.on(
'preUpdate',
parts.rendering._updateTrackedModel,
);
}
if (!flightState._moveEndRemove && viewer?.camera) {
if (!flightState._moveEndRemove && renderer) {
// Arrival polish (field test 2026-07-03: "planes look weird when you first
// come to them"): when a camera move SETTLES (voice fly-to, fast pan
// release), force a full rotation pass on the very next frame. The
@@ -182,43 +168,30 @@ export function createLifecycle({
// ROTATION_REFRESH_MS. Zeroing the tick throttle too means the pass runs
// on the next preRender, not up to FLEET_DR_INTERVAL_MS later. Cost: one
// extra rotation pass per completed camera gesture — nothing per-frame.
flightState._moveEndRemove = viewer.camera.moveEnd.addEventListener(
() => {
flightState._lastCamPoseSig = '';
flightState._lastFleetTickMs = 0;
},
);
flightState._moveEndRemove = renderer.view.on('moveEnd', () => {
flightState._lastCamPoseSig = '';
flightState._lastFleetTickMs = 0;
});
}
restoreSpriteOrderOnEnable('flights', viewer);
renderer?.fleet.restoreOrderOnEnable();
},
/**
* Hide all flight billboards and tear down click/keyboard handlers.
* Hide all flight billboards and leave the selection dispatcher.
* Also clears any active flight tracking so the camera is released.
* @param {Cesium.Viewer} viewer
*/
disable(viewer) {
disable() {
parts.controller._abortActiveUpdates();
parts.tracking._cancelPendingTrackingRestore();
if (flightState._billboardCollection)
flightState._billboardCollection.show = false;
flightState._renderer?.fleet.setVisible(false);
releaseContinuousRender('flights');
parts.rendering._releaseModels();
if (flightState._modelCollection)
flightState._modelCollection.show = false;
flightState._renderer?.models.setVisible(false);
parts.tracking._clearTracking();
parts.tracking._destroyTrail();
// Remove click handler + keydown listener while disabled to avoid
// intercepting input when the layer is off
if (flightState._clickHandler) {
flightState._clickHandler.destroy();
flightState._clickHandler = null;
}
if (flightState._trackedEntityChangedRemove) {
flightState._trackedEntityChangedRemove();
flightState._trackedEntityChangedRemove = null;
}
document.removeEventListener('keydown', parts.tracking._onKeyDown);
// Leave the selection dispatcher (clicks, Escape) while disabled to
// avoid intercepting input when the layer is off
parts.tracking._removeClickHandler();
unregisterPickOwner('flights');
if (flightState._preRenderRemove) {
flightState._preRenderRemove();
@@ -235,9 +208,9 @@ export function createLifecycle({
},
/**
* Fully tear down the flights layer — remove primitives, handlers,
* tracked entities, and clear all internal state maps.
* @param {Cesium.Viewer} viewer
* Fully tear down the flights layer — remove its drawings, handlers,
* the tracked visual, and clear all internal state maps.
* @param {object|null} viewer - The viewer the layer was drawn on.
*/
destroy(viewer) {
flightState.lifetime.abort();
@@ -248,19 +221,11 @@ export function createLifecycle({
parts.tracking._clearTracking();
parts.tracking._destroyTrail();
parts.tracking._cancelPendingTrackingRestore();
if (flightState._clickHandler) {
flightState._clickHandler.destroy();
flightState._clickHandler = null;
}
if (flightState._trackedEntityChangedRemove) {
flightState._trackedEntityChangedRemove();
flightState._trackedEntityChangedRemove = null;
}
parts.tracking._removeClickHandler();
if (flightState._milActiveChangeUnsub) {
flightState._milActiveChangeUnsub();
flightState._milActiveChangeUnsub = null;
}
document.removeEventListener('keydown', parts.tracking._onKeyDown);
if (flightState._cockpitModeListener) {
window.removeEventListener(
'gev:cockpit-mode-changed',
@@ -282,23 +247,13 @@ export function createLifecycle({
flightState._moveEndRemove = null;
}
parts.rendering._releaseModels();
if (flightState._billboardCollection) {
viewer.scene.primitives.remove(flightState._billboardCollection);
flightState._billboardCollection = null;
}
if (flightState._modelCollection) {
viewer.scene.primitives.remove(flightState._modelCollection); // removing destroys it + its models
flightState._modelCollection = null;
}
// Removing the model collection destroys it and its models.
flightState._renderer?.fleet.detach(viewer);
flightState._modelEpoch += 1; // invalidate any in-flight load from this lifecycle (settles post-destroy)
flightState._modelPending.clear();
flightState._modelGen.clear();
if (flightState._preloadModel) {
try {
flightState._preloadModel.destroy();
} catch {
/* gone */
}
flightState._renderer?.models.destroy(flightState._preloadModel);
flightState._preloadModel = null;
}
flightState._planeModelLoaded = false;
@@ -332,7 +287,8 @@ export function createLifecycle({
coverage: flightState.feed._lastCoverage,
};
parts.tracking._resetTrackedSelectionState(); // next lifecycle re-evaluates against the ENTER ceiling
flightState._viewer = null;
flightState._renderer?.destroy();
flightState._renderer = null;
},
};