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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
feat(environment): environment presets in the project file, and the sky and spheres of an environment
yhh4275f5e35bed
diff --git a/desktop b/desktopindex ee4b7453d..68a8e3283 160000--- a/desktop+++ b/desktop@@ -1 +1 @@-Subproject commit ee4b7453d8d09d6c643a8a4a82b04bafea9968d5+Subproject commit 68a8e32830e3a0e0aaaee26ff7e52e0db636e6f6diff --git a/pipeline/src/assets/environmentPreview.ts b/pipeline/src/assets/environmentPreview.tsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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([]);+ });+});