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 gpu-scene.test.ts
* @brief The scene the dynamic GI feeds the engine: which renderers become instances, and the arrays packed for the compute passes.
*/
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 { buildInstances, instanceKey, type GIEntry } from '../../sdk/src/gi/giInstances';
import { packGPUScene, GI_HEADER_FLOATS, GI_INSTANCE_FLOATS } from '../../sdk/src/gi/gpuScene';
import { GlobalSdf } from '../../sdk/src/gi/globalSdf';
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]));
}
const vertices = new Uint8Array(8 * 12), view = new DataView(vertices.buffer);
p.forEach((v, i) => view.setFloat32(i * 4, v, true));
return { channels: [{ semantic: MeshChannel.Position, components: 3, type: MeshChannelType.Float32, offset: 0 }], vertexStride: 12, vertexCount: 8, vertices,
indices: new Uint32Array(idx), aabbMin: [-h[0], -h[1], -h[2]], aabbMax: h };
}
const transform = (position: [number, number, number], scale: [number, number, number] = [1, 1, 1], rotation = { x: 0, y: 0, z: 0, w: 1 }) => ({
position: { x: 0, y: 0, z: 0 }, rotation: { x: 0, y: 0, z: 0, w: 1 }, scale: { x: 1, y: 1, z: 1 },
worldPosition: { x: position[0], y: position[1], z: position[2] }, worldRotation: rotation, worldScale: { x: scale[0], y: scale[1], z: scale[2] },
});
const entry = (mesh: number, t: ReturnType<typeof transform>, path: string | null = null, emissive: [number, number, number] = [0, 0, 0]): GIEntry =>
({ mesh, transform: t, colour: [0.5, 0.5, 0.5], emissive, path });
const CUBE = 7;
const mesh = box([50, 50, 50]);
const baked = { sdf: bakeMeshSdf(mesh, { cellSize: 10 })!, cards: bakeMeshCards(mesh, { cell: 25, baseColor: [0.2, 0.4, 0.6], emissive: [0, 1, 0] })! };
describe('which renderers become instances', () => {
it('takes a built-in cube as a box of its world scale, and a baked mesh with its files placed by its transform', () => {
const { instances } = buildInstances([
entry(CUBE, transform([0, 0, 0], [4, 1, 1])),
entry(9, transform([300, 0, 0], [2, 2, 2]), 'assets/rock.esmesh'),
], CUBE, (p) => (p === 'assets/rock.esmesh' ? baked : null));
expect(instances.length).toBe(2);
expect(instances[0]!.cards.aabbMax).toEqual([200, 50, 50]);
// The baked mesh is scaled by 2 about its own origin and moved to x = 300.
const m = instances[1]!.worldFromLocal;
expect([m[0], m[5], m[10], m[12]]).toEqual([2, 2, 2, 300]);
expect(instances[1]!.cards).toBe(baked.cards);
});
it('leaves out a mesh with no baked files, one scaled unevenly, and anything that is not drawn by a mesh', () => {
const { instances } = buildInstances([
entry(9, transform([0, 0, 0]), 'assets/none.esmesh'),
entry(9, transform([0, 0, 0], [1, 2, 1]), 'assets/rock.esmesh'),
entry(9, transform([0, 0, 0]), null),
], CUBE, (p) => (p === 'assets/rock.esmesh' ? baked : null));
expect(instances.length).toBe(0);
});
it('carries a material emissive colour onto the cards of a cube, and rotates it with the entity', () => {
const turn = { x: 0, y: Math.SQRT1_2, z: 0, w: Math.SQRT1_2 }; // 90 degrees about y
const { instances } = buildInstances([entry(CUBE, transform([10, 0, 0], [1, 1, 1], turn), null, [4, 2, 0])], CUBE, () => null);
expect(instances[0]!.cards.emissiveScale).toBe(4);
expect(Array.from(instances[0]!.cards.cards[2]!.emissive.slice(0, 3))).toEqual([255, 128, 0]);
const m = instances[0]!.worldFromLocal;
expect(Math.abs(m[2]! + 1)).toBeLessThan(1e-6); // local x now points along world -z
});
it('has a key that can be had without building: the same string, for the system to ask every frame', () => {
const entries = [entry(CUBE, transform([0, 0, 0], [2, 1, 3]), null, [1, 0, 0]), entry(9, transform([300, 0, 0], [2, 2, 2]), 'assets/rock.esmesh'), entry(9, transform([0, 0, 0], [1, 2, 1]), 'assets/rock.esmesh')];
const found = (p: string) => (p === 'assets/rock.esmesh' ? baked : null);
expect(instanceKey(entries, CUBE, found)).toBe(buildInstances(entries, CUBE, found).key);
expect(instanceKey(entries, CUBE, () => null)).toBe(buildInstances(entries, CUBE, () => null).key);
});
it('changes its key when anything that matters moves, and not when nothing does', () => {
const a = buildInstances([entry(CUBE, transform([0, 0, 0]))], CUBE, () => null).key;
expect(buildInstances([entry(CUBE, transform([0, 0, 0]))], CUBE, () => null).key).toBe(a);
expect(buildInstances([entry(CUBE, transform([1, 0, 0]))], CUBE, () => null).key).not.toBe(a);
expect(buildInstances([entry(CUBE, transform([0, 0, 0]), null, [1, 0, 0])], CUBE, () => null).key).not.toBe(a);
});
});
describe('the packed scene', () => {
const { instances } = buildInstances([entry(CUBE, transform([0, 150, 0], [4, 3, 5])), entry(CUBE, transform([300, 0, 0]))], CUBE, () => null);
const scene = packGPUScene(instances, { toLight: [0, 1, 0], radiance: [1, 1, 1] })!;
it('lays the header, the field, the instances and the card pixels out as the engine reads them', () => {
expect(scene.header.length).toBe(GI_HEADER_FLOATS);
const [dim, cell, , , , reach, count, pixels] = scene.header;
expect(dim).toBe(128);
expect(scene.sdf.length).toBe(128 ** 3 * 1.25); // the field, then the nearest instance of each cell, four to a word
expect(reach).toBeCloseTo(cell! * 6, 4);
expect(count).toBe(2);
expect(scene.instances.length).toBe(2 * GI_INSTANCE_FLOATS);
expect(scene.pixels.length).toBe(pixels! * 4);
expect(Array.from(scene.header.slice(8, 12))).toEqual([0, 1, 0, 1]);
});
it('numbers the faces of each instance one after the other through the pixel array', () => {
let expected = 0;
for (let i = 0; i < 2; i++) for (let face = 0; face < 6; face++) {
const at = i * GI_INSTANCE_FLOATS + 44 + face * 4;
expect(scene.instances[at + 2]).toBe(expected);
expected += scene.instances[at]! * scene.instances[at + 1]!;
}
expect(expected).toBe(scene.header[7]);
// Every pixel names its instance and face (word 3).
const w3 = scene.pixels[3]!;
expect([w3 >> 3, w3 & 7]).toEqual([0, 0]);
const last = scene.pixels[(scene.header[7]! - 1) * 4 + 3]!;
expect([last >> 3, last & 7]).toEqual([1, 5]);
});
it('stores the world box and the scale where the kernels look for them, and the inverse that undoes the placement', () => {
const b = 0;
expect(Array.from(scene.instances.slice(b + 28, b + 31))).toEqual([-200, 0, -250]);
expect(Array.from(scene.instances.slice(b + 32, b + 35))).toEqual([200, 300, 250]);
expect(scene.instances[b + 31]).toBe(1);
// World to local at the entity's centre is the origin: row . (0, 150, 0) + w = 0 for the y row.
expect(scene.instances[b + 16 + 4 + 1]! * 150 + scene.instances[b + 16 + 4 + 3]!).toBeCloseTo(0, 5);
});
it('packs a normal and a colour into the words the kernels unpack', () => {
// Pixel 0 is face 0 (+x) of the first box: normal (127, 0, 0), albedo 0.5 grey.
const w0 = scene.pixels[0]!, w1 = scene.pixels[1]!;
expect([w0 & 0xffff, (w0 >> 16) & 255, (w0 >> 24) & 255, w1 & 255]).toEqual([0, 127, 0, 0]);
expect([(w1 >> 8) & 255, (w1 >> 16) & 255, (w1 >>> 24) & 255]).toEqual([128, 128, 128]);
});
it('is nothing for a scene with nothing in it', () => {
expect(packGPUScene([], null)).toBeNull();
});
});
describe('a field that follows the camera', () => {
const boxes = [entry(CUBE, transform([0, 0, 0], [8, 1, 8])), entry(CUBE, transform([600, 50, 0], [2, 2, 2])), entry(CUBE, transform([-2500, 0, 0], [20, 4, 20]))];
const { instances } = buildInstances(boxes, CUBE, () => null);
it('packs three levels, each four times the last, with their windows and where their fields start', () => {
const sdf = new GlobalSdf([{ dim: 128, cell: 5 }, { dim: 128, cell: 20 }, { dim: 128, cell: 80 }]);
sdf.setCenter([0, 0, 0]);
instances.forEach((inst, id) => sdf.update({ id, sdf: inst.sdf, worldFromLocal: inst.worldFromLocal }));
const scene = packGPUScene(instances, null, { sdf })!;
const h = scene.header, cells = 128 ** 3, stride = cells + cells / 4;
expect(h[22]).toBe(3);
expect(scene.sdf.length).toBe(3 * stride);
// Level 1 and 2: dim, cell, origin, reach, field offset, owner offset.
expect([h[24], h[25], h[30], h[31]]).toEqual([128, 20, stride, stride + cells]);
expect([h[32], h[33], h[38], h[39]]).toEqual([128, 80, 2 * stride, 2 * stride + cells]);
// The finest window is centred on the camera: 64 cells of 5 either side.
expect(h[2]).toBe(-64);
});
it('hands a ray over to a coarser level where the finer window ends, and finds the far box there', () => {
const sdf = new GlobalSdf([{ dim: 128, cell: 5 }, { dim: 128, cell: 20 }, { dim: 128, cell: 80 }]);
sdf.setCenter([0, 0, 0]);
instances.forEach((inst, id) => sdf.update({ id, sdf: inst.sdf, worldFromLocal: inst.worldFromLocal }));
const levelOf = (p: [number, number, number]) => sdf.levels.indexOf(sdf.levelAt(p)!);
// The windows are 640, 2560 and 10240 across: 100 is in the first, 1000 in the second, 2000 only in the third.
expect([levelOf([100, 0, 0]), levelOf([-1000, 0, 0]), levelOf([-2000, 0, 0])]).toEqual([0, 1, 2]);
// From beside the near box toward the far one (its face is at x = -1500, 1050 away): the ray crosses all three levels and stops at it.
const t = sdf.sphereTrace([-450, 0, 0], [-1, 0, 0], 4000)!;
expect(t).toBeGreaterThan(950);
expect(t).toBeLessThan(1100);
// Straight past it, at a height the box does not reach, nothing is in the way.
expect(sdf.sphereTrace([-450, 900, 0], [-1, 0, 0], 4000)).toBeNull();
});
});
describe('lights in the packed scene', () => {
const { instances } = buildInstances([entry(CUBE, transform([0, 0, 0], [4, 1, 4]))], CUBE, () => null);
it('packs a lamp and a spot as the sixteen floats the kernels read', () => {
const scene = packGPUScene(instances, null, { lights: [
{ position: [1, 2, 3], radiance: [0.3, 0.4, 0.5], reach: 600, innerRadius: 50, falloff: 2 },
{ position: [4, 5, 6], radiance: [1, 1, 1], reach: 300, metre: 100, spot: { axis: [0, -2, 0], innerCos: 0.9, outerCos: 0.7 } },
] })!;
const h = scene.header, f = (i: number, n: number) => Array.from(h.slice(40 + i * 16, 40 + i * 16 + n)).map((v) => +v.toFixed(4));
expect(h[23]).toBe(2);
expect(f(0, 16)).toEqual([1, 2, 3, 600, 0.3, 0.4, 0.5, 0, 0, -1, 0, 2, 50, 1, 0, 0]);
// The spot: kind 2, its aim normalised, an inverse-square falloff written as minus the units to a metre, then the cone cosines.
expect(f(1, 16)).toEqual([4, 5, 6, 300, 1, 1, 1, 2, 0, -1, 0, -100, 0, 0.9, 0.7, 0]);
});
it('takes no more lights than the kernels have room for', () => {
const many = Array.from({ length: 12 }, (_, i) => ({ position: [i, 0, 0] as [number, number, number], radiance: [1, 1, 1] as [number, number, number], reach: 100 }));
expect(packGPUScene(instances, null, { lights: many })!.header[23]).toBe(8);
});
});