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 surface is lit by the sky above it

esengine0f9bea8775ae
diff --git a/desktop/public/scenes/env-triangles.esmesh b/desktop/public/scenes/env-triangles.esmesh
new file mode 100644
index 000000000..ad9e7303d
Binary files /dev/null and b/desktop/public/scenes/env-triangles.esmesh differ
diff --git a/desktop/public/scenes/env-triangles.esmesh.meta b/desktop/public/scenes/env-triangles.esmesh.meta
new file mode 100644
index 000000000..a5704982a
--- /dev/null
+++ b/desktop/public/scenes/env-triangles.esmesh.meta
@@ -0,0 +1,6 @@
+{
+ "uuid": "03d14743-6900-4460-872e-ba20be62c56f",
+ "version": "2.0",
+ "type": "mesh",
+ "importer": {}
+}
diff --git a/desktop/public/scenes/env-triangles.esprefab b/desktop/public/scenes/env-triangles.esprefab
new file mode 100644
index 000000000..58088fdaf
--- /dev/null
+++ b/desktop/public/scenes/env-triangles.esprefab
@@ -0,0 +1,28 @@
+{
+ "version": "2",
+ "name": "env-triangles",
+ "rootEntityId": "n0",
+ "entities": [
+ {
+ "prefabEntityId": "n0",
+ "name": "node_0",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {}
+ },
+ {
+ "type": "Mesh2D",
+ "data": {
+ "mesh": "scenes/env-triangles.esmesh",
+ "lit": true,
+ "enabled": true
+ }
+ }
+ ]
+ }
+ ]
+}
diff --git a/desktop/public/scenes/env-triangles.esprefab.meta b/desktop/public/scenes/env-triangles.esprefab.meta
new file mode 100644
index 000000000..88b4b7958
--- /dev/null
+++ b/desktop/public/scenes/env-triangles.esprefab.meta
@@ -0,0 +1,6 @@
+{
+ "uuid": "0136e5a0-5b96-4888-9fcd-b47169ea288f",
+ "version": "2.0",
+ "type": "prefab",
+ "importer": {}
+}
diff --git a/desktop/public/scenes/env-triangles.gltf b/desktop/public/scenes/env-triangles.gltf
new file mode 100644
index 000000000..a7bead8c6
--- /dev/null
+++ b/desktop/public/scenes/env-triangles.gltf
@@ -0,0 +1,99 @@
+{
+ "asset": {
+ "version": "2.0",
+ "generator": "estella test fixture"
+ },
+ "buffers": [
+ {
+ "byteLength": 252,
+ "uri": "data:application/octet-stream;base64,AABIwwAAyMIAAAAAAAAgwgAAyMIAAAAAAADwwgAAyEIAAAAAAAAgQgAAyMIAAAAAAABIQwAAyMIAAAAAAADwQgAAyEIAAAAAAAAAAAAAgD8AAAAAAAAAAAAAgD8AAAAAAAAAAAAAgD8AAAAAAAAAAAAAgL8AAAAAAAAAAAAAgL8AAAAAAAAAAAAAgL8AAAAAAACAPwAAgD8AAIA/AACAPwAAgD8AAIA/AACAPwAAgD8AAIA/AACAPwAAgD8AAIA/AACAPwAAgD8AAIA/AACAPwAAgD8AAIA/AACAPwAAgD8AAIA/AACAPwAAgD8AAIA/AAABAAIAAwAEAAUA"
+ }
+ ],
+ "bufferViews": [
+ {
+ "buffer": 0,
+ "byteOffset": 0,
+ "byteLength": 72
+ },
+ {
+ "buffer": 0,
+ "byteOffset": 72,
+ "byteLength": 72
+ },
+ {
+ "buffer": 0,
+ "byteOffset": 144,
+ "byteLength": 96
+ },
+ {
+ "buffer": 0,
+ "byteOffset": 240,
+ "byteLength": 12
+ }
+ ],
+ "accessors": [
+ {
+ "bufferView": 0,
+ "componentType": 5126,
+ "count": 6,
+ "type": "VEC3",
+ "min": [
+ -200,
+ -100,
+ 0
+ ],
+ "max": [
+ 200,
+ 100,
+ 0
+ ]
+ },
+ {
+ "bufferView": 1,
+ "componentType": 5126,
+ "count": 6,
+ "type": "VEC3"
+ },
+ {
+ "bufferView": 2,
+ "componentType": 5126,
+ "count": 6,
+ "type": "VEC4"
+ },
+ {
+ "bufferView": 3,
+ "componentType": 5123,
+ "count": 6,
+ "type": "SCALAR"
+ }
+ ],
+ "meshes": [
+ {
+ "name": "EnvTriangles",
+ "primitives": [
+ {
+ "attributes": {
+ "POSITION": 0,
+ "NORMAL": 1,
+ "COLOR_0": 2
+ },
+ "indices": 3,
+ "mode": 4
+ }
+ ]
+ }
+ ],
+ "nodes": [
+ {
+ "mesh": 0
+ }
+ ],
+ "scenes": [
+ {
+ "nodes": [
+ 0
+ ]
+ }
+ ],
+ "scene": 0
+}
diff --git a/desktop/public/scenes/mat-env.esscene b/desktop/public/scenes/mat-env.esscene
new file mode 100644
index 000000000..d0ad75296
--- /dev/null
+++ b/desktop/public/scenes/mat-env.esscene
@@ -0,0 +1,101 @@
+{
+ "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": "EnvTriangles",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 0,
+ "z": 0
+ }
+ }
+ },
+ {
+ "type": "Mesh2D",
+ "data": {
+ "color": {
+ "r": 1,
+ "g": 1,
+ "b": 1,
+ "a": 1
+ },
+ "layer": 0,
+ "enabled": true,
+ "lit": true,
+ "mesh": "/scenes/env-triangles.esmesh"
+ }
+ }
+ ]
+ }
+ ]
+}
diff --git a/desktop/public/scenes/studio.esenv b/desktop/public/scenes/studio.esenv
new file mode 100644
index 000000000..0ead30b78
--- /dev/null
+++ b/desktop/public/scenes/studio.esenv
@@ -0,0 +1,36 @@
+{
+ "version": 1,
+ "irradiance": [
+ 0.9894863963127136,
+ 0.6388990879058838,
+ 1.0027153491973877,
+ -0.593439519405365,
+ -0.032763008028268814,
+ 0.5999656319618225,
+ -0.07545698434114456,
+ 0.690542459487915,
+ -0.06211205944418907,
+ -0.003706963500007987,
+ 0.03392418473958969,
+ -0.003051366889849305,
+ 0.0007192579214461148,
+ -0.0011798106133937836,
+ -0.0004842201014980674,
+ 0.014640865847468376,
+ -0.024015601724386215,
+ -0.009856509044766426,
+ -0.0315692164003849,
+ 0.2917167544364929,
+ -0.026784716174006462,
+ -0.002706394996494055,
+ 0.024915089830756187,
+ -0.002257157349959016,
+ 0.00027758494252339005,
+ -0.0006669799913652241,
+ -0.0005578305572271347
+ ],
+ "specular": "scenes/studio_env.png",
+ "faceSize": 32,
+ "mipCount": 6,
+ "maxRange": 8
+}
diff --git a/desktop/public/scenes/studio.esenv.meta b/desktop/public/scenes/studio.esenv.meta
new file mode 100644
index 000000000..4435916d6
--- /dev/null
+++ b/desktop/public/scenes/studio.esenv.meta
@@ -0,0 +1,6 @@
+{
+ "uuid": "9e803799-5b25-4729-9111-baf06613fa54",
+ "version": "2.0",
+ "type": "environment",
+ "importer": {}
+}
diff --git a/desktop/public/scenes/studio.hdr b/desktop/public/scenes/studio.hdr
new file mode 100644
index 000000000..69dc3fe79
Binary files /dev/null and b/desktop/public/scenes/studio.hdr differ
diff --git a/desktop/public/scenes/studio_env.png b/desktop/public/scenes/studio_env.png
new file mode 100644
index 000000000..d203bbf86
Binary files /dev/null and b/desktop/public/scenes/studio_env.png differ
diff --git a/desktop/public/scenes/studio_env.png.meta b/desktop/public/scenes/studio_env.png.meta
new file mode 100644
index 000000000..3160497fe
--- /dev/null
+++ b/desktop/public/scenes/studio_env.png.meta
@@ -0,0 +1,19 @@
+{
+ "uuid": "710440a7-26e7-487e-bf08-a0668cbdc0a0",
+ "version": "2.0",
+ "type": "texture",
+ "importer": {
+ "maxSize": 2048,
+ "compress": false,
+ "compressFormat": "uastc",
+ "filterMode": "linear",
+ "wrapMode": "clamp",
+ "sRGB": false,
+ "sliceBorder": {
+ "left": 0,
+ "right": 0,
+ "top": 0,
+ "bottom": 0
+ }
+ }
+}
diff --git a/desktop/scripts/editor-checks/panorama-import.mjs b/desktop/scripts/editor-checks/panorama-import.mjs
new file mode 100644
index 000000000..1215df52f
--- /dev/null
+++ b/desktop/scripts/editor-checks/panorama-import.mjs
@@ -0,0 +1,91 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file panorama-import — a `.hdr` through the editor's import door.
+ *
+ * The pixel gate lights a scene with an environment the CLI baked; this is the
+ * other door, where the products are written by the bundled main process. Two
+ * things can only be checked here: that the `.esenv` points at an atlas really
+ * beside it, and that the atlas' `.meta` says authored-linear and uncompressed —
+ * an RGBM encoding cooked as a picture comes back as the wrong radiance, and
+ * nothing about the file says so.
+ */
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { makeProject, checker } from '../lib/editorDriver.mjs';
+
+export const name = 'panorama-import';
+export const describes = 'an imported panorama writes its environment and the atlas it names';
+
+/** A Radiance file, sky above and ground below, in the flat encoding. */
+function panoramaHdr(width = 32, height = 16) {
+ const header = Buffer.from(`#?RADIANCE\nFORMAT=32-bit_rle_rgbe\n\n-Y ${height} +X ${width}\n`);
+ const body = Buffer.alloc(width * height * 4);
+ for (let y = 0; y < height; y++) {
+ for (let x = 0; x < width; x++) {
+ const [r, g, b] = y < height / 2 ? [0, 0, 2] : [2, 0, 0];
+ const peak = Math.max(r, g, b);
+ const e = peak > 0 ? Math.ceil(Math.log2(peak)) + 128 : 0;
+ const scale = peak > 0 ? 256 / Math.pow(2, e - 128) : 0;
+ const at = (y * width + x) * 4;
+ body[at] = Math.min(255, Math.floor(r * scale));
+ body[at + 1] = Math.min(255, Math.floor(g * scale));
+ body[at + 2] = Math.min(255, Math.floor(b * scale));
+ body[at + 3] = e;
+ }
+ }
+ return Buffer.concat([header, body]);
+}
+
+export async function run(ed) {
+ const root = await makeProject({
+ 'project.esproject': JSON.stringify({ name: 'Panorama', version: '1.0' }, null, 2),
+ 'assets/scenes/main.esscene': JSON.stringify({
+ version: '1.0', 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 } },
+ ],
+ }],
+ }, null, 1),
+ });
+ await mkdir(path.join(root, 'assets'), { recursive: true });
+ const source = path.join(root, 'assets', 'sky.hdr');
+ await writeFile(source, panoramaHdr());
+
+ const check = checker();
+ await ed.open(root, 'assets/scenes/main.esscene');
+ const result = await ed.json('import_assets', { destDir: 'assets', sources: [source] }, 120000);
+ const imported = result?.imported ?? [];
+ if (!check(imported.includes('assets/sky.esenv') && imported.includes('assets/sky_env.png'),
+ `import reported ${JSON.stringify(imported)}`)) {
+ return check.failures;
+ }
+
+ const read = async (rel) => {
+ try {
+ return JSON.parse(await readFile(path.join(root, rel), 'utf8'));
+ } catch {
+ return null;
+ }
+ };
+ const env = await read('assets/sky.esenv');
+ if (!check(env != null, 'the environment is named in the import but is not on disk')) {
+ return check.failures;
+ }
+ check(env.specular === 'assets/sky_env.png',
+ `the environment points at ${JSON.stringify(env.specular)}`);
+ check(Array.isArray(env.irradiance) && env.irradiance.length === 27,
+ `the irradiance is ${env.irradiance?.length} numbers, not 27`);
+ // Up is blue and down is red, which is the whole point of nine coefficients
+ // rather than one colour. Coefficient 1 is the y band: blue above zero, red below.
+ check(env.irradiance?.[5] > 0.5, `the y band's blue reads ${env.irradiance?.[5]}`);
+ check(env.irradiance?.[3] < -0.5, `the y band's red reads ${env.irradiance?.[3]}`);
+
+ const meta = await read('assets/sky_env.png.meta');
+ check(meta?.importer?.sRGB === false, 'the atlas is marked sRGB, but it stores an encoding');
+ check(meta?.importer?.compress === false, 'the atlas would be block-compressed with its own multiplier');
+ return check.failures;
+}
diff --git a/desktop/scripts/make-env-fixture.mjs b/desktop/scripts/make-env-fixture.mjs
new file mode 100644
index 000000000..49913cb79
--- /dev/null
+++ b/desktop/scripts/make-env-fixture.mjs
@@ -0,0 +1,115 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file Writes the two sources behind the environment render gates, then imports
+ * them through the shipped tools.
+ *
+ * The panorama is generated rather than checked in as a photograph: a gate has to
+ * state what a pixel should be, and only a sky whose halves are two flat colours
+ * lets it. Sky above, ground below, and a bright patch at +Z — the direction a
+ * head-on surface reflects, which is what tells a mirror from a flat term.
+ *
+ * node scripts/make-env-fixture.mjs
+ */
+import { spawnSync } from 'node:child_process';
+import { writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const scenes = path.join(HERE, '..', 'public', 'scenes');
+const cli = path.join(HERE, '..', '..', 'pipeline', 'bin', 'estella.mjs');
+
+const W = 64;
+const H = 32;
+
+/** Radiance RGBE, flat encoding. The run marker is (1,1,1,n), so no pixel here
+ * may encode to that — none does: every colour below has a zero channel. */
+function radianceHdr(pixel) {
+ const header = Buffer.from(`#?RADIANCE\nFORMAT=32-bit_rle_rgbe\n\n-Y ${H} +X ${W}\n`);
+ const body = Buffer.alloc(W * H * 4);
+ for (let y = 0; y < H; y++) {
+ for (let x = 0; x < W; x++) {
+ const [r, g, b] = pixel(x, y);
+ const peak = Math.max(r, g, b);
+ let e = 0;
+ let scale = 0;
+ if (peak > 1e-9) {
+ e = Math.ceil(Math.log2(peak)) + 128;
+ scale = 256 / Math.pow(2, e - 128);
+ }
+ const at = (y * W + x) * 4;
+ body[at] = Math.min(255, Math.floor(r * scale));
+ body[at + 1] = Math.min(255, Math.floor(g * scale));
+ body[at + 2] = Math.min(255, Math.floor(b * scale));
+ body[at + 3] = e;
+ }
+ }
+ return Buffer.concat([header, body]);
+}
+
+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];
+ return y < H / 2 ? [0, 0, 0.6] : [0.6, 0, 0];
+}));
+
+// Two coplanar triangles facing the camera, one white colour, NORMALS pointing up
+// and down. Only a shader reading an environment by direction can tell the halves
+// apart — a flat ambient term draws them identically.
+const positions = new Float32Array([
+ -200, -100, 0, -40, -100, 0, -120, 100, 0,
+ 40, -100, 0, 200, -100, 0, 120, 100, 0,
+]);
+const normals = new Float32Array([
+ 0, 1, 0, 0, 1, 0, 0, 1, 0,
+ 0, -1, 0, 0, -1, 0, 0, -1, 0,
+]);
+const colors = new Float32Array(24).fill(1);
+const indices = new Uint16Array([0, 1, 2, 3, 4, 5]);
+const buffer = Buffer.concat([positions, normals, colors, indices].map(
+ (a) => Buffer.from(a.buffer, a.byteOffset, a.byteLength)));
+
+writeFileSync(path.join(scenes, 'env-triangles.gltf'), `${JSON.stringify({
+ asset: { version: '2.0', generator: 'estella test fixture' },
+ buffers: [{
+ byteLength: buffer.byteLength,
+ uri: `data:application/octet-stream;base64,${buffer.toString('base64')}`,
+ }],
+ bufferViews: [
+ { buffer: 0, byteOffset: 0, byteLength: positions.byteLength },
+ { buffer: 0, byteOffset: 72, byteLength: normals.byteLength },
+ { buffer: 0, byteOffset: 144, byteLength: colors.byteLength },
+ { buffer: 0, byteOffset: 240, byteLength: indices.byteLength },
+ ],
+ accessors: [
+ { bufferView: 0, componentType: 5126, count: 6, type: 'VEC3',
+ min: [-200, -100, 0], max: [200, 100, 0] },
+ { bufferView: 1, componentType: 5126, count: 6, type: 'VEC3' },
+ { bufferView: 2, componentType: 5126, count: 6, type: 'VEC4' },
+ { bufferView: 3, componentType: 5123, count: 6, type: 'SCALAR' },
+ ],
+ meshes: [{
+ name: 'EnvTriangles',
+ primitives: [{ attributes: { POSITION: 0, NORMAL: 1, COLOR_0: 2 }, indices: 3, mode: 4 }],
+ }],
+ nodes: [{ mesh: 0 }],
+ scenes: [{ nodes: [0] }],
+ scene: 0,
+}, null, 1)}\n`);
+
+for (const [command, source, ...extra] of [
+ ['import-gltf', 'env-triangles.gltf'],
+ // A small face keeps the checked-in atlas small; the gate probes flat regions,
+ // where the prefilter's resolution is not what it is measuring.
+ ['import-hdr', 'studio.hdr', '--face-size', '32'],
+]) {
+ const run = spawnSync(process.execPath,
+ [cli, command, path.join(scenes, source), '--project', path.join(HERE, '..', 'public'),
+ ...extra], {
+ stdio: 'inherit',
+ cwd: path.join(HERE, '..', '..'),
+ });
+ if (run.status !== 0) process.exit(run.status ?? 1);
+}
diff --git a/desktop/src/engine/AssetBinding.ts b/desktop/src/engine/AssetBinding.ts
index 174b39688..87a844c5e 100644
--- a/desktop/src/engine/AssetBinding.ts
+++ b/desktop/src/engine/AssetBinding.ts
@@ -20,11 +20,12 @@ export interface PreloadHandles {
materialHandles: Map<string, number>;
fontHandles: Map<string, number>;
meshHandles: Map<string, number>;
+ environmentHandles: Map<string, number>;
}
const emptyHandles = (): PreloadHandles => ({
textureHandles: new Map(), materialHandles: new Map(),
- fontHandles: new Map(), meshHandles: new Map(),
+ fontHandles: new Map(), meshHandles: new Map(), environmentHandles: new Map(),
});
class AssetBindingImpl {
@@ -120,7 +121,8 @@ class AssetBindingImpl {
if (!this.preload) this.preload = emptyHandles();
const maps = this.preload;
const target = kind === 'material' ? maps.materialHandles
- : kind === 'font' ? maps.fontHandles : maps.meshHandles;
+ : kind === 'font' ? maps.fontHandles
+ : kind === 'environment' ? maps.environmentHandles : maps.meshHandles;
target.set(path, handle);
}
}
diff --git a/desktop/src/project/assetSlots.ts b/desktop/src/project/assetSlots.ts
index 328f42286..3bc2ec83a 100644
--- a/desktop/src/project/assetSlots.ts
+++ b/desktop/src/project/assetSlots.ts
@@ -13,7 +13,7 @@ import type { AssetsData } from 'esengine';
/** Slots whose resolved `{handle}` must be recorded where the incremental resolver
* looks it up — these have no live engine-side cache getter like textures. */
-export type SlotRecord = 'material' | 'font' | 'mesh';
+export type SlotRecord = 'material' | 'font' | 'mesh' | 'environment';
export interface AssetSlotDef {
/** `.meta` type vocabulary values that resolve to this slot. `font` folds both
@@ -35,6 +35,12 @@ export const ASSET_SLOTS: Record<string, AssetSlotDef> = {
// GPU geometry: a handle like a material's, so a mesh assigned after the
// scene-open preload (or re-imported on disk) reaches the World the same way.
mesh: { metaTypes: ['mesh'], load: (a, _ref, path) => a.load('mesh', path), record: 'mesh' },
+ // A baked environment, on the same terms as a mesh: a handle a Light2D holds.
+ environment: {
+ metaTypes: ['environment'],
+ load: (a, _ref, path) => a.load('environment', path),
+ record: 'environment',
+ },
audio: { metaTypes: ['audio'], load: (a, ref) => a.loadAudio(ref) },
// Video streams at runtime (play-mode only) — no edit-mode handle to preload.
video: { metaTypes: ['video'], load: () => Promise.resolve() },
diff --git a/docs/astro/src/data/components.generated.json b/docs/astro/src/data/components.generated.json
index 498218170..eb9a61499 100644
--- a/docs/astro/src/data/components.generated.json
+++ b/docs/astro/src/data/components.generated.json
@@ -1257,6 +1257,12 @@
"range": "≥ 0",
"advanced": true
},
+ {
+ "key": "environment",
+ "type": "Asset<environment>",
+ "default": "none",
+ "doc": "Baked environment (.esenv) this Ambient light casts."
+ },
{
"key": "enabled",
"type": "boolean",
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 93854b323..1e9b6c007 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -5,7 +5,7 @@ Symbols: 113 public · 58 beta · 1418 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
-"9e0ab90e452805c7"
+"65f6ac377586cd75"
```
## ANCHOR_AXES — const @experimental
@@ -629,7 +629,7 @@ type: AssetFieldType
## AssetFieldType — type @public
```
-'texture' | 'material' | 'font' | 'anim-clip' | 'audio' | 'video' | 'tilemap' | 'tileset' | 'timeline' | 'statemachine' | 'behaviortree' | 'animatorcontroller' | 'mesh'
+'texture' | 'material' | 'font' | 'anim-clip' | 'audio' | 'video' | 'tilemap' | 'tileset' | 'timeline' | 'statemachine' | 'behaviortree' | 'animatorcontroller' | 'mesh' | 'environment'
```
## AssetGroupDef — interface @experimental
@@ -3813,6 +3813,7 @@ BuiltinComponentDef<Light2DData>
color: Color
direction: Vec2
enabled: boolean
+environment: number
innerAngle: number
intensity: number
meshShadows: boolean
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 7b242fa5a..42f2e5419 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -5,7 +5,7 @@ Symbols: 113 public · 63 beta · 1437 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
-"9e0ab90e452805c7"
+"65f6ac377586cd75"
```
## ANCHOR_AXES — const @experimental
@@ -629,7 +629,7 @@ type: AssetFieldType
## AssetFieldType — type @public
```
-'texture' | 'material' | 'font' | 'anim-clip' | 'audio' | 'video' | 'tilemap' | 'tileset' | 'timeline' | 'statemachine' | 'behaviortree' | 'animatorcontroller' | 'mesh'
+'texture' | 'material' | 'font' | 'anim-clip' | 'audio' | 'video' | 'tilemap' | 'tileset' | 'timeline' | 'statemachine' | 'behaviortree' | 'animatorcontroller' | 'mesh' | 'environment'
```
## AssetGroupDef — interface @experimental
@@ -3821,6 +3821,7 @@ BuiltinComponentDef<Light2DData>
color: Color
direction: Vec2
enabled: boolean
+environment: number
innerAngle: number
intensity: number
meshShadows: boolean
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 18f623fb8..5da47c16a 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -624,7 +624,7 @@ type: AssetFieldType
## AssetFieldType — type @public
```
-'texture' | 'material' | 'font' | 'anim-clip' | 'audio' | 'video' | 'tilemap' | 'tileset' | 'timeline' | 'statemachine' | 'behaviortree' | 'animatorcontroller' | 'mesh'
+'texture' | 'material' | 'font' | 'anim-clip' | 'audio' | 'video' | 'tilemap' | 'tileset' | 'timeline' | 'statemachine' | 'behaviortree' | 'animatorcontroller' | 'mesh' | 'environment'
```
## AssetGroupDef — interface @experimental
@@ -3808,6 +3808,7 @@ BuiltinComponentDef<Light2DData>
color: Color
direction: Vec2
enabled: boolean
+environment: number
innerAngle: number
intensity: number
meshShadows: boolean
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index f8cadd874..739e6a5b9 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -624,7 +624,7 @@ type: AssetFieldType
## AssetFieldType — type @public
```
-'texture' | 'material' | 'font' | 'anim-clip' | 'audio' | 'video' | 'tilemap' | 'tileset' | 'timeline' | 'statemachine' | 'behaviortree' | 'animatorcontroller' | 'mesh'
+'texture' | 'material' | 'font' | 'anim-clip' | 'audio' | 'video' | 'tilemap' | 'tileset' | 'timeline' | 'statemachine' | 'behaviortree' | 'animatorcontroller' | 'mesh' | 'environment'
```
## AssetGroupDef — interface @experimental
@@ -3808,6 +3808,7 @@ BuiltinComponentDef<Light2DData>
color: Color
direction: Vec2
enabled: boolean
+environment: number
innerAngle: number
intensity: number
meshShadows: boolean
diff --git a/sdk/etc/wasm.api.md b/sdk/etc/wasm.api.md
index a851d7ed7..96e9a9abf 100644
--- a/sdk/etc/wasm.api.md
+++ b/sdk/etc/wasm.api.md
@@ -227,6 +227,8 @@ engine_getCpuScopes: (() => string) | undefined
engine_getGpuScopes: (() => string) | undefined
engine_setCpuProfiling: ((on: boolean) => void) | undefined
engine_setRandomSeed: ((seed: number) => void) | undefined
+environment_create: ((shPtr: number, specularHandle: number, faceSize: number, mipCount: number, maxRange: number) => number) | undefined
+environment_release: ((environmentHandle: number) => void) | undefined
es_getMallocBytes: (() => number) | undefined
esshader_cookInfo: (source: string, featuresCsv: string) => { valid: boolean; error?: string; name: string; domain: string; hasWgslVertex: boolean; hasWgslFragment: boolean; hasSwitches: boolean; vertGlsl: string; fragGlsl: string; textures: Array<{ name: string; unit: number; }>; }
geometry_create: () => number
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 9974755c2..a419488f9 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -624,7 +624,7 @@ type: AssetFieldType
## AssetFieldType — type @public
```
-'texture' | 'material' | 'font' | 'anim-clip' | 'audio' | 'video' | 'tilemap' | 'tileset' | 'timeline' | 'statemachine' | 'behaviortree' | 'animatorcontroller' | 'mesh'
+'texture' | 'material' | 'font' | 'anim-clip' | 'audio' | 'video' | 'tilemap' | 'tileset' | 'timeline' | 'statemachine' | 'behaviortree' | 'animatorcontroller' | 'mesh' | 'environment'
```
## AssetGroupDef — interface @experimental
@@ -3815,6 +3815,7 @@ BuiltinComponentDef<Light2DData>
color: Color
direction: Vec2
enabled: boolean
+environment: number
innerAngle: number
intensity: number
meshShadows: boolean
diff --git a/sdk/src/asset/Assets.ts b/sdk/src/asset/Assets.ts
index 21fe148b3..2f94f564f 100644
--- a/sdk/src/asset/Assets.ts
+++ b/sdk/src/asset/Assets.ts
@@ -22,6 +22,7 @@ import { AssetRefLedger } from './AssetRefLedger';
import { SpineAssetLoader } from './loaders/SpineAssetLoader';
import { MaterialAssetLoader } from './loaders/MaterialAssetLoader';
import { MeshAssetLoader } from './loaders/MeshAssetLoader';
+import { EnvironmentAssetLoader } from './loaders/EnvironmentAssetLoader';
import { FontAssetLoader } from './loaders/FontAssetLoader';
import { AudioAssetLoader } from './loaders/AudioAssetLoader';
import { AnimClipAssetLoader } from './loaders/AnimClipAssetLoader';
@@ -239,6 +240,7 @@ export interface SceneAssetResult {
materialHandles: Map<string, number>;
fontHandles: Map<string, number>;
meshHandles: Map<string, number>;
+ environmentHandles: Map<string, number>;
releaseCallbacks: ReleaseCallback[];
missing: MissingAsset[];
}
@@ -1113,12 +1115,14 @@ export class Assets {
const btPaths = discovered.byType.get('behaviortree') ?? new Set<string>();
const animatorPaths = discovered.byType.get('animatorcontroller') ?? new Set<string>();
const meshPaths = discovered.byType.get('mesh') ?? new Set<string>();
+ const environmentPaths = discovered.byType.get('environment') ?? new Set<string>();
const spinePairs = discovered.spines;
const textureHandles = new Map<string, number>();
const materialHandles = new Map<string, number>();
const fontHandles = new Map<string, number>();
const meshHandles = new Map<string, number>();
+ const environmentHandles = new Map<string, number>();
const releaseCallbacks: ReleaseCallback[] = [];
let loadedCount = 0;
@@ -1179,6 +1183,9 @@ export class Assets {
pushHandleLoad(materialPaths, p => this.loadMaterial(p), materialHandles, 'material');
pushHandleLoad(fontPaths, p => this.loadFont(p), fontHandles, 'font');
pushHandleLoad(meshPaths, p => this.loadTyped<{ handle: number }>('mesh', p), meshHandles, 'mesh');
+ pushHandleLoad(environmentPaths,
+ p => this.loadTyped<{ handle: number }>('environment', p),
+ environmentHandles, 'environment');
// The runtime scene loader owns spine as a two-phase load+apply through the
// SpineManager (skeletons must bind to spawned entities); it opts out here so
// spine page textures / virtual-FS writes aren't done twice.
@@ -1212,11 +1219,13 @@ export class Assets {
onProgress?.(++loadedCount, totalCount);
});
- return { textureHandles, materialHandles, fontHandles, meshHandles, releaseCallbacks, missing };
+ return { textureHandles, materialHandles, fontHandles, meshHandles, environmentHandles,
+ releaseCallbacks, missing };
}
resolveSceneAssetPaths(sceneData: SceneData, result: SceneAssetResult): void {
- const { textureHandles, materialHandles, fontHandles, meshHandles } = result;
+ const { textureHandles, materialHandles, fontHandles, meshHandles,
+ environmentHandles } = result;
const counter = this.refCounter_;
for (const entity of sceneData.entities) {
@@ -1290,6 +1299,10 @@ export class Assets {
comp.data[field] = meshHandles.get(path) ?? 0;
break;
}
+ case 'environment': {
+ comp.data[field] = environmentHandles.get(path) ?? 0;
+ break;
+ }
}
}
}
@@ -1689,6 +1702,7 @@ export class Assets {
this.register(this.materialLoader_);
this.register(new FontAssetLoader());
this.register(new MeshAssetLoader(() => this.module_));
+ this.register(new EnvironmentAssetLoader(() => this.module_));
// The audio loader needs the AudioAPI outside load() too (unload /
// invalidate have no LoadContext), so it shares Assets' lazy accessor.
this.register(new AudioAssetLoader(() => this.getAudio_()));
diff --git a/sdk/src/asset/loaders/EnvironmentAssetLoader.ts b/sdk/src/asset/loaders/EnvironmentAssetLoader.ts
new file mode 100644
index 000000000..748decf49
--- /dev/null
+++ b/sdk/src/asset/loaders/EnvironmentAssetLoader.ts
@@ -0,0 +1,92 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+import type { AssetLoader, LoadContext } from '../AssetLoader';
+import type { ESEngineModule } from '../../wasm';
+import { withScratch } from '../../wasm/wasmScratch';
+import { log } from '../../util/logger';
+
+/** The `.esenv` document, as the importer wrote it. */
+interface EnvironmentAssetData {
+ version: number;
+ irradiance: number[];
+ /** Project path of the prefiltered octahedral atlas. */
+ specular?: string;
+ faceSize?: number;
+ mipCount?: number;
+ maxRange?: number;
+}
+
+/** A baked environment, named by the handle a Light2D references. */
+export interface EnvironmentResult {
+ handle: number;
+ /** The atlas path, so unload releases the texture ref this load took. */
+ specularPath?: string;
+}
+
+/**
+ * Loads `.esenv` — an environment's irradiance and its prefiltered reflection.
+ *
+ * The reflection is an ordinary texture asset, loaded through the same door as
+ * any other: the environment holds a ref to it while it lives, and gives it back
+ * on unload. Only the nine coefficients are the environment's own.
+ */
+export class EnvironmentAssetLoader implements AssetLoader<EnvironmentResult> {
+ readonly type = 'environment';
+ readonly extensions = ['.esenv'];
+
+ /** Lazy like the mesh loader's: the module arrives after construction. */
+ constructor(private readonly module_: () => ESEngineModule | null) {}
+
+ async load(path: string, ctx: LoadContext): Promise<EnvironmentResult> {
+ const text = await ctx.loadText(ctx.catalog.getBuildPath(path));
+ const data = JSON.parse(text) as EnvironmentAssetData;
+ if (!Array.isArray(data.irradiance) || data.irradiance.length !== 27) {
+ throw new Error(`${path}: an environment is nine RGB coefficients, got `
+ + `${data.irradiance?.length ?? 0} numbers`);
+ }
+ const m = this.module_();
+ if (!m?.environment_create) {
+ throw new Error('this engine build carries no environment_create');
+ }
+
+ // A missing atlas leaves the environment diffuse-only rather than failing
+ // the load: nine coefficients still light the scene, and a reflection that
+ // silently took the whole asset down would be the worse answer.
+ let specularHandle = 0;
+ let specularPath: string | undefined;
+ if (data.specular) {
+ const resolved = resolvePath(path, data.specular);
+ try {
+ specularHandle = (await ctx.loadTexture(resolved)).handle;
+ specularPath = resolved;
+ } catch (e) {
+ log.warn('asset', `${path}: no reflection atlas at '${resolved}'`, e);
+ }
+ }
+
+ const handle = withScratch(m, (alloc) => {
+ const shPtr = alloc(27 * 4);
+ m.HEAPF32.set(Float32Array.from(data.irradiance), shPtr >> 2);
+ return m.environment_create!(shPtr, specularHandle, data.faceSize ?? 0,
+ data.mipCount ?? 0, data.maxRange ?? 0);
+ });
+
+ if (!handle) {
+ if (specularPath) ctx.releaseTexture(specularPath);
+ throw new Error(`the engine rejected the environment in ${path}`);
+ }
+ return { handle, specularPath };
+ }
+
+ unload(asset: EnvironmentResult, ctx: LoadContext): void {
+ this.module_()?.environment_release?.(asset.handle);
+ if (asset.specularPath) ctx.releaseTexture(asset.specularPath);
+ }
+}
+
+/** Resolve the atlas ref relative to the `.esenv`; rooted refs pass through. */
+function resolvePath(fromPath: string, ref: string): string {
+ if (ref.startsWith('/') || ref.startsWith('http') || ref.startsWith('assets/')) return ref;
+ const dir = fromPath.substring(0, fromPath.lastIndexOf('/'));
+ return dir ? `${dir}/${ref}` : ref;
+}
diff --git a/sdk/src/ecs/bridge/nativeEngineApi.generated.ts b/sdk/src/ecs/bridge/nativeEngineApi.generated.ts
index 28ac7d1b2..69b644a6c 100644
--- a/sdk/src/ecs/bridge/nativeEngineApi.generated.ts
+++ b/sdk/src/ecs/bridge/nativeEngineApi.generated.ts
@@ -46,6 +46,8 @@ export interface NativeEngineApi {
engine_getGpuScopes?(): string;
engine_setCpuProfiling?(on: boolean): void;
engine_setRandomSeed?(seed: number): void;
+ environment_create?(shPtr: number, specularHandle: number, faceSize: number, mipCount: number, maxRange: number): number;
+ environment_release?(environmentHandle: number): void;
geometry_create?(): number;
geometry_init?(handle: number, verticesPtr: number, vertexCount: number, layoutPtr: number, layoutCount: number, dynamic: boolean): void;
geometry_isValid?(handle: number): boolean;
@@ -296,6 +298,8 @@ export function createNativeEngineApi(
bind('engine_getGpuScopes', 'es_engine_getGpuScopes', false);
bind('engine_setCpuProfiling', 'es_engine_setCpuProfiling', false);
bind('engine_setRandomSeed', 'es_engine_setRandomSeed', false);
+ bind('environment_create', 'es_environment_create', false);
+ bind('environment_release', 'es_environment_release', false);
bind('geometry_create', 'es_geometry_create', false);
bind('geometry_init', 'es_geometry_init', false);
bind('geometry_isValid', 'es_geometry_isValid', false);
diff --git a/sdk/src/ecs/bridge/ptrAccessors.generated.ts b/sdk/src/ecs/bridge/ptrAccessors.generated.ts
index 95f5f4e97..41930b457 100644
--- a/sdk/src/ecs/bridge/ptrAccessors.generated.ts
+++ b/sdk/src/ecs/bridge/ptrAccessors.generated.ts
@@ -501,6 +501,7 @@ export interface Light2DPtrData {
shadowDistance: number;
meshShadows: boolean;
shadowExtent: number;
+ environment: number;
enabled: boolean;
}
@@ -519,7 +520,8 @@ export function fillLight2D(
out.shadowDistance = f32[(ptr + 48) >> 2];
out.meshShadows = u8[ptr + 52] !== 0;
out.shadowExtent = f32[(ptr + 56) >> 2];
- out.enabled = u8[ptr + 60] !== 0;
+ out.environment = u32[(ptr + 60) >> 2];
+ out.enabled = u8[ptr + 64] !== 0;
}
export function writeLight2D(
@@ -537,7 +539,8 @@ export function writeLight2D(
f32[(ptr + 48) >> 2] = data.shadowDistance;
u8[ptr + 52] = data.meshShadows ? 1 : 0;
f32[(ptr + 56) >> 2] = data.shadowExtent;
- u8[ptr + 60] = data.enabled ? 1 : 0;
+ u32[(ptr + 60) >> 2] = data.environment;
+ u8[ptr + 64] = data.enabled ? 1 : 0;
}
export function createLight2DData(): Light2DPtrData {
@@ -553,6 +556,7 @@ export function createLight2DData(): Light2DPtrData {
shadowDistance: 0,
meshShadows: false,
shadowExtent: 0,
+ environment: 0,
enabled: false,
};
}
diff --git a/sdk/src/ecs/component.generated.ts b/sdk/src/ecs/component.generated.ts
index 873a3b2a2..1e0dfd42c 100644
--- a/sdk/src/ecs/component.generated.ts
+++ b/sdk/src/ecs/component.generated.ts
@@ -15,7 +15,7 @@ import type { Dimension, Padding } from '../wasm/wasm.generated';
* getAbiLayoutHash(); BuiltinBridge.connect() compares them and refuses to
* run on mismatch, because mismatched offsets read the wrong heap bytes.
*/
-export const ABI_LAYOUT_HASH = '9e0ab90e452805c7';
+export const ABI_LAYOUT_HASH = '65f6ac377586cd75';
/**
* One asset-valued field of a component: which field, and what kind of
@@ -310,10 +310,11 @@ export const COMPONENT_META: Record<string, ComponentMetaEntry> = {
shadowDistance: 0,
meshShadows: false,
shadowExtent: 0,
+ environment: 0,
enabled: true,
},
renderableField: 'enabled',
- assetFields: [],
+ assetFields: [{ field: 'environment', type: 'environment' as AssetFieldType }],
entityFields: [],
colorFields: ['color'],
animatableFields: ['color.r', 'color.g', 'color.b', 'color.a', 'intensity', 'radius', 'innerAngle', 'outerAngle', 'shadowSoftness', 'shadowDistance'],
@@ -328,6 +329,7 @@ export const COMPONENT_META: Record<string, ComponentMetaEntry> = {
shadowDistance: { min: 0, tooltip: "Directional shadow distance; 0 = no directional shadow.", advanced: true },
meshShadows: { tooltip: "Cast a shadow map over 3D meshes (Directional)." },
shadowExtent: { min: 0, tooltip: "Shadow map coverage radius; 0 = fit the view.", advanced: true },
+ environment: { tooltip: "Baked environment (.esenv) this Ambient light casts." },
},
},
Mesh2D: {
@@ -1016,6 +1018,7 @@ export interface Light2DData {
shadowDistance: number;
meshShadows: boolean;
shadowExtent: number;
+ environment: number;
enabled: boolean;
}
diff --git a/sdk/src/scene/scene.ts b/sdk/src/scene/scene.ts
index 7ad6c2c74..ca0043500 100644
--- a/sdk/src/scene/scene.ts
+++ b/sdk/src/scene/scene.ts
@@ -122,7 +122,7 @@ export class MissingAssetsError extends Error {
*
* @public
*/
-export type AssetFieldType = 'texture' | 'material' | 'font' | 'anim-clip' | 'audio' | 'video' | 'tilemap' | 'tileset' | 'timeline' | 'statemachine' | 'behaviortree' | 'animatorcontroller' | 'mesh';
+export type AssetFieldType = 'texture' | 'material' | 'font' | 'anim-clip' | 'audio' | 'video' | 'tilemap' | 'tileset' | 'timeline' | 'statemachine' | 'behaviortree' | 'animatorcontroller' | 'mesh' | 'environment';
// =============================================================================
// Component Query Helpers (read from self-describing ComponentDef)
diff --git a/sdk/src/wasm.ts b/sdk/src/wasm.ts
index ecb7c075c..80ef7f990 100644
--- a/sdk/src/wasm.ts
+++ b/sdk/src/wasm.ts
@@ -246,6 +246,15 @@ export interface ESEngineModule {
bindPtr: number, bindFloats: number): number;
/** Release a mesh and the buffers it owns. */
mesh_release?(meshHandle: number): void;
+ /**
+ * Register a baked environment: 27 floats of irradiance (nine RGB spherical-
+ * harmonic coefficients, already convolved and over pi) plus the prefiltered
+ * octahedral atlas an ambient light reflects. A 0 atlas is diffuse-only.
+ */
+ environment_create?(shPtr: number, specularHandle: number, faceSize: number,
+ mipCount: number, maxRange: number): number;
+ /** Release an environment; its atlas is an ordinary texture and outlives it. */
+ environment_release?(environmentHandle: number): void;
/** Point a Mesh2D at a resident mesh; 0 returns it to its inline payload. */
mesh2d_setMesh?(registry: CppRegistry, entity: number, meshHandle: number): void;
/**
diff --git a/sdk/src/wasm/ptrLayouts.generated.ts b/sdk/src/wasm/ptrLayouts.generated.ts
index 7b9be5a24..dc9ffd00d 100644
--- a/sdk/src/wasm/ptrLayouts.generated.ts
+++ b/sdk/src/wasm/ptrLayouts.generated.ts
@@ -161,7 +161,8 @@ export const PTR_LAYOUTS: Record<string, PtrLayout> = {
{ name: 'shadowDistance', type: 'f32', offset: 48 },
{ name: 'meshShadows', type: 'bool', offset: 52 },
{ name: 'shadowExtent', type: 'f32', offset: 56 },
- { name: 'enabled', type: 'bool', offset: 60 },
+ { name: 'environment', type: 'u32', offset: 60 },
+ { name: 'enabled', type: 'bool', offset: 64 },
],
},
Mesh2D: {
diff --git a/sdk/src/wasm/wasm.generated.ts b/sdk/src/wasm/wasm.generated.ts
index 4c4bb5951..815cdb332 100644
--- a/sdk/src/wasm/wasm.generated.ts
+++ b/sdk/src/wasm/wasm.generated.ts
@@ -341,6 +341,7 @@ export interface Light2D {
shadowDistance: number;
meshShadows: boolean;
shadowExtent: number;
+ environment: number;
enabled: boolean;
}
diff --git a/src/esengine/bindings/EditorAPI.generated.cpp b/src/esengine/bindings/EditorAPI.generated.cpp
index ed11c99f7..448c50b97 100644
--- a/src/esengine/bindings/EditorAPI.generated.cpp
+++ b/src/esengine/bindings/EditorAPI.generated.cpp
@@ -2,10 +2,10 @@
* @file EditorAPI.generated.cpp
* @brief Auto-generated editor API with string-dispatched component access
* @details Generated by EHT - DO NOT EDIT
- * @schema_hash ae111705aaf429d7
+ * @schema_hash 535f4ea75f733a04
*/
-#define ES_EDITOR_API_SCHEMA_HASH "ae111705aaf429d7"
+#define ES_EDITOR_API_SCHEMA_HASH "535f4ea75f733a04"
#include <emscripten/bind.h>
#include <string>
@@ -244,6 +244,7 @@ std::string editor_getComponentSchema(const std::string& name) {
{"key":"shadowDistance","type":"float","group":"Light2D"},
{"key":"meshShadows","type":"bool","group":"Light2D"},
{"key":"shadowExtent","type":"float","group":"Light2D"},
+ {"key":"environment","type":"asset","group":"Light2D"},
{"key":"enabled","type":"bool","group":"Light2D"}
])JSON";
} else if (name == "Mesh2D") {
@@ -1676,6 +1677,7 @@ bool editor_setInt(Registry& reg, u32 e, const std::string& comp, const std::str
if (!reg.has<esengine::ecs::Light2D>(entity)) return false;
auto& c = reg.get<esengine::ecs::Light2D>(entity);
if (field == "type") { c.type = static_cast<i32>(value); }
+ else if (field == "environment") { c.environment = resource::EnvironmentHandle(static_cast<u32>(value)); }
else { return false; }
return true;
} else if (comp == "Mesh2D") {
@@ -1866,6 +1868,7 @@ i32 editor_getInt(Registry& reg, u32 e, const std::string& comp, const std::stri
if (!reg.has<esengine::ecs::Light2D>(entity)) return 0;
const auto& c = reg.get<esengine::ecs::Light2D>(entity);
if (field == "type") { return static_cast<i32>(c.type); }
+ else if (field == "environment") { return static_cast<i32>(c.environment.id()); }
} else if (comp == "Mesh2D") {
if (!reg.has<esengine::ecs::Mesh2D>(entity)) return 0;
const auto& c = reg.get<esengine::ecs::Mesh2D>(entity);
diff --git a/src/esengine/bindings/RendererBindings.cpp b/src/esengine/bindings/RendererBindings.cpp
index 19298a34a..76e926afd 100644
--- a/src/esengine/bindings/RendererBindings.cpp
+++ b/src/esengine/bindings/RendererBindings.cpp
@@ -330,6 +330,30 @@ void mesh_release(u32 meshHandle) {
}
}
+/**
+ * @brief Registers a baked environment: nine irradiance coefficients and the
+ * prefiltered reflection an ambient light casts.
+ * @param shPtr 27 floats — nine RGB coefficients, already convolved and over pi.
+ * @param specularHandle The octahedral atlas, or 0 for a diffuse-only environment.
+ */
+u32 environment_create(uintptr_t shPtr, u32 specularHandle, f32 faceSize, u32 mipCount,
+ f32 maxRange) {
+ auto* rm = ctx().tryGet<resource::ResourceManager>();
+ if (!rm) return 0;
+ const f32* sh = boundarySpan<f32>(shPtr, 27, "environment_create.irradiance");
+ if (!sh) return 0;
+ return rm->createEnvironment(ConstSpan<f32>(sh, 27),
+ resource::TextureHandle(specularHandle),
+ faceSize, mipCount, maxRange).id();
+}
+
+/** @brief Releases an environment. Its atlas is an ordinary texture and outlives it. */
+void environment_release(u32 environmentHandle) {
+ if (auto* rm = ctx().tryGet<resource::ResourceManager>()) {
+ rm->releaseEnvironment(resource::EnvironmentHandle(environmentHandle));
+ }
+}
+
namespace {
// Freezes a Mesh2D's inline geometry onto the GPU: the same vertices, uploaded
// once and drawn with a per-object transform. The inline payload is cleared, so
diff --git a/src/esengine/bindings/RendererBindings.hpp b/src/esengine/bindings/RendererBindings.hpp
index d237ae1b0..85fa80c4d 100644
--- a/src/esengine/bindings/RendererBindings.hpp
+++ b/src/esengine/bindings/RendererBindings.hpp
@@ -78,6 +78,13 @@ u32 mesh_createFromChannels(uintptr_t channelsPtr, u32 channelCount, u32 vertexS
uintptr_t bindPtr, u32 bindFloats);
/** @brief Releases a mesh and the buffers it owns. */
void mesh_release(u32 meshHandle);
+
+/** @brief Registers a baked environment (27 irradiance floats + a reflection atlas). */
+u32 environment_create(uintptr_t shPtr, u32 specularHandle, f32 faceSize, u32 mipCount,
+ f32 maxRange);
+
+/** @brief Releases an environment; its atlas is an ordinary texture and outlives it. */
+void environment_release(u32 environmentHandle);
/** @brief Uploads geometry that stays on the GPU; returns its handle, 0 on failure. */
u32 mesh_create(uintptr_t posUvPtr, u32 vertexCount, uintptr_t colorsPtr,
uintptr_t indicesPtr, u32 indexCount);
diff --git a/src/esengine/bindings/WebBindings.generated.cpp b/src/esengine/bindings/WebBindings.generated.cpp
index 6e9fbdf1c..bf654d833 100644
--- a/src/esengine/bindings/WebBindings.generated.cpp
+++ b/src/esengine/bindings/WebBindings.generated.cpp
@@ -438,6 +438,62 @@ FlexContainerJS flexcontainerToJS(const esengine::ecs::FlexContainer& c) {
return js;
}
+struct Light2DJS {
+ i32 type;
+ glm::vec4 color;
+ f32 intensity;
+ f32 radius;
+ glm::vec2 direction;
+ f32 innerAngle;
+ f32 outerAngle;
+ f32 shadowSoftness;
+ f32 shadowDistance;
+ bool meshShadows;
+ f32 shadowExtent;
+ u32 environment;
+ bool enabled;
+};
+
+void light2dApplyJS(esengine::ecs::Light2D& c, const Light2DJS& js) {
+ c.type = js.type;
+ c.color = js.color;
+ c.intensity = js.intensity;
+ c.radius = js.radius;
+ c.direction = js.direction;
+ c.innerAngle = js.innerAngle;
+ c.outerAngle = js.outerAngle;
+ c.shadowSoftness = js.shadowSoftness;
+ c.shadowDistance = js.shadowDistance;
+ c.meshShadows = js.meshShadows;
+ c.shadowExtent = js.shadowExtent;
+ c.environment = resource::EnvironmentHandle(js.environment);
+ c.enabled = js.enabled;
+}
+
+esengine::ecs::Light2D light2dFromJS(const Light2DJS& js) {
+ esengine::ecs::Light2D c;
+ light2dApplyJS(c, js);
+ return c;
+}
+
+Light2DJS light2dToJS(const esengine::ecs::Light2D& c) {
+ Light2DJS js;
+ js.type = c.type;
+ js.color = c.color;
+ js.intensity = c.intensity;
+ js.radius = c.radius;
+ js.direction = c.direction;
+ js.innerAngle = c.innerAngle;
+ js.outerAngle = c.outerAngle;
+ js.shadowSoftness = c.shadowSoftness;
+ js.shadowDistance = c.shadowDistance;
+ js.meshShadows = c.meshShadows;
+ js.shadowExtent = c.shadowExtent;
+ js.environment = c.environment.id();
+ js.enabled = c.enabled;
+ return js;
+}
+
struct Mesh2DJS {
u32 texture;
u32 normalMap;
@@ -1230,19 +1286,20 @@ EMSCRIPTEN_BINDINGS(esengine_components) {
.field("blockRaycast", &esengine::ecs::Interactable::blockRaycast)
.field("raycastTarget", &esengine::ecs::Interactable::raycastTarget);
- value_object<esengine::ecs::Light2D>("Light2D")
- .field("type", &esengine::ecs::Light2D::type)
- .field("color", &esengine::ecs::Light2D::color)
- .field("intensity", &esengine::ecs::Light2D::intensity)
- .field("radius", &esengine::ecs::Light2D::radius)
- .field("direction", &esengine::ecs::Light2D::direction)
- .field("innerAngle", &esengine::ecs::Light2D::innerAngle)
- .field("outerAngle", &esengine::ecs::Light2D::outerAngle)
- .field("shadowSoftness", &esengine::ecs::Light2D::shadowSoftness)
- .field("shadowDistance", &esengine::ecs::Light2D::shadowDistance)
- .field("meshShadows", &esengine::ecs::Light2D::meshShadows)
- .field("shadowExtent", &esengine::ecs::Light2D::shadowExtent)
- .field("enabled", &esengine::ecs::Light2D::enabled);
+ value_object<Light2DJS>("Light2D")
+ .field("type", &Light2DJS::type)
+ .field("color", &Light2DJS::color)
+ .field("intensity", &Light2DJS::intensity)
+ .field("radius", &Light2DJS::radius)
+ .field("direction", &Light2DJS::direction)
+ .field("innerAngle", &Light2DJS::innerAngle)
+ .field("outerAngle", &Light2DJS::outerAngle)
+ .field("shadowSoftness", &Light2DJS::shadowSoftness)
+ .field("shadowDistance", &Light2DJS::shadowDistance)
+ .field("meshShadows", &Light2DJS::meshShadows)
+ .field("shadowExtent", &Light2DJS::shadowExtent)
+ .field("environment", &Light2DJS::environment)
+ .field("enabled", &Light2DJS::enabled);
value_object<Mesh2DJS>("Mesh2D")
.field("texture", &Mesh2DJS::texture)
@@ -1748,16 +1805,19 @@ EMSCRIPTEN_BINDINGS(esengine_registry) {
.function("hasLight2D", optional_override([](Registry& r, u32 e) {
return r.has<esengine::ecs::Light2D>(static_cast<Entity>(e));
}))
- .function("getLight2D", optional_override([](Registry& r, u32 e) -> esengine::ecs::Light2D& {
+ .function("getLight2D", optional_override([](Registry& r, u32 e) {
auto entity = static_cast<Entity>(e);
- static esengine::ecs::Light2D s_dummy{};
- if (!r.valid(entity) || !r.has<esengine::ecs::Light2D>(entity)) return s_dummy;
- return r.get<esengine::ecs::Light2D>(entity);
- }), allow_raw_pointers())
- .function("addLight2D", optional_override([](Registry& r, u32 e, const esengine::ecs::Light2D& c) {
+ if (!r.valid(entity) || !r.has<esengine::ecs::Light2D>(entity)) return Light2DJS{};
+ return light2dToJS(r.get<esengine::ecs::Light2D>(entity));
+ }))
+ .function("addLight2D", optional_override([](Registry& r, u32 e, const Light2DJS& js) {
auto entity = static_cast<Entity>(e);
if (!r.valid(entity)) return;
- r.emplaceOrReplace<esengine::ecs::Light2D>(entity, c);
+ if (auto* existing = r.tryGet<esengine::ecs::Light2D>(entity)) {
+ light2dApplyJS(*existing, js);
+ return;
+ }
+ r.emplaceOrReplace<esengine::ecs::Light2D>(entity, light2dFromJS(js));
}))
.function("removeLight2D", optional_override([](Registry& r, u32 e) {
auto entity = static_cast<Entity>(e);
@@ -2366,7 +2426,8 @@ static_assert(offsetof(esengine::ecs::Light2D, shadowSoftness) == 44, "ABI offse
static_assert(offsetof(esengine::ecs::Light2D, shadowDistance) == 48, "ABI offset drift: esengine::ecs::Light2D.shadowDistance (EHT expected 48)");
static_assert(offsetof(esengine::ecs::Light2D, meshShadows) == 52, "ABI offset drift: esengine::ecs::Light2D.meshShadows (EHT expected 52)");
static_assert(offsetof(esengine::ecs::Light2D, shadowExtent) == 56, "ABI offset drift: esengine::ecs::Light2D.shadowExtent (EHT expected 56)");
-static_assert(offsetof(esengine::ecs::Light2D, enabled) == 60, "ABI offset drift: esengine::ecs::Light2D.enabled (EHT expected 60)");
+static_assert(offsetof(esengine::ecs::Light2D, environment) == 60, "ABI offset drift: esengine::ecs::Light2D.environment (EHT expected 60)");
+static_assert(offsetof(esengine::ecs::Light2D, enabled) == 64, "ABI offset drift: esengine::ecs::Light2D.enabled (EHT expected 64)");
static_assert(offsetof(esengine::ecs::Mesh2D, texture) == 0, "ABI offset drift: esengine::ecs::Mesh2D.texture (EHT expected 0)");
static_assert(offsetof(esengine::ecs::Mesh2D, normalMap) == 4, "ABI offset drift: esengine::ecs::Mesh2D.normalMap (EHT expected 4)");
static_assert(offsetof(esengine::ecs::Mesh2D, color) == 8, "ABI offset drift: esengine::ecs::Mesh2D.color (EHT expected 8)");
@@ -2581,7 +2642,7 @@ static_assert(offsetof(esengine::ecs::Velocity, angular) == 12, "ABI offset drif
// ABI Hash -- runtime handshake against the SDK bundle
// =============================================================================
-static const char* kEsAbiLayoutHash = "9e0ab90e452805c7";
+static const char* kEsAbiLayoutHash = "65f6ac377586cd75";
std::string esengineGetAbiLayoutHash() {
return std::string(kEsAbiLayoutHash);
diff --git a/src/esengine/bindings/WebSDKEntry.cpp b/src/esengine/bindings/WebSDKEntry.cpp
index 4169099c6..ead84c1ec 100644
--- a/src/esengine/bindings/WebSDKEntry.cpp
+++ b/src/esengine/bindings/WebSDKEntry.cpp
@@ -526,6 +526,8 @@ EMSCRIPTEN_BINDINGS(esengine_renderer) {
emscripten::function("mesh_create", &esengine::mesh_create);
emscripten::function("mesh_createFromChannels", &esengine::mesh_createFromChannels);
emscripten::function("mesh_release", &esengine::mesh_release);
+ emscripten::function("environment_create", &esengine::environment_create);
+ emscripten::function("environment_release", &esengine::environment_release);
emscripten::function("mesh2d_setMesh", &esengine::mesh2d_setMesh);
emscripten::function("mesh2d_localBounds", &esengine::mesh2d_localBounds);
emscripten::function("mesh2d_makeResident", &esengine::mesh2d_makeResident);
diff --git a/src/esengine/ecs/components/Light2D.hpp b/src/esengine/ecs/components/Light2D.hpp
index 4eb20c7f6..805524d31 100644
--- a/src/esengine/ecs/components/Light2D.hpp
+++ b/src/esengine/ecs/components/Light2D.hpp
@@ -22,6 +22,7 @@
#include "../../core/Types.hpp"
#include "../../core/Reflection.hpp"
#include "../../math/Math.hpp"
+#include "../../resource/Handle.hpp"
namespace esengine::ecs {
@@ -104,6 +105,14 @@ struct Light2D {
ES_PROPERTY(min=0, advanced, tooltip="Shadow map coverage radius; 0 = fit the view.")
f32 shadowExtent{0.0f};
+ /** @brief What this Ambient light IS, when it is more than one colour: a baked
+ * panorama's irradiance and reflection. Without one the light stays the
+ * flat term it has always been — the same lighting, at order zero.
+ * @ref color and @ref intensity scale it. Ignored by the other types;
+ * the first Ambient light that carries one is the frame's environment. */
+ ES_PROPERTY(asset = environment, tooltip="Baked environment (.esenv) this Ambient light casts.")
+ resource::EnvironmentHandle environment;
+
/** @brief Disabled lights are skipped during collection. */
ES_PROPERTY()
bool enabled{true};
diff --git a/src/esengine/renderer/RenderTypePlugin.hpp b/src/esengine/renderer/RenderTypePlugin.hpp
index 5d2c10974..bcdbf667b 100644
--- a/src/esengine/renderer/RenderTypePlugin.hpp
+++ b/src/esengine/renderer/RenderTypePlugin.hpp
@@ -37,6 +37,8 @@ struct RenderFrameContext {
bool shadow_pass = false;
/// The map that pass produced, handed to the meshes that receive it (0 = none).
u32 shadow_texture_id = 0;
+ /// The frame environment's prefiltered reflection atlas (0 = none this frame).
+ u32 environment_texture_id = 0;
};
/** @brief The camera's view bounds in world space, derived once per collect from the
diff --git a/src/esengine/renderer/draw/BatchBuilder.cpp b/src/esengine/renderer/draw/BatchBuilder.cpp
index 59d3f8c00..36b65202a 100644
--- a/src/esengine/renderer/draw/BatchBuilder.cpp
+++ b/src/esengine/renderer/draw/BatchBuilder.cpp
@@ -116,6 +116,12 @@ void pushBatchDraw(DrawList& drawList, const ClipState& clips,
cmd.texture_ids[2] = key.shadowTextureId;
cmd.texture_count = 3;
}
+ // The reflection atlas is pinned one slot further on, filled the same way.
+ if (key.envTextureId != 0 && cmd.texture_count >= 1 && key.layoutId != LayoutId::Batch) {
+ for (u8 slot = cmd.texture_count; slot < 3; ++slot) cmd.texture_ids[slot] = key.textureId;
+ cmd.texture_ids[3] = key.envTextureId;
+ cmd.texture_count = 4;
+ }
cmd.entity = key.entity;
cmd.type = key.type;
cmd.layer = key.layer;
diff --git a/src/esengine/renderer/draw/BatchBuilder.hpp b/src/esengine/renderer/draw/BatchBuilder.hpp
index bd7eaf6aa..3d3ab73ec 100644
--- a/src/esengine/renderer/draw/BatchBuilder.hpp
+++ b/src/esengine/renderer/draw/BatchBuilder.hpp
@@ -91,6 +91,9 @@ struct BatchDrawKey {
// like the two above rather than a global unit: which draws receive a shadow is a
// question the collect answers, and the device has no "bind for everyone" seam.
u32 shadowTextureId = 0;
+ // The frame environment's prefiltered reflection, one slot further on. Same
+ // terms as the shadow map: per-draw, and only where a mesh vertex source asked.
+ u32 envTextureId = 0;
f32 depth = 0.0f;
// World-space Y of the draw's anchor. Consumed only when the layer is y-sorted
// (DrawList::ySortMask); layers outside 0..31 cannot y-sort.
diff --git a/src/esengine/renderer/frame/RenderFrame.cpp b/src/esengine/renderer/frame/RenderFrame.cpp
index a085c2755..b08c9f113 100644
--- a/src/esengine/renderer/frame/RenderFrame.cpp
+++ b/src/esengine/renderer/frame/RenderFrame.cpp
@@ -631,7 +631,8 @@ RenderFrameContext RenderFrame::makeContext() {
&context_.materials(),
this,
false,
- shadow_texture_id_
+ shadow_texture_id_,
+ environment_texture_id_
};
}
@@ -639,6 +640,7 @@ void RenderFrame::collectLights(ecs::Registry& registry) {
LightStore& lights = context_.lights();
lights.clear();
shadow_light_slot_ = -1;
+ environment_texture_id_ = 0;
// Gather non-ambient lights, then (if over the UBO's cap) keep the most intense — the
// brightest contribute most, and an explicit importance cull beats silently dropping
@@ -660,6 +662,10 @@ void RenderFrame::collectLights(ecs::Registry& registry) {
const glm::vec3 rgb = linear_color_ ? srgbToLinearCpu(glm::vec3{light.color})
: glm::vec3{light.color};
if (type == ecs::Light2DType::Ambient) {
+ // An environment REPLACES this light's flat term rather than adding to
+ // it: its coefficients already carry the same colour, and summing both
+ // would light the scene twice from one source.
+ if (collectEnvironment(light, rgb * light.intensity)) continue;
lights.addAmbient(rgb * light.intensity);
continue;
}
@@ -730,6 +736,27 @@ void RenderFrame::collectLights(ecs::Registry& registry) {
}
}
+bool RenderFrame::collectEnvironment(const ecs::Light2D& light, const glm::vec3& scale) {
+ if (!light.environment.isValid()) return false;
+ const Environment* environment = resource_manager_.getEnvironment(light.environment);
+ if (!environment) return false;
+
+ u32 textureId = 0;
+ if (environment->hasSpecular()) {
+ if (Texture* atlas = resource_manager_.getTexture(environment->specular)) {
+ textureId = atlas->getId();
+ }
+ }
+ const glm::vec4 params{textureId != 0 ? 1.0f : 0.0f, environment->maxRange,
+ static_cast<f32>(environment->mipCount) - 1.0f,
+ environment->faceSize};
+ if (!context_.lights().setEnvironment(environment->irradiance.data(), params, scale)) {
+ return false;
+ }
+ environment_texture_id_ = textureId;
+ return true;
+}
+
/// Side length of a shadow map. One size for every scene: the coverage adapts to the
/// camera instead, so the texel density a scene gets is a property of how far it asked
/// the light to reach rather than of a knob nobody can calibrate.
diff --git a/src/esengine/renderer/frame/RenderFrame.hpp b/src/esengine/renderer/frame/RenderFrame.hpp
index 87956420e..38cdfed94 100644
--- a/src/esengine/renderer/frame/RenderFrame.hpp
+++ b/src/esengine/renderer/frame/RenderFrame.hpp
@@ -28,6 +28,8 @@
namespace esengine {
+namespace ecs { struct Light2D; }
+
struct Plane {
glm::vec3 normal;
f32 distance;
@@ -292,6 +294,12 @@ private:
/// (point/directional into the light array, ambient summed). Run each frame in collectAll;
/// flush() uploads + binds the result so Lit2D material shaders read it.
void collectLights(ecs::Registry& registry);
+
+ /// Makes this ambient light the frame's environment, when it names one that is
+ /// loaded. `scale` is the light's colour times its intensity, folded into the
+ /// coefficients — an environment is what the light casts, not a second source.
+ /// @return false when it names none, leaving the caller to add a flat term.
+ bool collectEnvironment(const ecs::Light2D& light, const glm::vec3& scale);
/**
* @brief Draws the scene's mesh occluders from the shadow-casting light, into a map
* the main pass samples.
@@ -315,6 +323,8 @@ private:
RenderTargetManager::Handle shadow_rt_ = 0;
/// The map's colour texture, handed to every mesh that receives it. 0 = none this frame.
u32 shadow_texture_id_ = 0;
+ /// The frame environment's reflection atlas, on the same terms. 0 = none this frame.
+ u32 environment_texture_id_ = 0;
// processMasks scratch, reused across cameras/frames.
std::vector<Entity> mask_scissor_scratch_;
diff --git a/src/esengine/renderer/plugins/MeshPlugin.cpp b/src/esengine/renderer/plugins/MeshPlugin.cpp
index 43d7b23b9..322d85e3c 100644
--- a/src/esengine/renderer/plugins/MeshPlugin.cpp
+++ b/src/esengine/renderer/plugins/MeshPlugin.cpp
@@ -66,9 +66,10 @@ u32 skinPose(ecs::Registry& registry, Entity entity, const Mesh& mesh,
return count;
}
-u32 meshVariant(bool normals, bool lit, bool normalMapped, bool skinned, bool depthOnly) {
+u32 meshVariant(bool normals, bool lit, bool normalMapped, bool skinned, bool depthOnly,
+ bool envMapped) {
return (normals ? 1u : 0u) | (lit ? 2u : 0u) | (normalMapped ? 4u : 0u)
- | (skinned ? 8u : 0u) | (depthOnly ? 16u : 0u);
+ | (skinned ? 8u : 0u) | (depthOnly ? 16u : 0u) | (envMapped ? 32u : 0u);
}
} // namespace
@@ -97,8 +98,8 @@ void MeshPlugin::init(RenderFrameContext& ctx) {
* and unlit geometry carrying normals still has to declare them.
*/
u32 MeshPlugin::meshProgram(RenderFrameContext& ctx, bool normals, bool lit, bool normalMapped,
- bool skinned, bool depthOnly) {
- const u32 variant = meshVariant(normals, lit, normalMapped, skinned, depthOnly);
+ bool skinned, bool depthOnly, bool envMapped) {
+ const u32 variant = meshVariant(normals, lit, normalMapped, skinned, depthOnly, envMapped);
if (mesh_compiled_[variant]) return mesh_programs_[variant];
mesh_compiled_[variant] = true;
@@ -109,8 +110,12 @@ u32 MeshPlugin::meshProgram(RenderFrameContext& ctx, bool normals, bool lit, boo
if (skinned) features.emplace_back("SKINNED");
if (depthOnly) features.emplace_back("SHADOW_DEPTH");
// Resident geometry owns its texture slots, so it is the vertex source that can
- // carry a shadow map — the batch stream's are a per-vertex merge product.
- else if (lit) features.emplace_back("ES_RECEIVE_SHADOW");
+ // carry a shadow map and a reflection — the batch stream's are a per-vertex
+ // merge product, and a sampler pinned there would read someone's sprite.
+ else if (lit) {
+ features.emplace_back("ES_RECEIVE_SHADOW");
+ if (envMapped) features.emplace_back("ES_ENV_MAP");
+ }
// Authored as mesh.esshader, WGSL twin included. Its vertex stage is the one
// that reads a model matrix, which is what lets the vertices stay local.
@@ -202,6 +207,7 @@ void MeshPlugin::collect(RenderCollectContext& collect_ctx) {
.textureId = textureId,
.normalTextureId = normalTextureId,
.shadowTextureId = ctx.shadow_texture_id,
+ .envTextureId = ctx.environment_texture_id,
.depth = position.z,
.y = position.y,
.entity = entity,
@@ -229,6 +235,7 @@ void MeshPlugin::collect(RenderCollectContext& collect_ctx) {
key.depthWrite = true;
key.materialId = 0;
key.shadowTextureId = 0;
+ key.envTextureId = 0;
}
// Material resolve mirrors SpritePlugin: an unregistered handle falls back to
@@ -263,7 +270,8 @@ void MeshPlugin::collect(RenderCollectContext& collect_ctx) {
// light off the constant normal a 2D surface has.
const u32 residentShader =
meshProgram(ctx, resident->hasNormals, mesh.lit && !ctx.shadow_pass,
- normalTextureId != 0 && !ctx.shadow_pass, skinned, ctx.shadow_pass);
+ normalTextureId != 0 && !ctx.shadow_pass, skinned, ctx.shadow_pass,
+ key.envTextureId != 0);
if (resident->isDrawable() && residentShader != 0) {
const u32 stride = skinned ? MESH_INSTANCE_STRIDE_SKINNED
: resident->hasNormals ? MESH_INSTANCE_STRIDE_LIT
@@ -297,7 +305,8 @@ void MeshPlugin::collect(RenderCollectContext& collect_ctx) {
u32 materialProgram = 0;
if (key.materialId != 0 && ctx.materials) {
materialProgram = ctx.materials->meshProgram(key.materialId, ctx.resources,
- resident->hasNormals, skinned);
+ resident->hasNormals, skinned,
+ key.envTextureId != 0);
if (materialProgram == 0) {
if (!warned_material_) {
warned_material_ = true;
diff --git a/src/esengine/renderer/plugins/MeshPlugin.hpp b/src/esengine/renderer/plugins/MeshPlugin.hpp
index 989867020..7cf84a353 100644
--- a/src/esengine/renderer/plugins/MeshPlugin.hpp
+++ b/src/esengine/renderer/plugins/MeshPlugin.hpp
@@ -26,18 +26,18 @@ public:
private:
std::vector<BatchVertex> scratch_; ///< Reused per mesh; amortizes the transform buffer.
/// Resident-geometry programs, indexed by {has normals, lit, normal-mapped,
- /// skinned, depth-only}: what the geometry carries and what the draw asked for
- /// are separate questions. Compiled on first use — a scene draws a few.
- std::array<u32, 32> mesh_programs_{};
- std::array<bool, 32> mesh_compiled_{};
+ /// skinned, depth-only, environment-mapped}: what the geometry carries and what
+ /// the draw asked for are separate questions. Compiled on first use.
+ std::array<u32, 64> mesh_programs_{};
+ std::array<bool, 64> mesh_compiled_{};
/// The shader RESOURCES behind those ids, kept because init() runs again
/// after a device rebuild: with no handle to release, each rebuild left a
/// dead shader in the pool and one more program the host never freed.
- std::array<resource::ShaderHandle, 32> mesh_shaders_{};
+ std::array<resource::ShaderHandle, 64> mesh_shaders_{};
/// One entity's bone matrices while they are being built; reused per draw.
std::vector<glm::mat4> pose_scratch_;
u32 meshProgram(RenderFrameContext& ctx, bool normals, bool lit, bool normalMapped,
- bool skinned, bool depthOnly = false);
+ bool skinned, bool depthOnly = false, bool envMapped = false);
bool warned_material_ = false; ///< A material on resident geometry is said once.
};
diff --git a/src/esengine/renderer/rhi/Shader.cpp b/src/esengine/renderer/rhi/Shader.cpp
index 38e97597b..ab34a8a71 100644
--- a/src/esengine/renderer/rhi/Shader.cpp
+++ b/src/esengine/renderer/rhi/Shader.cpp
@@ -262,9 +262,14 @@ bool Shader::compile(const std::string& vertexSrc, const std::string& fragmentSr
// Engine-injected samplers sit on fixed units, pinned here for the same reason the
// blocks above are: the header reaches every Lit2D shader, so a compile site that
// forgot the unit would sample slot 0 silently. GLSL ES 300 has no layout(binding).
- if (hasUniform(SHADOW_MAP_SAMPLER)) {
+ if (hasUniform(SHADOW_MAP_SAMPLER) || hasUniform(ENV_MAP_SAMPLER)) {
bind();
- setUniform(SHADOW_MAP_SAMPLER, static_cast<i32>(SHADOW_MAP_TEXTURE_UNIT));
+ if (hasUniform(SHADOW_MAP_SAMPLER)) {
+ setUniform(SHADOW_MAP_SAMPLER, static_cast<i32>(SHADOW_MAP_TEXTURE_UNIT));
+ }
+ if (hasUniform(ENV_MAP_SAMPLER)) {
+ setUniform(ENV_MAP_SAMPLER, static_cast<i32>(ENV_MAP_TEXTURE_UNIT));
+ }
unbind();
}
diff --git a/src/esengine/renderer/store/LightConstants.hpp b/src/esengine/renderer/store/LightConstants.hpp
index 635a597d4..759fed93d 100644
--- a/src/esengine/renderer/store/LightConstants.hpp
+++ b/src/esengine/renderer/store/LightConstants.hpp
@@ -33,6 +33,10 @@ inline constexpr const char* LIGHT_CONSTANTS_BLOCK = "LightConstants";
inline constexpr const char* SHADOW_MAP_SAMPLER = "u_shadowMap";
inline constexpr u32 SHADOW_MAP_TEXTURE_UNIT = 2;
+/** @brief The injected reflection sampler, one unit past the shadow map's. */
+inline constexpr const char* ENV_MAP_SAMPLER = "u_envMap";
+inline constexpr u32 ENV_MAP_TEXTURE_UNIT = 3;
+
/**
* @brief Max simultaneous 2D lights packed into the UBO. The injected fragment loop is a fixed
* bound; inactive slots are zeroed (intensity 0) so they contribute nothing. Must match
@@ -90,11 +94,22 @@ struct LightConstants {
/// zeroed default cannot darken slot 0 before one exists; y = depth bias in the
/// map's own [0,1] units; z = one texel of it; w = the light slot that cast it.
glm::vec4 shadowParams{0.0f};
+ /// The frame environment's nine irradiance coefficients, rgb in xyz. Zero when
+ /// no light carries one, which makes the flat `ambient` term the order-zero case
+ /// of one expression rather than a second path. vec4: std140 pads vec3 anyway.
+ glm::vec4 envIrradiance[9]{};
+ /// x = 1 when a prefiltered reflection is bound; y = its RGBM decode range;
+ /// z = the highest mip index; w = mip 0's octahedral face size, in texels.
+ glm::vec4 envParams{0.0f};
+ /// rgb = the ambient light's colour times its intensity, which scales BOTH halves
+ /// of the environment. Kept out of the coefficients so the reflection — sampled
+ /// from a texture the light does not own — is tinted by the same number.
+ glm::vec4 envTint{0.0f};
};
static_assert(sizeof(GpuLight2D) == 64, "GpuLight2D must be std140-tight (four vec4s)");
static_assert(sizeof(LightConstants) == 16 + 64 * MAX_LIGHTS_2D + 16 + 16 * MAX_OCCLUDERS_2D
- + 64 + 16,
+ + 64 + 16 + 16 * 9 + 16 + 16,
"LightConstants must match the std140 GLSL block layout");
} // namespace esengine
diff --git a/src/esengine/renderer/store/LightStore.hpp b/src/esengine/renderer/store/LightStore.hpp
index 027d39895..c3c612f6d 100644
--- a/src/esengine/renderer/store/LightStore.hpp
+++ b/src/esengine/renderer/store/LightStore.hpp
@@ -47,6 +47,7 @@ public:
void clear() {
data_ = LightConstants{};
count_ = 0;
+ hasEnvironment_ = false;
dirty_ = true;
}
@@ -77,6 +78,23 @@ public:
dirty_ = true;
}
+ /// Sets the frame's environment: nine irradiance coefficients, the reflection
+ /// params, and the tint scaling both. The FIRST ambient light carrying one wins —
+ /// several environments do not sum the way flat terms do.
+ /// @return false when one was already set this frame.
+ bool setEnvironment(const glm::vec3* irradiance, const glm::vec4& params,
+ const glm::vec3& tint) {
+ if (hasEnvironment_) return false;
+ for (usize i = 0; i < 9; ++i) data_.envIrradiance[i] = glm::vec4(irradiance[i], 0.0f);
+ data_.envParams = params;
+ data_.envTint = glm::vec4(tint, 0.0f);
+ hasEnvironment_ = true;
+ dirty_ = true;
+ return true;
+ }
+
+ bool hasEnvironment() const { return hasEnvironment_; }
+
/// Appends a world-space AABB occluder (minX, minY, maxX, maxY). Silently drops past
/// MAX_OCCLUDERS_2D. With no occluders added, the injected shader shadow test is a no-op.
void addOccluder(const glm::vec4& box) {
@@ -100,6 +118,7 @@ public:
private:
LightConstants data_{};
u32 count_ = 0;
+ bool hasEnvironment_ = false;
BufferHandle ubo_ = BufferHandle::Invalid;
bool dirty_ = true;
GfxDevice* device_ = nullptr;
diff --git a/src/esengine/renderer/store/MaterialStore.cpp b/src/esengine/renderer/store/MaterialStore.cpp
index dabf78caf..f0d671589 100644
--- a/src/esengine/renderer/store/MaterialStore.cpp
+++ b/src/esengine/renderer/store/MaterialStore.cpp
@@ -45,14 +45,15 @@ void MaterialStore::recreateGpuResources() {
}
u32 MaterialStore::meshProgram(u32 materialId, resource::ResourceManager& resources,
- bool withNormals, bool skinned) const {
+ bool withNormals, bool skinned, bool envMapped) const {
const MaterialRecord* rec = find(materialId);
if (!rec || !rec->shaderRef.isValid()) return 0;
// Keyed by shader AND vertex shape: a layout may not declare an attribute its
// shader ignores, so geometry with normals — or posed by bones — needs its own.
const u64 key = static_cast<u64>(rec->shaderRef.id())
| (withNormals ? (1ull << 32) : 0ull)
- | (skinned ? (1ull << 33) : 0ull);
+ | (skinned ? (1ull << 33) : 0ull)
+ | (envMapped ? (1ull << 34) : 0ull);
auto cached = mesh_programs_.find(key);
if (cached != mesh_programs_.end()) return cached->second;
@@ -71,9 +72,11 @@ u32 MaterialStore::meshProgram(u32 materialId, resource::ResourceManager& resour
features.push_back("MESH");
if (withNormals) features.push_back("MESH_NORMALS");
if (skinned) features.push_back("SKINNED");
- // Resident geometry carries the frame's shadow map on its own slot 2; the batch
- // variant of the same material must not, which is why this rides the mesh path.
+ // Resident geometry carries the frame's shadow map on its own slot 2 and the
+ // reflection on slot 3; the batch variant of the same material must not, which
+ // is why these ride the mesh path.
features.push_back("ES_RECEIVE_SHADOW");
+ if (envMapped) features.push_back("ES_ENV_MAP");
const auto target = resources.preferredShaderTarget();
const std::string vert = resource::ShaderParser::assembleStage(
parsed, resource::ShaderStage::Vertex, "", features, target);
diff --git a/src/esengine/renderer/store/MaterialStore.hpp b/src/esengine/renderer/store/MaterialStore.hpp
index 71aaa24bf..2d3d25523 100644
--- a/src/esengine/renderer/store/MaterialStore.hpp
+++ b/src/esengine/renderer/store/MaterialStore.hpp
@@ -173,7 +173,8 @@ public:
/// matrix. 0 when the material's source was never kept or the variant fails —
/// the caller then falls back rather than drawing it wrong.
u32 meshProgram(u32 materialId, resource::ResourceManager& resources,
- bool withNormals = false, bool skinned = false) const;
+ bool withNormals = false, bool skinned = false,
+ bool envMapped = false) const;
/// Registers (or replaces) a shader's MaterialConstants layout — called when a shader
/// authored with #pragma param is compiled, so materials on it can pack their uniforms.
diff --git a/src/esengine/resource/Environment.hpp b/src/esengine/resource/Environment.hpp
new file mode 100644
index 000000000..a24da7f4e
--- /dev/null
+++ b/src/esengine/resource/Environment.hpp
@@ -0,0 +1,40 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file Environment.hpp
+ * @brief A baked environment: what a surface sees when no light faces it.
+ */
+#pragma once
+
+#include "../core/Types.hpp"
+#include "../math/Math.hpp"
+#include "./Handle.hpp"
+
+#include <array>
+
+namespace esengine {
+
+/**
+ * @brief The two halves of an image-based light, as the importer baked them.
+ *
+ * @details The diffuse half is nine spherical-harmonic coefficients, already
+ * convolved and divided by pi, so evaluating them at a normal gives the
+ * value that multiplies albedo — where the flat ambient term sits. The
+ * specular half is an octahedral atlas, mip i for roughness i/(mipCount-1).
+ */
+class Environment {
+public:
+ std::array<glm::vec3, 9> irradiance{};
+
+ resource::TextureHandle specular;
+
+ /** 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. */
+ f32 maxRange = 0.0f;
+
+ bool hasSpecular() const { return specular.isValid() && mipCount > 0 && faceSize > 0.0f; }
+};
+
+} // namespace esengine
diff --git a/src/esengine/resource/Handle.hpp b/src/esengine/resource/Handle.hpp
index a8e781ba9..b82397f61 100644
--- a/src/esengine/resource/Handle.hpp
+++ b/src/esengine/resource/Handle.hpp
@@ -188,6 +188,7 @@ namespace esengine {
class VertexBuffer;
class IndexBuffer;
class Mesh;
+ class Environment;
}
// Forward-declared only — the native spine runtime was removed (spine is fully
@@ -223,6 +224,9 @@ using IndexBufferHandle = Handle<esengine::IndexBuffer>;
/** @brief Handle to GPU-resident geometry */
using MeshHandle = Handle<esengine::Mesh>;
+/** @brief Handle to a baked environment (irradiance + prefiltered reflection) */
+using EnvironmentHandle = Handle<esengine::Environment>;
+
/** @brief Handle to a Spine skeleton data resource (vestigial — see fwd decl) */
using SpineDataHandle = Handle<esengine::spine::SpineSkeletonData>;
diff --git a/src/esengine/resource/ResourceManager.cpp b/src/esengine/resource/ResourceManager.cpp
index af3085ec3..fb31a8a06 100644
--- a/src/esengine/resource/ResourceManager.cpp
+++ b/src/esengine/resource/ResourceManager.cpp
@@ -569,6 +569,41 @@ void ResourceManager::releaseMesh(MeshHandle handle) {
meshes_.release(handle.id());
}
+// =============================================================================
+// Environment Resources
+// =============================================================================
+
+EnvironmentHandle ResourceManager::createEnvironment(ConstSpan<f32> irradiance,
+ TextureHandle specular, f32 faceSize,
+ u32 mipCount, f32 maxRange) {
+ if (irradiance.size() != 27) {
+ ES_LOG_ERROR("createEnvironment: {} coefficients, want 27", irradiance.size());
+ return EnvironmentHandle();
+ }
+ auto environment = std::make_unique<Environment>();
+ for (usize i = 0; i < 9; ++i) {
+ environment->irradiance[i] = {irradiance[i * 3], irradiance[i * 3 + 1],
+ irradiance[i * 3 + 2]};
+ }
+ environment->specular = specular;
+ environment->faceSize = faceSize;
+ environment->mipCount = mipCount;
+ environment->maxRange = maxRange;
+ return environments_.add(std::move(environment));
+}
+
+Environment* ResourceManager::getEnvironment(EnvironmentHandle handle) {
+ return environments_.get(handle);
+}
+
+const Environment* ResourceManager::getEnvironment(EnvironmentHandle handle) const {
+ return environments_.get(handle);
+}
+
+void ResourceManager::releaseEnvironment(EnvironmentHandle handle) {
+ environments_.release(handle.id());
+}
+
// =============================================================================
// Index Buffer Resources
// =============================================================================
diff --git a/src/esengine/resource/ResourceManager.hpp b/src/esengine/resource/ResourceManager.hpp
index 669adad45..d3f5ff66c 100644
--- a/src/esengine/resource/ResourceManager.hpp
+++ b/src/esengine/resource/ResourceManager.hpp
@@ -28,6 +28,7 @@
#include "../renderer/rhi/Texture.hpp"
#include "../renderer/rhi/Buffer.hpp"
#include "Mesh.hpp"
+#include "Environment.hpp"
#include "../text/BitmapFont.hpp"
// Standard library
@@ -470,6 +471,28 @@ public:
/** @brief Releases a mesh and the buffers it owns. */
void releaseMesh(MeshHandle handle);
+ // =========================================================================
+ // Environment Resources
+ // =========================================================================
+
+ /**
+ * @brief Registers a baked environment.
+ * @param irradiance Nine RGB spherical-harmonic coefficients.
+ * @param specular The prefiltered octahedral atlas; may be invalid, leaving
+ * the environment diffuse-only.
+ * @return Handle to the environment, or invalid when the coefficients are not nine.
+ */
+ EnvironmentHandle createEnvironment(ConstSpan<f32> irradiance, TextureHandle specular,
+ f32 faceSize, u32 mipCount, f32 maxRange);
+
+ /** @brief The environment a handle names, or null. */
+ Environment* getEnvironment(EnvironmentHandle handle);
+ const Environment* getEnvironment(EnvironmentHandle handle) const;
+
+ /** @brief Releases an environment. The atlas is an ordinary texture asset with
+ * its own lifetime, so it is NOT released here. */
+ void releaseEnvironment(EnvironmentHandle handle);
+
/**
* @brief Gets a vertex buffer by handle
* @param handle The buffer handle
@@ -609,6 +632,7 @@ private:
ResourcePool<VertexBuffer> vertexBuffers_;
ResourcePool<IndexBuffer> indexBuffers_;
ResourcePool<Mesh> meshes_;
+ ResourcePool<Environment> environments_;
ResourcePool<text::BitmapFont> fonts_;
/// Handles whose GPU texture died with the device, still showing the
/// placeholder. Empty means the content is whole again.
diff --git a/src/esengine/resource/ShaderParser.cpp b/src/esengine/resource/ShaderParser.cpp
index af0618e19..0a0eda67c 100644
--- a/src/esengine/resource/ShaderParser.cpp
+++ b/src/esengine/resource/ShaderParser.cpp
@@ -733,6 +733,9 @@ struct LightConstants {
u_occluders : array<vec4f, 8>,
u_shadowMatrix : mat4x4f,
u_shadowParams : vec4f,
+ u_envIrradiance : array<vec4f, 9>,
+ u_envParams : vec4f,
+ u_envTint : vec4f,
};
@group(0) @binding(2) var<uniform> lc : LightConstants;
fn packDepth(d : f32) -> vec3f {
@@ -848,12 +851,56 @@ fn envBRDFApprox(NdotV : f32, roughness : f32) -> vec2f {
let a = min(r.x * r.x, exp2(-9.28 * NdotV)) * r.x + r.y;
return vec2f(-1.04, 1.04) * a + r.zw;
}
+fn envIrradiance(N : vec3f) -> vec3f {
+ let sh = lc.u_envIrradiance[0].rgb * 0.282095
+ + lc.u_envIrradiance[1].rgb * (0.488603 * N.y)
+ + lc.u_envIrradiance[2].rgb * (0.488603 * N.z)
+ + lc.u_envIrradiance[3].rgb * (0.488603 * N.x)
+ + lc.u_envIrradiance[4].rgb * (1.092548 * N.x * N.y)
+ + lc.u_envIrradiance[5].rgb * (1.092548 * N.y * N.z)
+ + lc.u_envIrradiance[6].rgb * (0.315392 * (3.0 * N.z * N.z - 1.0))
+ + lc.u_envIrradiance[7].rgb * (1.092548 * N.x * N.z)
+ + lc.u_envIrradiance[8].rgb * (0.546274 * (N.x * N.x - N.y * N.y));
+ return lc.u_ambient.rgb + max(sh, vec3f(0.0)) * lc.u_envTint.rgb;
+}
+fn octEncode(d : vec3f) -> vec2f {
+ var p = d.xz / max(abs(d.x) + abs(d.y) + abs(d.z), 1e-6);
+ if (d.y < 0.0) {
+ p = (1.0 - abs(vec2f(p.y, p.x)))
+ * vec2f(select(-1.0, 1.0, p.x >= 0.0), select(-1.0, 1.0, p.y >= 0.0));
+ }
+ return p * 0.5 + 0.5;
+}
+fn envSampleMip(R : vec3f, mip : f32) -> vec3f {
+#ifndef ES_ENV_MAP
+ return vec3f(0.0);
+#else
+ let face = lc.u_envParams.w;
+ let size = face * exp2(-mip);
+ let yOff = 2.0 * face * (1.0 - exp2(-mip)) + 2.0 * mip;
+ let atlasW = face + 2.0;
+ let atlasH = 2.0 * face * (1.0 - exp2(-(lc.u_envParams.z + 1.0)))
+ + 2.0 * (lc.u_envParams.z + 1.0);
+ 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);
+#endif
+}
+fn envRadiance(R : vec3f, roughness : f32) -> vec3f {
+ if (lc.u_envParams.x < 0.5) { return lc.u_ambient.rgb; }
+ let lod = clamp(roughness, 0.0, 1.0) * lc.u_envParams.z;
+ let lo = floor(lod);
+ let a = envSampleMip(R, lo);
+ let b = envSampleMip(R, min(lo + 1.0, lc.u_envParams.z));
+ return lc.u_ambient.rgb + mix(a, b, lod - lo) * lc.u_envTint.rgb;
+}
fn applyLightingPBR(albedo : vec3f, N : vec3f, worldPos : vec3f, V : vec3f, metallic : f32,
roughness : f32, specular : f32, ao : f32) -> vec3f {
let F0 = mix(vec3f(0.04), albedo, vec3f(metallic));
let a = max(roughness * roughness, 1e-3);
let NdotV = max(dot(N, V), 1e-4);
- var lit = lc.u_ambient.rgb * ao;
+ var lit = envIrradiance(N) * ao;
var gloss = vec3f(0.0);
for (var i = 0; i < 16; i++) {
let pd = lc.u_lights[i].posDir;
@@ -904,7 +951,8 @@ fn applyLightingPBR(albedo : vec3f, N : vec3f, worldPos : vec3f, V : vec3f, meta
}
}
let ab = envBRDFApprox(NdotV, roughness);
- gloss += lc.u_ambient.rgb * (ao * specular) * (F0 * ab.x + vec3f(ab.y));
+ gloss += envRadiance(reflect(-V, N), roughness) * (ao * specular)
+ * (F0 * ab.x + vec3f(ab.y));
return albedo * (1.0 - metallic) * lit + gloss;
}
fn applyLighting2DAO(albedo : vec3f, N : vec3f, worldPos : vec2f, ao : f32) -> vec3f {
@@ -1209,6 +1257,9 @@ ShaderParser::AssembledStage ShaderParser::assembleStageEx(const ParsedShader& p
" highp vec4 u_occluders[8];\n" // world AABBs (minX,minY,maxX,maxY)
" highp mat4 u_shadowMatrix;\n" // world -> shadow map clip
" highp vec4 u_shadowParams;\n" // x = has map, y = bias, z = texel
+ " highp vec4 u_envIrradiance[9];\n" // SH9, rgb in xyz; zero = no environment
+ " highp vec4 u_envParams;\n" // x = has map, y = range, z = maxLod, w = face
+ " highp vec4 u_envTint;\n" // the ambient light's colour, scaling both halves
"};\n"
// The shadow map rides the draw's third texture slot, behind the feature the
// MESH vertex sources set: the batch stream owns 0..7 as a per-vertex merge
@@ -1216,6 +1267,9 @@ ShaderParser::AssembledStage ShaderParser::assembleStageEx(const ParsedShader& p
"#ifdef ES_RECEIVE_SHADOW\n"
"uniform highp sampler2D u_shadowMap;\n"
"#endif\n"
+ "#ifdef ES_ENV_MAP\n"
+ "uniform highp sampler2D u_envMap;\n"
+ "#endif\n"
// 24 bits of depth across RGB — an 8-bit target is what both backends have
// in common, and a metre of world depth does not survive 8 of them. The
// pair lives together: two files would be two chances to disagree.
@@ -1360,6 +1414,59 @@ ShaderParser::AssembledStage ShaderParser::assembleStageEx(const ParsedShader& p
" highp float a = min(r.x * r.x, exp2(-9.28 * NdotV)) * r.x + r.y;\n"
" return vec2(-1.04, 1.04) * a + r.zw;\n"
"}\n"
+ // The environment's diffuse half. With no environment the coefficients are
+ // zero and this IS the flat ambient term, which is what keeps every existing
+ // scene pixel-identical rather than merely close.
+ "highp vec3 envIrradiance(in highp vec3 N) {\n"
+ " highp vec3 sh = u_envIrradiance[0].rgb * 0.282095\n"
+ " + u_envIrradiance[1].rgb * (0.488603 * N.y)\n"
+ " + u_envIrradiance[2].rgb * (0.488603 * N.z)\n"
+ " + u_envIrradiance[3].rgb * (0.488603 * N.x)\n"
+ " + u_envIrradiance[4].rgb * (1.092548 * N.x * N.y)\n"
+ " + u_envIrradiance[5].rgb * (1.092548 * N.y * N.z)\n"
+ " + u_envIrradiance[6].rgb * (0.315392 * (3.0 * N.z * N.z - 1.0))\n"
+ " + u_envIrradiance[7].rgb * (1.092548 * N.x * N.z)\n"
+ " + u_envIrradiance[8].rgb * (0.546274 * (N.x * N.x - N.y * N.y));\n"
+ " return u_ambient.rgb + max(sh, vec3(0.0)) * u_envTint.rgb;\n"
+ "}\n"
+ // Direction -> the octahedral unit square, +Y at the centre. The importer's
+ // octEncode, in the shading language; the two must agree texel for texel.
+ "highp vec2 octEncode(in highp vec3 d) {\n"
+ " highp vec2 p = d.xz / max(abs(d.x) + abs(d.y) + abs(d.z), 1e-6);\n"
+ " if (d.y < 0.0) {\n"
+ " p = (1.0 - abs(p.yx)) * vec2(p.x >= 0.0 ? 1.0 : -1.0, p.y >= 0.0 ? 1.0 : -1.0);\n"
+ " }\n"
+ " return p * 0.5 + 0.5;\n"
+ "}\n"
+ // One mip of the prefiltered atlas. The mips stack downward, each face ringed
+ // by a border texel, so the offset is a closed form rather than a table:
+ // sum(face >> j, j < mip) = 2*face*(1 - 2^-mip), plus two rows per mip.
+ "highp vec3 envSampleMip(in highp vec3 R, in highp float mip) {\n"
+ "#ifndef ES_ENV_MAP\n"
+ " return vec3(0.0);\n"
+ "#else\n"
+ " highp float face = u_envParams.w;\n"
+ " highp float size = face * exp2(-mip);\n"
+ " highp float yOff = 2.0 * face * (1.0 - exp2(-mip)) + 2.0 * mip;\n"
+ " highp float atlasW = face + 2.0;\n"
+ " highp float atlasH = 2.0 * face * (1.0 - exp2(-(u_envParams.z + 1.0)))\n"
+ " + 2.0 * (u_envParams.z + 1.0);\n"
+ " 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"
+ "#endif\n"
+ "}\n"
+ // The environment's specular half, at the roughness asked for. Without a map
+ // this is the flat ambient term, the same way the diffuse half is.
+ "highp vec3 envRadiance(in highp vec3 R, in highp float roughness) {\n"
+ " if (u_envParams.x < 0.5) return u_ambient.rgb;\n"
+ " highp float lod = clamp(roughness, 0.0, 1.0) * u_envParams.z;\n"
+ " highp float lo = floor(lod);\n"
+ " highp vec3 a = envSampleMip(R, lo);\n"
+ " highp vec3 b = envSampleMip(R, min(lo + 1.0, u_envParams.z));\n"
+ " return u_ambient.rgb + mix(a, b, lod - lo) * u_envTint.rgb;\n"
+ "}\n"
// The lighting model in its general form; a lit 2D surface is its zero
// (metallic 0, roughness 1, specular 0 leaves albedo * NdotL, pixel for pixel
// what this engine has always drawn), so there is one model and not two.
@@ -1373,8 +1480,8 @@ ShaderParser::AssembledStage ShaderParser::assembleStageEx(const ParsedShader& p
" highp float a = max(roughness * roughness, 1e-3);\n"
" highp float NdotV = max(dot(N, V), 1e-4);\n"
// Occlusion darkens the light that arrives from everywhere, which is the
- // ambient term; a surface's own lights are unobstructed by it.
- " highp vec3 lit = u_ambient.rgb * ao;\n"
+ // environment; a surface's own lights are unobstructed by it.
+ " highp vec3 lit = envIrradiance(N) * ao;\n"
" highp vec3 gloss = vec3(0.0);\n"
// A Light2D has no third coordinate, so distance stays in the plane and a
// point light's height is its radius. Normal and view are the 3D part.
@@ -1437,7 +1544,8 @@ ShaderParser::AssembledStage ShaderParser::assembleStageEx(const ParsedShader& p
// radiance from every direction. A metal has no diffuse, so without a
// reflection of it a metal is black wherever no light happens to point.
" highp vec2 ab = envBRDFApprox(NdotV, roughness);\n"
- " gloss += u_ambient.rgb * (ao * specular) * (F0 * ab.x + ab.y);\n"
+ " gloss += envRadiance(reflect(-V, N), roughness) * (ao * specular)\n"
+ " * (F0 * ab.x + ab.y);\n"
" return albedo * (1.0 - metallic) * lit + gloss;\n"
"}\n"
"highp vec3 applyLighting2DAO(highp vec3 albedo, highp vec3 N, highp vec2 worldPos,\n"
diff --git a/tests/renderer/test_shader_device.cpp b/tests/renderer/test_shader_device.cpp
index 46e746c38..af0dcec80 100644
--- a/tests/renderer/test_shader_device.cpp
+++ b/tests/renderer/test_shader_device.cpp
@@ -32,13 +32,14 @@ int main() {
// compile() pins the engine-injected samplers to their units, so the counts
// the rest of this block asserts start from what that seeding left behind.
- CHECK(d.setUniform1iCalls == 1
- && d.lastUniform1iVal == static_cast<i32>(SHADOW_MAP_TEXTURE_UNIT),
- "compile pins the injected shadow sampler to its texture unit");
- CHECK(d.useProgramCalls == 2, "seeding it binds and unbinds the program");
+ // Two of them: the shadow map and the environment's reflection.
+ CHECK(d.setUniform1iCalls == 2
+ && d.lastUniform1iVal == static_cast<i32>(ENV_MAP_TEXTURE_UNIT),
+ "compile pins the injected samplers to their texture units");
+ CHECK(d.useProgramCalls == 2, "seeding them binds and unbinds the program once");
shader->setUniform("u_tex", 3);
- CHECK(d.setUniform1iCalls == 2, "setUniform(name,int) routes through device.setUniform1i");
+ CHECK(d.setUniform1iCalls == 3, "setUniform(name,int) routes through device.setUniform1i");
CHECK(d.lastUniform1iVal == 3, "uniform value forwarded");
shader->setUniform("u_color", glm::vec4(1, 0, 0, 1));
diff --git a/tools/renderScenes.mjs b/tools/renderScenes.mjs
index 0abad2827..049c531b5 100644
--- a/tools/renderScenes.mjs
+++ b/tools/renderScenes.mjs
@@ -56,6 +56,10 @@ export const SCENES = [
// x, so the shadow lands 100 along +x and x 75..175 is floor the light cannot see.
// The blocker itself stays lit — shadowing one's own caster is the classic bug.
{ id: "mesh-shadow", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/mesh-shadow.esscene", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.708,\"y\":0.5,\"rgb\":[0,0,0],\"tol\":20},{\"x\":0.167,\"y\":0.5,\"rgb\":[228,228,228],\"tol\":20},{\"x\":0.5,\"y\":0.5,\"rgb\":[228,228,228],\"tol\":20}]" } },
+ // 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}]" } },
// 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.