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(pipeline): a scene of placed surfaces becomes an atlas, and says what it skipped

esengine90f5396d7552
diff --git a/pipeline/src/assets/lightmapBake.ts b/pipeline/src/assets/lightmapBake.ts
new file mode 100644
index 000000000..6e899d7e4
--- /dev/null
+++ b/pipeline/src/assets/lightmapBake.ts
@@ -0,0 +1,95 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file lightmapBake.ts
+ * @brief A scene's surfaces and lights become the atlas a `MeshLightmap` reads.
+ *
+ * The same shape as the environment import: the computation lives here and the
+ * caller only writes files. What arrives is already placed — the editor holds
+ * the world the transforms come from, and this holds the meshes they name.
+ */
+import { readFileSync } from 'node:fs';
+import { bakeLightmap, decodeMesh, MeshChannel,
+ type BakeSurface, type BakeLight, type BakeOptions } from 'esengine';
+import { encodeRgbaPng } from './png';
+
+/** One placed object, as the editor's world describes it. */
+export interface SceneBakeSurface {
+ /** Absolute path of the `.esmesh` this object draws. */
+ meshFile: string;
+ /** How it is named where a warning has to be readable. */
+ label: string;
+ /** Column-major 4x4 world transform. */
+ transform: number[];
+ albedo?: [number, number, number];
+}
+
+export interface SceneBakeInput {
+ surfaces: SceneBakeSurface[];
+ lights: BakeLight[];
+ options?: BakeOptions;
+}
+
+export interface SceneBakeResult {
+ atlasBytes: Uint8Array;
+ /** Atlas rectangle per surface, in the order they were given — `null` for one
+ * that was skipped, so a caller can line results up with what it sent. */
+ scaleOffset: Array<[number, number, number, number] | null>;
+ /** Texels the bake actually solved. Zero means nothing was lit. */
+ lumels: number;
+ size: number;
+ warnings: string[];
+}
+
+/**
+ * Bakes what the caller placed, skipping what cannot receive light and saying so.
+ *
+ * A mesh with no second UV set is the case an author has to hear about: the bake
+ * cannot invent one here (that would split vertices the scene already references)
+ * and silently lighting everything else would look like the bake simply missed it.
+ */
+export function bakeSceneLightmap(input: SceneBakeInput): SceneBakeResult {
+ const warnings: string[] = [];
+ const surfaces: BakeSurface[] = [];
+ const slot: number[] = [];
+
+ for (let i = 0; i < input.surfaces.length; i++) {
+ const s = input.surfaces[i];
+ let mesh;
+ try {
+ mesh = decodeMesh(new Uint8Array(readFileSync(s.meshFile)));
+ } catch (err) {
+ warnings.push(`${s.label}: ${(err as Error).message}`);
+ continue;
+ }
+ if (!mesh.channels.some((c) => c.semantic === MeshChannel.TexCoord1)) {
+ warnings.push(`${s.label}: no second UV set, so it receives no baked light —`
+ + ' turn on Generate Lightmap UVs in its model\'s import settings and reimport');
+ continue;
+ }
+ slot.push(i);
+ surfaces.push({ mesh, transform: s.transform, albedo: s.albedo });
+ }
+
+ if (surfaces.length === 0) {
+ warnings.push('nothing in this scene can receive baked light');
+ return {
+ atlasBytes: encodeRgbaPng(1, 1, new Uint8Array([0, 0, 0, 255])),
+ scaleOffset: input.surfaces.map(() => null),
+ lumels: 0, size: 1, warnings,
+ };
+ }
+
+ const result = bakeLightmap(surfaces, input.lights, input.options);
+ const scaleOffset: Array<[number, number, number, number] | null> =
+ input.surfaces.map(() => null);
+ slot.forEach((at, k) => { scaleOffset[at] = result.scaleOffset[k]; });
+
+ return {
+ atlasBytes: encodeRgbaPng(result.size, result.size, result.pixels),
+ scaleOffset,
+ lumels: result.lumels,
+ size: result.size,
+ warnings,
+ };
+}
diff --git a/pipeline/src/index.ts b/pipeline/src/index.ts
index 2a8912328..679e4f819 100644
--- a/pipeline/src/index.ts
+++ b/pipeline/src/index.ts
@@ -19,6 +19,7 @@ export * from './assets/modelImport';
export * from './assets/readModelSource';
export * from './assets/gltfImport';
export * from './assets/fbxImport';
+export * from './assets/lightmapBake';
export * from './assets/assetMeta';
export * from './assets/assetDb';
export * from './assets/cookAssets';
diff --git a/pipeline/tests/lightmap-bake.test.ts b/pipeline/tests/lightmap-bake.test.ts
new file mode 100644
index 000000000..8a2417997
--- /dev/null
+++ b/pipeline/tests/lightmap-bake.test.ts
@@ -0,0 +1,108 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * The claim: a bake says what it could not light, and lights the rest anyway.
+ *
+ * Silence is the failure mode that matters here. A mesh with no second UV set
+ * looks, in the result, exactly like one the bake simply missed — and the fix
+ * (an import setting, then a reimport) is one only the author can apply.
+ */
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { encodeMesh, unwrapLightmapUV, MeshChannel, MeshChannelType,
+ type MeshData, type BakeLight } from 'esengine';
+import { bakeSceneLightmap, type SceneBakeSurface } from '../src/assets/lightmapBake';
+
+let dir = '';
+
+/** A quad on the XZ plane facing +Y. */
+function floor(half: number): MeshData {
+ const p = [[-half, 0, -half], [half, 0, -half], [half, 0, half], [-half, 0, half]];
+ const stride = 24;
+ const vertices = new Uint8Array(p.length * stride);
+ const view = new DataView(vertices.buffer);
+ p.forEach((q, i) => {
+ for (let k = 0; k < 3; k++) view.setFloat32(i * stride + k * 4, q[k], true);
+ view.setFloat32(i * stride + 16, 1, true);
+ });
+ return {
+ channels: [
+ { semantic: MeshChannel.Position, components: 3, type: MeshChannelType.Float32, offset: 0 },
+ { semantic: MeshChannel.Normal, components: 3, type: MeshChannelType.Float32, offset: 12 },
+ ],
+ vertexStride: stride,
+ vertexCount: 4,
+ vertices,
+ indices: Uint32Array.from([0, 2, 1, 0, 3, 2]),
+ aabbMin: [-half, 0, -half],
+ aabbMax: [half, 0, half],
+ };
+}
+
+const IDENTITY = [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1];
+const LAMP: BakeLight[] = [
+ { kind: 'point', position: [0, 4, 0], color: [1, 1, 1], intensity: 6, radius: 40 },
+];
+const SMALL = { atlasSize: 128, texelsPerUnit: 2, bounces: 0, samples: 8, dilate: 0 };
+
+beforeAll(async () => {
+ dir = await mkdtemp(path.join(tmpdir(), 'estella-bake-'));
+ await writeFile(path.join(dir, 'unwrapped.esmesh'), encodeMesh(unwrapLightmapUV(floor(4)).mesh));
+ await writeFile(path.join(dir, 'raw.esmesh'), encodeMesh(floor(4)));
+});
+
+afterAll(async () => {
+ await rm(dir, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 });
+});
+
+const surface = (file: string, label: string, x = 0): SceneBakeSurface => ({
+ meshFile: path.join(dir, file),
+ label,
+ transform: [...IDENTITY.slice(0, 12), x, 0, 0, 1],
+});
+
+describe('baking a scene', () => {
+ it('names the object it could not light, and lights the others', () => {
+ const result = bakeSceneLightmap({
+ surfaces: [surface('unwrapped.esmesh', 'Floor', -6), surface('raw.esmesh', 'Slab', 6)],
+ lights: LAMP,
+ options: SMALL,
+ });
+ expect(result.warnings).toHaveLength(1);
+ expect(result.warnings[0]).toContain('Slab');
+ expect(result.warnings[0]).toContain('Generate Lightmap UVs');
+ expect(result.lumels).toBeGreaterThan(0);
+ });
+
+ it('lines its answers up with what it was given', () => {
+ // The skipped object keeps its slot as null. A result that closed the gap
+ // would hand every rectangle after it to the wrong entity.
+ const result = bakeSceneLightmap({
+ surfaces: [surface('raw.esmesh', 'Slab'), surface('unwrapped.esmesh', 'Floor')],
+ lights: LAMP,
+ options: SMALL,
+ });
+ expect(result.scaleOffset).toHaveLength(2);
+ expect(result.scaleOffset[0]).toBeNull();
+ expect(result.scaleOffset[1]).not.toBeNull();
+ });
+
+ it('says so when nothing in the scene can take a bake', () => {
+ const result = bakeSceneLightmap({
+ surfaces: [surface('raw.esmesh', 'Slab')], lights: LAMP, options: SMALL,
+ });
+ expect(result.lumels).toBe(0);
+ expect(result.warnings.join(' ')).toContain('nothing in this scene');
+ });
+
+ it('writes a PNG the editor can adopt as an asset', () => {
+ const result = bakeSceneLightmap({
+ surfaces: [surface('unwrapped.esmesh', 'Floor')], lights: LAMP, options: SMALL,
+ });
+ expect(Array.from(result.atlasBytes.subarray(0, 8)))
+ .toEqual([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+ expect(result.size).toBe(128);
+ });
+});
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index 1fb24d81b..362a8e711 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -28,6 +28,13 @@ export const NOTES_FLOOR = 'v0.65.0';
* the reader recognises anyway.
*/
export const NOTED = {
+ 'refactor(pipeline): the PNG encoder gets its own file':
+ { internal: 'where one exported function lives — the bytes both imports write'
+ + ' are identical before and after' },
+ 'feat(pipeline): a scene of placed surfaces becomes an atlas, and says what it skipped':
+ { internal: 'the cook-side half of a bake with no trigger yet: no editor action'
+ + ' reaches it, so a creator cannot observe it until one does' },
+
'feat(render): lights become an atlas a mesh can be read through':
{ note: 'The bake itself: lights become an atlas.' },