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): environment presets in the project file, and the sky and spheres of an environment

yhh4275f5e35bed
diff --git a/desktop b/desktop
index ee4b7453d..68a8e3283 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit ee4b7453d8d09d6c643a8a4a82b04bafea9968d5
+Subproject commit 68a8e32830e3a0e0aaaee26ff7e52e0db636e6f6
diff --git a/pipeline/src/assets/environmentPreview.ts b/pipeline/src/assets/environmentPreview.ts
new file mode 100644
index 000000000..27ec4e440
--- /dev/null
+++ b/pipeline/src/assets/environmentPreview.ts
@@ -0,0 +1,136 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file What an environment looks like, without a scene: its sky as a picture, and the
+ * two spheres every lighting artist reaches for — a diffuse grey one, which
+ * shows the irradiance, and a mirror, which shows the reflection.
+ *
+ * Read from the products the import wrote (the nine coefficients in the `.esenv` and the
+ * RGBM sky image beside it), turned about +Y the way the frame and the bake turn them:
+ * `skyRadiance` in the SDK is the authority for that rotation, and the sphere here uses
+ * the same one. So the preview answers "which way does this sky face under this
+ * rotation" with the engine's own convention, not a second guess at it.
+ *
+ * A picture to judge by, not a render: linear light is clamped and gamma-encoded, with no
+ * tone curve of the project's, so a bright sun reads as white rather than as its true value.
+ */
+import { evalIrradianceSH, panoramaDirection, panoramaUV } from 'esengine';
+import { decodeRgbm } from './environmentImport';
+
+/** An 8-bit RGBM image, row 0 = top: what the import writes for the sky. */
+export interface RgbmImage {
+ width: number;
+ height: number;
+ rgba: Uint8Array;
+}
+
+export interface EnvironmentPreviewInput {
+ /** The nine RGB coefficients, as the `.esenv` stores them. */
+ irradiance: readonly number[];
+ /** The sky image; null when the import wrote none, and the mirror then shows the
+ * irradiance — the only sky there is. */
+ sky: RgbmImage | null;
+ /** The RGBM decode range the document names. */
+ maxRange: number;
+ /** `environmentRotation`, in degrees. */
+ rotationDeg: number;
+ /** Scales what is shown; a Light's intensity is 1 for a neutral preview. */
+ exposure?: number;
+}
+
+export interface PreviewImage {
+ width: number;
+ height: number;
+ /** RGBA8, row 0 = top. Transparent outside a sphere. */
+ rgba: Uint8Array;
+}
+
+const encode = (linear: number): number =>
+ Math.round(Math.min(1, Math.max(0, Math.pow(Math.max(0, linear), 1 / 2.2))) * 255);
+
+/** The sky as the frame turns it: a world direction, in the environment's own frame. */
+function inEnvironment(rotationDeg: number, dx: number, dy: number, dz: number): [number, number, number] {
+ const yaw = (rotationDeg * Math.PI) / 180;
+ const c = Math.cos(yaw), s = Math.sin(yaw);
+ return [c * dx + s * dz, dy, -s * dx + c * dz];
+}
+
+/** Bilinear read of the RGBM sky along an environment-frame direction, in linear light. */
+function skyAt(sky: RgbmImage, maxRange: number, x: number, y: number, z: number, out: Float32Array): void {
+ const [u, v] = panoramaUV(x, y, z);
+ const fx = u * sky.width - 0.5, fy = v * sky.height - 0.5;
+ const x0 = Math.floor(fx), y0 = Math.floor(fy);
+ const tx = fx - x0, ty = fy - y0;
+ const wrap = (i: number): number => ((i % sky.width) + sky.width) % sky.width;
+ const clamp = (j: number): number => Math.max(0, Math.min(sky.height - 1, j));
+ const texel = (i: number, j: number): [number, number, number] => {
+ const o = (clamp(j) * sky.width + wrap(i)) * 4;
+ return decodeRgbm(sky.rgba[o]!, sky.rgba[o + 1]!, sky.rgba[o + 2]!, sky.rgba[o + 3]!, maxRange);
+ };
+ const a = texel(x0, y0), b = texel(x0 + 1, y0), c = texel(x0, y0 + 1), d = texel(x0 + 1, y0 + 1);
+ for (let k = 0; k < 3; k++) {
+ out[k] = (a[k]! * (1 - tx) + b[k]! * tx) * (1 - ty) + (c[k]! * (1 - tx) + d[k]! * tx) * ty;
+ }
+}
+
+/** The sky as a flat picture of the WORLD: each texel is the direction `panoramaDirection`
+ * gives it, read through the rotation, so the centre is what faces +Z — as on the spheres. */
+export function previewPanorama(input: EnvironmentPreviewInput, width: number): PreviewImage {
+ const height = Math.max(1, Math.round(width / 2));
+ const rgba = new Uint8Array(width * height * 4);
+ const exposure = input.exposure ?? 1;
+ const lin = new Float32Array(3);
+ for (let y = 0; y < height; y++) {
+ for (let x = 0; x < width; x++) {
+ const [dx, dy, dz] = panoramaDirection((x + 0.5) / width, (y + 0.5) / height);
+ sampleInto(input, dx, dy, dz, lin);
+ const o = (y * width + x) * 4;
+ rgba[o] = encode(lin[0]! * exposure); rgba[o + 1] = encode(lin[1]! * exposure);
+ rgba[o + 2] = encode(lin[2]! * exposure); rgba[o + 3] = 255;
+ }
+ }
+ return { width, height, rgba };
+}
+
+/** What the environment gives along a WORLD direction: the sky, or its irradiance when there is no image. */
+function sampleInto(input: EnvironmentPreviewInput, dx: number, dy: number, dz: number, out: Float32Array): void {
+ const [x, y, z] = inEnvironment(input.rotationDeg, dx, dy, dz);
+ if (input.sky) { skyAt(input.sky, input.maxRange, x, y, z, out); return; }
+ const [r, g, b] = evalIrradianceSH(input.irradiance, x, y, z);
+ out[0] = Math.max(0, r); out[1] = Math.max(0, g); out[2] = Math.max(0, b);
+}
+
+/**
+ * A sphere seen from +Z, lit by the environment.
+ *
+ * `diffuse` is a mid-grey matte ball: the irradiance the surface receives along its
+ * normal. `mirror` is a perfect reflector: the sky along the reflected view direction, so
+ * the centre of the ball shows what faces the viewer — +Z.
+ */
+export function previewBall(input: EnvironmentPreviewInput, mode: 'diffuse' | 'mirror', size: number): PreviewImage {
+ const rgba = new Uint8Array(size * size * 4);
+ const exposure = input.exposure ?? 1;
+ const lin = new Float32Array(3);
+ const albedo = 0.5;
+ for (let py = 0; py < size; py++) {
+ for (let px = 0; px < size; px++) {
+ const x = ((px + 0.5) / size) * 2 - 1;
+ const y = 1 - ((py + 0.5) / size) * 2;
+ const r2 = x * x + y * y;
+ if (r2 > 1) continue;
+ const nz = Math.sqrt(1 - r2);
+ const o = (py * size + px) * 4;
+ if (mode === 'diffuse') {
+ const [r, g, b] = evalIrradianceSH(input.irradiance, ...inEnvironment(input.rotationDeg, x, y, nz));
+ lin[0] = Math.max(0, r) * albedo; lin[1] = Math.max(0, g) * albedo; lin[2] = Math.max(0, b) * albedo;
+ } else {
+ // The viewer looks along -Z, so the reflection of the view vector v off normal n is
+ // v - 2(v.n)n, whose z component is 2 nz^2 - 1.
+ sampleInto(input, 2 * nz * x, 2 * nz * y, 2 * nz * nz - 1, lin);
+ }
+ rgba[o] = encode(lin[0]! * exposure); rgba[o + 1] = encode(lin[1]! * exposure);
+ rgba[o + 2] = encode(lin[2]! * exposure); rgba[o + 3] = 255;
+ }
+ }
+ return { width: size, height: size, rgba };
+}
diff --git a/pipeline/src/project/format.ts b/pipeline/src/project/format.ts
index 891c33d83..d6aaa0638 100644
--- a/pipeline/src/project/format.ts
+++ b/pipeline/src/project/format.ts
@@ -88,6 +88,22 @@ export interface ScreenPreset {
safe?: { top: number; bottom: number; left: number; right: number };
}
+/**
+ * A saved environment look: the asset an Ambient light names and how it is shown.
+ * Applying one writes these fields to a light the author picked, after showing which
+ * of them change; the preset never reaches into the scene by itself.
+ */
+export interface EnvironmentPreset {
+ /** What the author calls it, and what identifies it among the project's presets. */
+ name: string;
+ /** The `.esenv`, by project path or `@uuid:`. */
+ environment: string;
+ drawEnvironment: boolean;
+ /** Degrees about +Y. */
+ rotation: number;
+ intensity: number;
+}
+
/**
* Script entry points. Splitting declaration from
* startup is what lets the editor extract a component schema WITHOUT executing
@@ -484,6 +500,8 @@ export interface ProjectManifest {
designResolution?: DesignResolution;
/** Extra screens the target-screen dropdown offers, beside the built-in devices. */
screenPresets?: ScreenPreset[];
+ /** Environment looks the Lighting panel can apply to an Ambient light. */
+ environmentPresets?: EnvironmentPreset[];
/** Spine runtime the project needs ('none' | '2.1' | '3.8' | '4.1' | '4.2' | '4.3' …). */
spineVersion?: string;
/** Per-path overrides of {@link DEFAULT_LAYOUT}. */
@@ -688,6 +706,25 @@ export function parseManifest(raw: unknown): ProjectManifest {
});
if (presets.length > 0) manifest.screenPresets = presets;
}
+ if (Array.isArray(o.environmentPresets)) {
+ // Dropped rather than failing the load, like the screens above, and a repeated
+ // name keeps its first entry: a name that means two looks applies neither reliably.
+ const seen = new Set<string>();
+ const presets = (o.environmentPresets as unknown[]).flatMap((raw) => {
+ const p = raw as Partial<EnvironmentPreset> | null;
+ if (!p || typeof p.name !== 'string' || p.name.trim() === '' || seen.has(p.name)) return [];
+ if (typeof p.environment !== 'string' || p.environment === '') return [];
+ seen.add(p.name);
+ return [{
+ name: p.name,
+ environment: p.environment,
+ drawEnvironment: p.drawEnvironment === true,
+ rotation: typeof p.rotation === 'number' && Number.isFinite(p.rotation) ? p.rotation : 0,
+ intensity: typeof p.intensity === 'number' && Number.isFinite(p.intensity) ? p.intensity : 1,
+ }];
+ });
+ if (presets.length > 0) manifest.environmentPresets = presets;
+ }
if (o.layout && typeof o.layout === 'object') {
manifest.layout = o.layout as Partial<ProjectLayout>;
}
diff --git a/pipeline/tests/environment-preview.test.ts b/pipeline/tests/environment-preview.test.ts
new file mode 100644
index 000000000..a1282b6bf
--- /dev/null
+++ b/pipeline/tests/environment-preview.test.ts
@@ -0,0 +1,99 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * What an environment looks like without a scene: the sky as a picture, a matte sphere and a
+ * mirror — turned by the rotation the way the frame and the bake turn the environment, so
+ * "which way does this sky face" is answered in the engine's own convention.
+ */
+import { describe, it, expect } from 'vitest';
+import { PNG } from 'pngjs';
+import { panoramaDirection } from 'esengine';
+import { importEnvironmentFromPanorama, ENV_MAX_RANGE, type Panorama } from '../src/assets/environmentImport';
+import { previewBall, previewPanorama, type EnvironmentPreviewInput } from '../src/assets/environmentPreview';
+
+/** A sky of six flat colours, one per axis, so a preview pixel names the direction it saw. */
+function axisSky(): Panorama {
+ const width = 128, height = 64, rgb = new Float32Array(width * height * 3);
+ const colors: Record<string, [number, number, number]> = {
+ px: [4, 0, 0], nx: [1, 0, 0], py: [0, 4, 0], ny: [0, 1, 0], pz: [0, 0, 4], nz: [2, 2, 0],
+ };
+ for (let y = 0; y < height; y++) {
+ for (let x = 0; x < width; x++) {
+ const [dx, dy, dz] = panoramaDirection((x + 0.5) / width, (y + 0.5) / height);
+ const ax = Math.abs(dx), ay = Math.abs(dy), az = Math.abs(dz);
+ const key = ax >= ay && ax >= az ? (dx > 0 ? 'px' : 'nx') : ay >= az ? (dy > 0 ? 'py' : 'ny') : (dz > 0 ? 'pz' : 'nz');
+ rgb.set(colors[key]!, (y * width + x) * 3);
+ }
+ }
+ return { width, height, rgb };
+}
+
+function inputOf(rotationDeg = 0, withSky = true): EnvironmentPreviewInput {
+ const made = importEnvironmentFromPanorama(axisSky(), 't', { faceSize: 16, skyWidth: 128 });
+ const png = PNG.sync.read(Buffer.from(made.sky!.bytes));
+ return {
+ irradiance: made.document.irradiance,
+ sky: withSky ? { width: png.width, height: png.height, rgba: new Uint8Array(png.data) } : null,
+ maxRange: ENV_MAX_RANGE, rotationDeg,
+ };
+}
+
+const SIZE = 33;
+const at = (img: { width: number; rgba: Uint8Array }, x: number, y: number): number[] =>
+ [...img.rgba.subarray((y * img.width + x) * 4, (y * img.width + x) * 4 + 4)];
+const dominant = (c: number[]): 'r' | 'g' | 'b' | 'y' => {
+ const [r, g, b] = c as [number, number, number];
+ if (r > 100 && g > 100 && b < 100) return 'y';
+ return r >= g && r >= b ? 'r' : g >= b ? 'g' : 'b';
+};
+
+describe('the mirror sphere', () => {
+ it('shows what faces the viewer — +Z — at its centre', () => {
+ const ball = previewBall(inputOf(), 'mirror', SIZE);
+ expect(dominant(at(ball, 16, 16))).toBe('b');
+ });
+
+ it('shows what is behind it, -Z, at its rim', () => {
+ const ball = previewBall(inputOf(), 'mirror', SIZE);
+ // Just inside the rim, the reflected ray turns almost straight back.
+ expect(dominant(at(ball, 16, 1))).not.toBe('b');
+ });
+
+ it('turns the sky with the rotation: after 90 degrees the centre shows the environment\'s +X', () => {
+ expect(dominant(at(previewBall(inputOf(90), 'mirror', SIZE), 16, 16))).toBe('r');
+ expect(dominant(at(previewBall(inputOf(0), 'mirror', SIZE), 16, 16))).toBe('b');
+ });
+
+ it('is transparent outside the sphere', () => {
+ expect(at(previewBall(inputOf(), 'mirror', SIZE), 0, 0)[3]).toBe(0);
+ });
+
+ it('falls back to the irradiance when the import wrote no sky image', () => {
+ const ball = previewBall(inputOf(0, false), 'mirror', SIZE);
+ expect(at(ball, 16, 16)[3]).toBe(255);
+ });
+});
+
+describe('the matte sphere', () => {
+ it('is lit more from the side the sky is brighter on', () => {
+ // +Y is a strong green and -Y a weak one, so the top of the ball is greener than the bottom.
+ const ball = previewBall(inputOf(), 'diffuse', SIZE);
+ expect(at(ball, 16, 4)[1]!).toBeGreaterThan(at(ball, 16, 28)[1]!);
+ });
+});
+
+describe('the sky picture', () => {
+ it('puts +Z at the centre, and turns it with the rotation', () => {
+ const flat = previewPanorama(inputOf(0), 64);
+ expect(flat.height).toBe(32);
+ expect(dominant(at(flat, 32, 16))).toBe('b');
+ // Turned 90 degrees, the centre of the picture is the same direction the ball's centre shows.
+ expect(dominant(at(previewPanorama(inputOf(90), 64), 32, 16))).toBe('r');
+ });
+
+ it('is as bright as exposure makes it', () => {
+ const dim = previewPanorama({ ...inputOf(0), exposure: 0.1 }, 64);
+ const full = previewPanorama(inputOf(0), 64);
+ expect(at(dim, 32, 16)[2]!).toBeLessThan(at(full, 32, 16)[2]!);
+ });
+});
diff --git a/pipeline/tests/project-environment-presets.test.ts b/pipeline/tests/project-environment-presets.test.ts
new file mode 100644
index 000000000..5984a54d5
--- /dev/null
+++ b/pipeline/tests/project-environment-presets.test.ts
@@ -0,0 +1,43 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * A project's saved environment looks are read tolerantly: a hand-edited file must not cost
+ * the project, a bad entry is dropped, and a repeated name keeps the first.
+ */
+import { describe, it, expect } from 'vitest';
+import { parseManifest, ignoredManifestKeys } from '../src/project/format';
+
+const base = { name: 'Sky', formatVersion: '1' };
+
+describe('environmentPresets in the project file', () => {
+ it('reads a look, and fills the defaults of a field it leaves out', () => {
+ const m = parseManifest({ ...base, environmentPresets: [
+ { name: 'Dusk', environment: 'assets/dusk.esenv', drawEnvironment: true, rotation: 90, intensity: 0.5 },
+ { name: 'Plain', environment: '@uuid:abc' },
+ ] });
+ expect(m.environmentPresets).toEqual([
+ { name: 'Dusk', environment: 'assets/dusk.esenv', drawEnvironment: true, rotation: 90, intensity: 0.5 },
+ { name: 'Plain', environment: '@uuid:abc', drawEnvironment: false, rotation: 0, intensity: 1 },
+ ]);
+ });
+
+ it('drops an entry that names no look or no environment, and keeps the rest', () => {
+ const m = parseManifest({ ...base, environmentPresets: [
+ null, { name: '', environment: 'a.esenv' }, { name: 'NoEnv' }, { name: 'Good', environment: 'a.esenv' },
+ ] });
+ expect(m.environmentPresets?.map((p) => p.name)).toEqual(['Good']);
+ });
+
+ it('keeps the first of a repeated name', () => {
+ const m = parseManifest({ ...base, environmentPresets: [
+ { name: 'Same', environment: 'a.esenv' }, { name: 'Same', environment: 'b.esenv' },
+ ] });
+ expect(m.environmentPresets).toHaveLength(1);
+ expect(m.environmentPresets![0]!.environment).toBe('a.esenv');
+ });
+
+ it('leaves the field absent when no look survives, and does not report the key as unread', () => {
+ expect(parseManifest({ ...base, environmentPresets: [{ name: '' }] }).environmentPresets).toBeUndefined();
+ expect(ignoredManifestKeys({ ...base, environmentPresets: [] })).toEqual([]);
+ });
+});