Carry Sonar with the Minimal HUD layout in links and scene shots

A link or scene shot made in Minimal with Sonar on played back with Sonar
off, and turned off the viewer's own. Tactical with Sonar keeps the `cyber`
layout code, which older readers understand; Minimal with Sonar now carries
an explicit mark beside its layout: flag bit 5 (`hudSonar`, default off) of
a compact link, `hs=1` in the long form, and `hud.sonar: true` in a scene
shot. A restore turns Sonar on when the state names Cyber or carries the
mark, so a state made before it restores exactly as it did.

Co-authored-by: Manjunath Paparaju <[email protected]>
This commit is contained in:
Sameh KhamisandManjunath Paparaju authored and Sameh Khamis committed 2026-11-18 19:45:47 -08:00
1 parent c69a421678
commit 40e2998466
14 files changed
+266 -28

No files matched your search

+1 -1
View File
@@ -36,7 +36,7 @@ function visual(value, path, legacy) {
const specs = {
bloom: { enabled: 'boolean', intensity: [-100, 10000], version: [1, 100] },
sharpen: { enabled: 'boolean', intensity: [0, 100] },
hud: { visible: 'boolean', variant: 'string' },
hud: { visible: 'boolean', variant: 'string', sonar: 'boolean' },
detection: {
mode: 'string',
density: [0, 100],
+27
View File
@@ -168,3 +168,30 @@ test('captured scope and extended detection edits survive migration', () => {
project.scenes[0].shots[0].visual.detection,
);
});
test('a shot keeps Sonar beside its HUD layout; one without it reads as before', () => {
const project = fixture();
const shot = project.scenes[0].shots[0];
shot.visual = { hud: { visible: true, variant: 'minimal', sonar: true } };
const read = (p) =>
normalizeProject(parseSceneDocument(JSON.stringify(p))).scenes[0].shots[0]
.visual.hud;
assert.deepEqual(read(project), {
visible: true,
variant: 'minimal',
sonar: true,
});
// Older shots name no Sonar: the layout alone, Cyber included, as before.
for (const variant of ['minimal', 'cyber']) {
shot.visual = { hud: { visible: true, variant } };
assert.deepEqual(read(project), { visible: true, variant });
}
// Off is the meaning of an absent field, so it is not kept.
shot.visual = { hud: { variant: 'minimal', sonar: false } };
assert.equal(Object.hasOwn(read(project), 'sonar'), false);
shot.visual = { hud: { variant: 'minimal', sonar: 'on' } };
assert.throws(
() => validateSceneDocument(project),
/\$\.scenes\[0\]\.shots\[0\]\.visual\.hud\.sonar/,
);
});
+3
View File
@@ -287,6 +287,9 @@ export function normalizeShot(
hud: {
visible: typeof hud.visible === 'boolean' ? hud.visible : true,
variant: typeof hud.variant === 'string' ? hud.variant : 'tactical',
// Sonar on beside a layout whose code cannot say so; absent is off
// unless the variant names the retired Cyber layout.
...(hud.sonar === true ? { sonar: true } : {}),
},
detection: {
...(typeof detection.allocation === 'string'
+1
View File
@@ -34,6 +34,7 @@ export const LEGACY_SHARE_STATE_KEYS = Object.freeze([
'bloomVersion',
'sharpenIntensity',
'hudVariant',
'hudSonar',
'hudVisible',
'detectionMode',
'detectionDensity',
+18
View File
@@ -146,6 +146,23 @@ test('links from earlier long-form versions keep their historical meaning', () =
assert.equal(off.layerState.options.flights.models3d, false);
});
test('Sonar beside the Minimal layout survives the compact form; older links do not name it', () => {
const { parsed, state } = assertLegacyRoundTrip(
'v=2&lat=10&lon=20&hud=minimal&hs=1',
);
assert.equal(parsed.hudSonar, true);
assert.equal(state.hudVariant, 'minimal');
assert.equal(state.hudSonar, true);
// Links made before `hs`: Minimal carries no Sonar, Cyber carries it in
// its own code.
for (const hud of ['minimal', 'cyber']) {
const old = assertLegacyRoundTrip(`v=2&lat=10&lon=20&hud=${hud}`);
assert.equal(old.parsed.hudSonar, false);
assert.equal(old.state.hudVariant, hud);
assert.equal(old.state.hudSonar, false);
}
});
test('a tracking selection becomes a thing view and back', () => {
const flights = assertLegacyRoundTrip('v=2&lat=1&lon=2&l=f&lo=f.t.a1b2c3');
assert.deepEqual(flights.state.view.entity, {
@@ -232,6 +249,7 @@ function generatedLegacyHash(random) {
bloomVersion: pick(random, [1, 2]),
sharpenIntensity: int(0, 100),
hudVariant: pick(random, HUD_LAYOUTS),
hudSonar: random() < 0.5,
hudVisible: random() < 0.5,
detectionMode: pick(random, ['OFF', 'SPARSE', 'BALANCED', 'DENSE']),
detectionDensity: density,
+3
View File
@@ -255,6 +255,9 @@ export const SHARE_VIEW_FLAGS = freezeAll([
{ bit: 2, key: 'hudVisible', default: BY_STYLE },
{ bit: 3, key: 'celestialRing', default: BY_STYLE },
{ bit: 4, key: 'scopeEnabled', default: true },
// Sonar on beside a HUD layout whose code cannot say so (Minimal). Tactical
// with Sonar stays the `cyber` layout code alone.
{ bit: 5, key: 'hudSonar', default: false },
]);
/**
+26 -2
View File
@@ -348,6 +348,7 @@ test('every registered field round-trips at once', () => {
bloomVersion: 1,
sharpenIntensity: 65,
hudVariant: 'operator',
hudSonar: true,
hudVisible: false,
detectionMode: 'SPARSE',
detectionDensity: 100,
@@ -449,6 +450,28 @@ test('links made with a retired HUD layout still decode to its name', () => {
}
});
test('Sonar beside the Minimal layout is flag bit 5; links made before it keep their meaning', () => {
const minimal = { ...createDefaultShareViewState(), hudVariant: 'minimal' };
const plain = encodeShareView(minimal);
// Off is the default, so a view without Sonar costs nothing for it.
assert.equal(encodeShareView({ ...minimal, hudSonar: false }), plain);
const withSonar = assertRoundTrip({ ...minimal, hudSonar: true });
assert.notEqual(withSonar, plain);
const decoded = decodeOk(withSonar).state;
assert.equal(decoded.hudVariant, 'minimal');
assert.equal(decoded.hudSonar, true);
assert.equal(decodeOk(plain).state.hudSonar, false);
// Tactical with Sonar is still the Cyber code alone.
const cyber = { ...createDefaultShareViewState(), hudVariant: 'cyber' };
assert.equal(decodeOk(encodeShareView(cyber)).state.hudSonar, false);
// A link made before the bit (thermal, Cyber, Scope off) decodes as it did:
// Cyber without the bit, which the app opens as Tactical with Sonar on.
const before = decodeOk('ARD-7j4YuxMguBcoUEgQcAOAAQPIASPQAWGa').state;
assert.equal(before.hudVariant, 'cyber');
assert.equal(before.hudSonar, false);
assert.equal(encodeShareView(before), 'ARD-7j4YuxMguBcoUEgQcAOAAQPIASPQAWGa');
});
test('defaults travel as frozen meanings that match today’s app defaults', () => {
const defaults = createDefaultShareViewState();
// When an app default moves, these tests should be updated to document the
@@ -535,6 +558,7 @@ test('the field registry is well formed and permanent', () => {
[2, 'hudVisible', BY_STYLE],
[3, 'celestialRing', BY_STYLE],
[4, 'scopeEnabled', true],
[5, 'hudSonar', false],
],
);
// The style-applied defaults are frozen meanings too. If the app's style
@@ -921,7 +945,7 @@ test('unknown fields inside a thing view, codes and bits are skipped too', () =>
thing.textField(20, 'cockpit'); // a future thing field
const writer = new WireWriter();
writer.bytes.push(1);
writer.sintField(2, 100000).uintField(9, 0b100001); // flag bit 5 unknown
writer.sintField(2, 100000).uintField(9, 0b1000001); // flag bit 6 unknown
writer.bytesField(
10,
[0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1],
@@ -944,7 +968,7 @@ test('unknown fields inside a thing view, codes and bits are skipped too', () =>
result.unknownFields.map((u) => [u.scope, u.field ?? u.code]),
[
['enum:style', 99],
['flags', 32],
['flags', 64],
['layer', 160],
['panel', 12],
['thing', 20],
+31
View File
@@ -158,6 +158,37 @@ test('share-link serialization emits the current celestial state', () => {
assert.equal(new URLSearchParams(window.location.hash.slice(1)).get('cr'), '1');
});
test('Sonar beside the HUD layout rides as hs only when on, and through the compact link', async () => {
// Links made before `hs` name no Sonar.
assert.equal(makeManager('#v=2&lat=10&lon=20&hud=minimal').parseInitialHash().hudSonar, false);
assert.equal(makeManager('#v=2&lat=10&lon=20&hud=minimal&hs=1').parseInitialHash().hudSonar, true);
const manager = makeManager();
manager.onToggleChange(false, false, { hudVariant: 'minimal', hudSonar: false });
assert.equal(manager._buildHashParams().has('hs'), false, 'off writes nothing');
assert.equal(sharedState(manager.buildLink()).hudSonar, false);
manager.onToggleChange(false, false, { hudVariant: 'minimal', hudSonar: true });
assert.equal(manager._buildHashParams().get('hs'), '1');
const shared = sharedState(manager.buildLink());
assert.equal(shared.hudVariant, 'minimal');
assert.equal(shared.hudSonar, true);
// Tactical with Sonar is written as the Cyber layout code alone.
manager.onToggleChange(false, false, { hudVariant: 'cyber', hudSonar: false });
assert.equal(manager._buildHashParams().get('hud'), 'cyber');
assert.equal(manager._buildHashParams().has('hs'), false);
assert.equal(sharedState(manager.buildLink()).hudVariant, 'cyber');
clearTimeout(manager._debounceTimer);
// The restore hands it to the visual settings beside the layout.
const opened = makeManager('#v=2&lat=40&lon=-74&hud=minimal&hs=1');
let restored = null;
opened._onRestore = (state) => { restored = state; };
opened._isNavigationCurrent = () => false;
await opened.applyState(opened.parseInitialHash(), { navigationToken: 1 });
assert.equal(restored.hudVariant, 'minimal');
assert.equal(restored.hudSonar, true);
});
test('generated links are v2 and include deterministic layers, options, style params, and panels', () => {
const manager = makeManager();
const layers = createDefaultLayerState();
+9
View File
@@ -94,6 +94,8 @@ export class ShareLinkManager {
this._bloomVersion = BLOOM_SCALE_VERSION;
this._sharpenIntensity = 49;
this._hudVariant = 'tactical';
// Sonar on beside a layout whose code cannot say so (Minimal); `hs`.
this._hudSonar = false;
this._hudVisible = false;
this._detectionMode = 'OFF';
this._detectionDensity = 50;
@@ -260,6 +262,9 @@ export class ShareLinkManager {
bloomVersion: parseOr(params.get('bv'), 1),
sharpenIntensity: parseOr(params.get('si'), 49),
hudVariant: params.get('hud') || 'tactical',
// Absent in links made before it, which restore Sonar from `hud=cyber`
// alone.
hudSonar: params.get('hs') === '1',
hudVisible: params.get('hv') === '1',
detectionMode: restoredDetection.enabled
? restoredDetection.profile
@@ -477,6 +482,7 @@ export class ShareLinkManager {
bloomVersion: visualCurrent ? state.bloomVersion : undefined,
sharpenIntensity: visualCurrent ? state.sharpenIntensity : undefined,
hudVariant: visualCurrent ? state.hudVariant : undefined,
hudSonar: visualCurrent ? state.hudSonar : undefined,
hudVisible: visualCurrent ? state.hudVisible : undefined,
detectionMode: visualCurrent ? state.detectionMode : undefined,
detectionDensity: visualCurrent ? state.detectionDensity : undefined,
@@ -627,6 +633,7 @@ export class ShareLinkManager {
this._sharpenIntensity = extras.sharpenIntensity;
if (typeof extras.hudVariant === 'string')
this._hudVariant = extras.hudVariant;
if (typeof extras.hudSonar === 'boolean') this._hudSonar = extras.hudSonar;
if (typeof extras.hudVisible === 'boolean')
this._hudVisible = extras.hudVisible;
if (typeof extras.detectionMode === 'string')
@@ -786,6 +793,8 @@ export class ShareLinkManager {
params.set('bv', Math.round(this._bloomVersion).toString());
params.set('si', Math.round(this._sharpenIntensity).toString());
params.set('hud', this._hudVariant);
// Only written when on, so a link without Sonar keeps its old form.
if (this._hudSonar) params.set('hs', '1');
params.set('hv', this._hudVisible ? '1' : '0');
params.set('dm', this._detectionMode);
params.set('dd', Math.round(this._detectionDensity).toString());
+96 -12
View File
@@ -28,6 +28,13 @@ import { setCyberSonarControls } from './cyberSonarControls.js';
import { createPinia } from 'pinia';
import { useDisplayStore } from './stores/display.js';
import { VisualSettings } from './visualSettings.js';
import { normalizeShot } from '../scenes/project.js';
import {
SCENE_DOCUMENT_VERSION,
validateSceneDocument,
} from '../director/document.js';
import { decodeShareView, encodeShareView } from '../share/viewCodec.js';
import { toLegacyShareState } from '../share/legacyShareState.js';
import { STYLES } from './visualPresets.js';
const read = (relative) =>
@@ -140,9 +147,10 @@ test('a share link, scene or saved view naming Cyber opens Tactical with Sonar o
assert.equal(isCyberSonarEnabled(root), true);
});
test('links and scene shots record Tactical with Sonar as the Cyber code, and only that', (t) => {
const { owner, root } = styleOwner(t, 'tactical');
Object.assign(owner.services, {
/** A styleOwner that can also read its share state and scene shot. */
function sharingOwner(t, initialVariant) {
const fixture = styleOwner(t, initialVariant);
Object.assign(fixture.owner.services, {
getDetectionTuning: () => ({ allocationStrategy: 'ELASTIC' }),
getDetectionMode: () => 'OFF',
isScopeMaskEnabled: () => true,
@@ -150,18 +158,94 @@ test('links and scene shots record Tactical with Sonar as the Cyber code, and on
getScopeMaskOpacity: () => 1,
getScopeTerminusOverride: () => null,
});
owner.readCelestialRing = () => null;
const shared = () => owner._readShareState().options.hudVariant;
assert.equal(shared(), 'tactical');
fixture.owner.readCelestialRing = () => null;
return fixture;
}
test('links and scene shots record Tactical with Sonar as the Cyber code, and only that', (t) => {
const { owner, root } = sharingOwner(t, 'tactical');
const shared = () => {
const { hudVariant, hudSonar } = owner._readShareState().options;
return [hudVariant, hudSonar];
};
const shot = () => owner.getVisualState().hud;
assert.deepEqual(shared(), ['tactical', false]);
assert.deepEqual(shot(), { visible: true, variant: 'tactical' });
owner._setCyberSonarEnabled(true);
assert.equal(shared(), 'cyber');
// Minimal has no code that carries Sonar; it stays local.
// Tactical with Sonar is the Cyber code alone, as older readers expect.
assert.deepEqual(shared(), ['cyber', false]);
assert.deepEqual(shot(), { visible: true, variant: 'cyber' });
// Minimal has no such code, so Sonar is carried beside it.
owner._setHudVariant('minimal');
assert.equal(shared(), 'minimal');
owner._setHudVariant('tactical');
assert.equal(shared(), 'cyber');
assert.deepEqual(shared(), ['minimal', true]);
assert.deepEqual(shot(), { visible: true, variant: 'minimal', sonar: true });
owner._setCyberSonarEnabled(false);
assert.equal(shared(), 'tactical');
assert.deepEqual(shared(), ['minimal', false]);
assert.deepEqual(shot(), { visible: true, variant: 'minimal' });
owner._setHudVariant('tactical');
assert.deepEqual(shared(), ['tactical', false]);
assert.equal(isCyberSonarEnabled(root), false);
});
test('Minimal with Sonar round-trips through a compact link and a scene shot', async (t) => {
const { owner, hud, root } = sharingOwner(t, 'minimal');
owner._setCyberSonarEnabled(true);
const options = owner._readShareState().options;
const shot = normalizeShot(
JSON.parse(JSON.stringify({ visual: owner.getVisualState() })),
);
validateSceneDocument({
version: SCENE_DOCUMENT_VERSION,
scenes: [{ id: 'scene', title: 'Scene', shots: [shot] }],
});
const code = encodeShareView({
hudVariant: options.hudVariant,
hudSonar: options.hudSonar,
});
const link = decodeShareView(code, { nowMs: Date.now() }).state;
// The viewer is elsewhere: Tactical, Sonar off.
owner._setHudVariant('tactical');
owner._setCyberSonarEnabled(false);
// The HUD fields of the parsed link (the fixture drives no detection).
const { hudVariant, hudSonar } = toLegacyShareState(link);
assert.deepEqual([hudVariant, hudSonar], ['minimal', true]);
await owner.restoreShareState({ hudVariant, hudSonar });
assert.equal(hud.getVariant(), 'minimal');
assert.equal(isCyberSonarEnabled(root), true);
owner._setHudVariant('tactical');
owner._setCyberSonarEnabled(false);
// The saved shot's HUD, as the editor normalized and validated it.
assert.deepEqual(shot.visual.hud, {
visible: true,
variant: 'minimal',
sonar: true,
});
await owner.applyVisualState({ hud: shot.visual.hud });
assert.equal(hud.getVariant(), 'minimal');
assert.equal(isCyberSonarEnabled(root), true);
});
test('a link or scene shot that does not mention Sonar restores as before', async (t) => {
const { owner, hud, root } = sharingOwner(t, 'minimal');
// Made before Sonar was carried: Minimal turns the viewer's Sonar off...
setCyberSonarEnabled(true, root);
await owner.restoreShareState({ hudVariant: 'minimal' });
assert.equal(isCyberSonarEnabled(root), false);
setCyberSonarEnabled(true, root);
await owner.applyVisualState({ hud: { variant: 'minimal' } });
assert.equal(isCyberSonarEnabled(root), false);
// ...and Cyber still opens Tactical with Sonar on.
await owner.restoreShareState({ hudVariant: 'cyber', hudSonar: false });
assert.equal(hud.getVariant(), 'tactical');
assert.equal(isCyberSonarEnabled(root), true);
owner._setCyberSonarEnabled(false);
await owner.applyVisualState({ hud: { variant: 'cyber' } });
assert.equal(isCyberSonarEnabled(root), true);
// Sonar beside a layout counts only in a restore, not a layout choice.
owner._setCyberSonarEnabled(false);
owner._setHudVariant('minimal', { sonar: true });
assert.equal(isCyberSonarEnabled(root), false);
});
+35 -9
View File
@@ -73,6 +73,7 @@ export class VisualSettings {
bloomVersion,
sharpenIntensity,
hudVariant,
hudSonar,
hudVisible,
detectionMode,
detectionDensity,
@@ -122,7 +123,8 @@ export class VisualSettings {
this._setSharpenIntensity(sharpenIntensity, { syncShare: false });
if (typeof bloom === 'boolean') this._setBloomEnabled(bloom);
if (typeof sharpen === 'boolean') this._setSharpenEnabled(sharpen);
if (hudVariant) this._setHudVariant(hudVariant, { restore: true });
if (hudVariant)
this._setHudVariant(hudVariant, { restore: true, sonar: hudSonar });
if (typeof hudVisible === 'boolean') {
this.hud.setMode(hudVisible ? 'on' : 'off');
this._updateHudButtonState();
@@ -719,15 +721,21 @@ export class VisualSettings {
/**
* @param {string} variantName Layout, or the removed `cyber` layout.
* @param {{restore?: boolean}} [options] A share link, scene or saved view
* is authoritative for Sonar too: it is on only when the state names
* Cyber. Other callers leave Sonar as the viewer set it.
* @param {{restore?: boolean, sonar?: boolean}} [options] A share link,
* scene or saved view is authoritative for Sonar too: it is on only when
* the state names Cyber or says `sonar: true`, so a state that does not
* mention Sonar turns it off unless it names Cyber. Other callers leave
* Sonar as the viewer set it.
*/
_setHudVariant(variantName, { restore = false } = {}) {
_setHudVariant(
variantName,
{ restore = false, sonar: sonarOn = false } = {},
) {
if (!variantName) return;
// Cyber was removed; its sonar became a visual style. A state that names
// Cyber opens in Tactical with Sonar on.
const sonar = isLegacySonarHudLayout(variantName);
const sonar =
isLegacySonarHudLayout(variantName) || (restore && sonarOn === true);
if (sonar || (restore && isCyberSonarEnabled()))
this._setCyberSonarEnabled(sonar);
this.hud.setVariant(variantName);
@@ -761,8 +769,8 @@ export class VisualSettings {
/**
* The HUD layout a share link or scene shot records. Tactical with Sonar on
* is written as the retired Cyber code, which restores exactly that; Minimal
* has no such code, so its Sonar stays local.
* is written as the retired Cyber code, which restores exactly that and
* which older readers understand too.
*/
_sharedHudVariant() {
const variant = this.hud.getVariant();
@@ -771,6 +779,17 @@ export class VisualSettings {
: variant;
}
/**
* Whether a share link or scene shot records Sonar on beside its layout:
* only when the layout code does not already say so (Minimal with Sonar),
* so a state with Tactical and Sonar stays the Cyber code alone.
*/
_sharedHudSonar() {
return (
isCyberSonarEnabled() && !isLegacySonarHudLayout(this._sharedHudVariant())
);
}
_setCyberSonarSetting(name, value) {
const settings = readCyberSonarSettings();
if (!Object.hasOwn(settings, name)) return settings;
@@ -919,6 +938,7 @@ export class VisualSettings {
bloomVersion: BLOOM_SCALE_VERSION,
sharpenIntensity: this._sharpenPct,
hudVariant: this._sharedHudVariant(),
hudSonar: this._sharedHudSonar(),
hudVisible: this.hud.visible,
detectionMode: detection.mode,
detectionDensity: detection.densityPct,
@@ -1237,6 +1257,9 @@ export class VisualSettings {
hud: {
visible: this.hud.visible,
variant: this._sharedHudVariant(),
// Written only when on beside a layout that cannot say it, so a shot
// without Sonar or with Tactical and Sonar reads in older builds.
...(this._sharedHudSonar() ? { sonar: true } : {}),
},
detection: {
mode: getDetectionMode(),
@@ -1284,7 +1307,10 @@ export class VisualSettings {
const hudState = state.hud || {};
if (hudState.variant) {
this._setHudVariant(hudState.variant, { restore: true });
this._setHudVariant(hudState.variant, {
restore: true,
sonar: hudState.sonar,
});
}
if (typeof hudState.visible === 'boolean') {
this.hud.setMode(hudState.visible ? 'on' : 'off');