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(render): lights become an atlas a mesh can be read through
esengine4b137b74d48f
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 6527b656d..a5629bb5f 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -16,6 +16,39 @@ published separately; it ships inside the editor.### Added+- **The bake itself: lights become an atlas.** `bakeLightmap` takes surfaces and+ lights and returns the texture a `MeshLightmap` reads, plus the rectangle each+ object occupies in it. It runs the way the navmesh builder does — plain+ TypeScript, a stage per file, one orchestration: lay out, rasterise, solve+ direct, bounce, dilate, encode.++ **Direct light** is a shadow ray per lamp per texel, so what stands in the way+ leaves a shadow, and there is no ceiling on how many lamps there are — which is+ the whole point, since a frame carries sixteen and drops the seventeenth by+ brightness. **The bounce** reads the atlas the pass before it wrote, so each+ round carries light one surface further and costs what the first did; that is+ the term a real-time frame here has no way to compute at all. Irradiance is+ what is stored, not colour: the surface's own texture is applied where the bake+ is read, so one atlas survives a retexture.++ Every object's patch is sized by the surface it actually has, at one+ world-to-texel ratio across the whole atlas — the same rule the unwrap follows+ inside one mesh, applied between them. Surfaces that do not fit are refused+ rather than quietly shrunk: a wall lit at a different resolution from the floor+ it meets is a seam, and choosing between a bigger atlas and a coarser density+ is the author's call.++ Five gates, one claim each: twenty lights all reach the picture, a wall leaves+ a shadow, a panel facing away from every lamp is lit only once light may+ bounce, two objects occupy two patches, and the same scene bakes to the same+ bytes twice. Five sabotages, each red only where it should be — including one+ that stayed green until the determinism gate was given a scene that actually+ bounces, since over a lone plane every ray misses and a random hemisphere+ passes too.++ **There is still nothing in the editor that triggers a bake.** The pieces are a+ library the next step drives.+- **A model can be given somewhere to receive baked light.** A bake is readthrough a second UV set, and it has to be one where no two surfaces share atexel — which the UV set the art is wrapped in deliberately is not: two armsdiff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.jsonindex 75b993e4a..84b7953d8 100644--- a/docs/astro/src/data/apiStability.generated.json+++ b/docs/astro/src/data/apiStability.generated.json@@ -3,10 +3,10 @@"counts": {"public": 114,"beta": 101,- "experimental": 1884,+ "experimental": 1889,"deprecated": 3},- "total": 2099,+ "total": 2104,"subsystems": [{"id": "ecs",@@ -347,10 +347,11 @@"title": "Baked lighting","titleZh": "烘焙光照","tier": "experimental",- "why": "half a line: the engine reads a bake and nothing here produces one yet, so the shape of this will follow what a baker turns out to need",- "whyZh": "只做了一半:引擎读得了烘焙图,而这里还产不出一张,所以这套接口的形状要跟着烘焙器最终需要什么走",+ "why": "the bake runs and nothing in the editor triggers one yet, so the shape of this will follow what an authoring panel turns out to need",+ "whyZh": "烘焙跑得起来,但编辑器里还没有什么去触发它,所以这套接口的形状要跟着创作面最终需要什么走","entry": [- "unwrapLightmapUV"+ "unwrapLightmapUV",+ "bakeLightmap"]},{diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 5245c0ec1..c0d2d0e5a 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: 114 public · 94 beta · 1723 experimental · 3 deprecated+Symbols: 114 public · 94 beta · 1728 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental```@@ -1331,6 +1331,43 @@ resolveUrl: (path: string) => stringsetBaseUrl: ((url: string) => void) | undefined```+## BakeLight — interface @experimental+```+color: readonly [number, number, number]+direction: readonly [number, number, number] | undefined+innerCos: number | undefined+intensity: number+kind: "directional" | "point" | "spot"+outerCos: number | undefined+position: readonly [number, number, number] | undefined+radius: number | undefined+```++## BakeOptions — interface @experimental+```+ambient: readonly [number, number, number] | undefined+atlasSize: number | undefined+bounces: number | undefined+dilate: number | undefined+samples: number | undefined+texelsPerUnit: number | undefined+```++## BakeResult — interface @experimental+```+lumels: number+pixels: Uint8Array<ArrayBufferLike>+scaleOffset: [number, number, number, number][]+size: number+```++## BakeSurface — interface @experimental+```+albedo: readonly [number, number, number] | undefined+mesh: MeshData+transform: ArrayLike<number>+```+## BatchBreak — enum @experimental```Blend = 4@@ -10964,6 +11001,11 @@ AudioPlugin(world: Pick<World, "tryGet">, avatar: AnimatorAvatar | null): JointResolver```+## bakeLightmap — function @experimental+```+(surfaces: readonly BakeSurface[], lights: readonly BakeLight[], options?: BakeOptions): BakeResult+```+## bind — function @experimental```<C extends object, K extends keyof C>(world: World, entity: Entity, component: ComponentDef<C>, field: K, source: ReadonlySignal<C[K]>): () => voiddiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex af201d59c..ae0c03660 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: 114 public · 99 beta · 1742 experimental · 3 deprecated+Symbols: 114 public · 99 beta · 1747 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental```@@ -1331,6 +1331,43 @@ resolveUrl: (path: string) => stringsetBaseUrl: ((url: string) => void) | undefined```+## BakeLight — interface @experimental+```+color: readonly [number, number, number]+direction: readonly [number, number, number] | undefined+innerCos: number | undefined+intensity: number+kind: "directional" | "point" | "spot"+outerCos: number | undefined+position: readonly [number, number, number] | undefined+radius: number | undefined+```++## BakeOptions — interface @experimental+```+ambient: readonly [number, number, number] | undefined+atlasSize: number | undefined+bounces: number | undefined+dilate: number | undefined+samples: number | undefined+texelsPerUnit: number | undefined+```++## BakeResult — interface @experimental+```+lumels: number+pixels: Uint8Array<ArrayBufferLike>+scaleOffset: [number, number, number, number][]+size: number+```++## BakeSurface — interface @experimental+```+albedo: readonly [number, number, number] | undefined+mesh: MeshData+transform: ArrayLike<number>+```+## BatchBreak — enum @experimental```Blend = 4@@ -11172,6 +11209,11 @@ AudioPlugin(world: Pick<World, "tryGet">, avatar: AnimatorAvatar | null): JointResolver```+## bakeLightmap — function @experimental+```+(surfaces: readonly BakeSurface[], lights: readonly BakeLight[], options?: BakeOptions): BakeResult+```+## bind — function @experimental```<C extends object, K extends keyof C>(world: World, entity: Entity, component: ComponentDef<C>, field: K, source: ReadonlySignal<C[K]>): () => voiddiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex c7e0637f9..a64b3f4bc 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: 114 public · 96 beta · 1722 experimental · 3 deprecated+Symbols: 114 public · 96 beta · 1727 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -1326,6 +1326,43 @@ resolveUrl: (path: string) => stringsetBaseUrl: ((url: string) => void) | undefined```+## BakeLight — interface @experimental+```+color: readonly [number, number, number]+direction: readonly [number, number, number] | undefined+innerCos: number | undefined+intensity: number+kind: "directional" | "point" | "spot"+outerCos: number | undefined+position: readonly [number, number, number] | undefined+radius: number | undefined+```++## BakeOptions — interface @experimental+```+ambient: readonly [number, number, number] | undefined+atlasSize: number | undefined+bounces: number | undefined+dilate: number | undefined+samples: number | undefined+texelsPerUnit: number | undefined+```++## BakeResult — interface @experimental+```+lumels: number+pixels: Uint8Array<ArrayBufferLike>+scaleOffset: [number, number, number, number][]+size: number+```++## BakeSurface — interface @experimental+```+albedo: readonly [number, number, number] | undefined+mesh: MeshData+transform: ArrayLike<number>+```+## BatchBreak — enum @experimental```Blend = 4@@ -10959,6 +10996,11 @@ AudioPlugin(world: Pick<World, "tryGet">, avatar: AnimatorAvatar | null): JointResolver```+## bakeLightmap — function @experimental+```+(surfaces: readonly BakeSurface[], lights: readonly BakeLight[], options?: BakeOptions): BakeResult+```+## bind — function @experimental```<C extends object, K extends keyof C>(world: World, entity: Entity, component: ComponentDef<C>, field: K, source: ReadonlySignal<C[K]>): () => voiddiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 5b569d1cd..b9c136b35 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: 114 public · 94 beta · 1744 experimental · 3 deprecated+Symbols: 114 public · 94 beta · 1749 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -1326,6 +1326,43 @@ resolveUrl: (path: string) => stringsetBaseUrl: ((url: string) => void) | undefined```+## BakeLight — interface @experimental+```+color: readonly [number, number, number]+direction: readonly [number, number, number] | undefined+innerCos: number | undefined+intensity: number+kind: "directional" | "point" | "spot"+outerCos: number | undefined+position: readonly [number, number, number] | undefined+radius: number | undefined+```++## BakeOptions — interface @experimental+```+ambient: readonly [number, number, number] | undefined+atlasSize: number | undefined+bounces: number | undefined+dilate: number | undefined+samples: number | undefined+texelsPerUnit: number | undefined+```++## BakeResult — interface @experimental+```+lumels: number+pixels: Uint8Array<ArrayBufferLike>+scaleOffset: [number, number, number, number][]+size: number+```++## BakeSurface — interface @experimental+```+albedo: readonly [number, number, number] | undefined+mesh: MeshData+transform: ArrayLike<number>+```+## BatchBreak — enum @experimental```Blend = 4@@ -11213,6 +11250,11 @@ AudioPlugin(world: Pick<World, "tryGet">, avatar: AnimatorAvatar | null): JointResolver```+## bakeLightmap — function @experimental+```+(surfaces: readonly BakeSurface[], lights: readonly BakeLight[], options?: BakeOptions): BakeResult+```+## bind — function @experimental```<C extends object, K extends keyof C>(world: World, entity: Entity, component: ComponentDef<C>, field: K, source: ReadonlySignal<C[K]>): () => voiddiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 2993d077d..b1f5333f7 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: 114 public · 94 beta · 1734 experimental · 3 deprecated+Symbols: 114 public · 94 beta · 1739 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -1326,6 +1326,43 @@ resolveUrl: (path: string) => stringsetBaseUrl: ((url: string) => void) | undefined```+## BakeLight — interface @experimental+```+color: readonly [number, number, number]+direction: readonly [number, number, number] | undefined+innerCos: number | undefined+intensity: number+kind: "directional" | "point" | "spot"+outerCos: number | undefined+position: readonly [number, number, number] | undefined+radius: number | undefined+```++## BakeOptions — interface @experimental+```+ambient: readonly [number, number, number] | undefined+atlasSize: number | undefined+bounces: number | undefined+dilate: number | undefined+samples: number | undefined+texelsPerUnit: number | undefined+```++## BakeResult — interface @experimental+```+lumels: number+pixels: Uint8Array<ArrayBufferLike>+scaleOffset: [number, number, number, number][]+size: number+```++## BakeSurface — interface @experimental+```+albedo: readonly [number, number, number] | undefined+mesh: MeshData+transform: ArrayLike<number>+```+## BatchBreak — enum @experimental```Blend = 4@@ -10987,6 +11024,11 @@ AudioPlugin(world: Pick<World, "tryGet">, avatar: AnimatorAvatar | null): JointResolver```+## bakeLightmap — function @experimental+```+(surfaces: readonly BakeSurface[], lights: readonly BakeLight[], options?: BakeOptions): BakeResult+```+## bind — function @experimental```<C extends object, K extends keyof C>(world: World, entity: Entity, component: ComponentDef<C>, field: K, source: ReadonlySignal<C[K]>): () => voiddiff --git a/sdk/src/core-content.ts b/sdk/src/core-content.tsindex d2330ff1a..8ec221633 100644--- a/sdk/src/core-content.ts+++ b/sdk/src/core-content.ts@@ -143,6 +143,16 @@ export type { MeshResult } from './asset/loaders/MeshAssetLoader';export {unwrapLightmapUV, type UnwrapOptions, type UnwrapResult,} from './lightmap';+/**+ * Bakes lights into an atlas a `MeshLightmap` reads. Direct light, then what+ * bounced — the term a frame here cannot compute, and the way past its ceiling+ * of sixteen lights.+ *+ * @experimental Pre-1.0: the options will follow what an authoring panel needs.+ */+export {+ bakeLightmap, type BakeOptions, type BakeResult, type BakeSurface, type BakeLight,+} from './lightmap';/*** Stock geometry a `builtin:<id>` mesh ref names. Public because the editor's* pickers and Create menu are built from this list. `@beta`.diff --git a/sdk/src/lightmap/atlas.ts b/sdk/src/lightmap/atlas.tsnew file mode 100644index 000000000..2f6c8ac25--- /dev/null+++ b/sdk/src/lightmap/atlas.ts@@ -0,0 +1,227 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file atlas.ts+ * @brief Which texel of the atlas is which point of the world.+ *+ * Every object gets a patch sized by the surface it actually has, so one+ * world-to-texel ratio holds across the whole bake — the same rule the unwrap+ * follows inside one mesh, applied between them.+ */++import { MeshChannel, MeshChannelType, type MeshData, type MeshChannelDesc } from '../asset/meshFormat';+import { packSkyline } from './pack';++/** One object to bake: geometry with a lightmap UV set, and where it stands. */+export interface BakeSurface {+ mesh: MeshData;+ /** Column-major 4x4, as `glm` and the engine write one. */+ transform: ArrayLike<number>;+ /** What fraction of each channel the surface reflects. Drives the bounce;+ * a surface that reflects nothing still receives light. */+ albedo?: readonly [number, number, number];+}++/** Texels of one object's patch, and where in the atlas it sits. */+export interface SurfacePatch {+ /** Side of the square patch, in texels. */+ side: number;+ x: number;+ y: number;+ rotated: boolean;+ /** What a `MeshLightmap` carries: `[scaleU, scaleV, offsetU, offsetV]`. */+ scaleOffset: [number, number, number, number];+}++/** Every texel a bake will solve, as parallel arrays. */+export interface LumelField {+ count: number;+ /** World position, three floats each. */+ position: Float32Array;+ /** World normal, three floats each. */+ normal: Float32Array;+ /** Index into the atlas, one per lumel. */+ texel: Int32Array;+ /** Which surface each lumel belongs to. */+ surface: Int32Array;+}++const chan = (m: MeshData, s: number): MeshChannelDesc | undefined =>+ m.channels.find((c) => c.semantic === s);++function reader(mesh: MeshData): (v: number, semantic: number, n: number, out: Float32Array, at: number) => boolean {+ const view = new DataView(mesh.vertices.buffer, mesh.vertices.byteOffset, mesh.vertices.byteLength);+ return (v, semantic, n, out, at) => {+ const c = chan(mesh, semantic);+ if (!c || c.type !== MeshChannelType.Float32) return false;+ const base = v * mesh.vertexStride + c.offset;+ for (let k = 0; k < n; k++) out[at + k] = k < c.components ? view.getFloat32(base + k * 4, true) : 0;+ return true;+ };+}++function transformPoint(m: ArrayLike<number>, x: number, y: number, z: number, out: Float32Array, at: number): void {+ out[at] = m[0] * x + m[4] * y + m[8] * z + m[12];+ out[at + 1] = m[1] * x + m[5] * y + m[9] * z + m[13];+ out[at + 2] = m[2] * x + m[6] * y + m[10] * z + m[14];+}++/** Direction under the same transform, without its translation. Not the inverse+ * transpose: a bake takes objects as placed, and a non-uniform scale on baked+ * geometry is a modelling choice this does not try to rescue. */+function transformDir(m: ArrayLike<number>, x: number, y: number, z: number, out: Float32Array, at: number): void {+ const nx = m[0] * x + m[4] * y + m[8] * z;+ const ny = m[1] * x + m[5] * y + m[9] * z;+ const nz = m[2] * x + m[6] * y + m[10] * z;+ const len = Math.hypot(nx, ny, nz) || 1;+ out[at] = nx / len; out[at + 1] = ny / len; out[at + 2] = nz / len;+}++/** World and UV area of one surface, which together give its texel ratio. */+function areasOf(surface: BakeSurface): { world: number; uv: number } {+ const read = reader(surface.mesh);+ const p = new Float32Array(9);+ const t = new Float32Array(6);+ const w = new Float32Array(9);+ let world = 0, uv = 0;+ const idx = surface.mesh.indices;+ for (let i = 0; i + 2 < idx.length; i += 3) {+ for (let k = 0; k < 3; k++) {+ if (!read(idx[i + k], MeshChannel.Position, 3, p, k * 3)) return { world: 0, uv: 0 };+ if (!read(idx[i + k], MeshChannel.TexCoord1, 2, t, k * 2)) return { world: 0, uv: 0 };+ transformPoint(surface.transform, p[k * 3], p[k * 3 + 1], p[k * 3 + 2], w, k * 3);+ }+ const ux = w[3] - w[0], uy = w[4] - w[1], uz = w[5] - w[2];+ const vx = w[6] - w[0], vy = w[7] - w[1], vz = w[8] - w[2];+ world += Math.hypot(uy * vz - uz * vy, uz * vx - ux * vz, ux * vy - uy * vx) / 2;+ uv += Math.abs((t[2] - t[0]) * (t[5] - t[1]) - (t[4] - t[0]) * (t[3] - t[1])) / 2;+ }+ return { world, uv };+}++/**+ * Gives every surface a patch of an `size`-by-`size` atlas at `texelsPerUnit`.+ *+ * Returns null when they do not fit — the caller's signal to ask for a bigger+ * atlas or a coarser density, which is a decision an author makes rather than+ * one a packer should make quietly by shrinking someone.+ */+export function layoutAtlas(surfaces: readonly BakeSurface[], size: number,+ texelsPerUnit: number): SurfacePatch[] | null {+ const sides = surfaces.map((s) => {+ const { world, uv } = areasOf(s);+ if (world <= 0 || uv <= 0) return 1;+ // The unwrap kept one ratio inside the mesh; this is what that ratio is,+ // and it says how many texels a patch needs to hit the density asked for.+ const side = texelsPerUnit / Math.sqrt(uv / world);+ return Math.max(2, Math.min(size, Math.ceil(side)));+ });+ const placed = packSkyline(sides.map((s) => [s, s] as const), size);+ if (!placed) return null;+ return sides.map((side, i) => ({+ side,+ x: placed[i].x,+ y: placed[i].y,+ rotated: placed[i].rotated,+ scaleOffset: [side / size, side / size, placed[i].x / size, placed[i].y / size],+ }));+}++/**+ * The world point and normal behind every texel the surfaces cover.+ *+ * A texel centred outside every triangle is not in the field: solving it would+ * pay for the gaps between charts. What keeps a bilinear tap off those gaps is+ * the dilate afterwards, not a lumel invented here.+ */+export function rasterizeLumels(surfaces: readonly BakeSurface[],+ patches: readonly SurfacePatch[], size: number): LumelField {+ const position: number[] = [];+ const normal: number[] = [];+ const texel: number[] = [];+ const owner: number[] = [];+ const seen = new Set<number>();++ const p = new Float32Array(9);+ const n = new Float32Array(9);+ const t = new Float32Array(6);+ const wp = new Float32Array(9);+ const wn = new Float32Array(9);++ for (let s = 0; s < surfaces.length; s++) {+ const surface = surfaces[s];+ const patch = patches[s];+ const read = reader(surface.mesh);+ const idx = surface.mesh.indices;+ const hasNormals = chan(surface.mesh, MeshChannel.Normal) !== undefined;+ for (let i = 0; i + 2 < idx.length; i += 3) {+ let ok = true;+ for (let k = 0; k < 3 && ok; k++) {+ ok = read(idx[i + k], MeshChannel.Position, 3, p, k * 3)+ && read(idx[i + k], MeshChannel.TexCoord1, 2, t, k * 2);+ if (!ok) break;+ transformPoint(surface.transform, p[k * 3], p[k * 3 + 1], p[k * 3 + 2], wp, k * 3);+ if (hasNormals && read(idx[i + k], MeshChannel.Normal, 3, n, k * 3)) {+ transformDir(surface.transform, n[k * 3], n[k * 3 + 1], n[k * 3 + 2], wn, k * 3);+ }+ }+ if (!ok) continue;+ if (!hasNormals) {+ // The face's own normal, for geometry that carries none.+ const ux = wp[3] - wp[0], uy = wp[4] - wp[1], uz = wp[5] - wp[2];+ const vx = wp[6] - wp[0], vy = wp[7] - wp[1], vz = wp[8] - wp[2];+ const fx = uy * vz - uz * vy, fy = uz * vx - ux * vz, fz = ux * vy - uy * vx;+ const len = Math.hypot(fx, fy, fz) || 1;+ for (let k = 0; k < 3; k++) {+ wn[k * 3] = fx / len; wn[k * 3 + 1] = fy / len; wn[k * 3 + 2] = fz / len;+ }+ }++ // Into the patch's own texels, then into the atlas.+ const ax: number[] = [], ay: number[] = [];+ for (let k = 0; k < 3; k++) {+ const u = patch.rotated ? t[k * 2 + 1] : t[k * 2];+ const v = patch.rotated ? t[k * 2] : t[k * 2 + 1];+ ax.push(patch.x + u * patch.side);+ ay.push(patch.y + v * patch.side);+ }+ const area = (ax[1] - ax[0]) * (ay[2] - ay[0]) - (ax[2] - ax[0]) * (ay[1] - ay[0]);+ if (Math.abs(area) < 1e-9) continue;+ const minX = Math.max(0, Math.floor(Math.min(...ax)));+ const maxX = Math.min(size - 1, Math.ceil(Math.max(...ax)));+ const minY = Math.max(0, Math.floor(Math.min(...ay)));+ const maxY = Math.min(size - 1, Math.ceil(Math.max(...ay)));+ for (let y = minY; y <= maxY; y++) {+ for (let x = minX; x <= maxX; x++) {+ const cx = x + 0.5, cy = y + 0.5;+ const w0 = ((ax[1] - cx) * (ay[2] - cy) - (ax[2] - cx) * (ay[1] - cy)) / area;+ const w1 = ((ax[2] - cx) * (ay[0] - cy) - (ax[0] - cx) * (ay[2] - cy)) / area;+ const w2 = 1 - w0 - w1;+ if (w0 < 0 || w1 < 0 || w2 < 0) continue;+ const at = y * size + x;+ if (seen.has(at)) continue;+ seen.add(at);+ for (let k = 0; k < 3; k++) {+ position.push(w0 * wp[k] + w1 * wp[3 + k] + w2 * wp[6 + k]);+ }+ let nx = w0 * wn[0] + w1 * wn[3] + w2 * wn[6];+ let ny = w0 * wn[1] + w1 * wn[4] + w2 * wn[7];+ let nz = w0 * wn[2] + w1 * wn[5] + w2 * wn[8];+ const len = Math.hypot(nx, ny, nz) || 1;+ nx /= len; ny /= len; nz /= len;+ normal.push(nx, ny, nz);+ texel.push(at);+ owner.push(s);+ }+ }+ }+ }++ return {+ count: texel.length,+ position: Float32Array.from(position),+ normal: Float32Array.from(normal),+ texel: Int32Array.from(texel),+ surface: Int32Array.from(owner),+ };+}diff --git a/sdk/src/lightmap/bake.ts b/sdk/src/lightmap/bake.tsnew file mode 100644index 000000000..e403aecb3--- /dev/null+++ b/sdk/src/lightmap/bake.ts@@ -0,0 +1,204 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file bake.ts+ * @brief Surfaces and lights in, an atlas out — the whole bake, in one place.+ *+ * Lay out, rasterise, solve direct, bounce, dilate, encode. Each stage is its+ * own file and testable on its own; this is the order they go in, and the one+ * place a caller's units are turned into the texels every stage works in.+ */++import { MeshChannel, MeshChannelType, type MeshData, type MeshChannelDesc } from '../asset/meshFormat';+import { Bvh, type TriangleSoup } from './bvh';+import { layoutAtlas, rasterizeLumels, type BakeSurface, type SurfacePatch } from './atlas';+import { solveDirect, solveBounce, type BakeLight, type HitLookup } from './solve';++export interface BakeOptions {+ /** Side of the square atlas, in texels. */+ atlasSize?: number;+ /** How finely a surface is lit, in texels per world unit. */+ texelsPerUnit?: number;+ /** How many times light is allowed to reflect. Zero is direct light only —+ * useful, because past the sixteen a frame can carry it is still the answer. */+ bounces?: number;+ /** Rays each lumel gathers per bounce. */+ samples?: number;+ /** Light every surface receives from no direction in particular. */+ ambient?: readonly [number, number, number];+ /** Texels the solved edges are smeared outwards, so a bilinear tap near a+ * chart's border does not read the empty atlas beside it. */+ dilate?: number;+}++export interface BakeResult {+ /** RGBA8, `atlasSize * atlasSize * 4` — what a `.png` is written from. */+ pixels: Uint8Array;+ size: number;+ /** What each surface's `MeshLightmap.scaleOffset` must be set to, in order. */+ scaleOffset: Array<[number, number, number, number]>;+ /** Texels the surfaces actually cover, out of the atlas. */+ lumels: number;+}++const DEFAULTS = {+ atlasSize: 512,+ texelsPerUnit: 2,+ bounces: 2,+ samples: 64,+ ambient: [0, 0, 0] as readonly [number, number, number],+ dilate: 2,+};++const chan = (m: MeshData, s: number): MeshChannelDesc | undefined =>+ m.channels.find((c) => c.semantic === s);++/** Every surface's triangles in world space, plus what a ray hit has to know. */+function collect(surfaces: readonly BakeSurface[], patches: readonly SurfacePatch[],+ size: number): { soup: TriangleSoup; lookup: HitLookup } {+ let total = 0;+ for (const s of surfaces) total += Math.floor(s.mesh.indices.length / 3);+ const positions = new Float32Array(total * 9);+ const triUV = new Float32Array(total * 6);+ const triSurface = new Int32Array(total);+ const patch = new Float32Array(surfaces.length * 4);+ const albedo = new Float32Array(surfaces.length * 3);++ let at = 0;+ for (let s = 0; s < surfaces.length; s++) {+ const mesh = surfaces[s].mesh;+ const m = surfaces[s].transform;+ const a = surfaces[s].albedo ?? [0.5, 0.5, 0.5];+ albedo.set(a, s * 3);+ patch[s * 4] = patches[s].x;+ patch[s * 4 + 1] = patches[s].y;+ patch[s * 4 + 2] = patches[s].side;+ patch[s * 4 + 3] = patches[s].rotated ? 1 : 0;++ const pos = chan(mesh, MeshChannel.Position);+ const uv1 = chan(mesh, MeshChannel.TexCoord1);+ const view = new DataView(mesh.vertices.buffer, mesh.vertices.byteOffset, mesh.vertices.byteLength);+ const idx = mesh.indices;+ for (let i = 0; i + 2 < idx.length; i += 3, at++) {+ triSurface[at] = s;+ for (let k = 0; k < 3; k++) {+ const v = idx[i + k];+ if (pos && pos.type === MeshChannelType.Float32) {+ const b = v * mesh.vertexStride + pos.offset;+ const x = view.getFloat32(b, true);+ const y = view.getFloat32(b + 4, true);+ const z = pos.components >= 3 ? view.getFloat32(b + 8, true) : 0;+ positions[at * 9 + k * 3] = m[0] * x + m[4] * y + m[8] * z + m[12];+ positions[at * 9 + k * 3 + 1] = m[1] * x + m[5] * y + m[9] * z + m[13];+ positions[at * 9 + k * 3 + 2] = m[2] * x + m[6] * y + m[10] * z + m[14];+ }+ if (uv1 && uv1.type === MeshChannelType.Float32) {+ const b = v * mesh.vertexStride + uv1.offset;+ triUV[at * 6 + k * 2] = view.getFloat32(b, true);+ triUV[at * 6 + k * 2 + 1] = view.getFloat32(b + 4, true);+ }+ }+ }+ }+ return { soup: { positions, count: total }, lookup: { triUV, triSurface, patch, albedo } };+}++/** Smears solved texels outwards so a bilinear tap near an edge reads light+ * rather than the gap beside it. The gaps are where charts do not meet. */+function dilate(radiance: Float32Array, solved: Uint8Array, size: number, rounds: number): void {+ for (let round = 0; round < rounds; round++) {+ const filled = solved.slice();+ for (let y = 0; y < size; y++) {+ for (let x = 0; x < size; x++) {+ const at = y * size + x;+ if (solved[at]) continue;+ let r = 0, g = 0, b = 0, n = 0;+ for (let dy = -1; dy <= 1; dy++) {+ for (let dx = -1; dx <= 1; dx++) {+ const nx = x + dx, ny = y + dy;+ if (nx < 0 || ny < 0 || nx >= size || ny >= size) continue;+ const near = ny * size + nx;+ if (!solved[near]) continue;+ r += radiance[near * 3]; g += radiance[near * 3 + 1]; b += radiance[near * 3 + 2];+ n++;+ }+ }+ if (n === 0) continue;+ radiance[at * 3] = r / n; radiance[at * 3 + 1] = g / n; radiance[at * 3 + 2] = b / n;+ filled[at] = 1;+ }+ }+ solved.set(filled);+ }+}++/**+ * Bakes `lights` into an atlas the surfaces can be read through.+ *+ * Throws when the surfaces do not fit: a bake that quietly shrank someone would+ * light one wall at a different resolution from the next, and the caller is the+ * one who can decide between a bigger atlas and a coarser density.+ */+export function bakeLightmap(surfaces: readonly BakeSurface[], lights: readonly BakeLight[],+ options: BakeOptions = {}): BakeResult {+ const opts = { ...DEFAULTS, ...options };+ const size = opts.atlasSize;+ const patches = layoutAtlas(surfaces, size, opts.texelsPerUnit);+ if (!patches) {+ throw new Error(`bakeLightmap: ${surfaces.length} surface(s) do not fit a ${size}px atlas at`+ + ` ${opts.texelsPerUnit} texels per unit — raise the atlas or lower the density`);+ }+ const lumels = rasterizeLumels(surfaces, patches, size);+ const { soup, lookup } = collect(surfaces, patches, size);+ const bvh = new Bvh(soup);++ const direct = new Float32Array(lumels.count * 3);+ solveDirect(lumels, bvh, lights, opts.ambient, direct);++ // The atlas as each pass leaves it, so the next reads what the last wrote —+ // which is what carries light one more surface along.+ const radiance = new Float32Array(size * size * 3);+ const solved = new Uint8Array(size * size);+ const total = new Float32Array(lumels.count * 3);+ total.set(direct);+ let emitted = direct;+ for (let bounce = 0; bounce < opts.bounces; bounce++) {+ radiance.fill(0);+ for (let i = 0; i < lumels.count; i++) {+ const at = lumels.texel[i] * 3;+ radiance[at] = emitted[i * 3];+ radiance[at + 1] = emitted[i * 3 + 1];+ radiance[at + 2] = emitted[i * 3 + 2];+ }+ const gathered = new Float32Array(lumels.count * 3);+ solveBounce(lumels, bvh, lookup, radiance, size, opts.samples, gathered);+ for (let i = 0; i < gathered.length; i++) total[i] += gathered[i];+ emitted = gathered;+ }++ radiance.fill(0);+ solved.fill(0);+ for (let i = 0; i < lumels.count; i++) {+ const at = lumels.texel[i] * 3;+ radiance[at] = total[i * 3];+ radiance[at + 1] = total[i * 3 + 1];+ radiance[at + 2] = total[i * 3 + 2];+ solved[lumels.texel[i]] = 1;+ }+ dilate(radiance, solved, size, opts.dilate);++ const pixels = new Uint8Array(size * size * 4);+ for (let i = 0; i < size * size; i++) {+ for (let k = 0; k < 3; k++) {+ pixels[i * 4 + k] = Math.max(0, Math.min(255, Math.round(radiance[i * 3 + k] * 255)));+ }+ pixels[i * 4 + 3] = 255;+ }++ return {+ pixels,+ size,+ scaleOffset: patches.map((p) => p.scaleOffset),+ lumels: lumels.count,+ };+}diff --git a/sdk/src/lightmap/bvh.ts b/sdk/src/lightmap/bvh.tsnew file mode 100644index 000000000..b143a41a6--- /dev/null+++ b/sdk/src/lightmap/bvh.ts@@ -0,0 +1,191 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file bvh.ts+ * @brief What a ray hits, and how far away — the question a bake asks millions+ * of times and nothing else here answers.+ *+ * Flat typed arrays throughout, and a traversal that allocates nothing: a bake+ * of one room is tens of millions of these, and an object per ray is the whole+ * cost of the pass.+ */++/** Triangles as `9 * count` floats: three world-space corners each. */+export interface TriangleSoup {+ positions: Float32Array;+ count: number;+}++const LEAF_TRIS = 4;+const STACK = 64;++export class Bvh {+ /** Six floats per node: min xyz, max xyz. */+ private readonly bounds: Float32Array;+ /** Two ints per node: a leaf's first triangle or an inner node's right child,+ * then the triangle count — zero for an inner node. */+ private readonly node: Int32Array;+ /** Triangle indices, reordered so a leaf's are contiguous. */+ private readonly order: Int32Array;+ private readonly tris: TriangleSoup;+ private used = 0;++ constructor(tris: TriangleSoup) {+ this.tris = tris;+ this.order = new Int32Array(tris.count);+ for (let i = 0; i < tris.count; i++) this.order[i] = i;+ const maxNodes = Math.max(1, tris.count * 2);+ this.bounds = new Float32Array(maxNodes * 6);+ this.node = new Int32Array(maxNodes * 2);+ this.used = 1;+ this.build(0, 0, tris.count);+ }++ private centroid(tri: number, axis: number): number {+ const at = this.order[tri] * 9;+ return (this.tris.positions[at + axis] + this.tris.positions[at + 3 + axis]+ + this.tris.positions[at + 6 + axis]) / 3;+ }++ private bound(node: number, from: number, to: number): void {+ const b = node * 6;+ for (let k = 0; k < 3; k++) { this.bounds[b + k] = Infinity; this.bounds[b + 3 + k] = -Infinity; }+ for (let t = from; t < to; t++) {+ const at = this.order[t] * 9;+ for (let c = 0; c < 3; c++) {+ for (let k = 0; k < 3; k++) {+ const v = this.tris.positions[at + c * 3 + k];+ if (v < this.bounds[b + k]) this.bounds[b + k] = v;+ if (v > this.bounds[b + 3 + k]) this.bounds[b + 3 + k] = v;+ }+ }+ }+ }++ /** Split on the widest axis at the centroid midpoint — cheap, and a bake+ * builds this once per scene while it traverses it for hours. */+ private build(node: number, from: number, to: number): void {+ this.bound(node, from, to);+ const n = to - from;+ if (n <= LEAF_TRIS) {+ this.node[node * 2] = from;+ this.node[node * 2 + 1] = n;+ return;+ }+ const b = node * 6;+ let axis = 0;+ let widest = -1;+ for (let k = 0; k < 3; k++) {+ const w = this.bounds[b + 3 + k] - this.bounds[b + k];+ if (w > widest) { widest = w; axis = k; }+ }+ const mid = (this.bounds[b + axis] + this.bounds[b + 3 + axis]) / 2;+ let i = from, j = to - 1;+ while (i <= j) {+ if (this.centroid(i, axis) < mid) i++;+ else { const tmp = this.order[i]; this.order[i] = this.order[j]; this.order[j] = tmp; j--; }+ }+ // Every centroid on one side of the midpoint: split down the middle+ // instead, or the recursion never shrinks.+ let split = i;+ if (split === from || split === to) split = (from + to) >> 1;++ const left = this.used++;+ const right = this.used++;+ this.node[node * 2] = right;+ this.node[node * 2 + 1] = 0;+ this.build(left, from, split);+ this.build(right, split, to);+ }++ /**+ * Whether anything blocks the segment from `origin` to `origin + dir * far`.+ *+ * A shadow ray wants the first blocker, not the nearest one, so this stops at+ * the first hit — which is most of what a bake asks and the cheapest to answer.+ */+ occluded(ox: number, oy: number, oz: number,+ dx: number, dy: number, dz: number, far: number, epsilon: number): boolean {+ return this.trace(ox, oy, oz, dx, dy, dz, far, epsilon, true) >= 0;+ }++ /** The nearest triangle along the ray, or -1. `hitDistance` holds how far. */+ hit(ox: number, oy: number, oz: number,+ dx: number, dy: number, dz: number, far: number, epsilon: number): number {+ return this.trace(ox, oy, oz, dx, dy, dz, far, epsilon, false);+ }++ /** Distance to the last {@link hit}; meaningless before one. */+ hitDistance = 0;+ /** Barycentric coordinates of the last {@link hit}, as `u` and `v` on corners+ * two and three — corner one takes `1 - u - v`. */+ hitU = 0;+ hitV = 0;++ private readonly stack = new Int32Array(STACK);++ private trace(ox: number, oy: number, oz: number, dx: number, dy: number, dz: number,+ far: number, epsilon: number, anyHit: boolean): number {+ const invX = 1 / dx, invY = 1 / dy, invZ = 1 / dz;+ let best = -1;+ let bestT = far;+ let sp = 0;+ this.stack[sp++] = 0;+ while (sp > 0) {+ const node = this.stack[--sp];+ const b = node * 6;+ const tx1 = (this.bounds[b] - ox) * invX, tx2 = (this.bounds[b + 3] - ox) * invX;+ let tmin = Math.min(tx1, tx2), tmax = Math.max(tx1, tx2);+ const ty1 = (this.bounds[b + 1] - oy) * invY, ty2 = (this.bounds[b + 4] - oy) * invY;+ tmin = Math.max(tmin, Math.min(ty1, ty2)); tmax = Math.min(tmax, Math.max(ty1, ty2));+ const tz1 = (this.bounds[b + 2] - oz) * invZ, tz2 = (this.bounds[b + 5] - oz) * invZ;+ tmin = Math.max(tmin, Math.min(tz1, tz2)); tmax = Math.min(tmax, Math.max(tz1, tz2));+ if (tmax < Math.max(tmin, epsilon) || tmin > bestT) continue;++ const count = this.node[node * 2 + 1];+ if (count === 0) {+ this.stack[sp++] = node + 1;+ this.stack[sp++] = this.node[node * 2];+ continue;+ }+ const first = this.node[node * 2];+ for (let k = 0; k < count; k++) {+ const tri = this.order[first + k];+ const t = this.intersect(tri, ox, oy, oz, dx, dy, dz, epsilon, bestT);+ if (t < 0) continue;+ if (anyHit) { this.hitDistance = t; return tri; }+ bestT = t; best = tri;+ this.hitU = this.lastU; this.hitV = this.lastV;+ }+ }+ this.hitDistance = bestT;+ return best;+ }++ private lastU = 0;+ private lastV = 0;++ /** Möller-Trumbore, both faces: a bake lights what is there, and a wall+ * modelled inside out still occludes the room. */+ private intersect(tri: number, ox: number, oy: number, oz: number,+ dx: number, dy: number, dz: number, epsilon: number, far: number): number {+ const p = this.tris.positions;+ const at = tri * 9;+ const e1x = p[at + 3] - p[at], e1y = p[at + 4] - p[at + 1], e1z = p[at + 5] - p[at + 2];+ const e2x = p[at + 6] - p[at], e2y = p[at + 7] - p[at + 1], e2z = p[at + 8] - p[at + 2];+ const hx = dy * e2z - dz * e2y, hy = dz * e2x - dx * e2z, hz = dx * e2y - dy * e2x;+ const a = e1x * hx + e1y * hy + e1z * hz;+ if (a > -1e-12 && a < 1e-12) return -1;+ const f = 1 / a;+ const sx = ox - p[at], sy = oy - p[at + 1], sz = oz - p[at + 2];+ const u = f * (sx * hx + sy * hy + sz * hz);+ if (u < 0 || u > 1) return -1;+ const qx = sy * e1z - sz * e1y, qy = sz * e1x - sx * e1z, qz = sx * e1y - sy * e1x;+ const v = f * (dx * qx + dy * qy + dz * qz);+ if (v < 0 || u + v > 1) return -1;+ const t = f * (e2x * qx + e2y * qy + e2z * qz);+ if (t <= epsilon || t >= far) return -1;+ this.lastU = u; this.lastV = v;+ return t;+ }+}diff --git a/sdk/src/lightmap/index.ts b/sdk/src/lightmap/index.tsindex ebb7ac5f1..c9d2cd604 100644--- a/sdk/src/lightmap/index.ts+++ b/sdk/src/lightmap/index.ts@@ -1,3 +1,6 @@// SPDX-License-Identifier: Apache-2.0// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Teamexport { unwrapLightmapUV, type UnwrapOptions, type UnwrapResult } from './unwrap';+export { bakeLightmap, type BakeOptions, type BakeResult } from './bake';+export type { BakeSurface } from './atlas';+export type { BakeLight } from './solve';diff --git a/sdk/src/lightmap/solve.ts b/sdk/src/lightmap/solve.tsnew file mode 100644index 000000000..bf633cc65--- /dev/null+++ b/sdk/src/lightmap/solve.ts@@ -0,0 +1,188 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file solve.ts+ * @brief How much light reaches each texel — direct, then what bounced.+ *+ * The bounce reads the atlas the pass before it wrote, so a second round costs+ * what the first did and carries light one surface further. That is the whole+ * reason a bake is worth having: it is the term a real-time renderer here has+ * no way to compute at all.+ */++import type { Bvh } from './bvh';+import type { LumelField } from './atlas';++/** A light as a bake sees one: no shadow maps, no cap on how many. */+export interface BakeLight {+ kind: 'directional' | 'point' | 'spot';+ /** Where it is — point and spot only. */+ position?: readonly [number, number, number];+ /** Where it aims — directional and spot only. */+ direction?: readonly [number, number, number];+ color: readonly [number, number, number];+ intensity: number;+ /** Reach, in world units. Past it a point or spot light contributes nothing. */+ radius?: number;+ /** Cosines of the half angles a spot falls off between. */+ innerCos?: number;+ outerCos?: number;+}++/** Where a ray that hit triangle `t` lands in the atlas, and what it reflects. */+export interface HitLookup {+ /** UV of each triangle's three corners, six floats each. */+ triUV: Float32Array;+ /** Which surface each triangle belongs to. */+ triSurface: Int32Array;+ /** Patch origin and side per surface, as `[x, y, side, rotated]`. */+ patch: Float32Array;+ /** Albedo per surface, three floats each. */+ albedo: Float32Array;+}++const SHADOW_EPSILON = 1e-3;++/** Cosine-weighted directions over a hemisphere, as a fixed low-discrepancy set.+ * Fixed and not random: a bake that answers differently twice cannot be told+ * from one that answers wrongly once. */+function hemisphere(samples: number): Float32Array {+ const out = new Float32Array(samples * 3);+ for (let i = 0; i < samples; i++) {+ // Hammersley: the second coordinate is the bit-reversal of the index.+ let bits = i;+ bits = ((bits << 16) | (bits >>> 16)) >>> 0;+ bits = (((bits & 0x55555555) << 1) | ((bits & 0xaaaaaaaa) >>> 1)) >>> 0;+ bits = (((bits & 0x33333333) << 2) | ((bits & 0xcccccccc) >>> 2)) >>> 0;+ bits = (((bits & 0x0f0f0f0f) << 4) | ((bits & 0xf0f0f0f0) >>> 4)) >>> 0;+ bits = (((bits & 0x00ff00ff) << 8) | ((bits & 0xff00ff00) >>> 8)) >>> 0;+ const u = (i + 0.5) / samples;+ const v = bits * 2.3283064365386963e-10;+ const r = Math.sqrt(u);+ const phi = 2 * Math.PI * v;+ out[i * 3] = r * Math.cos(phi);+ out[i * 3 + 1] = r * Math.sin(phi);+ out[i * 3 + 2] = Math.sqrt(Math.max(0, 1 - u));+ }+ return out;+}++/** An orthonormal frame around `n`, built branchlessly (Duff et al.). */+function frame(nx: number, ny: number, nz: number, out: Float32Array): void {+ const sign = nz >= 0 ? 1 : -1;+ const a = -1 / (sign + nz);+ const b = nx * ny * a;+ out[0] = 1 + sign * nx * nx * a; out[1] = sign * b; out[2] = -sign * nx;+ out[3] = b; out[4] = sign + ny * ny * a; out[5] = -ny;+}++/**+ * What every light delivers straight to each lumel, with nothing between.+ *+ * Writes irradiance, not colour: the surface's own albedo is applied where the+ * bake is read, so one atlas serves a mesh whose texture changes.+ */+export function solveDirect(lumels: LumelField, bvh: Bvh, lights: readonly BakeLight[],+ ambient: readonly [number, number, number],+ out: Float32Array): void {+ out.fill(0);+ for (let i = 0; i < lumels.count; i++) {+ const px = lumels.position[i * 3], py = lumels.position[i * 3 + 1], pz = lumels.position[i * 3 + 2];+ const nx = lumels.normal[i * 3], ny = lumels.normal[i * 3 + 1], nz = lumels.normal[i * 3 + 2];+ let r = ambient[0], g = ambient[1], b = ambient[2];+ for (const light of lights) {+ let lx: number, ly: number, lz: number, distance: number, falloff = 1;+ if (light.kind === 'directional') {+ const d = light.direction ?? [0, 0, -1];+ const len = Math.hypot(d[0], d[1], d[2]) || 1;+ lx = -d[0] / len; ly = -d[1] / len; lz = -d[2] / len;+ distance = Infinity;+ } else {+ const p = light.position ?? [0, 0, 0];+ lx = p[0] - px; ly = p[1] - py; lz = p[2] - pz;+ distance = Math.hypot(lx, ly, lz);+ if (distance < 1e-6) continue;+ lx /= distance; ly /= distance; lz /= distance;+ const radius = light.radius ?? 0;+ if (radius > 0) {+ if (distance >= radius) continue;+ const k = 1 - distance / radius;+ falloff = k * k;+ }+ if (light.kind === 'spot') {+ const d = light.direction ?? [0, 0, -1];+ const len = Math.hypot(d[0], d[1], d[2]) || 1;+ const cos = -(lx * d[0] + ly * d[1] + lz * d[2]) / len;+ const outer = light.outerCos ?? 0.7;+ const inner = light.innerCos ?? 0.9;+ if (cos <= outer) continue;+ falloff *= Math.min(1, (cos - outer) / Math.max(inner - outer, 1e-4));+ }+ }+ const lambert = nx * lx + ny * ly + nz * lz;+ if (lambert <= 0) continue;+ const far = distance === Infinity ? 1e7 : distance - SHADOW_EPSILON;+ if (bvh.occluded(px + nx * SHADOW_EPSILON, py + ny * SHADOW_EPSILON, pz + nz * SHADOW_EPSILON,+ lx, ly, lz, far, SHADOW_EPSILON)) continue;+ const w = lambert * falloff * light.intensity;+ r += light.color[0] * w; g += light.color[1] * w; b += light.color[2] * w;+ }+ out[i * 3] = r; out[i * 3 + 1] = g; out[i * 3 + 2] = b;+ }+}++/**+ * One bounce: every lumel gathers what the surfaces it can see are giving off.+ *+ * `previous` is the atlas as the pass before left it, indexed by texel — which+ * is why a ray has to be turned back into a texel to be worth anything, and what+ * {@link HitLookup} is for.+ */+export function solveBounce(lumels: LumelField, bvh: Bvh, lookup: HitLookup,+ previous: Float32Array, atlasSize: number, samples: number,+ accumulate: Float32Array): void {+ const dirs = hemisphere(samples);+ const basis = new Float32Array(6);+ const far = 1e7;+ for (let i = 0; i < lumels.count; i++) {+ const px = lumels.position[i * 3], py = lumels.position[i * 3 + 1], pz = lumels.position[i * 3 + 2];+ const nx = lumels.normal[i * 3], ny = lumels.normal[i * 3 + 1], nz = lumels.normal[i * 3 + 2];+ frame(nx, ny, nz, basis);+ let r = 0, g = 0, b = 0;+ for (let s = 0; s < samples; s++) {+ const a = dirs[s * 3], c = dirs[s * 3 + 1], d = dirs[s * 3 + 2];+ const dx = basis[0] * a + basis[3] * c + nx * d;+ const dy = basis[1] * a + basis[4] * c + ny * d;+ const dz = basis[2] * a + basis[5] * c + nz * d;+ const tri = bvh.hit(px + nx * SHADOW_EPSILON, py + ny * SHADOW_EPSILON, pz + nz * SHADOW_EPSILON,+ dx, dy, dz, far, SHADOW_EPSILON);+ if (tri < 0) continue;+ const texel = texelOf(lookup, tri, bvh.hitU, bvh.hitV, atlasSize);+ if (texel < 0) continue;+ const surface = lookup.triSurface[tri];+ r += previous[texel * 3] * lookup.albedo[surface * 3];+ g += previous[texel * 3 + 1] * lookup.albedo[surface * 3 + 1];+ b += previous[texel * 3 + 2] * lookup.albedo[surface * 3 + 2];+ }+ // Cosine-weighted sampling already carries the projected-area term, so+ // the estimator is the plain mean of what came back.+ accumulate[i * 3] += r / samples;+ accumulate[i * 3 + 1] += g / samples;+ accumulate[i * 3 + 2] += b / samples;+ }+}++/** Where on the atlas a hit lands, or -1 when it falls outside it. */+function texelOf(lookup: HitLookup, tri: number, u: number, v: number, size: number): number {+ const at = tri * 6;+ const w0 = 1 - u - v;+ const uu = w0 * lookup.triUV[at] + u * lookup.triUV[at + 2] + v * lookup.triUV[at + 4];+ const vv = w0 * lookup.triUV[at + 1] + u * lookup.triUV[at + 3] + v * lookup.triUV[at + 5];+ const s = lookup.triSurface[tri] * 4;+ const rotated = lookup.patch[s + 3] !== 0;+ const side = lookup.patch[s + 2];+ const x = Math.floor(lookup.patch[s] + (rotated ? vv : uu) * side);+ const y = Math.floor(lookup.patch[s + 1] + (rotated ? uu : vv) * side);+ if (x < 0 || y < 0 || x >= size || y >= size) return -1;+ return y * size + x;+}diff --git a/sdk/tests/lightmap-bake.test.ts b/sdk/tests/lightmap-bake.test.tsnew file mode 100644index 000000000..d77015bbf--- /dev/null+++ b/sdk/tests/lightmap-bake.test.ts@@ -0,0 +1,251 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * The claim a bake exists to make: light that a frame cannot carry still reaches+ * the picture. Sixteen lights is the engine's ceiling, so the cases here run+ * past it — and the shadows, the bounce and the atlas layout are what make the+ * result worth reading rather than a flat wash.+ */+import { describe, it, expect } from 'vitest';+import { unwrapLightmapUV, bakeLightmap, type BakeSurface, type BakeLight } from '../src/lightmap';+import { MeshChannel, MeshChannelType, type MeshData } from '../src/asset/meshFormat';++const IDENTITY = Float32Array.from([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]);++function translated(x: number, y: number, z: number): Float32Array {+ const m = IDENTITY.slice();+ m[12] = x; m[13] = y; m[14] = z;+ return m;+}++/** A quad on the XZ plane facing +Y, `half` units out from its centre. */+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 + 12, 0, true);+ view.setFloat32(i * stride + 16, 1, true);+ view.setFloat32(i * stride + 20, 0, 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],+ };+}++/** A quad on the XZ plane facing DOWN — the side a lamp above it cannot reach. */+function ceiling(half: number): MeshData {+ const flat = floor(half);+ const view = new DataView(flat.vertices.buffer);+ for (let i = 0; i < flat.vertexCount; i++) view.setFloat32(i * flat.vertexStride + 16, -1, true);+ return { ...flat, indices: Uint32Array.from([0, 1, 2, 0, 2, 3]) };+}++/** A wall on the XY plane facing +Z, standing at the origin. */+function wall(half: number, height: number): MeshData {+ const p = [[-half, 0, 0], [half, 0, 0], [half, height, 0], [-half, height, 0]];+ 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 + 12, 0, true);+ view.setFloat32(i * stride + 16, 0, true);+ view.setFloat32(i * stride + 20, 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, 1, 2, 0, 2, 3]),+ aabbMin: [-half, 0, 0],+ aabbMax: [half, height, 0],+ };+}++/** The unwrap's own output, which is also what an import would hand a bake. */+const baked = (mesh: MeshData): MeshData => unwrapLightmapUV(mesh).mesh;++/** Brightness of the texel a world point lands on. */+function brightnessAt(result: ReturnType<typeof bakeLightmap>, surface: number,+ u: number, v: number): number {+ const [su, sv, ou, ov] = result.scaleOffset[surface];+ const x = Math.floor((ou + u * su) * result.size);+ const y = Math.floor((ov + v * sv) * result.size);+ const at = (y * result.size + x) * 4;+ return (result.pixels[at] + result.pixels[at + 1] + result.pixels[at + 2]) / 3;+}++/**+ * The lightmap UV of a world point, found by the triangle it lands in.+ *+ * Looked up and not derived: an unwrap splits and reorders vertices, so a case+ * that assumed corner 0 stayed corner 0 would be asserting about the wrong+ * texel and could pass on a bake that lit nothing.+ */+function uvAtWorld(mesh: MeshData, wx: number, wy: number, wz: number): [number, number] | null {+ const pos = mesh.channels.find((c) => c.semantic === MeshChannel.Position)!;+ const uvc = mesh.channels.find((c) => c.semantic === MeshChannel.TexCoord1)!;+ const view = new DataView(mesh.vertices.buffer, mesh.vertices.byteOffset, mesh.vertices.byteLength);+ const at = (v: number, c: { offset: number }, k: number): number =>+ view.getFloat32(v * mesh.vertexStride + c.offset + k * 4, true);+ for (let i = 0; i + 2 < mesh.indices.length; i += 3) {+ const v = [0, 1, 2].map((k) => mesh.indices[i + k]);+ const p = v.map((x) => [at(x, pos, 0), at(x, pos, 1), at(x, pos, 2)]);+ const e1 = [p[1][0] - p[0][0], p[1][1] - p[0][1], p[1][2] - p[0][2]];+ const e2 = [p[2][0] - p[0][0], p[2][1] - p[0][1], p[2][2] - p[0][2]];+ const n = [e1[1] * e2[2] - e1[2] * e2[1], e1[2] * e2[0] - e1[0] * e2[2],+ e1[0] * e2[1] - e1[1] * e2[0]];+ const area2 = Math.hypot(n[0], n[1], n[2]);+ if (area2 < 1e-12) continue;+ const d = [wx - p[0][0], wy - p[0][1], wz - p[0][2]];+ if (Math.abs((d[0] * n[0] + d[1] * n[1] + d[2] * n[2]) / area2) > 1e-4) continue;+ const cross = (a: number[], b: number[]): number[] =>+ [a[1] * b[2] - a[2] * b[1], a[2] * b[0] - a[0] * b[2], a[0] * b[1] - a[1] * b[0]];+ const dot = (a: number[], b: number[]): number => a[0] * b[0] + a[1] * b[1] + a[2] * b[2];+ const u = dot(cross(d, e2), n) / (area2 * area2);+ const w = dot(cross(e1, d), n) / (area2 * area2);+ if (u < -1e-6 || w < -1e-6 || u + w > 1 + 1e-6) continue;+ const b0 = 1 - u - w;+ return [+ b0 * at(v[0], uvc, 0) + u * at(v[1], uvc, 0) + w * at(v[2], uvc, 0),+ b0 * at(v[0], uvc, 1) + u * at(v[1], uvc, 1) + w * at(v[2], uvc, 1),+ ];+ }+ return null;+}++const LIT = { atlasSize: 256, texelsPerUnit: 3, bounces: 0, samples: 16, dilate: 0 };++describe('a baked lightmap', () => {+ it('carries more lights than a frame can', () => {+ // Twenty, where the renderer stops at sixteen and drops the rest by+ // brightness. Each is small and directly over its own patch of floor, so+ // twenty separate bright spots is the whole claim.+ const ground = baked(floor(20));+ const surfaces: BakeSurface[] = [{ mesh: ground, transform: IDENTITY }];+ const lights: BakeLight[] = [];+ for (let i = 0; i < 20; i++) {+ const t = (i + 0.5) / 20;+ lights.push({+ kind: 'point',+ position: [-18 + 36 * t, 1.5, 0],+ color: [1, 1, 1], intensity: 1, radius: 3,+ });+ }+ const result = bakeLightmap(surfaces, lights, { ...LIT, texelsPerUnit: 2 });+ expect(result.lumels).toBeGreaterThan(1000);++ let brightSpots = 0;+ for (let i = 0; i < 20; i++) {+ const x = -18 + 36 * ((i + 0.5) / 20);+ const uv = uvAtWorld(ground, x, 0, 0);+ expect(uv).not.toBeNull();+ if (brightnessAt(result, 0, uv![0], uv![1]) > 20) brightSpots++;+ }+ expect(brightSpots).toBe(20);+ });++ it('leaves a shadow where something stands in the way', () => {+ const ground = baked(floor(8));+ const blocker = baked(wall(8, 4));+ const result = bakeLightmap(+ [{ mesh: ground, transform: IDENTITY }, { mesh: blocker, transform: translated(0, 0, 0) }],+ [{ kind: 'point', position: [0, 3, -6], color: [1, 1, 1], intensity: 4, radius: 40 }],+ LIT,+ );+ // The wall stands on z = 0 and the light is behind it, so the floor in+ // front is in shadow and the floor behind is not.+ const lightSide = sampleFloor(result, ground, -4);+ const shadowed = sampleFloor(result, ground, 4);+ expect(lightSide).toBeGreaterThan(20);+ expect(shadowed).toBeLessThan(lightSide / 3);+ });++ it('reaches what no light points at, once light is allowed to bounce', () => {+ // The panel faces DOWN and the lamp is above it, so its lit side is the+ // one no light points at. Everything it gets is what the floor sends up —+ // the term a real-time frame here has no way to compute at all.+ const ground = baked(floor(8));+ const panel = baked(ceiling(2));+ const surfaces: BakeSurface[] = [+ { mesh: ground, transform: IDENTITY, albedo: [1, 1, 1] },+ { mesh: panel, transform: translated(0, 3, 0), albedo: [1, 1, 1] },+ ];+ const lights: BakeLight[] = [+ { kind: 'point', position: [0, 6, 0], color: [1, 1, 1], intensity: 8, radius: 40 },+ ];+ const dark = bakeLightmap(surfaces, lights, { ...LIT, bounces: 0 });+ const lit = bakeLightmap(surfaces, lights, { ...LIT, bounces: 2, samples: 64 });+ expect(brightestOf(dark, 1)).toBe(0);+ expect(brightestOf(lit, 1)).toBeGreaterThan(0);+ });++ it('gives each object its own patch of the atlas', () => {+ const a = baked(floor(4));+ const b = baked(floor(4));+ const result = bakeLightmap(+ [{ mesh: a, transform: translated(-6, 0, 0) }, { mesh: b, transform: translated(6, 0, 0) }],+ [{ kind: 'directional', direction: [0, -1, 0], color: [1, 1, 1], intensity: 1 }],+ LIT,+ );+ expect(result.scaleOffset).toHaveLength(2);+ const [, , ax, ay] = result.scaleOffset[0];+ const [, , bx, by] = result.scaleOffset[1];+ expect(ax === bx && ay === by).toBe(false);+ });++ it('answers the same twice', () => {+ // A bake that differs between runs cannot be told from one that is wrong+ // once. The scene has to BOUNCE for this to be about the sample set: over+ // a lone plane every ray misses and a random hemisphere passes too.+ const ground = baked(floor(8));+ const panel = baked(ceiling(2));+ const args: [BakeSurface[], BakeLight[]] = [+ [{ mesh: ground, transform: IDENTITY, albedo: [1, 1, 1] },+ { mesh: panel, transform: translated(0, 3, 0), albedo: [1, 1, 1] }],+ [{ kind: 'point', position: [0, 6, 0], color: [1, 0.5, 0.25], intensity: 8, radius: 40 }],+ ];+ const first = bakeLightmap(...args, { ...LIT, bounces: 1, samples: 32 });+ const second = bakeLightmap(...args, { ...LIT, bounces: 1, samples: 32 });+ expect(brightestOf(first, 1)).toBeGreaterThan(0);+ expect(Array.from(first.pixels)).toEqual(Array.from(second.pixels));+ });+});++/** Brightest texel in one surface's patch of the atlas. */+function brightestOf(result: ReturnType<typeof bakeLightmap>, surface: number): number {+ const [su, sv, ou, ov] = result.scaleOffset[surface];+ let best = 0;+ const x0 = Math.floor(ou * result.size), x1 = Math.ceil((ou + su) * result.size);+ const y0 = Math.floor(ov * result.size), y1 = Math.ceil((ov + sv) * result.size);+ for (let y = y0; y < y1; y++) {+ for (let x = x0; x < x1; x++) {+ const at = (y * result.size + x) * 4;+ best = Math.max(best, (result.pixels[at] + result.pixels[at + 1] + result.pixels[at + 2]) / 3);+ }+ }+ return best;+}++/** Brightness of the floor at world z, on its centre line. */+function sampleFloor(result: ReturnType<typeof bakeLightmap>, mesh: MeshData, z: number): number {+ const uv = uvAtWorld(mesh, 0, 0, z);+ if (!uv) throw new Error(`no floor triangle at z=${z}`);+ return brightnessAt(result, 0, uv[0], uv[1]);+}diff --git a/tools/apiSubsystems.mjs b/tools/apiSubsystems.mjsindex bb4d9906d..52f010b1a 100644--- a/tools/apiSubsystems.mjs+++ b/tools/apiSubsystems.mjs@@ -299,9 +299,9 @@ export const SUBSYSTEMS = [titleZh: '烘焙光照',source: ['lightmap'],tier: 'experimental',- why: 'half a line: the engine reads a bake and nothing here produces one yet, so the shape of this will follow what a baker turns out to need',- whyZh: '只做了一半:引擎读得了烘焙图,而这里还产不出一张,所以这套接口的形状要跟着烘焙器最终需要什么走',- entry: ['unwrapLightmapUV'],+ why: 'the bake runs and nothing in the editor triggers one yet, so the shape of this will follow what an authoring panel turns out to need',+ whyZh: '烘焙跑得起来,但编辑器里还没有什么去触发它,所以这套接口的形状要跟着创作面最终需要什么走',+ entry: ['unwrapLightmapUV', 'bakeLightmap'],},{id: 'dragonbones',diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjsindex fee5e8195..1fb24d81b 100644--- a/tools/releaseNotes.mjs+++ b/tools/releaseNotes.mjs@@ -28,6 +28,9 @@ export const NOTES_FLOOR = 'v0.65.0';* the reader recognises anyway.*/export const NOTED = {+ 'feat(render): lights become an atlas a mesh can be read through':+ { note: 'The bake itself: lights become an atlas.' },+'feat(render): a model can be unwrapped for the light that will be baked into it':{ note: 'A model can be given somewhere to receive baked light.' },'feat(import): Generate Lightmap UVs reaches the mesh it decides':