Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

feat(environment): one rule for the scene's environment light, six-image sources, and an import report

yhh9146d7fc3d54
diff --git a/desktop b/desktop
index fb089268b..ee4b7453d 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit fb089268b0edf37635dc4a70f9fb68a0baa71973
+Subproject commit ee4b7453d8d09d6c643a8a4a82b04bafea9968d5
diff --git a/pipeline/bin/estella.mjs b/pipeline/bin/estella.mjs
index 2cdd12d70..f7be8c18d 100644
--- a/pipeline/bin/estella.mjs
+++ b/pipeline/bin/estella.mjs
@@ -246,8 +246,8 @@ async function bakeScene(baker, meta, sceneFile, check) {
const volumes = [];
const reflectionProbes = [];
const ambient = [0, 0, 0];
- // The sky a capture sees and the format its atlas adopts. Read from the FIRST
- // ambient light naming one, which is the frame's environment too.
+ // The sky a capture sees and the format its atlas adopts: the frame's environment,
+ // which `sceneEnvironment` answers for every door that needs it (see below).
let environment = null;
const readEnvironment = (ref) => {
const file = resolveRef(ref);
@@ -322,11 +322,6 @@ async function bakeScene(baker, meta, sceneFile, check) {
center: [p.x, p.y, p.z] });
}
if (light) {
- if (!environment && typeof light.data?.environment === 'string'
- && light.data.environment !== '') {
- environment = readEnvironment(light.data.environment);
- if (environment) environment.rotation = light.data.environmentRotation ?? 0;
- }
const p = bakeWorldVec(tf.position, BAKE_ZERO);
const made = baker.bakeLightOf(light.data, [p.x, p.y, p.z],
bakeWorldVec(tf.rotation, BAKE_IDENTITY_Q), linearColor);
@@ -339,6 +334,17 @@ async function bakeScene(baker, meta, sceneFile, check) {
}
}
+ // The same rule the frame and the editor's collector apply, read once from the
+ // document rather than re-derived per light.
+ const chosen = baker.sceneEnvironment(baker.sceneAmbientLights(scene.entities ?? [], (ref) => {
+ const file = resolveRef(ref);
+ return !!file && existsSync(file);
+ })).effective;
+ if (chosen?.environment) {
+ environment = readEnvironment(chosen.environment);
+ if (environment) environment.rotation = chosen.rotation;
+ }
+
const fingerprint = baker.bakeFingerprint({
surfaces: fingerprintSurfaces, lights,
volumes: volumes.map((v) => ({ center: v.center, halfExtents: v.halfExtents,
diff --git a/pipeline/src/assets/environmentCube.ts b/pipeline/src/assets/environmentCube.ts
index d0a896f71..66de6de17 100644
--- a/pipeline/src/assets/environmentCube.ts
+++ b/pipeline/src/assets/environmentCube.ts
@@ -156,3 +156,57 @@ export function cubeFacesToPanorama(faces: CubeFaceSet, colorSpace: 'srgb' | 'li
}
return { width, height, rgb };
}
+
+/** The version of the `.escube` document. */
+export const CUBE_SOURCE_VERSION = 1;
+
+/**
+ * An environment's source made of six images — the `.escube` file, a sibling of `.hdr` as a
+ * source: importing it produces the same `.esenv`, atlas and sky. The images are named, not
+ * embedded, so replacing one is a re-import, and what the author chose about each face
+ * (its turn, its mirroring) is part of the source rather than of a dialog's memory.
+ */
+export interface CubeSourceDocument {
+ version: typeof CUBE_SOURCE_VERSION;
+ /** How the images are encoded. PNG and JPEG are sRGB, the default. */
+ colorSpace?: 'srgb' | 'linear';
+ faces: Partial<Record<CubeFaceName, { file: string; rotate?: 0 | 90 | 180 | 270; flip?: boolean }>>;
+}
+
+/** Read a `.escube` document, refusing what it cannot mean. A face left out is allowed here:
+ * an unfinished set is a document, and the import names what is missing. */
+export function parseCubeSource(raw: unknown): CubeSourceDocument {
+ if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+ throw new CubeImportError('a cube source is a JSON object');
+ }
+ const doc = raw as Record<string, unknown>;
+ if (doc.version !== CUBE_SOURCE_VERSION) {
+ throw new CubeImportError(`cube source version ${String(doc.version)} is not the ${CUBE_SOURCE_VERSION} this editor reads`);
+ }
+ if (doc.colorSpace !== undefined && doc.colorSpace !== 'srgb' && doc.colorSpace !== 'linear') {
+ throw new CubeImportError(`colorSpace must be "srgb" or "linear", not ${JSON.stringify(doc.colorSpace)}`);
+ }
+ if (typeof doc.faces !== 'object' || doc.faces === null || Array.isArray(doc.faces)) {
+ throw new CubeImportError('a cube source names its images under "faces"');
+ }
+ const faces: CubeSourceDocument['faces'] = {};
+ for (const [key, value] of Object.entries(doc.faces as Record<string, unknown>)) {
+ const name = (CUBE_FACE_NAMES as readonly string[]).includes(key) ? key as CubeFaceName : null;
+ if (!name) {
+ throw new CubeImportError(`"${key}" is not a face; the faces are ${CUBE_FACE_NAMES.join(', ')}`);
+ }
+ const f = value as Record<string, unknown> | null;
+ if (typeof f !== 'object' || f === null || typeof f.file !== 'string' || f.file === '') {
+ throw new CubeImportError(`face ${CUBE_FACE_LABELS[name]} needs the "file" it reads`, name);
+ }
+ if (f.rotate !== undefined && f.rotate !== 0 && f.rotate !== 90 && f.rotate !== 180 && f.rotate !== 270) {
+ throw new CubeImportError(`face ${CUBE_FACE_LABELS[name]}: rotate is 0, 90, 180 or 270, not ${JSON.stringify(f.rotate)}`, name);
+ }
+ if (f.flip !== undefined && typeof f.flip !== 'boolean') {
+ throw new CubeImportError(`face ${CUBE_FACE_LABELS[name]}: flip is true or false`, name);
+ }
+ faces[name] = { file: f.file, ...(f.rotate !== undefined ? { rotate: f.rotate } : {}),
+ ...(f.flip !== undefined ? { flip: f.flip } : {}) };
+ }
+ return { version: CUBE_SOURCE_VERSION, ...(doc.colorSpace ? { colorSpace: doc.colorSpace } : {}), faces };
+}
diff --git a/pipeline/src/assets/environmentImport.ts b/pipeline/src/assets/environmentImport.ts
index 8d0800d46..4951f98a9 100644
--- a/pipeline/src/assets/environmentImport.ts
+++ b/pipeline/src/assets/environmentImport.ts
@@ -592,14 +592,6 @@ export interface ImportedEnvironment {
report: EnvironmentImportReport;
}
-/** Named quality settings: what an author picks between import time and image bytes. */
-export const ENV_QUALITY_PRESETS = {
- low: { faceSize: 64, skyWidth: 1024 },
- standard: { faceSize: ENV_FACE_SIZE, skyWidth: ENV_SKY_MAX_WIDTH },
- high: { faceSize: 256, skyWidth: 4096 },
-} as const;
-export type EnvironmentQuality = keyof typeof ENV_QUALITY_PRESETS;
-
/** The most an import is allowed to ask for: past these the memory and time are not a
* quality setting but a way to run out of both. */
export const ENV_MAX_FACE_SIZE = 1024;
@@ -609,8 +601,6 @@ export interface EnvironmentImportOptions {
faceSize?: number;
mipCount?: number;
skyWidth?: number;
- /** A named preset; an explicit `faceSize` or `skyWidth` wins over it. */
- quality?: EnvironmentQuality;
}
/** Turn a Radiance panorama into the assets a scene can reference. */
@@ -627,14 +617,13 @@ export function importEnvironment(bytes: Uint8Array, stem: string,
*/
export function importEnvironmentFromPanorama(panorama: Panorama, stem: string,
options: EnvironmentImportOptions = {}): ImportedEnvironment {
- const preset = ENV_QUALITY_PRESETS[options.quality ?? 'standard'];
const warnings: string[] = [];
- let faceSize = options.faceSize ?? preset.faceSize;
+ let faceSize = options.faceSize ?? ENV_FACE_SIZE;
if (faceSize > ENV_MAX_FACE_SIZE) {
warnings.push(`faceSize ${faceSize} is past the ${ENV_MAX_FACE_SIZE} an import allows; it was imported at ${ENV_MAX_FACE_SIZE}`);
faceSize = ENV_MAX_FACE_SIZE;
}
- let skyWidth = options.skyWidth ?? preset.skyWidth;
+ let skyWidth = options.skyWidth ?? ENV_SKY_MAX_WIDTH;
if (skyWidth > ENV_MAX_SKY_WIDTH) {
warnings.push(`skyWidth ${skyWidth} is past the ${ENV_MAX_SKY_WIDTH} an import allows; it was imported at ${ENV_MAX_SKY_WIDTH}`);
skyWidth = ENV_MAX_SKY_WIDTH;
diff --git a/pipeline/src/assets/lightmapBake.ts b/pipeline/src/assets/lightmapBake.ts
index 7278e15b2..58a5599f1 100644
--- a/pipeline/src/assets/lightmapBake.ts
+++ b/pipeline/src/assets/lightmapBake.ts
@@ -26,6 +26,7 @@ import { bakeSceneReflections, bakeSky, irradianceSky, type BakeEnvironment,
// them through the one module it loads. composeTRS especially: a second
// implementation would put the two doors a rounding error apart.
export { bakeHoldsStill, bakeFingerprint, bakeLightOf, composeTRS, BAKE_DEFAULTS,
+ sceneAmbientLights, sceneEnvironment,
type BakeMobility, type BakeInputs } from 'esengine';
/** One placed object, as the editor's world describes it. */
diff --git a/pipeline/src/project/importSettings.ts b/pipeline/src/project/importSettings.ts
index 439db26ca..0b76ee4ca 100644
--- a/pipeline/src/project/importSettings.ts
+++ b/pipeline/src/project/importSettings.ts
@@ -213,9 +213,19 @@ const MODEL: ImporterFieldSpec[] = [
const PANORAMA: ImporterFieldSpec[] = [
{
key: 'faceSize', label: 'Reflection Size', type: 'enum', default: 128, category: 'Import',
- options: [32, 64, 128, 256].map((n) => ({ label: `${n} px`, value: n })),
+ options: [32, 64, 128, 256, 512].map((n) => ({ label: `${n} px`, value: n })),
tooltip: 'Edge length of the sharpest prefiltered reflection. Larger keeps a mirror '
- + 'crisper and costs baking time; the diffuse half is nine numbers either way.',
+ + 'crisper and costs baking time and image bytes; the diffuse half is nine numbers either way.',
+ },
+ {
+ key: 'skyWidth', label: 'Sky Width', type: 'enum', default: 2048, category: 'Import',
+ options: [
+ { label: 'No sky image', value: 0 },
+ ...[1024, 2048, 4096].map((n) => ({ label: `${n} px`, value: n })),
+ ],
+ tooltip: 'Width of the panorama the sky is drawn from, kept at the resolution of the source up '
+ + 'to this. Fine detail — stars, thin lines — needs more; a sky behind a dark scene needs '
+ + 'less. The reflections are sized apart, by Reflection Size.',
},
];
diff --git a/pipeline/tests/environment-cube.test.ts b/pipeline/tests/environment-cube.test.ts
index b1b68f6e0..128056881 100644
--- a/pipeline/tests/environment-cube.test.ts
+++ b/pipeline/tests/environment-cube.test.ts
@@ -6,11 +6,11 @@
*/
import { describe, it, expect } from 'vitest';
import {
- cubeFacesToPanorama, validateCubeFaces, CubeImportError, CUBE_FACE_NAMES,
+ cubeFacesToPanorama, validateCubeFaces, parseCubeSource, CubeImportError, CUBE_FACE_NAMES,
type CubeFace, type CubeFaceSet, type CubeFaceName,
} from '../src/assets/environmentCube';
import {
- samplePanorama, importEnvironmentFromPanorama, ENV_MAX_FACE_SIZE, ENV_QUALITY_PRESETS, type Panorama,
+ samplePanorama, importEnvironmentFromPanorama, ENV_MAX_FACE_SIZE, type Panorama,
} from '../src/assets/environmentImport';
const N = 32;
@@ -164,16 +164,39 @@ describe('an imported panorama reports what it cost and what it clipped', () =>
expect(r.report.skyBytes).toBe(0);
});
- it('takes a named quality and lets an explicit size win', () => {
- const low = importEnvironmentFromPanorama(flat(0.5), 'q', { quality: 'low', skyWidth: 64 });
- expect(low.report.faceSize).toBe(ENV_QUALITY_PRESETS.low.faceSize);
- const own = importEnvironmentFromPanorama(flat(0.5), 'q', { quality: 'low', faceSize: 32, skyWidth: 64 });
- expect(own.report.faceSize).toBe(32);
- });
-
it('refuses to be asked for more than an import allows, and says so', () => {
const r = importEnvironmentFromPanorama(flat(0.5), 'huge', { faceSize: ENV_MAX_FACE_SIZE * 4, mipCount: 1, skyWidth: 0 });
expect(r.report.faceSize).toBe(ENV_MAX_FACE_SIZE);
expect(r.warnings.join(' ')).toMatch(/past the 1024/);
}, 120000);
});
+
+describe('a cube source document', () => {
+ const good = (): Record<string, unknown> => ({
+ version: 1, colorSpace: 'linear',
+ faces: { px: { file: 'sky/px.png', rotate: 90, flip: true }, nx: { file: 'sky/nx.png' } },
+ });
+ const refused = (raw: unknown): CubeImportError => {
+ try { parseCubeSource(raw); } catch (e) { return e as CubeImportError; }
+ throw new Error('expected the document to be refused');
+ };
+
+ it('reads the faces, their turns and the colour space, and allows an unfinished set', () => {
+ const doc = parseCubeSource(good());
+ expect(doc.colorSpace).toBe('linear');
+ expect(doc.faces.px).toEqual({ file: 'sky/px.png', rotate: 90, flip: true });
+ expect(doc.faces.nx).toEqual({ file: 'sky/nx.png' });
+ expect(doc.faces.pz).toBeUndefined();
+ });
+
+ it('refuses a document it cannot mean, naming the face where there is one', () => {
+ expect(refused({ version: 2, faces: {} }).message).toMatch(/version 2/);
+ expect(refused({ version: 1, faces: [] }).message).toMatch(/under "faces"/);
+ expect(refused({ version: 1, colorSpace: 'p3', faces: {} }).message).toMatch(/colorSpace/);
+ expect(refused({ version: 1, faces: { up: { file: 'a.png' } } }).message).toMatch(/"up" is not a face/);
+ expect(refused({ version: 1, faces: { py: { file: '' } } }).face).toBe('py');
+ expect(refused({ version: 1, faces: { ny: { file: 'a.png', rotate: 45 } } }).face).toBe('ny');
+ expect(refused({ version: 1, faces: { nz: { file: 'a.png', flip: 'yes' } } }).face).toBe('nz');
+ expect(refused('nope').message).toMatch(/JSON object/);
+ });
+});
diff --git a/sdk/src/core-content.ts b/sdk/src/core-content.ts
index 2a73cdf63..b2aebc6b7 100644
--- a/sdk/src/core-content.ts
+++ b/sdk/src/core-content.ts
@@ -175,6 +175,8 @@ export {
export {
BakedLighting, type BakedLightingData, bakeFingerprint, type BakeInputs,
bakeLightOf, bakeLightForward, type AuthoredLight, type BakeLightContribution,
+ sceneAmbientLights, sceneEnvironment, carriesEnvironment, type SceneAmbientLight, type AmbientSkip,
+ type EnvironmentLightEntity,
} from './lightmap';
/**
* A decal's geometry: the surface under a projector, cut to its box. Ordinary
diff --git a/sdk/src/lightmap/environmentLight.ts b/sdk/src/lightmap/environmentLight.ts
new file mode 100644
index 000000000..96d0ec3ac
--- /dev/null
+++ b/sdk/src/lightmap/environmentLight.ts
@@ -0,0 +1,105 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file environmentLight.ts
+ * @brief Which Ambient light is a scene's environment.
+ *
+ * @details The frame decides this in RenderFrame.cpp: the first active Light that is
+ * enabled, has intensity, is Ambient and names an environment the registry
+ * holds. A bake has to take the same light's sky, and an editor has to say
+ * which light that is and why the others lose — three readers of one rule,
+ * so the document-side reading is this one function, beside `bakeLightOf`
+ * which fills defaults the same way. The C++ rule is the authority; this
+ * mirrors it over a scene document, so a change to one is a change to both.
+ */
+
+import { COMPONENT_META } from './metaAccess';
+import { LightType } from '../wasm/wasm.generated';
+
+/** The slice of a scene entity this reads. */
+export interface EnvironmentLightEntity {
+ id: number;
+ name: string;
+ /** Absent is visible. */
+ visible?: boolean;
+ components: ReadonlyArray<{ type: string; data: Record<string, unknown> }>;
+}
+
+/** Why the frame passes over an Ambient light, or null when it is in play. */
+export type AmbientSkip = 'hidden' | 'disabled' | 'no-intensity';
+
+/** One Ambient light, as the scene document states it with the component's defaults filled in. */
+export interface SceneAmbientLight {
+ entityId: number;
+ name: string;
+ skipped: AmbientSkip | null;
+ /** The environment it names, as written, or null when it names none. */
+ environment: string | null;
+ /** It names one the project does not hold. */
+ environmentMissing: boolean;
+ drawEnvironment: boolean;
+ /** Degrees about +Y. */
+ rotation: number;
+ intensity: number;
+}
+
+function field<T>(authored: Record<string, unknown>, defaults: Record<string, unknown> | undefined, key: string, fallback: T): T {
+ const own = authored[key];
+ if (own !== undefined) return own as T;
+ const base = defaults?.[key];
+ return (base !== undefined ? base : fallback) as T;
+}
+
+/**
+ * Every Ambient light in a scene, in document order.
+ *
+ * @param exists Whether the project holds the asset a light names. The frame cannot
+ * use an environment it cannot load, and it moves on to the next light.
+ */
+export function sceneAmbientLights(entities: readonly EnvironmentLightEntity[],
+ exists: (ref: string) => boolean): SceneAmbientLight[] {
+ const defaults = COMPONENT_META['Light']?.defaults as Record<string, unknown> | undefined;
+ const editorDefaults = COMPONENT_META['Light']?.editorDefaults as Record<string, unknown> | undefined;
+ const base = { ...defaults, ...editorDefaults };
+ const out: SceneAmbientLight[] = [];
+ for (const entity of entities) {
+ for (const component of entity.components) {
+ if (component.type !== 'Light') continue;
+ if (field<number>(component.data, base, 'type', 0) !== LightType.Ambient) continue;
+ const named = field<unknown>(component.data, base, 'environment', '');
+ const ref = typeof named === 'string' && named !== '' ? named : null;
+ const intensity = field<number>(component.data, base, 'intensity', 1);
+ const skipped: AmbientSkip | null =
+ entity.visible === false ? 'hidden'
+ : field<boolean>(component.data, base, 'enabled', true) === false ? 'disabled'
+ : !(intensity > 0) ? 'no-intensity' : null;
+ const rotation = field<number>(component.data, base, 'environmentRotation', 0);
+ out.push({
+ entityId: entity.id,
+ name: entity.name,
+ skipped,
+ environment: ref,
+ environmentMissing: ref !== null && !exists(ref),
+ drawEnvironment: field<boolean>(component.data, base, 'drawEnvironment', false) === true,
+ rotation: Number.isFinite(rotation) ? rotation : 0,
+ intensity: Number.isFinite(intensity) ? intensity : 1,
+ });
+ }
+ }
+ return out;
+}
+
+/** An Ambient light the frame could take the environment from. */
+export function carriesEnvironment(light: SceneAmbientLight): boolean {
+ return light.skipped === null && light.environment !== null && !light.environmentMissing;
+}
+
+/**
+ * The light whose environment the frame uses, and the lights that name one but lose to it.
+ * Nothing is removed from the scene to settle it: a shadowed light is kept, and said so.
+ */
+export function sceneEnvironment(lights: readonly SceneAmbientLight[]):
+ { effective: SceneAmbientLight | null; shadowed: SceneAmbientLight[] } {
+ const live = lights.filter(carriesEnvironment);
+ return { effective: live[0] ?? null, shadowed: live.slice(1) };
+}
diff --git a/sdk/src/lightmap/index.ts b/sdk/src/lightmap/index.ts
index ab6b15475..24584302b 100644
--- a/sdk/src/lightmap/index.ts
+++ b/sdk/src/lightmap/index.ts
@@ -14,6 +14,8 @@ export { bakeFingerprint, type BakeInputs } from './fingerprint';
export { BakedLighting, type BakedLightingData } from './components';
export { bakeLightOf, bakeLightForward, type AuthoredLight, type BakeLightContribution }
from './lights';
+export { sceneAmbientLights, sceneEnvironment, carriesEnvironment, type SceneAmbientLight, type AmbientSkip,
+ type EnvironmentLightEntity } from './environmentLight';
export { BAKE_DEFAULTS } from './bake';
export { shBasis, convolveCosine, evalIrradianceSH, SH_BASIS_SCALE, SH_COSINE_BAND } from './sh';
export { panoramaDirection, panoramaUV } from './panorama';
diff --git a/sdk/tests/environment-light.test.ts b/sdk/tests/environment-light.test.ts
new file mode 100644
index 000000000..25cd31758
--- /dev/null
+++ b/sdk/tests/environment-light.test.ts
@@ -0,0 +1,79 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * Which Ambient light is the scene's environment, read from a scene document the way the
+ * frame reads it from the world: the first that is in play, enabled, lit and names an
+ * environment the project holds — and every other one named, never removed.
+ */
+import { describe, it, expect } from 'vitest';
+import {
+ sceneAmbientLights, sceneEnvironment, carriesEnvironment, type EnvironmentLightEntity,
+} from '../src/lightmap';
+
+let next = 1;
+function entity(name: string, light: Record<string, unknown>, visible?: boolean): EnvironmentLightEntity {
+ return { id: next++, name, ...(visible === undefined ? {} : { visible }), components: [{ type: 'Light', data: light }] };
+}
+const AMBIENT = 2;
+const ambient = (name: string, data: Record<string, unknown> = {}, visible?: boolean): EnvironmentLightEntity =>
+ entity(name, { type: AMBIENT, ...data }, visible);
+const all = (): boolean => true;
+
+describe('the Ambient lights of a scene document', () => {
+ it('reads only Ambient lights, in document order, and fills the component\'s defaults in', () => {
+ const lights = sceneAmbientLights([
+ entity('Sun', { type: 1 }), ambient('A'), ambient('B', { environment: 'b.esenv' }),
+ ], all);
+ expect(lights.map((l) => l.name)).toEqual(['A', 'B']);
+ // Nothing was written for intensity or enabled, so the component's own defaults answer.
+ expect(lights[0]).toMatchObject({ skipped: null, environment: null, drawEnvironment: false, rotation: 0 });
+ expect(lights[0]!.intensity).toBeGreaterThan(0);
+ });
+
+ it('says why the frame passes over a light: hidden, switched off, or no intensity', () => {
+ const lights = sceneAmbientLights([
+ ambient('Hidden', { environment: 'a.esenv' }, false),
+ ambient('Off', { environment: 'a.esenv', enabled: false }),
+ ambient('Dark', { environment: 'a.esenv', intensity: 0 }),
+ ambient('On', { environment: 'a.esenv' }),
+ ], all);
+ expect(lights.map((l) => l.skipped)).toEqual(['hidden', 'disabled', 'no-intensity', null]);
+ });
+
+ it('marks a named environment the project does not hold', () => {
+ const [l] = sceneAmbientLights([ambient('Sky', { environment: 'gone.esenv' })], () => false);
+ expect(l).toMatchObject({ environment: 'gone.esenv', environmentMissing: true });
+ expect(carriesEnvironment(l!)).toBe(false);
+ });
+});
+
+describe('the scene\'s environment', () => {
+ const pick = (entities: EnvironmentLightEntity[], exists: (r: string) => boolean = all) =>
+ sceneEnvironment(sceneAmbientLights(entities, exists));
+
+ it('is none when no light names one', () => {
+ expect(pick([ambient('Flat')]).effective).toBeNull();
+ expect(pick([]).effective).toBeNull();
+ });
+
+ it('is the first light in play, skipping those the frame passes over', () => {
+ const r = pick([
+ ambient('Off', { environment: 'a.esenv', enabled: false }),
+ ambient('Gone', { environment: 'gone.esenv' }),
+ ambient('Zero', { environment: 'c.esenv', intensity: 0 }),
+ ambient('Winner', { environment: 'd.esenv' }),
+ ], (ref) => ref !== 'gone.esenv');
+ expect(r.effective?.name).toBe('Winner');
+ expect(r.shadowed).toEqual([]);
+ });
+
+ it('names the lights that lose to an earlier one, and keeps them', () => {
+ const r = pick([
+ ambient('First', { environment: 'a.esenv' }),
+ ambient('Second', { environment: 'b.esenv' }),
+ ambient('Third', { environment: 'c.esenv' }),
+ ]);
+ expect(r.effective?.name).toBe('First');
+ expect(r.shadowed.map((l) => l.name)).toEqual(['Second', 'Third']);
+ });
+});
diff --git a/tools/assetMetaTable.js b/tools/assetMetaTable.js
index 9ab75764b..d61828066 100644
--- a/tools/assetMetaTable.js
+++ b/tools/assetMetaTable.js
@@ -68,8 +68,11 @@ export const EXT_TO_TYPE = Object.freeze({
'.glb': 'model',
'.fbx': 'model',
// The same shape for lighting: a `.hdr` panorama is import-only and produces
- // the `.esenv` + atlas a scene references.
+ // the `.esenv` + atlas a scene references. So is a `.escube`, which names six
+ // images instead of holding one — the same type, because it is imported the same
+ // way and answers to the same settings.
'.hdr': 'panorama',
+ '.escube': 'panorama',
// And for 2D art: a layered document produces one image per layer plus the
// prefab that stacks them, and those are what a scene references.
'.psd': 'layered',