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
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
* @file The C++ bake kernel solves what the TypeScript solve does: the same
* rays, the same cutout hash, the same sky, to rounding — and the same
* answer however many threads it runs on.
*/
import { describe, it, expect, beforeAll, afterAll } from 'vitest';
import { mkdtemp, rm, writeFile } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import path from 'node:path';
import { encodeMesh, unwrapLightmapUV, decodeLightmap, MeshChannel, MeshChannelType,
type MeshData, type BakeLight } from 'esengine';
import { bakeSceneLightmap, bakeSceneLightmapParallel, statsOf, TO_LINEAR, type SceneBakeInput }
from '../src/assets/lightmapBake';
import { PNG } from 'pngjs';
import { BakeKernelExecutor } from '../src/assets/lightmapKernel';
import { encodeRgbaPng } from '../src/assets/png';
import { decodeRgbaPng } from '../src/assets/tilesetExtrude';
import { loadBakeKernel } from '../../build-tools/lightmap/kernel.mjs';
let dir = '';
let kernel: BakeKernelExecutor;
function quad(half: number, y: number, facing: 1 | -1): MeshData {
const p = [[-half, y, -half], [half, y, -half], [half, y, half], [-half, y, half]];
const vertices = new Uint8Array(4 * 24);
const view = new DataView(vertices.buffer);
p.forEach((q, i) => {
q.forEach((v, k) => view.setFloat32(i * 24 + k * 4, v, true));
view.setFloat32(i * 24 + 16, facing, true);
});
return unwrapLightmapUV({
channels: [
{ semantic: MeshChannel.Position, components: 3, type: MeshChannelType.Float32, offset: 0 },
{ semantic: MeshChannel.Normal, components: 3, type: MeshChannelType.Float32, offset: 12 },
],
vertexStride: 24, vertexCount: 4, vertices,
indices: Uint32Array.from(facing > 0 ? [0, 2, 1, 0, 3, 2] : [0, 1, 2, 0, 2, 3]),
aabbMin: [-half, y, -half], aabbMax: [half, y, half],
}).mesh;
}
beforeAll(async () => {
dir = await mkdtemp(path.join(tmpdir(), 'estella-kernel-'));
await writeFile(path.join(dir, 'floor.esmesh'), encodeMesh(quad(4, 0, 1)));
await writeFile(path.join(dir, 'roof.esmesh'), encodeMesh(quad(1.5, 1, -1)));
await writeFile(path.join(dir, 'shelf.esmesh'), encodeMesh(quad(0.8, 0.5, 1)));
// Closer above the floor than half a lumel: the floor's rays pass its back.
await writeFile(path.join(dir, 'decal.esmesh'), encodeMesh(quad(2.5, 0.03, 1)));
const holes = new Uint8Array(4 * 4 * 4).fill(200);
for (let i = 8; i < 16; i++) holes[i * 4 + 3] = 0;
await writeFile(path.join(dir, 'holes.png'), encodeRgbaPng(4, 4, holes));
await writeFile(path.join(dir, 'cutout.esmaterial'), JSON.stringify(
{ version: '1.0', type: 'material', shader: 'builtin:model', properties: { u_alphaCutoff: 0.5 } }));
kernel = await BakeKernelExecutor.load();
});
afterAll(async () => {
await kernel?.close();
await rm(dir, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 });
});
const IDENTITY = [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1];
const LIGHTS: BakeLight[] = [
{ kind: 'point', position: [2, 3, 1], color: [1, 0.8, 0.6], intensity: 5, radius: 20 },
{ kind: 'spot', position: [-1, 2.5, -1], direction: [0.2, -1, 0.1], color: [0.4, 0.6, 1], intensity: 8,
radius: 10, innerCos: 0.95, outerCos: 0.8 },
{ kind: 'directional', direction: [-0.4, -1, -0.3], color: [1, 0.95, 0.9], intensity: 2 },
];
const SH = Array.from({ length: 27 }, (_, i) => [0.9, 0.3, -0.2, 0.25, 0.1, -0.05, 0.08, 0.04, -0.06][Math.floor(i / 3)]!
* [1, 0.9, 1.2][i % 3]!);
function scene(sky: boolean): SceneBakeInput {
return {
surfaces: [
{ meshFile: path.join(dir, 'floor.esmesh'), label: 'Floor', transform: IDENTITY,
baseColor: [0.7, 0.6, 0.5], realtimeDirect: true },
{ meshFile: path.join(dir, 'roof.esmesh'), label: 'Roof', transform: IDENTITY,
baseColorTexture: path.join(dir, 'holes.png'), material: path.join(dir, 'cutout.esmaterial'),
twoSided: true },
{ meshFile: path.join(dir, 'shelf.esmesh'), label: 'Shelf', transform: IDENTITY,
baseColor: [0.3, 0.8, 0.4] },
{ meshFile: path.join(dir, 'decal.esmesh'), label: 'Decal', transform: IDENTITY,
baseColor: [0.9, 0.2, 0.2] },
],
lights: LIGHTS,
probeVolumes: [{ label: 'Air', center: [0, 0.5, 0], halfExtents: [2, 0.4, 2], spacing: 1 }],
// No face size: the environment lights the gather and nothing is captured from it.
environment: sky ? { document: { irradiance: SH }, atlasPng: new Uint8Array(0), rotation: 40 } : null,
options: { atlasSize: 128, texelsPerUnit: 6, bounces: 2, samples: 32, ambient: [0.3, 0.4, 0.5] },
} as SceneBakeInput;
}
function worstTexel(pngA: Uint8Array, pngB: Uint8Array): { worst: number; differing: number } {
const a = decodeRgbaPng(pngA).rgba, b = decodeRgbaPng(pngB).rgba;
expect(a.length).toBe(b.length);
let worst = 0, differing = 0;
for (let i = 0; i < a.length / 4; i++) {
const x = decodeLightmap(a, i), y = decodeLightmap(b, i);
let d = 0;
for (let k = 0; k < 3; k++) d = Math.max(d, Math.abs(x[k]! - y[k]!) / Math.max(0.05, y[k]!));
if (d > 0) differing++;
worst = Math.max(worst, d);
}
return { worst, differing };
}
describe('the C++ bake kernel', () => {
it('reuses exact visibility across bounces and relighting without changing solved bytes', async () => {
const raw = await loadBakeKernel();
try {
raw.setCacheBudget(0);
const original = await bakeSceneLightmapParallel(scene(true), kernel);
raw.setCacheBudget(384 * 1024 * 1024);
const before = raw.cacheStats().resolvedRays;
const cached = await bakeSceneLightmapParallel(scene(true), kernel);
expect(cached.atlasBytes).toEqual(original.atlasBytes);
expect(raw.cacheStats().resolvedRays - before).toBe(cached.lumels * 32);
expect(raw.cacheStats().bytes).toBe(cached.lumels * 32 * 8);
const changed = scene(true);
changed.lights = changed.lights.map(l => ({ ...l, intensity: l.intensity * 0.4,
color: [0.2, 0.9, 0.5] }));
changed.environment!.rotation = 120;
const resolved = raw.cacheStats().resolvedRays;
const relit = await bakeSceneLightmapParallel(changed, kernel);
expect(raw.cacheStats().resolvedRays).toBe(resolved);
expect(relit.atlasBytes).not.toEqual(original.atlasBytes);
raw.setCacheBudget(0);
const reference = await bakeSceneLightmapParallel(changed, kernel);
expect(relit.atlasBytes).toEqual(reference.atlasBytes);
expect(relit.probes).toEqual(reference.probes);
} finally { raw.setCacheBudget(384 * 1024 * 1024); }
});
it('invalidates changed geometry/sample sequences and falls back within a memory budget', async () => {
const raw = await loadBakeKernel();
try {
raw.setCacheBudget(384 * 1024 * 1024);
await bakeSceneLightmapParallel(scene(false), kernel);
const changed = scene(false);
changed.surfaces[2].transform = [...IDENTITY];
changed.surfaces[2].transform[12] = 0.3;
const before = raw.cacheStats().resolvedRays;
const moved = await bakeSceneLightmapParallel(changed, kernel);
expect(raw.cacheStats().resolvedRays - before).toBe(moved.lumels * 32);
const resampled = raw.cacheStats().resolvedRays;
changed.options!.samples = 16;
const cached = await bakeSceneLightmapParallel(changed, kernel);
expect(raw.cacheStats().resolvedRays - resampled).toBe(cached.lumels * 16);
raw.setCacheBudget(1);
const bounded = raw.cacheStats().resolvedRays;
const uncached = await bakeSceneLightmapParallel(changed, kernel);
expect(raw.cacheStats().bytes).toBe(0);
expect(raw.cacheStats().resolvedRays - bounded).toBe(cached.lumels * 16 * 2);
expect(uncached.atlasBytes).toEqual(cached.atlasBytes);
} finally { raw.setCacheBudget(384 * 1024 * 1024); }
});
it('averages a texture as the TypeScript does, bit for bit', async () => {
const w = 37, h = 23;
const rgba = new Uint8Array(w * h * 4);
for (let i = 0; i < rgba.length; i++) rgba[i] = (i * 2654435761 >>> 7) & 255;
const files: string[] = [];
const kinds: Array<[number, number]> = [[6, 8], [2, 8], [0, 8], [4, 8], [6, 16]];
for (const [colorType, bitDepth] of kinds) {
const png = new PNG({ width: w, height: h });
Buffer.from(rgba).copy(png.data);
const file = path.join(dir, `tex-${colorType}-${bitDepth}.png`);
await writeFile(file, PNG.sync.write(png, { colorType, bitDepth, inputHasAlpha: true } as never));
files.push(file);
}
const notPng = path.join(dir, 'not.png');
await writeFile(notPng, 'not a png');
files.push(notPng);
for (const cutoff of [0, 0.5, 128 / 255]) {
const got = await kernel.textureStats(files, files.map(() => cutoff), TO_LINEAR);
files.forEach((file, i) => {
if (kinds[i]?.[1] === 16 || file === notPng) {
expect(got[i]).toBeUndefined();
return;
}
expect(got[i]).toEqual(statsOf(file, cutoff));
});
}
});
for (const sky of [false, true]) {
it(`bakes what the TypeScript solve bakes (${sky ? 'SH' : 'flat'} sky)`, async () => {
const ts = bakeSceneLightmap(scene(sky));
const cpp = await bakeSceneLightmapParallel(scene(sky), kernel);
expect(cpp.lumels).toBe(ts.lumels);
const { worst } = worstTexel(cpp.atlasBytes, ts.atlasBytes);
expect(worst).toBeLessThan(0.02);
expect(cpp.probes.length).toBe(ts.probes.length);
});
}
it('bakes the same bytes on one thread as on many', async () => {
const saved = (kernel as unknown as { kernel: { threads: number } }).kernel;
const threads = saved.threads;
try {
saved.threads = 1;
const one = await bakeSceneLightmapParallel(scene(true), kernel);
saved.threads = 5;
const many = await bakeSceneLightmapParallel(scene(true), kernel);
expect(Buffer.from(many.atlasBytes).equals(Buffer.from(one.atlasBytes))).toBe(true);
} finally {
saved.threads = threads;
}
});
});