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(gi): surface cache - mesh cards baked at import, lit by the sun with distance-field shadows, and looked up by a ray's hit
yhhe10f19087300
diff --git a/docs/GI_LUMEN_DESIGN.md b/docs/GI_LUMEN_DESIGN.mdindex 5ec0616cf..228960d96 100644--- a/docs/GI_LUMEN_DESIGN.md+++ b/docs/GI_LUMEN_DESIGN.md@@ -111,8 +111,8 @@| 期 | 内容 | 验收 ||---|---|---|-| P0 | 网格 SDF 烘焙(pipeline)+ `.esmeshsdf` 资源类型与加载器 + 全局距离场。**已落地(2026-11-11)**:烘焙器 `pipeline/src/assets/meshSdf.ts`;导入设置 `distanceField`(默认关);`MeshSdfAssetLoader`;CPU 合成的 clipmap `sdk/src/gi/globalSdf.ts`(环形寻址、按脏区重建、`sphereTrace`/`occluded`);WGSL 追踪 `GLOBAL_SDF_WGSL`,由 `tools/gi/check-sdf-wgsl.mjs` 在无头 WebGPU 上与球的闭式解比对。**未做**:clipmap 接到渲染帧的网格实例、上传 GPU 存储缓冲、编辑器里的导入开关+ 全局距离场 clipmap + `sphereTrace`/`occlusion` 公共 WGSL | 新 oracle 场景:球、盒、薄墙的距离值和闭式解比对(`tools/oracle`);薄墙 10 cm 在 0.1 m 格下 `occlusion` 为真 |-| P1 | 表面缓存:card 烘焙、图集分配、直接光 + 自发光刷新 | 卡面亮度与 `shade()` 参考一致;自发光面板出现在命中点取光里 |+| P0 | 网格 SDF 烘焙 + `.esmeshsdf` 资源类型与加载器 + 全局距离场 clipmap + 公共 WGSL 追踪 | 球、盒、薄墙的距离和追踪与闭式解比对;WGSL 追踪由 `tools/gi/check-sdf-wgsl.mjs` 在无头 WebGPU 上校验。**已落地(2026-11-11)**:`pipeline/src/assets/meshSdf.ts`、`MeshSdfAssetLoader`、`sdk/src/gi/globalSdf.ts`;导入设置 `dynamicGI`(默认关)。**未做**:clipmap 接到渲染帧的网格实例、上传 GPU 存储缓冲、编辑器导入开关 |+| P1 | 表面缓存:card 烘焙、直接光 + 自发光、命中点取光 | 卡面亮度与 Lambert 闭式值一致,SDF 遮挡产生阴影,自发光出现在命中点取光里。**CPU 参考已落地(2026-11-11)**:`pipeline/src/assets/meshCards.ts`(`.esmeshcards`,6 个轴向 card)、`MeshCardsAssetLoader`、`sdk/src/gi/surfaceCache.ts`(`light`、`lookup`)、`pipeline/tests/surface-cache.test.ts`。**未做**:基色贴图不读(只用材质基色与顶点色)、图集分配、GPU 刷新通道 || P2 | 屏幕探针 + SDF 追踪 + 时间/空间滤波,单次反弹 | `gi_leak` 为 0;`gi_room` 阴影区 0.6–1.1 || P3 | 表面缓存吃上一帧间接光(多次反弹)+ 世界辐射缓存 | `gi_room` 0.8–1.1;`gi_away` ≥ 0.8;`gi_emissive` ≥ 0.8 || P4 | 成本:自适应探针、光线预算、QualityConfig 档位、手机与桌面实测 | 帧时间达标;gate 内加成本断言(同阴影通道做法) |diff --git a/pipeline/src/assets/importModelFile.ts b/pipeline/src/assets/importModelFile.tsindex 4357e3ce0..b0b0a7713 100644--- a/pipeline/src/assets/importModelFile.ts+++ b/pipeline/src/assets/importModelFile.ts@@ -21,6 +21,8 @@ import {} from './modelImport';import { modelStem, readModelSource } from './readModelSource';import { bakeMeshSdf, encodeMeshSdf } from './meshSdf';+import { bakeMeshCards } from './meshCards';+import { encodeMeshCards } from '../../../sdk/src/gi/cardFormat';import { parseManifest } from '../project/format';export interface ModelImportSettings {@@ -31,8 +33,8 @@ export interface ModelImportSettings {lodMinTriangles: number;characters: boolean;springBones: boolean;- /** Bake a signed distance field beside each mesh (`<name>.esmeshsdf`), which the dynamic GI traces against. */- distanceField: boolean;+ /** Bake what the dynamic GI reads of each mesh: its distance field (`<name>.esmeshsdf`) and its surface cards (`<name>.esmeshcards`). */+ dynamicGI: boolean;}export interface ImportedModel {@@ -66,7 +68,7 @@ export interface ImportModelOptions {}const DEFAULTS: ModelImportSettings = {- scale: 1, lightmapUV: false, specularMap: 'color', lodLevels: 0, lodMinTriangles: 256, characters: false, springBones: false, distanceField: false,+ scale: 1, lightmapUV: false, specularMap: 'color', lodLevels: 0, lodMinTriangles: 256, characters: false, springBones: false, dynamicGI: false,};/** What a model's `.meta` asks of the import; the schema's defaults where it is silent or unreadable. One read, because two would be two chances to disagree. */@@ -74,7 +76,7 @@ export function modelSettings(absSource: string): ModelImportSettings {try {const meta = JSON.parse(readFileSync(`${absSource}.meta`, 'utf8')) as{ importer?: { scale?: unknown; lightmapUV?: unknown; specularMap?: unknown;- lodLevels?: unknown; lodMinTriangles?: unknown; characterMaterials?: unknown; springBones?: unknown; distanceField?: unknown } };+ lodLevels?: unknown; lodMinTriangles?: unknown; characterMaterials?: unknown; springBones?: unknown; dynamicGI?: unknown } };const imp = meta.importer;const scale = imp?.scale;const levels = imp?.lodLevels;@@ -87,7 +89,7 @@ export function modelSettings(absSource: string): ModelImportSettings {lodMinTriangles: typeof minTriangles === 'number' && minTriangles >= 0 ? minTriangles : 256,characters: imp?.characterMaterials === 'auto',springBones: imp?.springBones === 'auto',- distanceField: imp?.distanceField === true,+ dynamicGI: imp?.dynamicGI === true,};} catch {return { ...DEFAULTS };@@ -127,7 +129,7 @@ export async function importModelFile(opts: ImportModelOptions): Promise<Importeconst sourceDir = opts.originDir ?? path.dirname(absSource);const stem = modelStem(absSource);const projectRef = (abs: string): string => path.relative(path.resolve(root), abs).split(path.sep).join('/');- const { scale, lightmapUV, specularMap, lodLevels, lodMinTriangles, characters, springBones, distanceField } = { ...modelSettings(absSource), ...opts.settings };+ const { scale, lightmapUV, specularMap, lodLevels, lodMinTriangles, characters, springBones, dynamicGI } = { ...modelSettings(absSource), ...opts.settings };const { meshes, textures, nodes, animations, externalFiles, warnings } = await readModelSource(new Uint8Array(readFileSync(absSource)), stem,@@ -259,9 +261,15 @@ export async function importModelFile(opts: ImportModelOptions): Promise<Importeawait write(`${lodName(mesh, i + 1)}.esmesh`, lodBytes);}// A skinned or morphing mesh moves its surface: a field baked from the bind pose would be a wrong wall.- if (distanceField && !mesh.data.inverseBindMatrices && !mesh.data.morph) {+ if (dynamicGI && !mesh.data.inverseBindMatrices && !mesh.data.morph) {const field = bakeMeshSdf(mesh.data, { cellSize: (0.1 * projectUnitsPerMeter(root)) / Math.max(scale, 1e-6) });if (field) await write(`${mesh.name}.esmeshsdf`, encodeMeshSdf(field));+ const m = mesh.material;+ const cards = bakeMeshCards(mesh.data, {+ cell: (0.25 * projectUnitsPerMeter(root)) / Math.max(scale, 1e-6),+ baseColor: m ? [m.baseColor[0], m.baseColor[1], m.baseColor[2]] : undefined, emissive: m?.emissive,+ });+ if (cards) await write(`${mesh.name}.esmeshcards`, encodeMeshCards(cards));}}}diff --git a/pipeline/src/assets/meshCards.ts b/pipeline/src/assets/meshCards.tsnew file mode 100644index 000000000..dd885fe31--- /dev/null+++ b/pipeline/src/assets/meshCards.ts@@ -0,0 +1,91 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file meshCards.ts+ * @brief Bakes the six axis cards of a mesh at import: what the surface cache lights (docs/GI_LUMEN_DESIGN.md, 3.3).+ *+ * @details Each card is an orthographic render from outside along one axis, done on the CPU: every triangle that faces the viewer is+ * scan-converted at the card's pixel centres and the nearest wins. Colour is the material's base colour times the vertex+ * colour where the mesh has one; a base-colour TEXTURE is not read (the bake works from the mesh and its constants), so a+ * textured surface is cached at its tint, not its picture. That is stated here because it is the largest thing the bake+ * leaves out.+ */+import { MeshChannel, MeshChannelType, type MeshData } from 'esengine';+import { CARD_AXES, NO_DEPTH, type MeshCard, type MeshCards } from '../../../sdk/src/gi/cardFormat';+import { meshPositions } from './meshSdf';++export interface MeshCardOptions {+ /** World size of a card pixel; raised so no card is wider than `maxResolution`. */+ cell: number;+ maxResolution?: number;+ baseColor?: readonly [number, number, number];+ emissive?: readonly [number, number, number];+}++function vertexColors(data: MeshData): Float32Array | null {+ const c = data.channels.find((ch) => ch.semantic === MeshChannel.Color && ch.components >= 3+ && (ch.type === MeshChannelType.Float32 || ch.type === MeshChannelType.UNorm8));+ if (!c) return null;+ const view = new DataView(data.vertices.buffer, data.vertices.byteOffset, data.vertices.byteLength);+ const out = new Float32Array(data.vertexCount * 3);+ for (let v = 0; v < data.vertexCount; v++) for (let k = 0; k < 3; k++) {+ out[v * 3 + k] = c.type === MeshChannelType.Float32+ ? view.getFloat32(v * data.vertexStride + c.offset + k * 4, true)+ : view.getUint8(v * data.vertexStride + c.offset + k) / 255;+ }+ return out;+}++export function bakeMeshCards(data: MeshData, options: MeshCardOptions): MeshCards | null {+ const positions = meshPositions(data);+ if (!positions || data.indices.length < 3) return null;+ const colors = vertexColors(data), base = options.baseColor ?? [1, 1, 1], emit = options.emissive ?? [0, 0, 0];+ const maxRes = options.maxResolution ?? 32;+ const extent = [0, 1, 2].map((k) => data.aabbMax[k]! - data.aabbMin[k]!);+ const cell = Math.max(options.cell, Math.max(...extent, 1e-9) / maxRes);+ const emissiveScale = Math.max(...emit, 1e-6);+ const cards: MeshCard[] = [];+ for (const { axis, sign, u, v } of CARD_AXES) {+ const width = Math.max(1, Math.min(maxRes, Math.ceil(extent[u]! / cell))), height = Math.max(1, Math.min(maxRes, Math.ceil(extent[v]! / cell)));+ const n = width * height;+ const card: MeshCard = { width, height, depth: new Uint16Array(n).fill(NO_DEPTH), normal: new Int8Array(n * 3), albedo: new Uint8Array(n * 3), emissive: new Uint8Array(n * 3) };+ const best = new Float32Array(n).fill(Infinity);+ const du = extent[u]! / width, dv = extent[v]! / height, ext = extent[axis]! || 1;+ for (let t = 0; t < data.indices.length; t += 3) {+ const i = [data.indices[t]!, data.indices[t + 1]!, data.indices[t + 2]!];+ const P = i.map((k) => [positions[k * 3]!, positions[k * 3 + 1]!, positions[k * 3 + 2]!]);+ const e1 = [0, 1, 2].map((k) => P[1]![k]! - P[0]![k]!), e2 = [0, 1, 2].map((k) => P[2]![k]! - P[0]![k]!);+ const nx = e1[1]! * e2[2]! - e1[2]! * e2[1]!, ny = e1[2]! * e2[0]! - e1[0]! * e2[2]!, nz = e1[0]! * e2[1]! - e1[1]! * e2[0]!;+ const nl = Math.hypot(nx, ny, nz);+ if (nl < 1e-20) continue;+ const nrm = [nx / nl, ny / nl, nz / nl];+ if (nrm[axis]! * sign <= 1e-6) continue; // not facing this card's viewer+ // Barycentric in the (u, v) plane.+ const ax = P[0]![u]!, ay = P[0]![v]!, bx = P[1]![u]!, by = P[1]![v]!, cx = P[2]![u]!, cy = P[2]![v]!;+ const det = (bx - ax) * (cy - ay) - (cx - ax) * (by - ay);+ if (Math.abs(det) < 1e-20) continue;+ const x0 = Math.max(Math.floor((Math.min(ax, bx, cx) - data.aabbMin[u]!) / du), 0), x1 = Math.min(Math.floor((Math.max(ax, bx, cx) - data.aabbMin[u]!) / du), width - 1);+ const y0 = Math.max(Math.floor((Math.min(ay, by, cy) - data.aabbMin[v]!) / dv), 0), y1 = Math.min(Math.floor((Math.max(ay, by, cy) - data.aabbMin[v]!) / dv), height - 1);+ for (let y = y0; y <= y1; y++) for (let x = x0; x <= x1; x++) {+ const pu = data.aabbMin[u]! + (x + 0.5) * du, pv = data.aabbMin[v]! + (y + 0.5) * dv;+ const l1 = ((pu - ax) * (cy - ay) - (cx - ax) * (pv - ay)) / det, l2 = ((bx - ax) * (pv - ay) - (pu - ax) * (by - ay)) / det, l0 = 1 - l1 - l2;+ const eps = -1e-6;+ if (l0 < eps || l1 < eps || l2 < eps) continue;+ const a = l0 * P[0]![axis]! + l1 * P[1]![axis]! + l2 * P[2]![axis]!;+ const depth = sign > 0 ? data.aabbMax[axis]! - a : a - data.aabbMin[axis]!;+ const px = x + y * width;+ if (depth >= best[px]!) continue;+ best[px] = depth;+ card.depth[px] = Math.min(Math.round((depth / ext) * 65534), 65534);+ for (let k = 0; k < 3; k++) {+ card.normal[px * 3 + k] = Math.round(nrm[k]! * 127);+ const tint = colors ? l0 * colors[i[0]! * 3 + k]! + l1 * colors[i[1]! * 3 + k]! + l2 * colors[i[2]! * 3 + k]! : 1;+ card.albedo[px * 3 + k] = Math.round(Math.min(Math.max(base[k]! * tint, 0), 1) * 255);+ card.emissive[px * 3 + k] = Math.round(Math.min(Math.max(emit[k]! / emissiveScale, 0), 1) * 255);+ }+ }+ }+ cards.push(card);+ }+ return { aabbMin: [...data.aabbMin], aabbMax: [...data.aabbMax], cell, emissiveScale, cards };+}diff --git a/pipeline/tests/model-distance-field.test.ts b/pipeline/tests/model-distance-field.test.tsindex 74def4bb6..30d312d9a 100644--- a/pipeline/tests/model-distance-field.test.ts+++ b/pipeline/tests/model-distance-field.test.ts@@ -1,7 +1,7 @@// SPDX-License-Identifier: Apache-2.0// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team/**- * @file A model imported with `distanceField` on gets a `.esmeshsdf` beside each mesh; without it, none.+ * @file A model imported with `dynamicGI` on gets a `.esmeshsdf` and `.esmeshcards` beside each mesh; without it, none.*/import { mkdtempSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';import { tmpdir } from 'node:os';@@ -9,6 +9,7 @@ import path from 'node:path';import { afterAll, describe, expect, it } from 'vitest';import { importModelFile } from '../src/assets/importModelFile';import { decodeMeshSdf, sampleMeshSdf } from '../src/assets/meshSdf';+import { decodeMeshCards } from '../../sdk/src/gi/cardFormat';/** A cube of half extent 50 (units), glTF with outward winding. */function cubeGltf(): string {@@ -40,13 +41,13 @@ describe('importing a model with a distance field', () => {const roots: string[] = [];afterAll(() => { for (const r of roots) rmSync(r, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 }); });- async function run(distanceField: boolean) {+ async function run(dynamicGI: boolean) {const root = mkdtempSync(path.join(tmpdir(), 'model-sdf-'));roots.push(root);const dir = path.join(root, 'assets', 'models');mkdirSync(dir, { recursive: true });writeFileSync(path.join(dir, 'cube.gltf'), cubeGltf());- const result = await importModelFile({ root, destDir: 'assets/models', absSource: path.join(dir, 'cube.gltf'), settings: { distanceField } });+ const result = await importModelFile({ root, destDir: 'assets/models', absSource: path.join(dir, 'cube.gltf'), settings: { dynamicGI } });return { result, dir, files: readdirSync(dir) };}@@ -58,10 +59,13 @@ describe('importing a model with a distance field', () => {const sdf = decodeMeshSdf(new Uint8Array(readFileSync(path.join(dir, name!))));expect(sampleMeshSdf(sdf, [0, 0, 0])).toBeLessThan(-40);expect(sampleMeshSdf(sdf, [80, 0, 0])).toBeGreaterThan(20);+ const cardsName = files.find((f) => f.endsWith('.esmeshcards'));+ expect(cardsName).toBeDefined();+ expect(decodeMeshCards(new Uint8Array(readFileSync(path.join(dir, cardsName!)))).cards.length).toBe(6);});it('writes none unless it is asked to', async () => {const { files } = await run(false);- expect(files.some((f) => f.endsWith('.esmeshsdf'))).toBe(false);+ expect(files.some((f) => f.endsWith('.esmeshsdf') || f.endsWith('.esmeshcards'))).toBe(false);});});diff --git a/pipeline/tests/surface-cache.test.ts b/pipeline/tests/surface-cache.test.tsnew file mode 100644index 000000000..0de654b16--- /dev/null+++ b/pipeline/tests/surface-cache.test.ts@@ -0,0 +1,151 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file surface-cache.test.ts+ * @brief Mesh cards baked from a box, lit by a sun with the scene distance field for shadows, against the Lambert values the maths gives.+ */+import { describe, it, expect } from 'vitest';+import { MeshChannel, MeshChannelType, type MeshData } from 'esengine';+import { bakeMeshCards } from '../src/assets/meshCards';+import { bakeMeshSdf } from '../src/assets/meshSdf';+import { decodeMeshCards, encodeMeshCards } from '../../sdk/src/gi/cardFormat';+import { GlobalSdf } from '../../sdk/src/gi/globalSdf';+import { SurfaceCache } from '../../sdk/src/gi/surfaceCache';++function meshOf(positions: number[], indices: number[]): MeshData {+ const vertexCount = positions.length / 3, vertices = new Uint8Array(vertexCount * 12), view = new DataView(vertices.buffer);+ positions.forEach((v, i) => view.setFloat32(i * 4, v, true));+ const min = [Infinity, Infinity, Infinity] as [number, number, number], max = [-Infinity, -Infinity, -Infinity] as [number, number, number];+ for (let v = 0; v < vertexCount; v++) for (let k = 0; k < 3; k++) { min[k] = Math.min(min[k], positions[v * 3 + k]!); max[k] = Math.max(max[k], positions[v * 3 + k]!); }+ return { channels: [{ semantic: MeshChannel.Position, components: 3, type: MeshChannelType.Float32, offset: 0 }], vertexStride: 12, vertexCount,+ vertices, indices: new Uint32Array(indices), aabbMin: min, aabbMax: max };+}++function box(h: [number, number, number]): MeshData {+ const p: number[] = [];+ for (let i = 0; i < 8; i++) p.push((i & 1 ? 1 : -1) * h[0], (i & 2 ? 1 : -1) * h[1], (i & 4 ? 1 : -1) * h[2]);+ const idx: number[] = [];+ for (const [a, b, c, d] of [[0, 2, 3, 1], [4, 5, 7, 6], [0, 1, 5, 4], [2, 6, 7, 3], [0, 4, 6, 2], [1, 3, 7, 5]] as [number, number, number, number][]) {+ const pa = p.slice(a * 3, a * 3 + 3), pb = p.slice(b * 3, b * 3 + 3), pc = p.slice(c * 3, c * 3 + 3);+ const u = pb.map((v, k) => v - pa[k]!), w = pc.map((v, k) => v - pa[k]!);+ const n = [u[1]! * w[2]! - u[2]! * w[1]!, u[2]! * w[0]! - u[0]! * w[2]!, u[0]! * w[1]! - u[1]! * w[0]!];+ idx.push(...(n[0]! * pa[0]! + n[1]! * pa[1]! + n[2]! * pa[2]! > 0 ? [a, b, c, a, c, d] : [a, c, b, a, d, c]));+ }+ return meshOf(p, idx);+}++const matrix = (t: [number, number, number], s = 1): number[] => [s, 0, 0, 0, 0, s, 0, 0, 0, 0, s, 0, t[0], t[1], t[2], 1];+const ALBEDO = [0.8, 0.4, 0.2] as const;+// Faces: 0 +x, 1 -x, 2 +y, 3 -y, 4 +z, 5 -z.+const TOP = 2, SIDE = 0, BOTTOM = 3;++describe('mesh cards', () => {+ const cards = bakeMeshCards(box([1, 1, 1]), { cell: 0.25, baseColor: ALBEDO })!;++ it('are six views of a box, each filled edge to edge with the face that looks out', () => {+ expect(cards.cards.length).toBe(6);+ for (const card of cards.cards) {+ expect(card.width).toBe(8);+ expect(card.height).toBe(8);+ expect(card.depth.every((d) => d === 0)).toBe(true);+ }+ const top = cards.cards[TOP]!;+ expect(Array.from(top.normal.slice(0, 3))).toEqual([0, 127, 0]);+ expect(Array.from(top.albedo.slice(0, 3))).toEqual(ALBEDO.map((c) => Math.round(c * 255)));+ });++ it('read back as written', () => {+ const back = decodeMeshCards(encodeMeshCards(cards));+ expect(back.cell).toBeCloseTo(cards.cell, 6);+ expect(back.cards[SIDE]!.albedo).toEqual(cards.cards[SIDE]!.albedo);+ expect(back.cards[TOP]!.depth).toEqual(cards.cards[TOP]!.depth);+ expect(() => decodeMeshCards(new Uint8Array(100))).toThrow();+ });++ it('record the depth of a surface set back from the box face', () => {+ // A flat plate at y = 0.5 inside a box of height 1: seen from +y it is 0.5 down from the top of the box, seen from -y it faces away.+ const plate = meshOf([-1, 0.5, -1, 1, 0.5, -1, 1, 0.5, 1, -1, 0.5, 1, 0, 1, 0, 0, -1, 0], [0, 2, 1, 0, 3, 2]);+ const c = bakeMeshCards(plate, { cell: 0.5 })!;+ const top = c.cards[TOP]!;+ expect(top.depth[0]).toBeGreaterThan(0);+ expect(Math.abs((top.depth[0]! / 65534) * 2 - 0.5)).toBeLessThan(0.01);+ expect(c.cards[BOTTOM]!.depth[0]).toBe(65535);+ });+});++describe('the surface cache', () => {+ const cards = bakeMeshCards(box([1, 1, 1]), { cell: 0.25, baseColor: ALBEDO, emissive: [0.5, 0, 0] })!;+ const lit = (toLight: [number, number, number], extra?: (cache: SurfaceCache, sdf: GlobalSdf) => void, ownSdf = false) => {+ const sdf = new GlobalSdf([{ dim: 64, cell: 0.25 }, { dim: 64, cell: 1 }]);+ sdf.setCenter([0, 0, 0]);+ const cache = new SurfaceCache();+ cache.add({ id: 1, cards, worldFromLocal: matrix([0, 0, 0]) });+ if (ownSdf) sdf.update({ id: 1, sdf: bakeMeshSdf(box([1, 1, 1]), { cellSize: 0.1 })!, worldFromLocal: matrix([0, 0, 0]) });+ extra?.(cache, sdf);+ cache.light({ sun: { toLight, radiance: [1, 1, 1] }, sdf, bias: 0.4 });+ return { cache, sdf };+ };++ it('lights a face by albedo times the sun times the cosine, and adds what the surface emits', () => {+ const dir = [0.6, 0.8, 0] as [number, number, number];+ const { cache } = lit(dir);+ const top = cache.radianceAt(1, TOP, 3, 3)!, side = cache.radianceAt(1, SIDE, 3, 3)!, bottom = cache.radianceAt(1, BOTTOM, 3, 3)!;+ for (let k = 0; k < 3; k++) {+ expect(top[k]!).toBeCloseTo(ALBEDO[k]! * 0.8 + (k === 0 ? 0.5 : 0), 2);+ expect(side[k]!).toBeCloseTo(ALBEDO[k]! * 0.6 + (k === 0 ? 0.5 : 0), 2);+ expect(bottom[k]!).toBeCloseTo(k === 0 ? 0.5 : 0, 2); // facing away: emission only+ }+ });++ it('shadows a face the distance field says is behind something, and only that face', () => {+ const plate = box([3, 0.2, 3]);+ const { cache } = lit([0, 1, 0], (_cache, sdf) => {+ sdf.update({ id: 2, sdf: bakeMeshSdf(plate, { cellSize: 0.1 })!, worldFromLocal: matrix([0, 3, 0]) });+ });+ // The plate is a body in the field and not in the cache: its shadow falls on the box under it.+ expect(cache.radianceAt(1, TOP, 3, 3)![1]!).toBeCloseTo(0, 2);+ const open = lit([0, 1, 0]).cache.radianceAt(1, TOP, 3, 3)!;+ expect(open[1]!).toBeCloseTo(ALBEDO[1]!, 2);+ });++ it('is not shadowed by its own mesh', () => {+ const { cache } = lit([0, 1, 0], undefined, true);+ expect(cache.radianceAt(1, TOP, 3, 3)![1]!).toBeCloseTo(ALBEDO[1]!, 2);+ });++ it('answers a ray with the face it looks at: the top from above, the side from the side, nothing from open air', () => {+ const { cache } = lit([0, 1, 0]);+ const fromAbove = cache.lookup([0.3, 1, 0.2], [0, -1, 0], 0.3)!;+ expect(fromAbove[1]!).toBeCloseTo(ALBEDO[1]!, 2);+ const fromSide = cache.lookup([1, 0.2, 0.1], [-1, 0, 0], 0.3)!;+ expect(fromSide[1]!).toBeCloseTo(0, 2); // the side is not toward the sun+ expect(cache.lookup([0.3, 2.5, 0.2], [0, -1, 0], 0.3)).toBeNull();+ expect(cache.lookup([9, 9, 9], [0, -1, 0], 0.3)).toBeNull();+ });++ it('blends the faces a slanted ray sees by how squarely it looks at each', () => {+ const { cache } = lit([0, 1, 0]);+ const r = cache.lookup([1, 1, 0.1], [-Math.SQRT1_2, -Math.SQRT1_2, 0], 0.3)!;+ // Half top (lit: albedo), half side (dark): about half the albedo.+ expect(r[1]!).toBeCloseTo(ALBEDO[1]! / 2, 1);+ });++ it('feeds an indirect term through the albedo', () => {+ const sdf = new GlobalSdf([{ dim: 32, cell: 0.5 }]);+ const cache = new SurfaceCache();+ cache.add({ id: 1, cards, worldFromLocal: matrix([0, 0, 0]) });+ cache.light({ sdf, indirect: () => [0.5, 0.5, 0.5] });+ const r = cache.radianceAt(1, BOTTOM, 2, 2)!;+ expect(r[1]!).toBeCloseTo(ALBEDO[1]! * 0.5, 2);+ });++ it('follows an instance that is moved and scaled', () => {+ const cache = new SurfaceCache();+ cache.add({ id: 1, cards, worldFromLocal: matrix([10, 0, 0], 2) });+ cache.light({ sun: { toLight: [0, 1, 0], radiance: [1, 1, 1] } });+ // Scaled by 2 about its centre, the top is at y = 2.+ const r = cache.lookup([10.5, 2, 0.5], [0, -1, 0], 0.3)!;+ expect(r[1]!).toBeCloseTo(ALBEDO[1]!, 2);+ expect(cache.lookup([0.5, 1, 0.5], [0, -1, 0], 0.3)).toBeNull();+ });+});diff --git a/sdk/src/asset/Assets.ts b/sdk/src/asset/Assets.tsindex 22295f6e3..325c2c2d4 100644--- a/sdk/src/asset/Assets.ts+++ b/sdk/src/asset/Assets.ts@@ -42,6 +42,7 @@ import { isBuiltinMeshRef } from './builtinMeshes';import { EnvironmentAssetLoader } from './loaders/EnvironmentAssetLoader';import { ProbeVolumeAssetLoader } from './loaders/ProbeVolumeAssetLoader';import { MeshSdfAssetLoader } from './loaders/MeshSdfAssetLoader';+import { MeshCardsAssetLoader } from './loaders/MeshCardsAssetLoader';import { FontAssetLoader } from './loaders/FontAssetLoader';import { AudioAssetLoader } from './loaders/AudioAssetLoader';import { AnimClipAssetLoader } from './loaders/AnimClipAssetLoader';@@ -2693,6 +2694,7 @@ export class Assets {this.register(new EnvironmentAssetLoader(core));this.register(new ProbeVolumeAssetLoader(core));this.register(new MeshSdfAssetLoader());+ this.register(new MeshCardsAssetLoader());// The audio loader needs the AudioAPI outside load() too (unload /// invalidate have no LoadContext), so it shares Assets' lazy accessor.this.register(new AudioAssetLoader(() => this.getAudio_()));diff --git a/sdk/src/asset/loaders/MeshCardsAssetLoader.ts b/sdk/src/asset/loaders/MeshCardsAssetLoader.tsnew file mode 100644index 000000000..e8ae5a469--- /dev/null+++ b/sdk/src/asset/loaders/MeshCardsAssetLoader.ts@@ -0,0 +1,25 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+import type { AssetLoader, LoadContext } from '../AssetLoader';+import { decodeMeshCards, type MeshCards } from '../../gi/cardFormat';++/**+ * Loads `.esmeshcards` — the six axis views of a mesh the dynamic GI's surface cache lights. Plain memory, like the distance field.+ */+export class MeshCardsAssetLoader implements AssetLoader<MeshCards> {+ readonly type = 'meshCards';+ readonly extensions = ['.esmeshcards'];++ async load(path: string, ctx: LoadContext): Promise<MeshCards> {+ const bytes = new Uint8Array(await ctx.loadBinary(ctx.catalog.getBuildPath(path)));+ try {+ return decodeMeshCards(bytes);+ } catch (err) {+ throw new Error(`${path}: ${err instanceof Error ? err.message : String(err)}`);+ }+ }++ unload(): void {+ // Decoded arrays are ordinary memory the caller may still hold.+ }+}diff --git a/sdk/src/gi/cardFormat.ts b/sdk/src/gi/cardFormat.tsnew file mode 100644index 000000000..39f1485b2--- /dev/null+++ b/sdk/src/gi/cardFormat.ts@@ -0,0 +1,105 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file cardFormat.ts+ * @brief `.esmeshcards`: the six axis views of a mesh the surface cache lights (docs/GI_LUMEN_DESIGN.md, 3.3).+ *+ * @details A card is an orthographic view of the mesh from outside along one of +-x, +-y, +-z: for each pixel the nearest surface that+ * faces the viewer, as its depth from the mesh's bounding box, its normal, its colour and what it emits. The pixel grid+ * spans the box face, so a card says nothing about where the mesh stands in the world: the instance's transform does.+ *+ * Face order is +x, -x, +y, -y, +z, -z (`CARD_AXES`). The two axes a card's pixels run along are the other two, in order+ * (for +-x: y then z; for +-y: x then z; for +-z: x then y); pixel (i, j) is centred at box min + (i + 0.5, j + 0.5) * cell there.+ */++export interface MeshCard {+ width: number;+ height: number;+ /** Depth from the box face the card looks in from, in 1/65535ths of the box's extent along the card's axis; 65535 = nothing here. */+ depth: Uint16Array;+ /** Unit normal, signed bytes (x, y, z) per pixel; /127. */+ normal: Int8Array;+ /** Linear albedo, bytes (r, g, b) per pixel. */+ albedo: Uint8Array;+ /** Emission, bytes (r, g, b) per pixel, times `MeshCards.emissiveScale` / 255. */+ emissive: Uint8Array;+}++export interface MeshCards {+ aabbMin: [number, number, number];+ aabbMax: [number, number, number];+ /** World size of one pixel the card was baked at. */+ cell: number;+ emissiveScale: number;+ /** +x, -x, +y, -y, +z, -z. */+ cards: MeshCard[];+}++export const NO_DEPTH = 65535;+/** Per face: the axis it looks along, the sign of the side it looks from, and the two axes its pixels run over. */+export const CARD_AXES: ReadonlyArray<{ axis: number; sign: 1 | -1; u: number; v: number }> = [+ { axis: 0, sign: 1, u: 1, v: 2 }, { axis: 0, sign: -1, u: 1, v: 2 },+ { axis: 1, sign: 1, u: 0, v: 2 }, { axis: 1, sign: -1, u: 0, v: 2 },+ { axis: 2, sign: 1, u: 0, v: 1 }, { axis: 2, sign: -1, u: 0, v: 1 },+];++export const MESH_CARDS_MAGIC = 0x44435345; // 'ESCD'+const HEADER = 4 * (2 + 3 + 3 + 2);++export function encodeMeshCards(m: MeshCards): Uint8Array {+ let size = HEADER;+ for (const c of m.cards) size += 4 + c.width * c.height * (2 + 3 + 3 + 3);+ const bytes = new Uint8Array(size), view = new DataView(bytes.buffer);+ let o = 0;+ const u32 = (v: number) => { view.setUint32(o, v, true); o += 4; };+ const f32 = (v: number) => { view.setFloat32(o, v, true); o += 4; };+ u32(MESH_CARDS_MAGIC); u32(1);+ m.aabbMin.forEach(f32); m.aabbMax.forEach(f32);+ f32(m.cell); f32(m.emissiveScale);+ for (const c of m.cards) {+ view.setUint16(o, c.width, true); view.setUint16(o + 2, c.height, true); o += 4;+ for (let i = 0; i < c.depth.length; i++) view.setUint16(o + i * 2, c.depth[i]!, true);+ o += c.depth.length * 2;+ for (const plane of [c.normal, c.albedo, c.emissive]) {+ bytes.set(new Uint8Array(plane.buffer, plane.byteOffset, plane.byteLength), o);+ o += plane.byteLength;+ }+ }+ return bytes;+}++export function decodeMeshCards(bytes: Uint8Array): MeshCards {+ const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);+ if (bytes.byteLength < HEADER || view.getUint32(0, true) !== MESH_CARDS_MAGIC) throw new Error('not a mesh card file');+ if (view.getUint32(4, true) !== 1) throw new Error(`unsupported mesh card file version ${view.getUint32(4, true)}`);+ const f = (at: number) => view.getFloat32(at, true);+ const aabbMin: [number, number, number] = [f(8), f(12), f(16)], aabbMax: [number, number, number] = [f(20), f(24), f(28)];+ const cell = f(32), emissiveScale = f(36);+ let o = HEADER;+ const cards: MeshCard[] = [];+ for (let k = 0; k < 6; k++) {+ if (o + 4 > bytes.byteLength) throw new Error('mesh card file is truncated');+ const width = view.getUint16(o, true), height = view.getUint16(o + 2, true);+ o += 4;+ const n = width * height;+ if (o + n * 11 > bytes.byteLength) throw new Error('mesh card file is truncated');+ const depth = new Uint16Array(n);+ for (let i = 0; i < n; i++) depth[i] = view.getUint16(o + i * 2, true);+ o += n * 2;+ const normal = new Int8Array(bytes.slice(o, o + n * 3).buffer); o += n * 3;+ const albedo = bytes.slice(o, o + n * 3); o += n * 3;+ const emissive = bytes.slice(o, o + n * 3); o += n * 3;+ cards.push({ width, height, depth, normal, albedo, emissive });+ }+ return { aabbMin, aabbMax, cell, emissiveScale, cards };+}++/** The card pixel of face `face` that a local-space point falls in, or null outside the box; with the depth of that point from the card's plane. */+export function cardPixel(m: MeshCards, face: number, p: readonly [number, number, number]): { x: number; y: number; depth: number } | null {+ const { axis, sign, u, v } = CARD_AXES[face]!, card = m.cards[face]!;+ const extent = m.aabbMax[axis]! - m.aabbMin[axis]!;+ const fu = (p[u]! - m.aabbMin[u]!) / (m.aabbMax[u]! - m.aabbMin[u]! || 1), fv = (p[v]! - m.aabbMin[v]!) / (m.aabbMax[v]! - m.aabbMin[v]! || 1);+ if (fu < 0 || fu >= 1 || fv < 0 || fv >= 1) return null;+ const depth = sign > 0 ? m.aabbMax[axis]! - p[axis]! : p[axis]! - m.aabbMin[axis]!;+ return { x: Math.min(Math.floor(fu * card.width), card.width - 1), y: Math.min(Math.floor(fv * card.height), card.height - 1), depth: depth / (extent || 1) };+}diff --git a/sdk/src/gi/surfaceCache.ts b/sdk/src/gi/surfaceCache.tsnew file mode 100644index 000000000..cfb1a5e24--- /dev/null+++ b/sdk/src/gi/surfaceCache.ts@@ -0,0 +1,182 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file surfaceCache.ts+ * @brief The scene's surfaces with the light on them, kept per card pixel: what a ray that hits a surface brings back (docs/GI_LUMEN_DESIGN.md, 3.3).+ *+ * @details An instance is a mesh's cards (`.esmeshcards`) placed in the world. Lighting a card pixel is: the sun's direct light, gated by the+ * scene's distance field (so a wall shadows what is behind it with no shadow map in the cache), plus an indirect term handed in+ * by the caller (the previous frame's gather: that is how the cache converges on many bounces), times the albedo, plus the emission.+ * Radiance is in the engine's units for a diffuse surface: albedo times the irradiance over pi, so a surface facing a sun of+ * intensity I reads albedo * I.+ *+ * A ray's hit is looked up by `lookup`: the point where the distance field stopped it and the direction it came in, answered by+ * the cards that face the ray, blended by how squarely they face it.+ *+ * This is the reference the GPU refresh follows; it runs on the CPU in tests and in tools.+ */+import { CARD_AXES, NO_DEPTH, cardPixel, type MeshCards } from './cardFormat';+import type { GlobalSdf } from './globalSdf';++export interface CardInstance {+ id: number;+ cards: MeshCards;+ /** Column-major 4x4, local to world: rotation, translation, one uniform scale. */+ worldFromLocal: ArrayLike<number>;+}++export interface SunLight {+ /** Unit vector toward the sun. */+ toLight: readonly [number, number, number];+ /** Colour times intensity: the radiance a surface facing the sun gives per unit albedo. */+ radiance: readonly [number, number, number];+}++export interface LightOptions {+ sun?: SunLight;+ /** Shadows from the scene distance field; the sun is unshadowed without it. */+ sdf?: GlobalSdf;+ /** How far a shadow ray looks. */+ shadowRange?: number;+ /** Extra light per surface point, to be multiplied by the albedo: the indirect term. Receives the world position and unit normal. */+ indirect?: (position: [number, number, number], normal: [number, number, number]) => readonly [number, number, number];+ /** How far off the surface a shadow ray starts, in world units; must clear the growth of the distance field. */+ bias?: number;+}++interface Placed {+ instance: CardInstance;+ scale: number;+ inverse: Float64Array;+ /** Per card pixel, linear RGB: what the surface gives out. */+ radiance: Float32Array[];+ min: [number, number, number];+ max: [number, number, number];+}++export class SurfaceCache {+ private placed_ = new Map<number, Placed>();++ add(instance: CardInstance): void {+ const m = instance.worldFromLocal, scale = Math.hypot(m[0]!, m[1]!, m[2]!);+ const r = [0, 1, 2].map((c) => [0, 1, 2].map((row) => m[c * 4 + row]! / scale));+ const inverse = new Float64Array(16);+ for (let row = 0; row < 3; row++) {+ for (let col = 0; col < 3; col++) inverse[col * 4 + row] = r[row]![col]! / scale;+ inverse[12 + row] = -(r[row]![0]! * m[12]! + r[row]![1]! * m[13]! + r[row]![2]! * m[14]!) / scale;+ }+ inverse[15] = 1;+ const { cards } = instance;+ const min: [number, number, number] = [Infinity, Infinity, Infinity], max: [number, number, number] = [-Infinity, -Infinity, -Infinity];+ for (let c = 0; c < 8; c++) {+ const l = [c & 1 ? cards.aabbMax[0] : cards.aabbMin[0], c & 2 ? cards.aabbMax[1] : cards.aabbMin[1], c & 4 ? cards.aabbMax[2] : cards.aabbMin[2]];+ for (let k = 0; k < 3; k++) {+ const w = m[k]! * l[0]! + m[4 + k]! * l[1]! + m[8 + k]! * l[2]! + m[12 + k]!;+ min[k] = Math.min(min[k], w); max[k] = Math.max(max[k], w);+ }+ }+ this.placed_.set(instance.id, { instance, scale, inverse, radiance: cards.cards.map((c) => new Float32Array(c.width * c.height * 3)), min, max });+ }++ remove(id: number): void { this.placed_.delete(id); }++ /** The radiance of one card pixel as last lit (tests and tools). */+ radianceAt(id: number, face: number, x: number, y: number): [number, number, number] | null {+ const placed = this.placed_.get(id);+ if (!placed) return null;+ const card = placed.instance.cards.cards[face]!, i = x + y * card.width;+ if (card.depth[i] === NO_DEPTH) return null;+ const r = placed.radiance[face]!;+ return [r[i * 3]!, r[i * 3 + 1]!, r[i * 3 + 2]!];+ }++ /** The world position and unit normal of a card pixel, or null where it holds no surface. */+ private pixelSurface_(placed: Placed, face: number, x: number, y: number): { position: [number, number, number]; normal: [number, number, number] } | null {+ const { cards } = placed.instance, card = cards.cards[face]!, i = x + y * card.width;+ if (card.depth[i] === NO_DEPTH) return null;+ const { axis, sign, u, v } = CARD_AXES[face]!;+ const local: [number, number, number] = [0, 0, 0];+ local[u] = cards.aabbMin[u]! + ((x + 0.5) / card.width) * (cards.aabbMax[u]! - cards.aabbMin[u]!);+ local[v] = cards.aabbMin[v]! + ((y + 0.5) / card.height) * (cards.aabbMax[v]! - cards.aabbMin[v]!);+ const depth = (card.depth[i]! / 65534) * (cards.aabbMax[axis]! - cards.aabbMin[axis]!);+ local[axis] = sign > 0 ? cards.aabbMax[axis]! - depth : cards.aabbMin[axis]! + depth;+ const m = placed.instance.worldFromLocal;+ const position = [0, 1, 2].map((k) => m[k]! * local[0] + m[4 + k]! * local[1] + m[8 + k]! * local[2] + m[12 + k]!) as [number, number, number];+ const n = [card.normal[i * 3]! / 127, card.normal[i * 3 + 1]! / 127, card.normal[i * 3 + 2]! / 127];+ const nl = Math.hypot(...n) || 1;+ const normal = [0, 1, 2].map((k) => (m[k]! * n[0]! + m[4 + k]! * n[1]! + m[8 + k]! * n[2]!) / (placed.scale * nl)) as [number, number, number];+ return { position, normal };+ }++ /** Refreshes every card pixel's radiance. */+ light(options: LightOptions): void {+ const range = options.shadowRange ?? 500, bias = options.bias ?? 0.3;+ for (const placed of this.placed_.values()) {+ const { cards } = placed.instance;+ cards.cards.forEach((card, face) => {+ for (let y = 0; y < card.height; y++) for (let x = 0; x < card.width; x++) {+ const i = x + y * card.width, out = placed.radiance[face]!;+ const s = this.pixelSurface_(placed, face, x, y);+ if (!s) { out[i * 3] = out[i * 3 + 1] = out[i * 3 + 2] = 0; continue; }+ const light = [0, 0, 0];+ const sun = options.sun;+ if (sun) {+ const ndl = s.normal[0] * sun.toLight[0] + s.normal[1] * sun.toLight[1] + s.normal[2] * sun.toLight[2];+ if (ndl > 0) {+ const origin: [number, number, number] = [s.position[0] + s.normal[0] * bias, s.position[1] + s.normal[1] * bias, s.position[2] + s.normal[2] * bias];+ const blocked = options.sdf ? options.sdf.sphereTrace(origin, sun.toLight as [number, number, number], range) !== null : false;+ if (!blocked) for (let k = 0; k < 3; k++) light[k] += sun.radiance[k]! * ndl;+ }+ }+ if (options.indirect) {+ const g = options.indirect(s.position, s.normal);+ for (let k = 0; k < 3; k++) light[k] += g[k]!;+ }+ for (let k = 0; k < 3; k++) {+ out[i * 3 + k] = (card.albedo[i * 3 + k]! / 255) * light[k]! + (card.emissive[i * 3 + k]! / 255) * cards.emissiveScale;+ }+ }+ });+ }+ }++ /**+ * What a ray brings back from the surface it hit at `point`, travelling along unit `dir`: the radiance of the cards that face it,+ * blended by how squarely each does, from the pixel whose surface is within `tolerance` of the point. Null when no card sees it.+ */+ lookup(point: readonly [number, number, number], dir: readonly [number, number, number], tolerance: number): [number, number, number] | null {+ for (const placed of this.placed_.values()) {+ let near = true;+ for (let k = 0; k < 3; k++) if (point[k]! < placed.min[k]! - tolerance || point[k]! > placed.max[k]! + tolerance) { near = false; break; }+ if (!near) continue;+ const i = placed.inverse;+ const local = [0, 1, 2].map((k) => i[k]! * point[0]! + i[4 + k]! * point[1]! + i[8 + k]! * point[2]! + i[12 + k]!) as [number, number, number];+ const d = [0, 1, 2].map((k) => i[k]! * dir[0]! + i[4 + k]! * dir[1]! + i[8 + k]! * dir[2]!);+ const dl = Math.hypot(...d) || 1;+ const { cards } = placed.instance;+ const sum = [0, 0, 0];+ let total = 0;+ for (let axis = 0; axis < 3; axis++) {+ const weight = Math.abs(d[axis]! / dl);+ if (weight < 0.05) continue;+ // The face the ray looks at: the one on the side it came from.+ const face = axis * 2 + (d[axis]! > 0 ? 1 : 0);+ const clamped: [number, number, number] = [local[0], local[1], local[2]];+ for (let k = 0; k < 3; k++) clamped[k] = Math.min(Math.max(clamped[k]!, cards.aabbMin[k]!), cards.aabbMax[k]! - 1e-9);+ const px = cardPixel(cards, face, clamped);+ if (!px) continue;+ const card = cards.cards[face]!, idx = px.x + px.y * card.width;+ if (card.depth[idx] === NO_DEPTH) continue;+ const ext = cards.aabbMax[axis]! - cards.aabbMin[axis]!;+ const cardDepth = (card.depth[idx]! / 65534) * ext;+ const pointDepth = px.depth * ext;+ if (Math.abs(cardDepth - pointDepth) * placed.scale > tolerance) continue;+ const r = placed.radiance[face]!;+ for (let k = 0; k < 3; k++) sum[k] += weight * r[idx * 3 + k]!;+ total += weight;+ }+ if (total > 0) return [sum[0]! / total, sum[1]! / total, sum[2]! / total];+ }+ return null;+ }+}diff --git a/tools/assetMetaTable.js b/tools/assetMetaTable.jsindex c02d09d50..966b506df 100644--- a/tools/assetMetaTable.js+++ b/tools/assetMetaTable.js@@ -88,6 +88,7 @@ export const EXT_TO_TYPE = Object.freeze({'.esprobes': 'probeVolume','.esmesh': 'mesh','.esmeshsdf': 'meshSdf',+ '.esmeshcards': 'meshCards',// A model as the steps that build it. Never shipped: saving one bakes the sibling// `.esmesh`, and that is what a scene references. Typed for the same reason// `.esmatgraph` is, and apart from `model` because nothing imports it.