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(render): a metal reflects the sky it stands under
esengine0d1db6c34483
diff --git a/desktop/electron/importEnvironment.ts b/desktop/electron/importEnvironment.tsindex b8d20d494..c1c6d9af0 100644--- a/desktop/electron/importEnvironment.ts+++ b/desktop/electron/importEnvironment.ts@@ -56,8 +56,11 @@ export async function importPanorama(root: string, destDir: string,// The atlas is not a picture: its channels are an RGBM encoding of radiance, so// sRGB would linearize what is already linear, and a block compressor would// quantize the shared multiplier along with the colour it scales.- result.document.specular = await write(result.atlasName, result.atlasBytes,- { sRGB: false, compress: false, wrapMode: 'clamp' });+ await write(result.atlasName, result.atlasBytes,+ { sRGB: false, compress: false, wrapMode: 'clamp' });+ // Named BESIDE the document, the way an imported material names its images: the+ // pair moves together, and a project-relative path would not survive that.+ result.document.specular = result.atlasName;await write(`${stem}.esenv`, `${JSON.stringify(result.document, null, 2)}\n`);return { products, warnings: result.warnings };diff --git a/desktop/public/scenes/mat-env-mirror.esscene b/desktop/public/scenes/mat-env-mirror.esscenenew file mode 100644index 000000000..6c27be991--- /dev/null+++ b/desktop/public/scenes/mat-env-mirror.esscene@@ -0,0 +1,145 @@+{+ "version": 1,+ "name": "Main",+ "entities": [+ {+ "id": 0,+ "name": "Camera",+ "parent": null,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": 0,+ "y": 0,+ "z": 10+ }+ }+ },+ {+ "type": "Camera",+ "data": {+ "projectionType": 1,+ "orthoSize": 300,+ "isActive": true,+ "priority": 0+ }+ }+ ]+ },+ {+ "id": 1,+ "name": "Sky",+ "parent": null,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": 0,+ "y": 0,+ "z": 0+ }+ }+ },+ {+ "type": "Light2D",+ "data": {+ "type": 2,+ "color": {+ "r": 1,+ "g": 1,+ "b": 1,+ "a": 1+ },+ "intensity": 1,+ "environment": "/scenes/studio.esenv"+ }+ }+ ]+ },+ {+ "id": 2,+ "name": "Mirror",+ "parent": null,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": -150,+ "y": 0,+ "z": 0+ },+ "scale": {+ "x": 200,+ "y": 200,+ "z": 1+ }+ }+ },+ {+ "type": "Mesh2D",+ "data": {+ "mesh": "/scenes/shadow-quad.esmesh",+ "material": "/scenes/mat-env/mirror.esmaterial",+ "color": {+ "r": 1,+ "g": 1,+ "b": 1,+ "a": 1+ },+ "lit": true,+ "enabled": true+ }+ }+ ]+ },+ {+ "id": 3,+ "name": "Rough",+ "parent": null,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": 150,+ "y": 0,+ "z": 0+ },+ "scale": {+ "x": 200,+ "y": 200,+ "z": 1+ }+ }+ },+ {+ "type": "Mesh2D",+ "data": {+ "mesh": "/scenes/shadow-quad.esmesh",+ "material": "/scenes/mat-env/rough.esmaterial",+ "color": {+ "r": 1,+ "g": 1,+ "b": 1,+ "a": 1+ },+ "lit": true,+ "enabled": true+ }+ }+ ]+ }+ ]+}diff --git a/desktop/public/scenes/mat-env/mirror.esmaterial b/desktop/public/scenes/mat-env/mirror.esmaterialnew file mode 100644index 000000000..c44d2a215--- /dev/null+++ b/desktop/public/scenes/mat-env/mirror.esmaterial@@ -0,0 +1,11 @@+{+ "version": "1.0",+ "type": "material",+ "shader": "builtin:model",+ "blendMode": 0,+ "depthTest": false,+ "properties": {+ "u_metallic": 1,+ "u_roughness": 0+ }+}diff --git a/desktop/public/scenes/mat-env/rough.esmaterial b/desktop/public/scenes/mat-env/rough.esmaterialnew file mode 100644index 000000000..d91eb6cfa--- /dev/null+++ b/desktop/public/scenes/mat-env/rough.esmaterial@@ -0,0 +1,11 @@+{+ "version": "1.0",+ "type": "material",+ "shader": "builtin:model",+ "blendMode": 0,+ "depthTest": false,+ "properties": {+ "u_metallic": 1,+ "u_roughness": 1+ }+}diff --git a/desktop/public/scenes/studio.esenv b/desktop/public/scenes/studio.esenvindex 0ead30b78..afd30ed43 100644--- a/desktop/public/scenes/studio.esenv+++ b/desktop/public/scenes/studio.esenv@@ -2,35 +2,35 @@"version": 1,"irradiance": [0.9894863963127136,- 0.6388990879058838,+ 0.19133681058883667,1.0027153491973877,-0.593439519405365,- -0.032763008028268814,+ -0.009811840020120144,0.5999656319618225,-0.07545698434114456,- 0.690542459487915,+ 0.20680324733257294,-0.06211205944418907,-0.003706963500007987,- 0.03392418473958969,+ 0.010159586556255817,-0.003051366889849305,0.0007192579214461148,- -0.0011798106133937836,+ -0.00035332870902493596,-0.0004842201014980674,0.014640865847468376,- -0.024015601724386215,+ -0.007192172110080719,-0.009856509044766426,-0.0315692164003849,- 0.2917167544364929,+ 0.0873631089925766,-0.026784716174006462,-0.002706394996494055,- 0.024915089830756187,+ 0.007461550645530224,-0.002257157349959016,0.00027758494252339005,- -0.0006669799913652241,+ -0.00019974734459538013,-0.0005578305572271347],- "specular": "scenes/studio_env.png",+ "specular": "studio_env.png","faceSize": 32,- "mipCount": 6,+ "mipCount": 3,"maxRange": 8}diff --git a/desktop/public/scenes/studio.hdr b/desktop/public/scenes/studio.hdrindex 69dc3fe79..c9d004ef7 100644Binary files a/desktop/public/scenes/studio.hdr and b/desktop/public/scenes/studio.hdr differdiff --git a/desktop/public/scenes/studio_env.png b/desktop/public/scenes/studio_env.pngindex d203bbf86..169acbd72 100644Binary files a/desktop/public/scenes/studio_env.png and b/desktop/public/scenes/studio_env.png differdiff --git a/desktop/scripts/make-env-fixture.mjs b/desktop/scripts/make-env-fixture.mjsindex 49913cb79..3247f135e 100644--- a/desktop/scripts/make-env-fixture.mjs+++ b/desktop/scripts/make-env-fixture.mjs@@ -51,7 +51,7 @@ function radianceHdr(pixel) {writeFileSync(path.join(scenes, 'studio.hdr'), radianceHdr((x, y) => {// The green patch spans the equator at the image centre, so a mirror facing the// camera sees it while the two hemispheres stay the diffuse claim.- if (Math.abs(x - W / 2) < 5 && Math.abs(y - H / 2) < 5) return [0, 3, 0];+ if (Math.abs(x - W / 2) < 5 && Math.abs(y - H / 2) < 5) return [0, 0.9, 0];return y < H / 2 ? [0, 0, 0.6] : [0.6, 0, 0];}));diff --git a/desktop/tests/environment-import.test.ts b/desktop/tests/environment-import.test.tsindex b1aaa75dc..3ec67a948 100644--- a/desktop/tests/environment-import.test.ts+++ b/desktop/tests/environment-import.test.ts@@ -14,7 +14,7 @@ import { describe, it, expect } from 'vitest';import {decodeRadianceHdr, projectIrradianceSH, evalIrradianceSH, samplePanorama,octEncode, octDecode, encodeRgbm, decodeRgbm, atlasLayout, prefilterOctahedral,- importEnvironment, ENV_MAX_RANGE,+ importEnvironment, mipCountFor, ENV_MAX_RANGE,type Panorama,} from '../../pipeline/src/assets/environmentImport';@@ -174,6 +174,14 @@ describe('RGBM', () => {});describe('prefiltered atlas', () => {+ it('stops before a face gets too small to be an environment', () => {+ // A 4-texel octahedral face is not a blurrier sky, it is a different one.+ expect(mipCountFor(128)).toBe(5);+ expect(mipCountFor(32)).toBe(3);+ expect(mipCountFor(8)).toBe(1);+ expect(mipCountFor(128, 2)).toBe(2);+ });+it('stacks the mips with a border between them', () => {const { width, height, offsets } = atlasLayout(128, 6);expect(width).toBe(130);@@ -236,10 +244,10 @@ describe('prefiltered atlas', () => {describe('importEnvironment', () => {it('produces a document and an atlas that describe each other', () => {const hdr = flatHdr(32, 16, (_x, y) => (y < 8 ? [2, 2, 2] : [0, 0, 0]));- const result = importEnvironment(hdr, 'studio', { faceSize: 8, mipCount: 3 });+ const result = importEnvironment(hdr, 'studio', { faceSize: 32, mipCount: 3 });expect(result.atlasName).toBe('studio_env.png');expect(result.document.irradiance).toHaveLength(27);- expect(result.document.faceSize).toBe(8);+ expect(result.document.faceSize).toBe(32);expect(result.document.mipCount).toBe(3);expect(result.document.maxRange).toBe(ENV_MAX_RANGE);// A PNG, and one whose size the layout predicts.diff --git a/pipeline/bin/estella.mjs b/pipeline/bin/estella.mjsindex c6736cc8a..80d3e778e 100644--- a/pipeline/bin/estella.mjs+++ b/pipeline/bin/estella.mjs@@ -15,8 +15,7 @@ const REPO = path.join(PIPELINE, '..');const USAGE = `usage: node pipeline/bin/estella.mjs export <projectDir> [options]node pipeline/bin/estella.mjs import-gltf <file.gltf|file.glb> [outDir][--project <dir>] [--scale <n>]- node pipeline/bin/estella.mjs import-hdr <file.hdr> [outDir]- [--project <dir>] [--face-size <n>]+ node pipeline/bin/estella.mjs import-hdr <file.hdr> [outDir] [--face-size <n>]--platform <id> web | desktop | wechat | playable | android | ios (default web)--out <dir> output dir (default <projectDir>/dist-<platform>)@@ -46,8 +45,8 @@ otherwise; --scale sizes the model, whose metres are world units otherwise.import-hdr bakes an equirectangular panorama into the two things a renderer asksan environment for: nine irradiance coefficients (in the \`.esenv\`) and one-prefiltered octahedral atlas beside it. The panorama itself is not shipped —-a light references the \`.esenv\`.`;+prefiltered octahedral atlas beside it, which the document names as a sibling.+The panorama itself is not shipped — a light references the \`.esenv\`.`;/** Options take a value; these do not — without the distinction a trailing flag* swallows nothing, ends the loop, and a CI job silently gets no gate. */@@ -278,15 +277,9 @@ if (opts.command === 'import-hdr') {const sourceDir = path.dirname(opts.source);const dir = opts.out ?? sourceDir;const stem = path.basename(opts.source).replace(/\.hdr$/i, '');- const root = opts.project ?? findProjectRoot(sourceDir);- const projectRef = (abs) => path.relative(root, abs).split(path.sep).join('/');const result = importer.importEnvironment(new Uint8Array(readFileSync(opts.source)), stem, { faceSize: opts.faceSize });for (const w of result.warnings) console.warn(` ! ${w}`);- if (!root) {- console.warn(' ! no project found above the source — the atlas ref is a bare file name'- + ' (pass --project <dir>)');- }const report = (file, what) =>console.log(`${path.relative(process.cwd(), file)}: ${what}`);@@ -298,7 +291,8 @@ if (opts.command === 'import-hdr') {await meta.adoptOrphan(atlasFile, { sRGB: false, compress: false, wrapMode: 'clamp' });report(atlasFile, `${result.document.mipCount} prefiltered mips`);- result.document.specular = root ? projectRef(atlasFile) : result.atlasName;+ // Beside the document, the way an imported material names its images.+ result.document.specular = result.atlasName;const envFile = path.join(dir, `${stem}.esenv`);writeFileSync(envFile, `${JSON.stringify(result.document, null, 2)}\n`);await meta.adoptOrphan(envFile);diff --git a/pipeline/src/assets/environmentImport.ts b/pipeline/src/assets/environmentImport.tsindex 85b9c0b4b..07f388584 100644--- a/pipeline/src/assets/environmentImport.ts+++ b/pipeline/src/assets/environmentImport.ts@@ -28,22 +28,31 @@ export interface EnvironmentAssetData {/** Nine RGB coefficients, already divided by π: evaluating them at N gives the* value that multiplies albedo directly, the way `ambient` does. */irradiance: number[];- /** The octahedral mip atlas, as an `@uuid:` reference. */+ /** The octahedral mip atlas, named as a sibling of this document. */specular: string;/** Edge length of mip 0's octahedral face, in texels. */faceSize: number;/** How many mips the atlas holds; mip i is prefiltered for roughness i/(mipCount-1). */mipCount: number;- /** The RGBM decode range: `rgb*rgb * (a * maxRange)` is the stored radiance. */+ /** The RGBM decode range: `(rgb*a)^2 * maxRange` is the stored radiance. */maxRange: number;}export const ENVIRONMENT_FORMAT_VERSION = 1;-/** Mip 0's face size, and how many mips follow it. Six mips put roughness on a- * 0.2 grid, which is finer than the prefilter's own error at the rough end. */+/** Mip 0's face size, and how many mips follow it. Five mips put roughness on a+ * 0.25 grid, which is finer than the prefilter's own error at the rough end. */export const ENV_FACE_SIZE = 128;-export const ENV_MIP_COUNT = 6;+export const ENV_MIP_COUNT = 5;+/** No mip goes below this. An octahedral face of a few texels is not a blurrier+ * environment, it is a different one: the roughest lobe covers most of the+ * sphere, and at 4 texels the SEAM is a quarter of what a sample can reach. */+export const ENV_MIN_FACE = 8;++/** How many mips `faceSize` supports without falling under {@link ENV_MIN_FACE}. */+export function mipCountFor(faceSize: number, want = ENV_MIP_COUNT): number {+ return Math.max(1, Math.min(want, Math.floor(Math.log2(faceSize / ENV_MIN_FACE)) + 1));+}/** Radiance above this clips. Sky detail lives well below it; a sun disc does not,* and is meant to survive as a bright blob rather than as its true thousands. */export const ENV_MAX_RANGE = 8;@@ -446,7 +455,7 @@ export function importEnvironment(bytes: Uint8Array, stem: string,options: { faceSize?: number; mipCount?: number } = {}):ImportedEnvironment {const faceSize = options.faceSize ?? ENV_FACE_SIZE;- const mipCount = options.mipCount ?? ENV_MIP_COUNT;+ const mipCount = mipCountFor(faceSize, options.mipCount ?? ENV_MIP_COUNT);const panorama = decodeRadianceHdr(bytes);const warnings: string[] = [];// Equirectangular is 2:1 by construction. Another ratio still bakes, but thediff --git a/sdk/src/asset/loaders/EnvironmentAssetLoader.ts b/sdk/src/asset/loaders/EnvironmentAssetLoader.tsindex 748decf49..72d9ce416 100644--- a/sdk/src/asset/loaders/EnvironmentAssetLoader.ts+++ b/sdk/src/asset/loaders/EnvironmentAssetLoader.ts@@ -57,7 +57,10 @@ export class EnvironmentAssetLoader implements AssetLoader<EnvironmentResult> {if (data.specular) {const resolved = resolvePath(path, data.specular);try {- specularHandle = (await ctx.loadTexture(resolved)).handle;+ // flipY false: the atlas' rows are a layout, not a picture. Row 0+ // is mip 0, and a load that turned it over would put the mip+ // offsets — and every face's v — upside down.+ specularHandle = (await ctx.loadTexture(resolved, false)).handle;specularPath = resolved;} catch (e) {log.warn('asset', `${path}: no reflection atlas at '${resolved}'`, e);diff --git a/src/esengine/resource/Environment.hpp b/src/esengine/resource/Environment.hppindex a24da7f4e..0a87e2792 100644--- a/src/esengine/resource/Environment.hpp+++ b/src/esengine/resource/Environment.hpp@@ -31,7 +31,7 @@ public:/** Edge length of mip 0's octahedral face, in texels. */f32 faceSize = 0.0f;u32 mipCount = 0;- /** RGBM decode range: `rgb*rgb * (a * maxRange)` is the stored radiance. */+ /** RGBM decode range: `(rgb*a)^2 * maxRange` is the stored radiance. */f32 maxRange = 0.0f;bool hasSpecular() const { return specular.isValid() && mipCount > 0 && faceSize > 0.0f; }diff --git a/src/esengine/resource/ShaderParser.cpp b/src/esengine/resource/ShaderParser.cppindex 0a0eda67c..932c0f419 100644--- a/src/esengine/resource/ShaderParser.cpp+++ b/src/esengine/resource/ShaderParser.cpp@@ -884,7 +884,7 @@ fn envSampleMip(R : vec3f, mip : f32) -> vec3f {let uv = octEncode(R);let px = vec2f(1.0 + uv.x * size, yOff + 1.0 + uv.y * size);let t = textureSampleLevel(t3, s3, px / vec2f(atlasW, atlasH), 0.0);- return t.rgb * t.rgb * (t.a * lc.u_envParams.y);+ return t.rgb * t.rgb * (t.a * t.a * lc.u_envParams.y);#endif}fn envRadiance(R : vec3f, roughness : f32) -> vec3f {@@ -1454,7 +1454,7 @@ ShaderParser::AssembledStage ShaderParser::assembleStageEx(const ParsedShader& p" highp vec2 uv = octEncode(R);\n"" highp vec2 px = vec2(1.0 + uv.x * size, yOff + 1.0 + uv.y * size);\n"" highp vec4 t = texture(u_envMap, px / vec2(atlasW, atlasH));\n"- " return t.rgb * t.rgb * (t.a * u_envParams.y);\n"+ " return t.rgb * t.rgb * (t.a * t.a * u_envParams.y);\n""#endif\n""}\n"// The environment's specular half, at the roughness asked for. Without a mapdiff --git a/tools/renderScenes.mjs b/tools/renderScenes.mjsindex 049c531b5..98b57f02e 100644--- a/tools/renderScenes.mjs+++ b/tools/renderScenes.mjs@@ -59,7 +59,11 @@ export const SCENES = [// A baked panorama lighting a surface BY DIRECTION: two coplanar triangles, one// white colour, normals up and down under a sky blue above and red below. A flat// ambient term draws the halves identically, which is why the probes invert.- { id: "mat-env", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/mat-env.esscene", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.25,\"y\":0.55,\"rgb\":[0,19,149],\"tol\":20},{\"x\":0.75,\"y\":0.55,\"rgb\":[148,27,0],\"tol\":20},{\"x\":0.5,\"y\":0.55,\"rgb\":[0,0,0],\"tol\":20}]" } },+ { id: "mat-env", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/mat-env.esscene", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.25,\"y\":0.55,\"rgb\":[0,6,149],\"tol\":20},{\"x\":0.75,\"y\":0.55,\"rgb\":[148,8,0],\"tol\":20},{\"x\":0.5,\"y\":0.55,\"rgb\":[0,0,0],\"tol\":20}]" } },+ // The same sky in a MIRROR: two metal quads, roughness 0 and 1. A head-on+ // surface reflects +Z, which is the image centre — green there, and the whole+ // sphere averaged at the rough end. One flat term would draw them alike.+ { id: "mat-env-mirror", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/mat-env-mirror.esscene", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.25,\"y\":0.5,\"rgb\":[0,228,0],\"tol\":20},{\"x\":0.75,\"y\":0.5,\"rgb\":[29,23,24],\"tol\":20},{\"x\":0.5,\"y\":0.5,\"rgb\":[0,0,0],\"tol\":20}]" } },// A glTF animation, through the shipped importer. The scene puts the quad at// x=150 and the clip runs -120 to 120 over a second, so 30 fixed steps is its// midpoint: the model is at the origin and where the SCENE put it is empty.