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(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.tsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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.mjsindex 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.' },