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
fix(bake): a baked atlas is read the way up it was baked
esengine284892f93aad
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 60181c381..b42c26072 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -22,6 +22,8 @@ published separately; it ships inside the editor.### Fixed+- **Baked light lands where it was baked.** The atlas file was written with its first texel row on top, and the engine uploads a picture bottom-up, so every surface read its light from the mirror-image place in the atlas — mostly empty, so a lit surface in shadow went near black and showed only its reflection of the sky. ORCA Bistro's awnings in the shade came out grey and its hedges blue-black; now they are red and green. A bake now writes its file bottom-up, and a gate draws an atlas that differs only by row the way a shipped game loads it. Rebake a scene to pick it up.+- **A shipped game samples normal maps and roughness maps as data.** The engine's own upload — a web export, a mini-game, a native build, the editor's Play — made every image an sRGB colour texture in a linear project whatever its import settings said, so every normal map was bent (a flat one by about fifty degrees) and every packed occlusion, roughness and metal map gamma-darkened, while the editor's viewport, which uploads through its own path, looked right. ORCA Bistro's Vespa came out as dark chrome in an exported game and blue in the editor. Khronos's NormalTangentTest now draws each normal-mapped bump as its geometric twin does.- Normal maps stay on up close. The tangent frame taken from screen derivatives was refused below a fixed size, which shrinks with the fourth power of distance and scale, so in a metre-scale scene a surface a few metres from the camera silently lost its normal map.- A coloured light bakes the colour it lights with. In a linear project the frame linearizes a light's colour and the bake took it as written, so a warm sun baked a paler, pinker bounce than the one it cast in real time.diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.jsonindex bc8258117..8debc7474 100644--- a/docs/astro/src/data/apiStability.generated.json+++ b/docs/astro/src/data/apiStability.generated.json@@ -3,10 +3,10 @@"counts": {"public": 115,"beta": 103,- "experimental": 2137,+ "experimental": 2138,"deprecated": 3},- "total": 2355,+ "total": 2356,"subsystems": [{"id": "ecs",diff --git a/examples/physics-3d/assets/scenes/main_lightmap.png b/examples/physics-3d/assets/scenes/main_lightmap.pngindex a6015473e..c3c23b6aa 100644Binary files a/examples/physics-3d/assets/scenes/main_lightmap.png and b/examples/physics-3d/assets/scenes/main_lightmap.png differdiff --git a/fixtures/scenes/lightmap-rows.esscene b/fixtures/scenes/lightmap-rows.esscenenew file mode 100644index 000000000..242ba89df--- /dev/null+++ b/fixtures/scenes/lightmap-rows.esscene@@ -0,0 +1,80 @@+{+ "version": 4,+ "name": "LightmapUnlit",+ "entities": [+ {+ "id": 0,+ "name": "Camera",+ "parent": null,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": 0,+ "y": 0,+ "z": 10+ }+ }+ },+ {+ "type": "Camera",+ "data": {+ "projectionType": 1,+ "orthoSize": 100,+ "isActive": true,+ "priority": 0+ }+ }+ ]+ },+ {+ "id": 1,+ "name": "Baked",+ "parent": null,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": 0,+ "y": 0,+ "z": 0+ }+ }+ },+ {+ "type": "MeshRenderer",+ "data": {+ "color": {+ "r": 1,+ "g": 1,+ "b": 1,+ "a": 1+ },+ "layer": 0,+ "enabled": true,+ "lit": false,+ "mesh": "/scenes/lightmap-quad.esmesh"+ }+ },+ {+ "type": "MeshLightmap",+ "data": {+ "lightmap": "@uuid:bbbbbbbb-1111-2222-3333-666666666666",+ "scaleOffset": {+ "x": 1,+ "y": 1,+ "z": 0,+ "w": 0+ }+ }+ }+ ]+ }+ ]+}\ No newline at end of filediff --git a/fixtures/scenes/lightmap-rows.png b/fixtures/scenes/lightmap-rows.pngnew file mode 100644index 000000000..75504aa75Binary files /dev/null and b/fixtures/scenes/lightmap-rows.png differdiff --git a/fixtures/scenes/lightmap-rows.textures.json b/fixtures/scenes/lightmap-rows.textures.jsonnew file mode 100644index 000000000..991c8b60a--- /dev/null+++ b/fixtures/scenes/lightmap-rows.textures.json@@ -0,0 +1,3 @@+{+ "bbbbbbbb-1111-2222-3333-666666666666": "/scenes/lightmap-rows.png"+}\ No newline at end of filediff --git a/pipeline/src/assets/lightmapBake.ts b/pipeline/src/assets/lightmapBake.tsindex d6fd1b36c..a3122b3a3 100644--- a/pipeline/src/assets/lightmapBake.ts+++ b/pipeline/src/assets/lightmapBake.ts@@ -10,7 +10,7 @@*/import { readFileSync } from 'node:fs';import { PNG } from 'pngjs';-import { bakeLightmapSteps, bakeRunner, decodeMesh, unwrapLightmapUV, builtinMeshTemplate, MeshChannel,+import { bakeLightmapSteps, bakeRunner, lightmapImage, decodeMesh, unwrapLightmapUV, builtinMeshTemplate, MeshChannel,type MeshData, type BakeSurface, type BakeLight, type BakeOptions,type BakeStep, type CapturedPanorama, type ProbeGrid } from 'esengine';import { encodeRgbaPng } from './png';@@ -424,7 +424,7 @@ function* sceneBakeSteps(input: SceneBakeInput, averages = new Map<string, TextugridSlot.forEach((at, k) => { probes[at] = asDocument(grids[k], result.probes[k]); });return {- atlasBytes: encodeRgbaPng(result.size, result.size, result.pixels),+ atlasBytes: encodeRgbaPng(result.size, result.size, lightmapImage(result.pixels, result.size)),scaleOffset,lumels: result.lumels,size: result.size,diff --git a/pipeline/tests/lightmap-bake.test.ts b/pipeline/tests/lightmap-bake.test.tsindex cff482c80..fa68bacbe 100644--- a/pipeline/tests/lightmap-bake.test.ts+++ b/pipeline/tests/lightmap-bake.test.ts@@ -208,7 +208,7 @@ describe('baking a scene', () => {let sum = 0;for (let y = Math.floor(ov * image.width); y < Math.ceil((ov + sv) * image.width); y++) {for (let x = Math.floor(ou * image.width); x < Math.ceil((ou + su) * image.width); x++) {- sum += decodeLightmap(image.rgba, y * image.width + x)[0];+ sum += decodeLightmap(image.rgba, (image.width - 1 - y) * image.width + x)[0];}}return sum;diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 516aae8fa..71f7cf035 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -1,7 +1,7 @@# API surface — esengine/index<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 115 public · 91 beta · 1523 experimental · 3 deprecated+Symbols: 115 public · 91 beta · 1524 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental```@@ -11433,6 +11433,11 @@ LifecyclePlugin(aim: Vec3): Quat```+## lightmapImage — function @experimental+```+(pixels: Uint8Array, size: number): Uint8Array+```+## linearKey — function @experimental```(time: number, value: number): Keyframediff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 9732af566..de0688361 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -1,7 +1,7 @@# API surface — esengine/index.native<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 115 public · 96 beta · 1542 experimental · 3 deprecated+Symbols: 115 public · 96 beta · 1543 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental```@@ -11684,6 +11684,11 @@ LifecyclePlugin(aim: Vec3): Quat```+## lightmapImage — function @experimental+```+(pixels: Uint8Array, size: number): Uint8Array+```+## linearKey — function @experimental```(time: number, value: number): Keyframediff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex d7455d733..4a00cebd1 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -1,7 +1,7 @@# API surface — esengine/index.node<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 115 public · 93 beta · 1522 experimental · 3 deprecated+Symbols: 115 public · 93 beta · 1523 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -11428,6 +11428,11 @@ LifecyclePlugin(aim: Vec3): Quat```+## lightmapImage — function @experimental+```+(pixels: Uint8Array, size: number): Uint8Array+```+## linearKey — function @experimental```(time: number, value: number): Keyframediff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 830d470d6..4dce13d59 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -1,7 +1,7 @@# API surface — esengine/minigame<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 115 public · 91 beta · 1544 experimental · 3 deprecated+Symbols: 115 public · 91 beta · 1545 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -11719,6 +11719,11 @@ LifecyclePlugin(aim: Vec3): Quat```+## lightmapImage — function @experimental+```+(pixels: Uint8Array, size: number): Uint8Array+```+## linearKey — function @experimental```(time: number, value: number): Keyframediff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 00a5c6236..62c961865 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -1,7 +1,7 @@# API surface — esengine/wechat<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 115 public · 91 beta · 1535 experimental · 3 deprecated+Symbols: 115 public · 91 beta · 1536 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -11469,6 +11469,11 @@ LifecyclePlugin(aim: Vec3): Quat```+## lightmapImage — function @experimental+```+(pixels: Uint8Array, size: number): Uint8Array+```+## linearKey — function @experimental```(time: number, value: number): Keyframediff --git a/sdk/src/core-content.ts b/sdk/src/core-content.tsindex fb28edb5e..202bab294 100644--- a/sdk/src/core-content.ts+++ b/sdk/src/core-content.ts@@ -156,7 +156,7 @@ export {bakeLightmap, type BakeOptions, type BakeResult, type BakeSurface, type BakeLight,type ProbeGrid, bakeHoldsStill, type BakeMobility, BAKE_DEFAULTS,captureReflection, flatSky, type CapturedPanorama, type SkyRadiance,- LIGHTMAP_RANGE, encodeLightmap, decodeLightmap,+ LIGHTMAP_RANGE, encodeLightmap, decodeLightmap, lightmapImage,bakeLightmapSteps, bakeRunner, type BakeScene, type BakeJob, type BakeStep,skyRadiance, type SkySpec,} from './lightmap';diff --git a/sdk/src/lightmap/bake.ts b/sdk/src/lightmap/bake.tsindex b30855bcc..fbf5913cb 100644--- a/sdk/src/lightmap/bake.ts+++ b/sdk/src/lightmap/bake.ts@@ -234,6 +234,18 @@ export function encodeLightmap(rgb: Float32Array, count: number): Uint8Array {return out;}+/**+ * The atlas as an image file holds it: texel row `y` (second UV `v` = y / size) in+ * image row `size - 1 - y`. The engine uploads a picture bottom-up, so a UV of 0+ * reads the image's LAST row; written top-down, every lookup lands on its mirror.+ */+export function lightmapImage(pixels: Uint8Array, size: number): Uint8Array {+ const out = new Uint8Array(pixels.length);+ const row = size * 4;+ for (let y = 0; y < size; y++) out.set(pixels.subarray(y * row, (y + 1) * row), (size - 1 - y) * row);+ return out;+}+/** What {@link encodeLightmap} wrote at texel `i`. */export function decodeLightmap(pixels: ArrayLike<number>, i: number): [number, number, number] {const d = (b: number): number => (b / 255) * (b / 255) * LIGHTMAP_RANGE;diff --git a/sdk/src/lightmap/index.ts b/sdk/src/lightmap/index.tsindex b401562ca..4b1285863 100644--- a/sdk/src/lightmap/index.ts+++ b/sdk/src/lightmap/index.ts@@ -1,7 +1,7 @@// SPDX-License-Identifier: Apache-2.0// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Teamexport { unwrapLightmapUV, type UnwrapOptions, type UnwrapResult } from './unwrap';-export { bakeLightmap, bakeLightmapSteps, bakeRunner, LIGHTMAP_RANGE, encodeLightmap, decodeLightmap,+export { bakeLightmap, bakeLightmapSteps, bakeRunner, LIGHTMAP_RANGE, encodeLightmap, decodeLightmap, lightmapImage,type BakeOptions, type BakeResult, type BakeScene, type BakeJob, type BakeStep } from './bake';export { skyRadiance, type SkySpec } from './sky';export type { BakeSurface } from './atlas';diff --git a/tools/make-lightmap-fixture.mjs b/tools/make-lightmap-fixture.mjsindex 084ac82d6..8543d43bc 100644--- a/tools/make-lightmap-fixture.mjs+++ b/tools/make-lightmap-fixture.mjs@@ -1,9 +1,9 @@// SPDX-License-Identifier: Apache-2.0// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team/**- * Regenerate the baked-light fixture: a quad with TWO UV sets (and a copy carrying a- * normal) and a four-texel atlas, red half then blue half. The second UV set is the- * TRANSPOSE of the first, so a bake read through the wrong channel turns ninety degrees.+ * Regenerate the baked-light fixtures: a quad whose UV1 is its UV0 TRANSPOSED (and a+ * copy with a normal), a red|blue four-texel atlas, and one differing only by ROW,+ * written by `lightmapImage` as a bake is, so a loader reading v = 0 wrong mirrors it.** node tools/make-lightmap-fixture.mjs*/@@ -11,12 +11,14 @@ import { writeFileSync } from 'node:fs';import { deflateSync } from 'node:zlib';import path from 'node:path';import { fileURLToPath } from 'node:url';-import { encodeMesh, packChannels, encodeLightmap, MeshChannel, MeshChannelType } from '../sdk/dist/index.node.js';+import { encodeMesh, packChannels, encodeLightmap, lightmapImage, MeshChannel, MeshChannelType }+ from '../sdk/dist/index.node.js';const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');const MESH = path.join(ROOT, 'fixtures', 'scenes', 'lightmap-quad.esmesh');const MESH_LIT = path.join(ROOT, 'fixtures', 'scenes', 'lightmap-quad-lit.esmesh');const ATLAS = path.join(ROOT, 'fixtures', 'scenes', 'lightmap-atlas.png');+const ROWS = path.join(ROOT, 'fixtures', 'scenes', 'lightmap-rows.png');/** Wide enough that every gate point lands well inside the quad. */const HALF = 80;@@ -86,20 +88,33 @@ const chunk = (type, body) => {return Buffer.concat([head, typed, tail]);};-const ihdr = Buffer.alloc(13);-ihdr.writeUInt32BE(TEXELS.length, 0);-ihdr.writeUInt32BE(1, 4);-ihdr[8] = 8; // bit depth-ihdr[9] = 6; // RGBA-const raw = Buffer.concat([- Buffer.from([0]), // filter: none- Buffer.from(encoded),-]);-writeFileSync(ATLAS, Buffer.concat([- Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),- chunk('IHDR', ihdr),- chunk('IDAT', deflateSync(raw)),- chunk('IEND', Buffer.alloc(0)),-]));+/** An RGBA8 PNG of `width` x `height`, rows top first. */+function writePng(file, width, height, rgba) {+ const ihdr = Buffer.alloc(13);+ ihdr.writeUInt32BE(width, 0);+ ihdr.writeUInt32BE(height, 4);+ ihdr[8] = 8; // bit depth+ ihdr[9] = 6; // RGBA+ const rows = [];+ for (let y = 0; y < height; y++) {+ rows.push(Buffer.from([0]), Buffer.from(rgba.subarray(y * width * 4, (y + 1) * width * 4)));+ }+ writeFileSync(file, Buffer.concat([+ Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),+ chunk('IHDR', ihdr),+ chunk('IDAT', deflateSync(Buffer.concat(rows))),+ chunk('IEND', Buffer.alloc(0)),+ ]));+}+writePng(ATLAS, TEXELS.length, 1, encoded);++/** Texel rows 0-1 (v below one half) red, rows 2-3 blue. Square, as a bake's+ * atlas is, and repeated across so the rows are the only thing that differs. */+const SIDE = 4;+const rowsTexels = new Float32Array(SIDE * SIDE * 3);+for (let y = 0; y < SIDE; y++) {+ for (let x = 0; x < SIDE; x++) rowsTexels.set(y < SIDE / 2 ? [1, 0, 0] : [0, 0, 1], (y * SIDE + x) * 3);+}+writePng(ROWS, SIDE, SIDE, lightmapImage(encodeLightmap(rowsTexels, SIDE * SIDE), SIDE));-console.log(`wrote ${path.relative(ROOT, MESH)}, ${path.relative(ROOT, MESH_LIT)} and ${path.relative(ROOT, ATLAS)}`);+console.log(`wrote ${path.relative(ROOT, MESH)}, ${path.relative(ROOT, MESH_LIT)}, ${path.relative(ROOT, ATLAS)} and ${path.relative(ROOT, ROWS)}`);diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjsindex 033cfd1bd..31cc41856 100644--- a/tools/releaseNotes.mjs+++ b/tools/releaseNotes.mjs@@ -1290,6 +1290,8 @@ export const NOTED = {{ note: 'A bake uses every core, in C++' },'perf(bake): the kernel averages a bake\'s textures on every core':{ note: 'A bake uses every core, in C++' },+ 'fix(bake): a baked atlas is read the way up it was baked':+ { note: 'Baked light lands where it was baked' },'fix(bake): a coloured light bakes the colour it lights with':{ note: 'A coloured light bakes the colour it lights with' },'fix(bake): the collector reads the colour space from the engine host':diff --git a/tools/renderScenes.mjs b/tools/renderScenes.mjsindex cfbbc7c40..cccba4e4f 100644--- a/tools/renderScenes.mjs+++ b/tools/renderScenes.mjs@@ -124,6 +124,9 @@ export const SCENES = [// right and the quad's second UV set is the transpose of its first, so reading// the wrong channel turns the halves and swaps two of these four points.{ id: "lightmap-unlit", tier: "pr", webgpu: true, env: { "ESTELLA_VERIFY_SCENE": "/scenes/lightmap-unlit.esscene", "ESTELLA_VERIFY_MANIFEST": "/scenes/lightmap-unlit.textures.json", "ESTELLA_VERIFY_W": "256", "ESTELLA_VERIFY_H": "256", "ESTELLA_VERIFY_STEPS": "2", "ESTELLA_VERIFY_EXPECT": "[{\"x\":0.3,\"y\":0.25,\"rgb\":[0,0,255],\"tol\":30},{\"x\":0.7,\"y\":0.25,\"rgb\":[0,0,255],\"tol\":30},{\"x\":0.3,\"y\":0.75,\"rgb\":[255,0,0],\"tol\":30},{\"x\":0.7,\"y\":0.75,\"rgb\":[255,0,0],\"tol\":30}]" } },+ // The atlas differs only by row, and is uploaded as a shipped game uploads a+ // picture: a baker and a loader that disagree on which row is v = 0 swap its halves.+ { id: "lightmap-rows", tier: "pr", webgpu: true, env: { "ESTELLA_VERIFY_SCENE": "/scenes/lightmap-rows.esscene", "ESTELLA_VERIFY_MANIFEST": "/scenes/lightmap-rows.textures.json", "ESTELLA_VERIFY_TEXTURES": "runtime", "ESTELLA_VERIFY_W": "256", "ESTELLA_VERIFY_H": "256", "ESTELLA_VERIFY_STEPS": "2", "ESTELLA_VERIFY_EXPECT": "[{\"x\":0.3,\"y\":0.25,\"rgb\":[255,0,0],\"tol\":30},{\"x\":0.3,\"y\":0.75,\"rgb\":[255,0,0],\"tol\":30},{\"x\":0.7,\"y\":0.25,\"rgb\":[0,0,255],\"tol\":30},{\"x\":0.7,\"y\":0.75,\"rgb\":[0,0,255],\"tol\":30}]" } },// A baked object and an unbaked one in ONE lit frame. Cyan and yellow halves// say the green sun SURVIVED, so the bake joins the lamps rather than replacing them; the plain// green quad says an unbaked one is not brightened by an unbound unit's white.