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
/** What a surface is made of: said by faces, kept by a map in the packing the engine's material reads, and named by a material. */
import { beforeAll, describe, expect, it } from 'vitest';
import { MeshChannel } from 'esengine';
import { applyModelEdits, bakeModel, bakeNormalMap, modelMaterialDoc, prepareModeling, validateModelSource, type BakedModel, type ModelStep } from '../src/modeling';
beforeAll(() => prepareModeling());
const ball: ModelStep = { id: 'form', op: 'sphere', radius: 1, rings: 32, sides: 64, tag: 'ball' };
const thin: ModelStep = { op: 'decimate', from: 'form', triangles: 300, error: 0.5 };
const SIZE = 128;
function surfaceAt(m: BakedModel, rgba: Uint8Array, triangle: number): { texel: number[]; at: number[] } {
const { data } = m;
const channel = (semantic: number) => data.channels.find((c) => c.semantic === semantic)!.offset;
const view = new DataView(data.vertices.buffer, data.vertices.byteOffset, data.vertices.byteLength);
const mean = (offset: number, k: number): number => [0, 1, 2].reduce((sum, c) => sum + view.getFloat32(data.indices[triangle * 3 + c]! * data.vertexStride + offset + k * 4, true), 0) / 3;
const [u, v] = [mean(channel(MeshChannel.TexCoord0), 0), mean(channel(MeshChannel.TexCoord0), 1)];
const i = (Math.floor((1 - v) * SIZE) * SIZE + Math.floor(u * SIZE)) * 4;
return { texel: [...rgba.subarray(i, i + 4)], at: [0, 1, 2].map((k) => mean(channel(MeshChannel.Position), k)) };
}
describe('paint and stain say what a surface is made of', () => {
it('paint sets them on what it names, and leaves colour alone', () => {
const m = bakeModel({ version: 1, steps: [{ op: 'box', size: 1, color: [0.5, 0.5, 0.5] }, { op: 'paint', faces: '+y', roughness: 0.2, metallic: 1 }] });
for (const f of m.poly.faces) {
expect(f.color).toEqual([0.5, 0.5, 0.5, 1]);
if (f.roughness !== undefined) expect([f.roughness, f.metallic]).toEqual([0.2, 1]);
}
expect(m.poly.faces.filter((f) => f.metallic === 1)).toHaveLength(1);
});
it('stain mixes toward them by `amount`, from what the source says everything is', () => {
const m = bakeModel({ version: 1, material: { roughness: 0.8, metallic: 0 }, steps: [{ op: 'plane', size: 1 }, { op: 'stain', near: { at: [0, 0, 0], radius: 10 }, hard: true, amount: 0.5, roughness: 0.2, metallic: 1, detail: 5 }] });
expect(m.poly.faces[0]!.roughness).toBeCloseTo(0.5, 6);
expect(m.poly.faces[0]!.metallic).toBeCloseTo(0.5, 6);
expect(m.poly.faces[0]!.color).toBeUndefined();
});
it('refuse a step that says nothing, and values out of range', () => {
expect(() => bakeModel({ version: 1, steps: [ball, { op: 'paint', faces: 'all' }] })).toThrow(/at least one of color, roughness, metallic/);
expect(() => bakeModel({ version: 1, steps: [ball, { op: 'stain', facing: [0, 1, 0] }] })).toThrow(/at least one of color, roughness, metallic/);
expect(() => bakeModel({ version: 1, steps: [ball, { op: 'paint', faces: 'all', roughness: 2 }] })).toThrow(/roughness 2 must be 0..1/);
expect(() => validateModelSource({ steps: [ball], material: { roughness: 2 } })).toThrow(/material.roughness must be 0..1/);
expect(() => validateModelSource({ steps: [ball], material: { shiny: 1 } })).toThrow(/unknown field "shiny"/);
});
it('survive a decimate on the side they were on', () => {
const m = bakeModel({ version: 1, steps: [ball, { op: 'stain', faces: { within: { min: [null, 0, null] } }, facing: [0, 1, 0], metallic: 1, threshold: 0 }, { op: 'decimate', ratio: 0.3, error: 0.2 }] });
const metal = m.poly.faces.filter((f) => (f.metallic ?? 0) > 0.5);
expect(metal.length).toBeGreaterThan(5);
for (const f of metal) expect(f.v.reduce((sum, v) => sum + m.poly.positions[v]![1], 0) / 3).toBeGreaterThan(-0.2);
});
it('warn when nothing carries them, and say what would', () => {
const m = bakeModel({ version: 1, steps: [ball, { op: 'paint', faces: 'all', metallic: 1 }] });
expect(m.report.warnings.join()).toMatch(/nothing carries that: give normalBake `surface: true`, or say it once in `material`/);
});
});
describe('normalBake surface', () => {
it('packs as the material reads it: full red, roughness in green, metal in blue, and where it was painted', () => {
const m = bakeModel({ version: 1, normalBake: { size: SIZE, surface: true }, steps: [ball, { op: 'stain', near: { at: [0, 1, 0], radius: 1.2 }, hard: true, roughness: 0.2, metallic: 1 }, thin] });
const map = bakeNormalMap(m);
expect(map.surfaceRgba).toBeDefined();
const seen = { steel: 0, chalk: 0 };
for (let t = 0; t < m.data.indices.length / 3; t++) {
const { texel, at } = surfaceAt(m, map.surfaceRgba!, t);
if (at[1]! > 0.5) { expect(texel).toEqual([255, 51, 255, 255]); seen.steel++; }
if (at[1]! < -0.5) { expect(texel).toEqual([255, 255, 0, 255]); seen.chalk++; }
}
expect(seen.steel).toBeGreaterThan(3);
expect(seen.chalk).toBeGreaterThan(3);
});
it('takes the source\'s `material` for faces that say nothing, and for texels no surface reached', () => {
const steps: ModelStep[] = [{ op: 'plane', size: 4, at: [0, 5, 0] }, { id: 'away', op: 'transform', scale: 1 }, { op: 'delete', faces: 'all' }, { op: 'plane', size: 1 }];
const missed = bakeModel({ version: 1, material: { roughness: 0.4, metallic: 0.5 }, normalBake: { size: SIZE, surface: true, from: 'away', distance: 0.1 }, steps });
const map = bakeNormalMap(missed);
expect(map.report.missed).toBe(1);
expect(surfaceAt(missed, map.surfaceRgba!, 0).texel).toEqual([255, 102, 128, 255]);
const hit = bakeModel({ version: 1, material: { roughness: 0.4, metallic: 0.5 }, normalBake: { size: SIZE, surface: true }, steps: [ball, thin] });
expect(surfaceAt(hit, bakeNormalMap(hit).surfaceRgba!, 0).texel).toEqual([255, 102, 128, 255]);
});
it('is not written unless asked for', () => {
const m = bakeModel({ version: 1, normalBake: { size: 64 }, steps: [ball, thin] });
expect(bakeNormalMap(m).surfaceRgba).toBeUndefined();
});
it('`surface` must be true or false, and an edit can take a material away', () => {
expect(() => validateModelSource({ steps: [ball, thin], normalBake: { surface: 1 } })).toThrow(/surface must be true or false/);
const source = validateModelSource({ steps: [ball], material: { metallic: 1 } });
expect(applyModelEdits(source, [{ op: 'settings', fields: { material: null as never } }]).material).toBeUndefined();
});
});
describe('normalBake occlusion', () => {
/** The occlusion map at the point of the thin mesh nearest @p want. */
function at(m: BakedModel, map: { size: number; rgba: Uint8Array }, want: readonly number[]): number {
const { data } = m;
const offset = (semantic: number) => data.channels.find((c) => c.semantic === semantic)!.offset;
const view = new DataView(data.vertices.buffer, data.vertices.byteOffset, data.vertices.byteLength);
let best = Infinity, u = 0, v = 0;
for (let t = 0; t < data.indices.length / 3; t++) {
const mean = (o: number, k: number): number => [0, 1, 2].reduce((sum, c) => sum + view.getFloat32(data.indices[t * 3 + c]! * data.vertexStride + o + k * 4, true), 0) / 3;
const d = Math.hypot(mean(offset(MeshChannel.Position), 0) - want[0]!, mean(offset(MeshChannel.Position), 1) - want[1]!, mean(offset(MeshChannel.Position), 2) - want[2]!);
if (d < best) { best = d; u = mean(offset(MeshChannel.TexCoord0), 0); v = mean(offset(MeshChannel.TexCoord0), 1); }
}
return map.rgba[(Math.floor((1 - v) * map.size) * map.size + Math.floor(u * map.size)) * 4]!;
}
it('is white over a ball, which nothing shades, and on any open flat', () => {
const m = bakeModel({ version: 1, normalBake: { size: 256, occlusion: true }, steps: [ball, thin] });
const { occlusion } = bakeNormalMap(m);
expect(occlusion!.size).toBe(128);
expect(at(m, occlusion!, [0, 1, 0])).toBeGreaterThan(245);
expect(at(m, occlusion!, [1, 0, 0])).toBeGreaterThan(245);
});
it('is dark at the bottom of a deep slot, and light on the open face beside it', () => {
const m = bakeModel({ version: 1, normalBake: { size: 512, from: 'form', occlusion: { reach: 1, samples: 64 } }, steps: [
{ id: 'form', op: 'organic', resolution: 80, blend: 0.01, parts: [
{ shape: 'box', size: [3, 2, 2] }, { shape: 'box', size: [0.3, 3, 1.4], at: [0, 0, 0.75], subtract: true, blend: 0.01 },
] },
] });
const { occlusion } = bakeNormalMap(m);
const inSlot = at(m, occlusion!, [0, 0, 0.05]);
const open = at(m, occlusion!, [1, 0, 1]);
expect(open).toBeGreaterThan(200);
expect(inSlot).toBeLessThan(open * 0.6);
}, 60000);
it('sees where two parts meet, and not one far away', () => {
const bake = (gap: number) => {
const m = bakeModel({ version: 1, normalBake: { size: 256, from: 'high', occlusion: { reach: 0.5, samples: 36, size: 128 } }, steps: [
{ op: 'box', size: [4, 0.2, 4], at: [0, -0.1, 0], tag: 'floor' }, { op: 'sphere', radius: 0.5, rings: 24, sides: 48, at: [0, 0.5 + gap, 0], tag: 'ball' }, { id: 'high', op: 'tag', faces: 'floor', tag: 'floor' },
] });
return at(m, bakeNormalMap(m).occlusion!, [0.2, 0, 0.1]);
};
expect(bake(0)).toBeLessThan(bake(3) * 0.75);
}, 60000);
it('fills past the charts\' edges, and is the same every time', () => {
const source = { version: 1, normalBake: { size: 256, occlusion: { samples: 9 } }, steps: [ball, thin] };
const a = bakeNormalMap(bakeModel(source)).occlusion!;
const b = bakeNormalMap(bakeModel(source)).occlusion!;
expect(a.rgba).toEqual(b.rgba);
expect(a.rgba.every((_, i) => i % 4 !== 3 || a.rgba[i] === 255)).toBe(true);
});
it('is not worked out unless asked for', () => {
expect(bakeNormalMap(bakeModel({ version: 1, normalBake: { size: 64 }, steps: [ball, thin] })).occlusion).toBeUndefined();
});
it('refuses what cannot be meant', () => {
const steps = [ball, thin];
expect(() => validateModelSource({ steps, normalBake: { occlusion: 1 } })).toThrow(/occlusion must be true, false or/);
expect(() => validateModelSource({ steps, normalBake: { occlusion: { rays: 9 } } })).toThrow(/unknown field "rays"/);
expect(() => validateModelSource({ steps, normalBake: { occlusion: { samples: 0 } } })).toThrow(/samples must be 1..256/);
expect(() => validateModelSource({ steps, normalBake: { occlusion: { size: 100 } } })).toThrow(/power of two/);
expect(() => validateModelSource({ steps, normalBake: { occlusion: { strength: 2 } } })).toThrow(/strength must be 0..1/);
});
});
describe('the material a model writes', () => {
it('is none where a MeshRenderer says it all', () => {
expect(modelMaterialDoc(validateModelSource({ steps: [ball] }), true, {})).toBeNull();
expect(modelMaterialDoc(validateModelSource({ steps: [ball] }), true, { normal: 'a_normal.png' })).toBeNull();
});
it('holds constants, and the normal map a renderer would otherwise hold', () => {
const doc = modelMaterialDoc(validateModelSource({ steps: [ball], material: { roughness: 0.3, metallic: 1 } }), true, { normal: 'a_normal.png' })!;
expect(doc.shader).toBe('builtin:model');
expect(doc.properties).toEqual({ u_normalMap: 'a_normal.png', u_roughness: 0.3, u_metallic: 1 });
});
it('leaves a map\'s values unscaled: the factors multiply it, so they are 1', () => {
const doc = modelMaterialDoc(validateModelSource({ steps: [ball, thin], material: { roughness: 0.3, metallic: 0 }, normalBake: { surface: true } }), true, { surface: 'a_surface.png' })!;
expect(doc.properties).toEqual({ u_metallicRoughnessMap: 'a_surface.png', u_roughness: 1, u_metallic: 1 });
});
it('names an occlusion map and its strength, with constants left as they were', () => {
const doc = modelMaterialDoc(validateModelSource({ steps: [ball, thin], normalBake: { occlusion: { strength: 0.5 } } }), true, { occlusion: 'a_occlusion.png' })!;
expect(doc.properties).toEqual({ u_occlusionMap: 'a_occlusion.png', u_occlusionStrength: 0.5, u_roughness: 1, u_metallic: 0 });
});
it('culls as the surface allows', () => {
const source = validateModelSource({ steps: [ball], material: { metallic: 1 } });
expect(modelMaterialDoc(source, true, {})!.cull).not.toBe(modelMaterialDoc(source, false, {})!.cull);
});
});