Skip to content

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.

feat(render): a metal reflects the sky it stands under

esengine0d1db6c34483
diff --git a/desktop/electron/importEnvironment.ts b/desktop/electron/importEnvironment.ts
index 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.esscene
new file mode 100644
index 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.esmaterial
new file mode 100644
index 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.esmaterial
new file mode 100644
index 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.esenv
index 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.hdr
index 69dc3fe79..c9d004ef7 100644
Binary files a/desktop/public/scenes/studio.hdr and b/desktop/public/scenes/studio.hdr differ
diff --git a/desktop/public/scenes/studio_env.png b/desktop/public/scenes/studio_env.png
index d203bbf86..169acbd72 100644
Binary files a/desktop/public/scenes/studio_env.png and b/desktop/public/scenes/studio_env.png differ
diff --git a/desktop/scripts/make-env-fixture.mjs b/desktop/scripts/make-env-fixture.mjs
index 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.ts
index 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.mjs
index 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 asks
an 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.ts
index 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 the
diff --git a/sdk/src/asset/loaders/EnvironmentAssetLoader.ts b/sdk/src/asset/loaders/EnvironmentAssetLoader.ts
index 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.hpp
index 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.cpp
index 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 map
diff --git a/tools/renderScenes.mjs b/tools/renderScenes.mjs
index 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.