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(render): lights become an atlas a mesh can be read through

esengine4b137b74d48f
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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 read
through a second UV set, and it has to be one where no two surfaces share a
texel — which the UV set the art is wrapped in deliberately is not: two arms
diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.json
index 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.md
index 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) => string
setBaseUrl: ((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]>): () => void
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 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) => string
setBaseUrl: ((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]>): () => void
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 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) => string
setBaseUrl: ((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]>): () => void
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 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) => string
setBaseUrl: ((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]>): () => void
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 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) => string
setBaseUrl: ((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]>): () => void
diff --git a/sdk/src/core-content.ts b/sdk/src/core-content.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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 Team
export { 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.mjs
index 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.mjs
index 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':