A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
feat(render): the sky lights the scene — Sky Atmosphere as the environment
yhhdd918da11e6d
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 7482323ac..4fa7e48b9 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -20,6 +20,8 @@ published separately; it ships inside the editor.- **A material reads its maps through Tiling, Offset and Rotation.** The Model shader's `u_uvTiling`, `u_uvOffset` and `u_uvRotation` move where every map is read (colour, normal, occlusion, metal-roughness, emission), as Unity's Tiling and Offset do; Ground Blend takes them too. A glTF's `KHR_texture_transform` is imported into them, turned into the engine's V-up uv, where before it was dropped with a warning and a tiled texture set was stretched once over each mesh: a three.js port of a container port lost 224 of them. Maps of one material that disagree are all read through the first map's, and the import says so. A cut-out's shadow and depth prepass read through the same transform, so a tiled fence casts the shadow of the fence drawn.+- **The sky lights the scene.** Sky Atmosphere's **Light the Scene** makes the sky the scene's environment: every Ambient light that names no environment of its own lights with it, its diffuse light from the dome and the clouds and its reflection on metal and wet ground, scaled by the light's colour and intensity as an imported one is. The sky is worked out again as it changes (the sun moving, a weather coming in, clouds drifting), at most once a second; with clouds that takes about 20 ms on a desktop. The sun's disc is left out, since the directional light the sky follows is its direct light. Off by default, so a scene already lit by hand looks as it did.+### Fixed- **An opaque surface no longer lets the sky through where its map's alpha is below 1.** An unblended draw wrote its base colour's alpha into the frame, and Sky Atmosphere reads a pixel's alpha as how much of it geometry covers, so wherever a texture used its alpha for something else (glTF's OPAQUE ignores it) the clouds showed through the wall. An opaque Model surface now writes 1, except a cut-out's coverage and the subsurface mark.diff --git a/fixtures/scenes/sky-lights-scene.esscene b/fixtures/scenes/sky-lights-scene.esscenenew file mode 100644index 000000000..f105cfdfb--- /dev/null+++ b/fixtures/scenes/sky-lights-scene.esscene@@ -0,0 +1,131 @@+{+ "version": 4,+ "name": "SkyLightsScene",+ "entities": [+ {+ "id": 0,+ "name": "Camera",+ "parent": null,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": 0,+ "y": 0,+ "z": 600+ },+ "rotation": {+ "w": 1,+ "x": 0,+ "y": 0,+ "z": 0+ }+ }+ },+ {+ "type": "Camera",+ "data": {+ "projectionType": 0,+ "fov": 60,+ "nearPlane": 1,+ "farPlane": 5000,+ "isActive": true,+ "priority": 0+ }+ },+ {+ "type": "PostProcessVolume",+ "data": {+ "isGlobal": true,+ "priority": 0,+ "weight": 1,+ "effects": [+ {+ "type": "skyAtmosphere",+ "enabled": true,+ "uniforms": {+ "u_lightScene": 1,+ "u_followSun": 0,+ "u_sunAzimuth": 180,+ "u_sunElevation": 35,+ "u_clouds": 0+ }+ }+ ]+ }+ }+ ]+ },+ {+ "id": 1,+ "name": "Sky",+ "parent": null,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": 0,+ "y": 0,+ "z": 0+ }+ }+ },+ {+ "type": "Light",+ "data": {+ "type": 2,+ "color": {+ "r": 1,+ "g": 1,+ "b": 1,+ "a": 1+ },+ "intensity": 1+ }+ }+ ]+ },+ {+ "id": 2,+ "name": "Quad",+ "parent": null,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": 0,+ "y": 0,+ "z": 0+ }+ }+ },+ {+ "type": "MeshRenderer",+ "data": {+ "mesh": "/scenes/normalmap-quad.esmesh",+ "lit": true,+ "opaque": true,+ "cullBackfaces": false,+ "enabled": true,+ "material": "/scenes/sky-lights-scene_m0.esmaterial",+ "color": {+ "r": 1,+ "g": 1,+ "b": 1,+ "a": 1+ }+ }+ }+ ]+ }+ ]+}\ No newline at end of filediff --git a/fixtures/scenes/sky-lights-scene_m0.esmaterial b/fixtures/scenes/sky-lights-scene_m0.esmaterialnew file mode 100644index 000000000..7e83a763f--- /dev/null+++ b/fixtures/scenes/sky-lights-scene_m0.esmaterial@@ -0,0 +1,13 @@+{+ "version": "1.0",+ "type": "material",+ "shader": "builtin:model",+ "blendMode": 9,+ "depthTest": true,+ "depthWrite": true,+ "cull": 0,+ "properties": {+ "u_metallic": 0,+ "u_roughness": 1+ }+}\ No newline at end of filediff --git a/pipeline/src/assets/environmentImport.ts b/pipeline/src/assets/environmentImport.tsindex 4951f98a9..16a726dac 100644--- a/pipeline/src/assets/environmentImport.ts+++ b/pipeline/src/assets/environmentImport.ts@@ -11,16 +11,14 @@* at all — and the specular half one ordinary RGBA8 image, so nothing* downstream learns a cube map or a float format.*/-import { shBasis, convolveCosine, evalIrradianceSH, panoramaDirection, panoramaUV } from 'esengine';+import { shBasis, evalIrradianceSH, panoramaDirection, samplePanorama, octDecode, octEncode,+ projectIrradianceSH, atlasLayout, encodeRgbm, decodeRgbm, prefilterOctahedral as prefilterOctahedralAtlas,+ type Panorama } from 'esengine';++export type { Panorama };+export { samplePanorama, octDecode, octEncode, projectIrradianceSH, atlasLayout, encodeRgbm, decodeRgbm };import { encodeRgbaPng } from './png';-/** A panorama in linear light: equirectangular, row 0 = up (+Y). */-export interface Panorama {- width: number;- height: number;- /** RGB triples, `width * height * 3` linear values. */- rgb: Float32Array;-}/** The `.esenv` document. `specular` is filled in by the importer, which is what* knows the atlas' project path. */@@ -190,236 +188,20 @@ function readScanline(bytes: Uint8Array, at: number, width: number, out: Uint8Ar// Directions// =============================================================================-/** Bilinear lookup of the panorama along `d` (normalized), by `panoramaUV`. */-export function samplePanorama(env: Panorama, dx: number, dy: number, dz: number,- out: Float32Array): void {- const [u, v] = panoramaUV(dx, dy, dz);- const fx = u * env.width - 0.5;- const fy = v * env.height - 0.5;- const x0 = Math.floor(fx), y0 = Math.floor(fy);- const tx = fx - x0, ty = fy - y0;- // u wraps (the seam is continuous); v clamps (there is nothing past a pole).- const wrapX = (x: number): number => ((x % env.width) + env.width) % env.width;- const clampY = (y: number): number => Math.max(0, Math.min(env.height - 1, y));- const x1 = wrapX(x0 + 1), y1 = clampY(y0 + 1);- const xa = wrapX(x0), ya = clampY(y0);- for (let c = 0; c < 3; c++) {- const a = env.rgb[(ya * env.width + xa) * 3 + c]!;- const b = env.rgb[(ya * env.width + x1) * 3 + c]!;- const d = env.rgb[(y1 * env.width + xa) * 3 + c]!;- const e = env.rgb[(y1 * env.width + x1) * 3 + c]!;- out[c] = (a * (1 - tx) + b * tx) * (1 - ty) + (d * (1 - tx) + e * tx) * ty;- }-}--/** Octahedral unit square → direction, with +Y at the centre. Values slightly- * outside [0,1] stay continuous, which is what makes the atlas' border texels- * the neighbours a bilinear tap expects. */-export function octDecode(u: number, v: number): [number, number, number] {- const fx = u * 2 - 1;- const fz = v * 2 - 1;- let x = fx;- let z = fz;- const y = 1 - Math.abs(fx) - Math.abs(fz);- if (y < 0) {- const sx = x >= 0 ? 1 : -1;- const sz = z >= 0 ? 1 : -1;- x = (1 - Math.abs(fz)) * sx;- z = (1 - Math.abs(fx)) * sz;- }- const len = Math.hypot(x, y, z) || 1;- return [x / len, y / len, z / len];-}--/** The inverse of {@link octDecode}. */-export function octEncode(dx: number, dy: number, dz: number): [number, number] {- const norm = Math.abs(dx) + Math.abs(dy) + Math.abs(dz) || 1;- let px = dx / norm;- let pz = dz / norm;- if (dy < 0) {- const sx = px >= 0 ? 1 : -1;- const sz = pz >= 0 ? 1 : -1;- const ax = Math.abs(px);- const az = Math.abs(pz);- px = (1 - az) * sx;- pz = (1 - ax) * sz;- }- return [px * 0.5 + 0.5, pz * 0.5 + 0.5];-}-// =============================================================================// Diffuse: nine coefficients// =============================================================================-/**- * Project the panorama onto nine RGB coefficients, convolved with the clamped- * cosine lobe and divided by π — the same nine a probe solve produces, through- * the same basis, because one expression in the shader reads them both.- */-export function projectIrradianceSH(env: Panorama): Float32Array {- const coefficients = new Float32Array(27);- const basis = new Float32Array(9);- const dPhi = (2 * Math.PI) / env.width;- const dTheta = Math.PI / env.height;- for (let y = 0; y < env.height; y++) {- const theta = (y + 0.5) * dTheta;- const solidAngle = Math.sin(theta) * dTheta * dPhi;- for (let x = 0; x < env.width; x++) {- const [dx, dy, dz] = panoramaDirection((x + 0.5) / env.width, (y + 0.5) / env.height);- shBasis(dx, dy, dz, basis);- const o = (y * env.width + x) * 3;- for (let i = 0; i < 9; i++) {- const weighted = basis[i]! * solidAngle;- coefficients[i * 3] += env.rgb[o]! * weighted;- coefficients[i * 3 + 1] += env.rgb[o + 1]! * weighted;- coefficients[i * 3 + 2] += env.rgb[o + 2]! * weighted;- }- }- }-- convolveCosine(coefficients);- return coefficients;-}-export { shBasis, evalIrradianceSH };// =============================================================================// Specular: one prefiltered octahedral atlas// =============================================================================-/** The atlas' pixel size, and where each mip's face begins in it. Mips stack- * downward, every face ringed by one texel so a bilinear tap at the edge of one- * never reaches into the next. */-export function atlasLayout(faceSize: number, mipCount: number): {- width: number; height: number; offsets: number[];-} {- const offsets: number[] = [];- let height = 0;- for (let mip = 0; mip < mipCount; mip++) {- offsets.push(height);- height += (faceSize >> mip) + 2;- }- return { width: faceSize + 2, height, offsets };-}--/** Van der Corput radical inverse — the second half of a Hammersley pair. */-function radicalInverse(bits: number): number {- let b = bits;- b = ((b << 16) | (b >>> 16)) >>> 0;- b = (((b & 0x55555555) << 1) | ((b & 0xaaaaaaaa) >>> 1)) >>> 0;- b = (((b & 0x33333333) << 2) | ((b & 0xcccccccc) >>> 2)) >>> 0;- b = (((b & 0x0f0f0f0f) << 4) | ((b & 0xf0f0f0f0) >>> 4)) >>> 0;- b = (((b & 0x00ff00ff) << 8) | ((b & 0xff00ff00) >>> 8)) >>> 0;- return b * 2.3283064365386963e-10;-}--/**- * GGX-importance-sample the panorama around `N`, the standard prefilter with- * V = N. That approximation drops the stretched grazing highlight, which is the- * price every runtime prefilter pays; the split-sum term the shader applies on- * top is derived under the same assumption, so the two agree.- */-function prefilterDirection(env: Panorama, roughness: number, samples: number,- nx: number, ny: number, nz: number,- out: Float32Array, scratch: Float32Array): void {- out[0] = 0; out[1] = 0; out[2] = 0;- if (roughness <= 0) {- samplePanorama(env, nx, ny, nz, out);- return;- }- // A tangent frame around N; the branch keeps the helper axis off N.- const ax = Math.abs(nz) < 0.999 ? 0 : 1;- let tx = ax === 0 ? -ny : 0;- let ty = ax === 0 ? nx : nz;- let tz = ax === 0 ? 0 : -ny;- const tl = Math.hypot(tx, ty, tz) || 1;- tx /= tl; ty /= tl; tz /= tl;- const bx = ny * tz - nz * ty;- const by = nz * tx - nx * tz;- const bz = nx * ty - ny * tx;-- const a = roughness * roughness;- let weight = 0;- for (let i = 0; i < samples; i++) {- const u1 = (i + 0.5) / samples;- const u2 = radicalInverse(i);- const phi = 2 * Math.PI * u1;- const cosTheta = Math.sqrt((1 - u2) / (1 + (a * a - 1) * u2));- const sinTheta = Math.sqrt(Math.max(0, 1 - cosTheta * cosTheta));- const hx = sinTheta * Math.cos(phi);- const hy = sinTheta * Math.sin(phi);- const wx = tx * hx + bx * hy + nx * cosTheta;- const wy = ty * hx + by * hy + ny * cosTheta;- const wz = tz * hx + bz * hy + nz * cosTheta;- const vdoth = nx * wx + ny * wy + nz * wz;- const lx = 2 * vdoth * wx - nx;- const ly = 2 * vdoth * wy - ny;- const lz = 2 * vdoth * wz - nz;- const ndotl = nx * lx + ny * ly + nz * lz;- if (ndotl <= 0) continue;- samplePanorama(env, lx, ly, lz, scratch);- out[0] += scratch[0]! * ndotl;- out[1] += scratch[1]! * ndotl;- out[2] += scratch[2]! * ndotl;- weight += ndotl;- }- if (weight > 0) {- out[0] /= weight; out[1] /= weight; out[2] /= weight;- }-}--/** RGBM, gamma-2 in the colour channels: an 8-bit encoding whose channels each- * interpolate the way the GPU is about to interpolate them. */-export function encodeRgbm(r: number, g: number, b: number, maxRange: number,- out: Uint8Array, at: number): void {- const sr = Math.sqrt(Math.max(0, r) / maxRange);- const sg = Math.sqrt(Math.max(0, g) / maxRange);- const sb = Math.sqrt(Math.max(0, b) / maxRange);- const m = Math.min(1, Math.max(sr, sg, sb, 1 / 255));- const a = Math.ceil(m * 255) / 255;- out[at] = Math.round(Math.min(1, sr / a) * 255);- out[at + 1] = Math.round(Math.min(1, sg / a) * 255);- out[at + 2] = Math.round(Math.min(1, sb / a) * 255);- out[at + 3] = Math.round(a * 255);-}--/** The inverse of {@link encodeRgbm} — the same expression the shader runs. */-export function decodeRgbm(r: number, g: number, b: number, a: number,- maxRange: number): [number, number, number] {- const f = (v: number): number => ((v / 255) * (a / 255)) ** 2 * maxRange;- return [f(r), f(g), f(b)];-}--/** Prefilter `env` into the octahedral mip atlas, as RGBA8 rows top-first. */-export function prefilterOctahedral(env: Panorama, faceSize = ENV_FACE_SIZE,- mipCount = ENV_MIP_COUNT,- maxRange = ENV_MAX_RANGE): {- width: number; height: number; rgba: Uint8Array;-} {- const { width, height, offsets } = atlasLayout(faceSize, mipCount);- const rgba = new Uint8Array(width * height * 4);- const colour = new Float32Array(3);- const scratch = new Float32Array(3);- for (let mip = 0; mip < mipCount; mip++) {- const size = faceSize >> mip;- const roughness = mipCount > 1 ? mip / (mipCount - 1) : 0;- // Fewer texels to fill as the lobe widens, so the sample count can climb- // without the cost doing the same.- const samples = mip === 0 ? 1 : Math.min(256, 64 << mip);- for (let y = -1; y <= size; y++) {- for (let x = -1; x <= size; x++) {- const u = (x + 0.5) / size;- const v = (y + 0.5) / size;- const [dx, dy, dz] = octDecode(u, v);- prefilterDirection(env, roughness, samples, dx, dy, dz, colour, scratch);- const px = x + 1;- const py = offsets[mip]! + y + 1;- encodeRgbm(colour[0]!, colour[1]!, colour[2]!, maxRange,- rgba, (py * width + px) * 4);- }- }- }- return { width, height, rgba };+/** Prefilter `env` into the octahedral mip atlas, as RGBA8 rows top-first (the SDK's, with the import's defaults). */+export function prefilterOctahedral(env: Panorama, faceSize = ENV_FACE_SIZE, mipCount = ENV_MIP_COUNT,+ maxRange = ENV_MAX_RANGE): { width: number; height: number; rgba: Uint8Array } {+ return prefilterOctahedralAtlas(env, faceSize, mipCount, maxRange);}/**diff --git a/sdk/src/core-content.ts b/sdk/src/core-content.tsindex 3d36fea53..9b9acadf9 100644--- a/sdk/src/core-content.ts+++ b/sdk/src/core-content.ts@@ -200,6 +200,8 @@ export {*/export {shBasis, convolveCosine, evalIrradianceSH, SH_BASIS_SCALE, SH_COSINE_BAND, panoramaDirection, panoramaUV,+ samplePanorama, octDecode, octEncode, projectIrradianceSH, atlasLayout, encodeRgbm, decodeRgbm, prefilterOctahedral,+ type Panorama,} from './lightmap';/*** Stock geometry a `builtin:<id>` mesh ref names. Public because the editor's@@ -657,6 +659,11 @@ export {gripPoseStatus,gripPoseByJoint,gripPoseFromJson,+ gripHandJoints,+ GripSurface,+ GripSurfaceShape,+ type GripSurfaceData,+ type GripJoint,type GripPoseData,type GripPoseDef,type GripFinger,diff --git a/sdk/src/ecs/bridge/nativeEngineApi.generated.ts b/sdk/src/ecs/bridge/nativeEngineApi.generated.tsindex 8c010c449..713192e24 100644--- a/sdk/src/ecs/bridge/nativeEngineApi.generated.ts+++ b/sdk/src/ecs/bridge/nativeEngineApi.generated.ts@@ -230,6 +230,7 @@ export interface NativeEngineApi {renderer_setQualityBudgets?(atlasSize: number, cellSize: number, cascades: number, particleLimit: number): void;renderer_setShadow2DSoftSamples?(samples: number): void;renderer_setShadowDistance?(distance: number): void;+ renderer_setSkyEnvironment?(environmentHandle: number): void;renderer_setStage?(stage: number): void;renderer_setTextureParams?(textureId: number, minFilter: number, magFilter: number, wrapS: number, wrapT: number): void;renderer_setTreeSortLayers?(mask: number): void;@@ -572,6 +573,7 @@ export function createNativeEngineApi(bind('renderer_setQualityBudgets', 'es_renderer_setQualityBudgets', false);bind('renderer_setShadow2DSoftSamples', 'es_renderer_setShadow2DSoftSamples', false);bind('renderer_setShadowDistance', 'es_renderer_setShadowDistance', false);+ bind('renderer_setSkyEnvironment', 'es_renderer_setSkyEnvironment', false);bind('renderer_setStage', 'es_renderer_setStage', false);bind('renderer_setTextureParams', 'es_renderer_setTextureParams', false);bind('renderer_setTreeSortLayers', 'es_renderer_setTreeSortLayers', false);diff --git a/sdk/src/lightmap/environmentAtlas.ts b/sdk/src/lightmap/environmentAtlas.tsnew file mode 100644index 000000000..8b8a68c52--- /dev/null+++ b/sdk/src/lightmap/environmentAtlas.ts@@ -0,0 +1,242 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file environmentAtlas.ts+ * @brief A panorama of radiance → what an environment is to the renderer: nine irradiance coefficients and one+ * prefiltered octahedral reflection atlas (RGBM, mips stacked downward).+ *+ * @details The importer runs this over an `.hdr` once (pipeline/environmentImport) and the sky lights the scene+ * from it at run time (postprocess/skyEnvironment): one implementation, so a baked sky and a live one+ * are the same numbers through the same basis.+ */+import { shBasis, convolveCosine } from './sh';+import { panoramaDirection, panoramaUV } from './panorama';++/** A panorama in linear light: equirectangular, row 0 = up (+Y). */+export interface Panorama {+ width: number;+ height: number;+ /** RGB triples, `width * height * 3` linear values. */+ rgb: Float32Array;+}++/** Bilinear lookup of the panorama along `d` (normalized), by `panoramaUV`. */+export function samplePanorama(env: Panorama, dx: number, dy: number, dz: number,+ out: Float32Array): void {+ const [u, v] = panoramaUV(dx, dy, dz);+ const fx = u * env.width - 0.5;+ const fy = v * env.height - 0.5;+ const x0 = Math.floor(fx), y0 = Math.floor(fy);+ const tx = fx - x0, ty = fy - y0;+ // u wraps (the seam is continuous); v clamps (there is nothing past a pole).+ const wrapX = (x: number): number => ((x % env.width) + env.width) % env.width;+ const clampY = (y: number): number => Math.max(0, Math.min(env.height - 1, y));+ const x1 = wrapX(x0 + 1), y1 = clampY(y0 + 1);+ const xa = wrapX(x0), ya = clampY(y0);+ for (let c = 0; c < 3; c++) {+ const a = env.rgb[(ya * env.width + xa) * 3 + c]!;+ const b = env.rgb[(ya * env.width + x1) * 3 + c]!;+ const d = env.rgb[(y1 * env.width + xa) * 3 + c]!;+ const e = env.rgb[(y1 * env.width + x1) * 3 + c]!;+ out[c] = (a * (1 - tx) + b * tx) * (1 - ty) + (d * (1 - tx) + e * tx) * ty;+ }+}++/** Octahedral unit square → direction, with +Y at the centre. Values slightly+ * outside [0,1] stay continuous, which is what makes the atlas' border texels+ * the neighbours a bilinear tap expects. */+export function octDecode(u: number, v: number): [number, number, number] {+ const fx = u * 2 - 1;+ const fz = v * 2 - 1;+ let x = fx;+ let z = fz;+ const y = 1 - Math.abs(fx) - Math.abs(fz);+ if (y < 0) {+ const sx = x >= 0 ? 1 : -1;+ const sz = z >= 0 ? 1 : -1;+ x = (1 - Math.abs(fz)) * sx;+ z = (1 - Math.abs(fx)) * sz;+ }+ const len = Math.hypot(x, y, z) || 1;+ return [x / len, y / len, z / len];+}++/** The inverse of {@link octDecode}. */+export function octEncode(dx: number, dy: number, dz: number): [number, number] {+ const norm = Math.abs(dx) + Math.abs(dy) + Math.abs(dz) || 1;+ let px = dx / norm;+ let pz = dz / norm;+ if (dy < 0) {+ const sx = px >= 0 ? 1 : -1;+ const sz = pz >= 0 ? 1 : -1;+ const ax = Math.abs(px);+ const az = Math.abs(pz);+ px = (1 - az) * sx;+ pz = (1 - ax) * sz;+ }+ return [px * 0.5 + 0.5, pz * 0.5 + 0.5];+}++/**+ * Project the panorama onto nine RGB coefficients, convolved with the clamped+ * cosine lobe and divided by π — the same nine a probe solve produces, through+ * the same basis, because one expression in the shader reads them both.+ */+export function projectIrradianceSH(env: Panorama): Float32Array {+ const coefficients = new Float32Array(27);+ const basis = new Float32Array(9);+ const dPhi = (2 * Math.PI) / env.width;+ const dTheta = Math.PI / env.height;+ for (let y = 0; y < env.height; y++) {+ const theta = (y + 0.5) * dTheta;+ const solidAngle = Math.sin(theta) * dTheta * dPhi;+ for (let x = 0; x < env.width; x++) {+ const [dx, dy, dz] = panoramaDirection((x + 0.5) / env.width, (y + 0.5) / env.height);+ shBasis(dx, dy, dz, basis);+ const o = (y * env.width + x) * 3;+ for (let i = 0; i < 9; i++) {+ const weighted = basis[i]! * solidAngle;+ coefficients[i * 3] += env.rgb[o]! * weighted;+ coefficients[i * 3 + 1] += env.rgb[o + 1]! * weighted;+ coefficients[i * 3 + 2] += env.rgb[o + 2]! * weighted;+ }+ }+ }++ convolveCosine(coefficients);+ return coefficients;+}++/** The atlas' pixel size, and where each mip's face begins in it. Mips stack+ * downward, every face ringed by one texel so a bilinear tap at the edge of one+ * never reaches into the next. */+export function atlasLayout(faceSize: number, mipCount: number): {+ width: number; height: number; offsets: number[];+} {+ const offsets: number[] = [];+ let height = 0;+ for (let mip = 0; mip < mipCount; mip++) {+ offsets.push(height);+ height += (faceSize >> mip) + 2;+ }+ return { width: faceSize + 2, height, offsets };+}++/** Van der Corput radical inverse — the second half of a Hammersley pair. */+function radicalInverse(bits: number): number {+ let b = bits;+ b = ((b << 16) | (b >>> 16)) >>> 0;+ b = (((b & 0x55555555) << 1) | ((b & 0xaaaaaaaa) >>> 1)) >>> 0;+ b = (((b & 0x33333333) << 2) | ((b & 0xcccccccc) >>> 2)) >>> 0;+ b = (((b & 0x0f0f0f0f) << 4) | ((b & 0xf0f0f0f0) >>> 4)) >>> 0;+ b = (((b & 0x00ff00ff) << 8) | ((b & 0xff00ff00) >>> 8)) >>> 0;+ return b * 2.3283064365386963e-10;+}++/**+ * GGX-importance-sample the panorama around `N`, the standard prefilter with+ * V = N. That approximation drops the stretched grazing highlight, which is the+ * price every runtime prefilter pays; the split-sum term the shader applies on+ * top is derived under the same assumption, so the two agree.+ */+function prefilterDirection(env: Panorama, roughness: number, samples: number,+ nx: number, ny: number, nz: number,+ out: Float32Array, scratch: Float32Array): void {+ out[0] = 0; out[1] = 0; out[2] = 0;+ if (roughness <= 0) {+ samplePanorama(env, nx, ny, nz, out);+ return;+ }+ // A tangent frame around N; the branch keeps the helper axis off N.+ const ax = Math.abs(nz) < 0.999 ? 0 : 1;+ let tx = ax === 0 ? -ny : 0;+ let ty = ax === 0 ? nx : nz;+ let tz = ax === 0 ? 0 : -ny;+ const tl = Math.hypot(tx, ty, tz) || 1;+ tx /= tl; ty /= tl; tz /= tl;+ const bx = ny * tz - nz * ty;+ const by = nz * tx - nx * tz;+ const bz = nx * ty - ny * tx;++ const a = roughness * roughness;+ let weight = 0;+ for (let i = 0; i < samples; i++) {+ const u1 = (i + 0.5) / samples;+ const u2 = radicalInverse(i);+ const phi = 2 * Math.PI * u1;+ const cosTheta = Math.sqrt((1 - u2) / (1 + (a * a - 1) * u2));+ const sinTheta = Math.sqrt(Math.max(0, 1 - cosTheta * cosTheta));+ const hx = sinTheta * Math.cos(phi);+ const hy = sinTheta * Math.sin(phi);+ const wx = tx * hx + bx * hy + nx * cosTheta;+ const wy = ty * hx + by * hy + ny * cosTheta;+ const wz = tz * hx + bz * hy + nz * cosTheta;+ const vdoth = nx * wx + ny * wy + nz * wz;+ const lx = 2 * vdoth * wx - nx;+ const ly = 2 * vdoth * wy - ny;+ const lz = 2 * vdoth * wz - nz;+ const ndotl = nx * lx + ny * ly + nz * lz;+ if (ndotl <= 0) continue;+ samplePanorama(env, lx, ly, lz, scratch);+ out[0] += scratch[0]! * ndotl;+ out[1] += scratch[1]! * ndotl;+ out[2] += scratch[2]! * ndotl;+ weight += ndotl;+ }+ if (weight > 0) {+ out[0] /= weight; out[1] /= weight; out[2] /= weight;+ }+}++/** RGBM, gamma-2 in the colour channels: an 8-bit encoding whose channels each+ * interpolate the way the GPU is about to interpolate them. */+export function encodeRgbm(r: number, g: number, b: number, maxRange: number,+ out: Uint8Array, at: number): void {+ const sr = Math.sqrt(Math.max(0, r) / maxRange);+ const sg = Math.sqrt(Math.max(0, g) / maxRange);+ const sb = Math.sqrt(Math.max(0, b) / maxRange);+ const m = Math.min(1, Math.max(sr, sg, sb, 1 / 255));+ const a = Math.ceil(m * 255) / 255;+ out[at] = Math.round(Math.min(1, sr / a) * 255);+ out[at + 1] = Math.round(Math.min(1, sg / a) * 255);+ out[at + 2] = Math.round(Math.min(1, sb / a) * 255);+ out[at + 3] = Math.round(a * 255);+}++/** The inverse of {@link encodeRgbm} — the same expression the shader runs. */+export function decodeRgbm(r: number, g: number, b: number, a: number,+ maxRange: number): [number, number, number] {+ const f = (v: number): number => ((v / 255) * (a / 255)) ** 2 * maxRange;+ return [f(r), f(g), f(b)];+}++/** Prefilter `env` into the octahedral mip atlas, as RGBA8 rows top-first. */+export function prefilterOctahedral(env: Panorama, faceSize: number, mipCount: number, maxRange: number): {+ width: number; height: number; rgba: Uint8Array;+} {+ const { width, height, offsets } = atlasLayout(faceSize, mipCount);+ const rgba = new Uint8Array(width * height * 4);+ const colour = new Float32Array(3);+ const scratch = new Float32Array(3);+ for (let mip = 0; mip < mipCount; mip++) {+ const size = faceSize >> mip;+ const roughness = mipCount > 1 ? mip / (mipCount - 1) : 0;+ // Fewer texels to fill as the lobe widens, so the sample count can climb+ // without the cost doing the same.+ const samples = mip === 0 ? 1 : Math.min(256, 64 << mip);+ for (let y = -1; y <= size; y++) {+ for (let x = -1; x <= size; x++) {+ const u = (x + 0.5) / size;+ const v = (y + 0.5) / size;+ const [dx, dy, dz] = octDecode(u, v);+ prefilterDirection(env, roughness, samples, dx, dy, dz, colour, scratch);+ const px = x + 1;+ const py = offsets[mip]! + y + 1;+ encodeRgbm(colour[0]!, colour[1]!, colour[2]!, maxRange,+ rgba, (py * width + px) * 4);+ }+ }+ }+ return { width, height, rgba };+}+diff --git a/sdk/src/lightmap/index.ts b/sdk/src/lightmap/index.tsindex 24584302b..579bfa674 100644--- a/sdk/src/lightmap/index.ts+++ b/sdk/src/lightmap/index.ts@@ -19,3 +19,5 @@ export { sceneAmbientLights, sceneEnvironment, carriesEnvironment, type SceneAmbexport { BAKE_DEFAULTS } from './bake';export { shBasis, convolveCosine, evalIrradianceSH, SH_BASIS_SCALE, SH_COSINE_BAND } from './sh';export { panoramaDirection, panoramaUV } from './panorama';+export { samplePanorama, octDecode, octEncode, projectIrradianceSH, atlasLayout, encodeRgbm, decodeRgbm, prefilterOctahedral,+ type Panorama } from './environmentAtlas';diff --git a/sdk/src/postprocess/PostProcessPlugin.ts b/sdk/src/postprocess/PostProcessPlugin.tsindex f9891bacc..149d84405 100644--- a/sdk/src/postprocess/PostProcessPlugin.ts+++ b/sdk/src/postprocess/PostProcessPlugin.ts@@ -8,10 +8,53 @@ import { postProcessVolumeSystem, editorViewVolumeSystem, cleanupVolumeSystem, simport { createTextureFromPixels } from '../runtime/runtimeAssets';import { TextureContent } from '../wasm';import { weatherSystem, resetWeatherSystem } from './weatherSystem';+import { defineSystem } from '../ecs/system';+import { Query } from '../ecs/query';+import { Light, Transform, type LightData, type TransformData } from '../ecs/component';+import { LightType } from '../wasm/wasm.generated';+import { EditorView } from '../camera/EditorView';+import { linearColorSpace } from '../ecs/env';+import type { Entity } from '../types';+import { resolvedLightingSky } from './volumeSystem';+import { SkyEnvironment, skyParamsOf, skySunOf } from './skyEnvironment';++/** Toward the sun from the first directional light that shines: the way the sky's shader finds it (the light's aim reversed). */+function sunFromLights(lights: Iterable<[Entity, LightData, TransformData]>): [number, number, number] | null {+ for (const [, light, transform] of lights) {+ if (!light.enabled || light.intensity <= 0 || light.type !== LightType.Directional) continue;+ const q = transform.worldRotation;+ // The aim is the rotation's -Z: q * (0, 0, -1) * q^-1, written out.+ const ax = -(2 * (q.x * q.z + q.w * q.y));+ const ay = -(2 * (q.y * q.z - q.w * q.x));+ const az = -(1 - 2 * (q.x * q.x + q.y * q.y));+ const n = Math.hypot(ax, ay, az) || 1;+ return [-ax / n, -ay / n, -az / n];+ }+ return null;+}++/** The Sky Atmosphere as the scene's environment, after the volumes have resolved it for the view being drawn. */+function skyEnvironmentSystem(app: App, sky: SkyEnvironment) {+ return defineSystem(+ [Query(Light, Transform)],+ (lights: Iterable<[Entity, LightData, TransformData]>) => {+ if (!app.hasResource(PostProcess)) return;+ const view = app.hasResource(EditorView) ? app.getResource(EditorView) : null;+ const effect = resolvedLightingSky(app.getResource(PostProcess), !!view?.active);+ if (!effect) { sky.update(app.wasmModule, null, 0); return; }+ const params = skyParamsOf(effect);+ sky.update(app.wasmModule, { sun: skySunOf(params, sunFromLights(lights)), params, linear: linearColorSpace() },+ performance.now() / 1000);+ },+ { name: 'SkyEnvironmentSystem', runWhenPaused: true },+ );+}export class PostProcessPlugin implements Plugin {name = 'postProcess';readonly profileDomain = 'render';+ /** Each App's own: the plugin is one object, and an editor holds several apps (the edit world, a game playing). */+ private readonly skies_ = new WeakMap<App, SkyEnvironment>();build(app: App): void {// Per-App post-process API, injected into the render pipeline as an@@ -33,10 +76,18 @@ export class PostProcessPlugin implements Plugin {app.addSystemToSchedule(Schedule.PostUpdate, weatherSystem);app.addSystemToSchedule(Schedule.PostUpdate, postProcessVolumeSystem);app.addSystemToSchedule(Schedule.PostUpdate, editorViewVolumeSystem(app));+ // After the volumes: it lights the scene with the sky they resolved.+ const sky = new SkyEnvironment();+ this.skies_.set(app, sky);+ app.addSystemToSchedule(Schedule.PostUpdate, skyEnvironmentSystem(app, sky));}cleanup(app?: App): void {resetWeatherSystem();+ if (app) {+ this.skies_.get(app)?.release(app.wasmModule);+ this.skies_.delete(app);+ }if (app?.hasResource(PostProcess)) {cleanupVolumeSystem(app.getResource(PostProcess));}diff --git a/sdk/src/postprocess/effects.ts b/sdk/src/postprocess/effects.tsindex ee8d113d2..dd6b653d5 100644--- a/sdk/src/postprocess/effects.ts+++ b/sdk/src/postprocess/effects.ts@@ -406,6 +406,9 @@ registerEffect({{ name: 'u_planetZ', label: 'Planet Centre Z', min: -100000000, max: 100000000, step: 100, defaultValue: 0 },// How bright the sky is.{ name: 'u_intensity', label: 'Brightness', min: 0, max: 8, step: 0.01, defaultValue: 1 },+ // The sky as the scene's environment: every Ambient light that names no environment of its own lights with this sky (its diffuse+ // light and its reflection), worked out again as the sky changes. Off, the sky is only seen (postprocess/skyEnvironment).+ { name: 'u_lightScene', label: 'Light the Scene', min: 0, max: 1, step: 1, defaultValue: 0, neutralValue: 0 },// How much of the sky behind the scene (a panorama, a clear colour) is kept: 0 replaces it, 1 leaves it.{ name: 'u_panorama', label: 'Keep Background', min: 0, max: 1, step: 0.01, defaultValue: 0, neutralValue: 1 },// 0 is the weather's to say not at all; 1 a sky with no break in it. A Weather component drives it.diff --git a/sdk/src/postprocess/skyEnvironment.ts b/sdk/src/postprocess/skyEnvironment.tsnew file mode 100644index 000000000..65bf50a7c--- /dev/null+++ b/sdk/src/postprocess/skyEnvironment.ts@@ -0,0 +1,442 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file skyEnvironment.ts+ * @brief The Sky Atmosphere as the scene's environment: the light the sky sends down, and what a surface sees of it.+ *+ * @details With Sky Atmosphere's **Light the Scene** on, the dome the effect draws is worked out here too, on the CPU, by the+ * same expressions (single scattering through the air, the cloud slab marched against the same noise), as a small+ * panorama of radiance. That panorama is made into an environment the way an imported `.hdr` is (nine irradiance+ * coefficients and a prefiltered octahedral reflection, lightmap/environmentAtlas) and handed to the frame as its sky+ * environment, which every Ambient light that names no environment of its own then lights with: its colour and+ * intensity scale it, as they scale an imported one.+ *+ * The sun's disc is left out: the directional light the sky follows is the sun's direct light, and counting the disc+ * in the environment as well would light the scene twice from it. A night sky's moon and stars are left out for+ * the same kind of reason (they are points, and the nine coefficients cannot hold them); its glow is kept.+ *+ * A sky that changes (a sun that moves, a weather coming in, clouds drifting) is worked out again, at most once a+ * second, and only when what it is made from has moved by more than can be seen in its light.+ */+import { getEffectDef } from './effects';+import type { BlendedEffect } from './volumeBlending';+import { projectIrradianceSH, prefilterOctahedral, type Panorama } from '../lightmap/environmentAtlas';+import { panoramaDirection } from '../lightmap/panorama';+import { createTextureFromPixels } from '../runtime/runtimeAssets';+import { getResourceManager } from '../wasm/resourceManager';+import { TextureContent } from '../wasm';+import type { ESEngineModule } from '../wasm';+import { withScratch } from '../wasm/wasmScratch';+import { log } from '../util/logger';++/** What the sky is made from: the effect's resolved parameters and the direction toward the sun. */+export interface SkyEnvironmentInput {+ /** Toward the sun, unit. */+ sun: [number, number, number];+ params: (name: string) => number;+ /** Whether the frame lights in linear space (the effect's small constant colours are authored sRGB). */+ linear: boolean;+}++// The constants of the effect's own shader (sources/atmosphere.ts): kilometres, per kilometre.+const R_E = 6360;+const R_A = 6420;+const BETA_R = [0.0058, 0.0135, 0.0331] as const;+const BETA_M = 0.021;+const H_R = 8;+const H_M = 1.2;+const SUN_I = 22;++const fract = (x: number): number => x - Math.floor(x);+const mix = (a: number, b: number, t: number): number => a + (b - a) * t;+const clamp01 = (x: number): number => Math.min(Math.max(x, 0), 1);+const smoothstep = (a: number, b: number, x: number): number => {+ const t = clamp01((x - a) / (b - a));+ return t * t * (3 - 2 * t);+};+const toLinear = (c: number): number => (c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4);++function hash13(x: number, y: number, z: number): number {+ let px = fract(x * 0.1031), py = fract(y * 0.1031), pz = fract(z * 0.1031);+ const d = px * (pz + 31.32) + py * (py + 31.32) + pz * (px + 31.32);+ px += d; py += d; pz += d;+ return fract((px + py) * pz);+}++function vnoise(x: number, y: number, z: number): number {+ const ix = Math.floor(x), iy = Math.floor(y), iz = Math.floor(z);+ let fx = x - ix, fy = y - iy, fz = z - iz;+ fx = fx * fx * (3 - 2 * fx); fy = fy * fy * (3 - 2 * fy); fz = fz * fz * (3 - 2 * fz);+ const a = mix(hash13(ix, iy, iz), hash13(ix + 1, iy, iz), fx);+ const b = mix(hash13(ix, iy + 1, iz), hash13(ix + 1, iy + 1, iz), fx);+ const c = mix(hash13(ix, iy, iz + 1), hash13(ix + 1, iy, iz + 1), fx);+ const d = mix(hash13(ix, iy + 1, iz + 1), hash13(ix + 1, iy + 1, iz + 1), fx);+ return mix(mix(a, b, fy), mix(c, d, fy), fz);+}++/** Where a ray from o along d leaves the sphere of radius r about the planet's centre; -1 for a miss. */+function sphereExit(oy: number, dy: number, r: number): number {+ // o = (0, oy, 0): b = oy * dy, |o|^2 = oy^2.+ const b = oy * dy;+ const disc = b * b - (oy * oy - r * r);+ return disc < 0 ? -1 : -b + Math.sqrt(disc);+}++/** The air between p and the top of the atmosphere along d as (Rayleigh, Mie) optical depth, or null where the planet is in the way. */+function lightDepth(px: number, py: number, pz: number, dx: number, dy: number, dz: number): [number, number] | null {+ const b = px * dx + py * dy + pz * dz;+ const pp = px * px + py * py + pz * pz;+ const discE = b * b - (pp - R_E * R_E);+ if (discE >= 0) {+ const s = Math.sqrt(discE);+ if (-b - s > 0 && -b + s > 0) return null;+ }+ const discA = b * b - (pp - R_A * R_A);+ const len = discA < 0 ? 0 : -b + Math.sqrt(discA);+ const ds = len / 4;+ let r = 0, m = 0;+ for (let j = 0; j < 4; j++) {+ const t = ds * (j + 0.5);+ const qx = px + dx * t, qy = py + dy * t, qz = pz + dz * t;+ const h = Math.hypot(qx, qy, qz) - R_E;+ r += Math.exp(-h / H_R) * ds;+ m += Math.exp(-h / H_M) * ds;+ }+ return [r, m];+}++/** The sky's radiance along dir by single scattering (the effect's `scatter`), and the sun's light where the eye is. */+function scatter(dir: readonly number[], sun: readonly number[], alt: number, haze: number,+ out: Float64Array, sunTrans: Float64Array): void {+ const oy = R_E + alt;+ const len = sphereExit(oy, dir[1]!, R_A);+ const N = 16;+ const ds = len / N;+ const mu = dir[0]! * sun[0]! + dir[1]! * sun[1]! + dir[2]! * sun[2]!;+ const g = 0.76;+ const phaseR = 3 / (16 * Math.PI) * (1 + mu * mu);+ const phaseM = 3 / (8 * Math.PI) * ((1 - g * g) * (1 + mu * mu)) / ((2 + g * g) * (1 + g * g - 2 * g * mu) ** 1.5);+ let odR = 0, odM = 0;+ let rR = 0, rG = 0, rB = 0, mR = 0, mG = 0, mB = 0;+ const kM = BETA_M * haze * 1.1;+ for (let i = 0; i < N; i++) {+ const t = ds * (i + 0.5);+ const px = dir[0]! * t, py = oy + dir[1]! * t, pz = dir[2]! * t;+ const h = Math.hypot(px, py, pz) - R_E;+ const dR = Math.exp(-h / H_R) * ds, dM = Math.exp(-h / H_M) * ds;+ odR += dR; odM += dM;+ const ol = lightDepth(px, py, pz, sun[0]!, sun[1]!, sun[2]!);+ if (!ol) continue;+ const tr = odR + ol[0], tm = odM + ol[1];+ const ar = Math.exp(-(BETA_R[0] * tr + kM * tm));+ const ag = Math.exp(-(BETA_R[1] * tr + kM * tm));+ const ab = Math.exp(-(BETA_R[2] * tr + kM * tm));+ rR += ar * dR; rG += ag * dR; rB += ab * dR;+ mR += ar * dM; mG += ag * dM; mB += ab * dM;+ }+ const st = lightDepth(0, oy, 0, sun[0]!, sun[1]!, sun[2]!);+ for (let c = 0; c < 3; c++) {+ sunTrans[c] = st ? Math.exp(-(BETA_R[c]! * st[0] + kM * st[1])) : 0;+ }+ const kMs = BETA_M * haze * phaseM;+ out[0] = (rR * BETA_R[0] * phaseR + mR * kMs) * SUN_I;+ out[1] = (rG * BETA_R[1] * phaseR + mG * kMs) * SUN_I;+ out[2] = (rB * BETA_R[2] * phaseR + mB * kMs) * SUN_I;+}++interface CloudParams {+ coverage: number; base: number; thick: number; alt: number; scale: number; softness: number; evolve: number;+ silver: number; brightness: number; driftX: number; driftZ: number;+ c2: { coverage: number; base: number; thick: number; scale: number; driftX: number; driftZ: number };+}++function cloudDensity(x: number, y: number, z: number, p: CloudParams, octaves: number): number {+ const h = clamp01((y - p.base) / p.thick);+ const shape = smoothstep(0, 0.14, h) * smoothstep(1, 0.55, h);+ if (shape <= 0) return 0;+ const k = 0.32 * p.scale;+ const qx = x * k, qy = (y * 1.8 + p.evolve) * k, qz = z * k;+ let n = vnoise(qx, qy, qz) * 0.58 + vnoise(qx * 2.13, qy * 2.13, qz * 2.13) * 0.28;+ n += octaves > 2 ? vnoise(qx * 4.7, qy * 4.7, qz * 4.7) * 0.14 : 0.07;+ let d = smoothstep(1 - p.coverage, 1 - p.coverage + p.softness, n) * shape;+ if (octaves > 2 && d > 0 && d < 0.9) d = Math.max(d - (1 - d) * vnoise(qx * 11, qy * 11, qz * 11) * 0.55, 0);+ return d;+}++function cloud2Density(x: number, y: number, z: number, p: CloudParams): number {+ const c = p.c2;+ const h = clamp01((y - c.base) / c.thick);+ const shape = smoothstep(0, 0.3, h) * smoothstep(1, 0.5, h);+ if (shape <= 0) return 0;+ const k = 0.32 * c.scale;+ const qx = x * k, qy = (y * 3 + p.evolve * 1.7) * k, qz = z * k;+ const n = vnoise(qx, qy, qz) * 0.62 + vnoise(qx * 2.31, qy * 2.31, qz * 2.31) * 0.38;+ return smoothstep(1 - c.coverage, 1 - c.coverage + 0.3, n) * shape;+}++function cloudPhase(cosS: number, silver: number): number {+ const G = 0.86;+ return 0.42 + 0.018 * silver * (1 - G * G) / (1 + G * G - 2 * G * cosS) ** 1.5;+}++/** The cloud slab along dir as colour * T + L (the effect's `cloudLayer`), with the march's jitter at its middle. */+function cloudLayer(dir: readonly number[], sun: readonly number[], dome: Float64Array, sunTrans: Float64Array,+ nightGlow: readonly number[], overcast: number, p: CloudParams, L: Float64Array): number {+ L[0] = 0; L[1] = 0; L[2] = 0;+ let T = 1;+ const fade = smoothstep(0.01, 0.14, dir[1]!);+ const cosS = dir[0]! * sun[0]! + dir[1]! * sun[1]! + dir[2]! * sun[2]!;+ const amb = [dome[0]! * 0.7 + nightGlow[0]!, dome[1]! * 0.7 + nightGlow[1]!, dome[2]! * 0.7 + nightGlow[2]!];+ const sunL = [sunTrans[0]! * 1.2 * p.brightness, sunTrans[1]! * 1.2 * p.brightness, sunTrans[2]! * 1.2 * p.brightness];+ if (p.coverage > 0.01 && dir[1]! > 0.01) {+ const tb = Math.max(p.base - p.alt, 0) / dir[1]!;+ const tt = Math.min((p.base + p.thick - p.alt) / dir[1]!, tb + p.thick * 6);+ const STEPS = 16;+ const ds = (tt - tb) / STEPS;+ const sigma = 1.3 * (1 + overcast * 1.5);+ const phase = cloudPhase(cosS, p.silver);+ let trans = 1, lr = 0, lg = 0, lb = 0;+ for (let i = 0; i < STEPS && trans >= 0.02; i++) {+ const t = tb + (i + 0.5) * ds;+ const x = dir[0]! * t + p.driftX, y = p.alt + dir[1]! * t, z = dir[2]! * t + p.driftZ;+ const d = cloudDensity(x, y, z, p, 3);+ if (d < 0.002) continue;+ let tau = 0;+ const reach = Math.max(p.thick, 0.5) * 0.14;+ for (let k = 1; k <= 3; k++) {+ const along = reach * k * k;+ tau += cloudDensity(x + sun[0]! * along, y + sun[1]! * along, z + sun[2]! * along, p, 2) * reach * (2 * k - 1) * sigma;+ }+ const energy = (Math.exp(-tau * 1.1) + 0.25 * Math.exp(-tau * 0.25)) * mix(1, 1 - Math.exp(-(d * sigma * ds + tau) * 3), 0.5);+ const tr = Math.exp(-d * sigma * ds);+ const w = trans * (1 - tr);+ lr += w * (sunL[0]! * energy * phase * 2 + amb[0]!);+ lg += w * (sunL[1]! * energy * phase * 2 + amb[1]!);+ lb += w * (sunL[2]! * energy * phase * 2 + amb[2]!);+ trans *= tr;+ }+ T = mix(1, trans, fade);+ L[0] = lr * fade; L[1] = lg * fade; L[2] = lb * fade;+ }+ const c2 = p.c2;+ if (c2.coverage > 0.01 && dir[1]! > 0.01) {+ const tb = Math.max(c2.base - p.alt, 0) / dir[1]!;+ const tt = Math.max(c2.base + c2.thick - p.alt, 0) / dir[1]!;+ const STEPS = 6;+ const ds = (tt - tb) / STEPS;+ const sigma = 1.3 * (1 + overcast);+ const phase = cloudPhase(cosS, p.silver);+ let trans = 1, lr = 0, lg = 0, lb = 0;+ for (let i = 0; i < STEPS; i++) {+ const t = tb + (i + 0.5) * ds;+ const x = dir[0]! * t + p.driftX + c2.driftX, y = p.alt + dir[1]! * t, z = dir[2]! * t + p.driftZ + c2.driftZ;+ const d = cloud2Density(x, y, z, p);+ if (d < 0.002) continue;+ const half = c2.thick * 0.5;+ const tau = cloud2Density(x + sun[0]! * half, y + sun[1]! * half, z + sun[2]! * half, p) * half * sigma;+ const e = Math.exp(-tau) * phase * 2;+ const tr = Math.exp(-d * sigma * ds);+ const w = trans * (1 - tr);+ lr += w * (sunL[0]! * e + amb[0]!); lg += w * (sunL[1]! * e + amb[1]!); lb += w * (sunL[2]! * e + amb[2]!);+ trans *= tr;+ }+ trans = mix(1, trans, fade);+ lr *= fade; lg *= fade; lb *= fade;+ if (c2.base >= p.base) { L[0] += T * lr; L[1] += T * lg; L[2] += T * lb; }+ else { L[0] = lr + trans * L[0]!; L[1] = lg + trans * L[1]!; L[2] = lb + trans * L[2]!; }+ T *= trans;+ }+ return T;+}++/**+ * The sky the effect draws along `dir`, without the sun's disc, the moon or the stars: the dome, the glow a night keeps, the+ * clouds over it and the grey an overcast lends it. In the frame's units, before exposure.+ */+export function skyRadianceAt(dir: readonly number[], input: SkyEnvironmentInput, out: Float64Array): void {+ const P = input.params;+ const sun = input.sun;+ const overcast = clamp01(P('u_overcast'));+ const haze = P('u_haze') * (1 + overcast * 2);+ const lin = (c: number): number => (input.linear ? toLinear(c) : c);++ const dy = Math.max(dir[1]!, 0.015);+ const n = Math.hypot(dir[0]!, dy, dir[2]!);+ const sdir = [dir[0]! / n, dy / n, dir[2]! / n];+ const dome = new Float64Array(3);+ const sunTrans = new Float64Array(3);+ scatter(sdir, sun, P('u_altitude'), haze, dome, sunTrans);+ const below = 1 - 0.75 * smoothstep(0, -0.3, dir[1]!);+ const k = 0.55 * P('u_intensity') * below;+ dome[0]! *= k; dome[1]! *= k; dome[2]! *= k;++ const night = 1 - smoothstep(-0.1, 0.12, sun[1]!);+ const up = (1 - Math.max(dir[1]!, 0)) ** 3;+ const glow = [mix(lin(0.003), lin(0.016), up) * night, mix(lin(0.006), lin(0.024), up) * night, mix(lin(0.02), lin(0.06), up) * night];+ for (let c = 0; c < 3; c++) dome[c]! += glow[c]!;+ out[0] = dome[0]!; out[1] = dome[1]!; out[2] = dome[2]!;++ const coverage = Math.max(P('u_clouds'), overcast * 0.95);+ if ((coverage > 0.01 || P('u_cloud2Coverage') > 0.01) && dir[1]! > 0.01) {+ const cloudNight = [lin(0.55) * 0.015 * night, lin(0.65) * 0.015 * night, lin(0.9) * 0.015 * night];+ const L = new Float64Array(3);+ const T = cloudLayer(dir, sun, dome, sunTrans, cloudNight, overcast, {+ coverage, base: P('u_cloudBase'), thick: P('u_cloudThickness'), alt: P('u_altitude'), scale: P('u_cloudScale'),+ softness: P('u_cloudSoftness'), evolve: P('u_cloudEvolve'), silver: P('u_cloudSilver'), brightness: P('u_cloudBrightness'),+ driftX: P('u_cloudDriftX'), driftZ: P('u_cloudDriftZ'),+ c2: { coverage: P('u_cloud2Coverage'), base: P('u_cloud2Base'), thick: P('u_cloud2Thickness'), scale: P('u_cloud2Scale'),+ driftX: P('u_cloud2DriftX') - P('u_cloudDriftX'), driftZ: P('u_cloud2DriftZ') - P('u_cloudDriftZ') },+ }, L);+ for (let c = 0; c < 3; c++) out[c] = out[c]! * T + L[c]!;+ }+ const luma = 0.2126 * out[0]! + 0.7152 * out[1]! + 0.0722 * out[2]!;+ for (let c = 0; c < 3; c++) out[c] = mix(out[c]!, luma, overcast * 0.5);+}++/** The sky as an equirectangular panorama of radiance, `width` by `width / 2` (panoramaDirection's mapping). */+export function skyPanorama(input: SkyEnvironmentInput, width = SKY_PANORAMA_WIDTH): Panorama {+ const height = Math.max(2, width >> 1);+ const rgb = new Float32Array(width * height * 3);+ const c = new Float64Array(3);+ for (let y = 0; y < height; y++) {+ for (let x = 0; x < width; x++) {+ skyRadianceAt(panoramaDirection((x + 0.5) / width, (y + 0.5) / height), input, c);+ const o = (y * width + x) * 3;+ rgb[o] = c[0]!; rgb[o + 1] = c[1]!; rgb[o + 2] = c[2]!;+ }+ }+ return { width, height, rgb };+}++/** Small: the light a sky sends is smooth, and its reflection on anything but a mirror is a blur of it. */+export const SKY_PANORAMA_WIDTH = 64;+export const SKY_FACE_SIZE = 32;+export const SKY_MIP_COUNT = 3;+export const SKY_MAX_RANGE = 8;++/** The parameters of a resolved Sky Atmosphere, its own default where the volume says nothing. */+export function skyParamsOf(effect: BlendedEffect): (name: string) => number {+ const def = getEffectDef('skyAtmosphere');+ return (name) => effect.uniforms.get(name) ?? def?.uniforms.find((u) => u.name === name)?.defaultValue ?? 0;+}++/** Toward the sun as the effect places it: the first directional light when it follows one, else its own azimuth and elevation. */+export function skySunOf(params: (name: string) => number, light: [number, number, number] | null): [number, number, number] {+ if (params('u_followSun') > 0.5 && light) return light;+ const az = params('u_sunAzimuth') * Math.PI / 180, el = params('u_sunElevation') * Math.PI / 180;+ return [Math.cos(el) * Math.sin(az), Math.sin(el), Math.cos(el) * Math.cos(az)];+}++/**+ * What the sky is made from, rounded to what can be seen in its light: a key that changes only when the environment would.+ * The cloud drift is rounded coarsest — a drifting sky lights the ground the same from one second to the next.+ */+export function skyEnvironmentKey(input: SkyEnvironmentInput): string {+ const P = input.params;+ const r = (v: number, step: number): number => Math.round(v / step);+ const parts = [+ r(input.sun[0], 0.004), r(input.sun[1], 0.004), r(input.sun[2], 0.004),+ r(P('u_intensity'), 0.01), r(P('u_haze'), 0.02), r(P('u_overcast'), 0.01), r(P('u_altitude'), 0.05),+ r(P('u_clouds'), 0.01), r(P('u_cloudBase'), 0.02), r(P('u_cloudThickness'), 0.02), r(P('u_cloudBrightness'), 0.02),+ r(P('u_cloudScale'), 0.02), r(P('u_cloudSoftness'), 0.01), r(P('u_cloudSilver'), 0.05),+ r(P('u_cloud2Coverage'), 0.01), r(P('u_cloud2Base'), 0.05), r(P('u_cloud2Thickness'), 0.05), r(P('u_cloud2Scale'), 0.05),+ r(P('u_cloudDriftX'), 0.5), r(P('u_cloudDriftZ'), 0.5), r(P('u_cloudEvolve'), 0.25),+ input.linear ? 1 : 0,+ ];+ return parts.join(',');+}++/** A sky made into an environment: what the frame is handed, and the reflection atlas it holds. */+interface BakedSky {+ environment: number;+ texture: number;+}++interface SkyEnvironmentCore {+ HEAPF32: Float32Array;+ environment_create?(shPtr: number, specularHandle: number, faceSize: number, mipCount: number, maxRange: number, columns: number): number;+ environment_release?(environmentHandle: number): void;+ renderer_setSkyEnvironment?(environmentHandle: number): void;+}++/**+ * The sky environment the frame lights with: worked out again when the sky changes, at most once a `minInterval` seconds, and+ * let go (the frame told it has none) when no Sky Atmosphere asks to light the scene.+ */+export class SkyEnvironment {+ private baked_: BakedSky | null = null;+ private key_ = '';+ private lastBake_ = -Infinity;+ private warned_ = false;++ constructor(private readonly minInterval = 1) {}++ /** The environment handle the frame is lighting with, 0 when none. */+ get environment(): number { return this.baked_?.environment ?? 0; }++ update(module: ESEngineModule | null, input: SkyEnvironmentInput | null, now: number): void {+ const core = module as unknown as SkyEnvironmentCore | null;+ if (!core?.environment_create || !core.renderer_setSkyEnvironment) {+ if (input && !this.warned_) {+ this.warned_ = true;+ log.warn('postprocess', 'Sky Atmosphere cannot light the scene: this engine build has no sky environment');+ }+ return;+ }+ if (!input) {+ if (this.baked_) {+ core.renderer_setSkyEnvironment(0);+ this.drop(core);+ this.key_ = '';+ }+ return;+ }+ const key = skyEnvironmentKey(input);+ if (key === this.key_) return;+ // A first sky is made at once; a sky that keeps changing waits its turn.+ if (this.baked_ && now - this.lastBake_ < this.minInterval) return;+ const made = bakeSky(module, core, input);+ if (!made) return;+ core.renderer_setSkyEnvironment(made.environment);+ this.drop(core);+ this.baked_ = made;+ this.key_ = key;+ this.lastBake_ = now;+ }++ /** Lets the environment and its atlas go and tells the frame. */+ release(module: ESEngineModule | null): void {+ const core = module as unknown as SkyEnvironmentCore | null;+ if (!core) return;+ if (this.baked_) core.renderer_setSkyEnvironment?.(0);+ this.drop(core);+ this.key_ = '';+ }++ private drop(core: SkyEnvironmentCore): void {+ if (!this.baked_) return;+ core.environment_release?.(this.baked_.environment);+ getResourceManager()?.releaseTexture(this.baked_.texture);+ this.baked_ = null;+ }+}++function bakeSky(module: ESEngineModule | null, core: SkyEnvironmentCore, input: SkyEnvironmentInput): BakedSky | null {+ const panorama = skyPanorama(input);+ const irradiance = projectIrradianceSH(panorama);+ const atlas = prefilterOctahedral(panorama, SKY_FACE_SIZE, SKY_MIP_COUNT, SKY_MAX_RANGE);+ // flipY false: the atlas' rows are a layout (row 0 is mip 0), as the environment loader takes it.+ const texture = createTextureFromPixels(module, { width: atlas.width, height: atlas.height, pixels: atlas.rgba },+ TextureContent.Retained, false, { filterMode: 'linear', wrapMode: 'clamp', srgb: false });+ if (!texture) return null;+ const environment = withScratch(core as never, (alloc: (bytes: number) => number) => {+ const shPtr = alloc(27 * 4);+ core.HEAPF32.set(irradiance, shPtr >> 2);+ return core.environment_create!(shPtr, texture, SKY_FACE_SIZE, SKY_MIP_COUNT, SKY_MAX_RANGE, 1);+ });+ if (!environment) {+ getResourceManager()?.releaseTexture(texture);+ return null;+ }+ return { environment, texture };+}diff --git a/sdk/src/postprocess/volumeSystem.ts b/sdk/src/postprocess/volumeSystem.tsindex 4221fef89..364a7a550 100644--- a/sdk/src/postprocess/volumeSystem.ts+++ b/sdk/src/postprocess/volumeSystem.ts@@ -318,6 +318,30 @@ export function effectsAt(volumes: { data: PostProcessVolumeData; tx: VolumeTranreturn blended;}+/** The Sky Atmosphere a view resolved this frame, where it asks to light the scene: the game's camera and the editor's eye each. */+interface ResolvedSkies { game: BlendedEffect | null; editor: BlendedEffect | null }+const resolvedSkies = new WeakMap<PostProcessAPI, ResolvedSkies>();++function skiesOf(api: PostProcessAPI): ResolvedSkies {+ let s = resolvedSkies.get(api);+ if (!s) { s = { game: null, editor: null }; resolvedSkies.set(api, s); }+ return s;+}++const lightingSky = (effects: ResolvedEffects): BlendedEffect | null => {+ const sky = effects.get('skyAtmosphere');+ return sky?.enabled && (sky.uniforms.get('u_lightScene') ?? 0) > 0.5 ? sky : null;+};++/**+ * The Sky Atmosphere that lights the scene this frame, as resolved for the view being drawn: the editor's eye while it looks,+ * else the first active game camera's. Null when that view's sky does not ask to light the scene (or there is none).+ */+export function resolvedLightingSky(api: PostProcessAPI, editorLooking: boolean): BlendedEffect | null {+ const s = skiesOf(api);+ return editorLooking ? s.editor : s.game;+}+export const postProcessVolumeSystem = defineSystem([Res(PostProcess), Query(PostProcessVolume, Transform), Query(Camera, Transform)],(@@ -334,10 +358,16 @@ export const postProcessVolumeSystem = defineSystem(}// Recomputed per camera: a local volume's weight depends on the camera position.+ const skies = skiesOf(api);+ skies.game = null;+ let first = true;for (const [cameraEntity, cameraData, cameraTransform] of cameraQuery) {if (!cameraData.isActive) continue;const p = cameraTransform.position;- applyBlendedEffects(api, cameraEntity, effectsAt(volumes, p.x, p.y, p.z), cameraData.projectionType !== ProjectionType.Orthographic);+ const effects = effectsAt(volumes, p.x, p.y, p.z);+ // The scene has one environment: the first camera's sky lights it.+ if (first) { skies.game = lightingSky(effects); first = false; }+ applyBlendedEffects(api, cameraEntity, effects, cameraData.projectionType !== ProjectionType.Orthographic);}},{ name: 'PostProcessVolumeSystem', runWhenPaused: true }@@ -354,6 +384,7 @@ export function editorViewVolumeSystem(app: App) {const view = app.hasResource(EditorView) ? app.getResource(EditorView) : null;const eye = EDITOR_VIEW_ENTITY as Entity;if (!view || !view.active || !app.getResource(PostProcessVolumeConfigResource).enabled) {+ skiesOf(api).editor = null;if (api.volumeStacks.has(eye)) applyBlendedEffects(api, eye, new Map() as ResolvedEffects, false);return;}@@ -362,7 +393,9 @@ export function editorViewVolumeSystem(app: App) {volumes.push({ data: volumeData, tx: { x: transform.position.x, y: transform.position.y, z: transform.position.z } });}const at = view.perspective ? editorViewEye(view) : { x: view.x, y: view.y, z: view.z };- applyBlendedEffects(api, eye, effectsAt(volumes, at.x, at.y, at.z), view.perspective);+ const effects = effectsAt(volumes, at.x, at.y, at.z);+ skiesOf(api).editor = lightingSky(effects);+ applyBlendedEffects(api, eye, effects, view.perspective);},{ name: 'EditorViewVolumeSystem', runWhenPaused: true },);diff --git a/sdk/src/wasm.ts b/sdk/src/wasm.tsindex 0cb2485ff..128a56a34 100644--- a/sdk/src/wasm.ts+++ b/sdk/src/wasm.ts@@ -350,6 +350,8 @@ export interface ESEngineModule {/** Release an environment; its atlas is an ordinary texture and outlives it. */environment_release?(environmentHandle: number): void;environment_setSky?(environmentHandle: number, skyHandle: number): void;+ /** The environment the sky lights the scene with, 0 for none (postprocess/skyEnvironment). */+ renderer_setSkyEnvironment?(environmentHandle: number): void;/*** Give an environment the sun its importer separated from the sky: 27 floats of* irradiance without it, the direction toward it (panorama frame) and itsdiff --git a/sdk/tests/sky-environment.test.ts b/sdk/tests/sky-environment.test.tsnew file mode 100644index 000000000..15e3f07d0--- /dev/null+++ b/sdk/tests/sky-environment.test.ts@@ -0,0 +1,86 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+import { describe, it, expect } from 'vitest';+import { skyRadianceAt, skyPanorama, skyEnvironmentKey, skySunOf, type SkyEnvironmentInput } from '../src/postprocess/skyEnvironment';+import { projectIrradianceSH } from '../src/lightmap/environmentAtlas';+import { evalIrradianceSH } from '../src/lightmap/sh';+import { getEffectDef } from '../src/postprocess/effects';++const defaults = (over: Record<string, number> = {}) => (name: string): number =>+ over[name] ?? getEffectDef('skyAtmosphere')!.uniforms.find((u) => u.name === name)?.defaultValue ?? 0;++const sunAt = (elevationDeg: number): [number, number, number] => {+ const e = elevationDeg * Math.PI / 180;+ return [0, Math.sin(e), Math.cos(e)];+};++const clear = (elevation = 35, over: Record<string, number> = {}): SkyEnvironmentInput =>+ ({ sun: sunAt(elevation), params: defaults({ u_clouds: 0, ...over }), linear: true });++const at = (input: SkyEnvironmentInput, d: [number, number, number]): number[] => {+ const n = Math.hypot(...d);+ const out = new Float64Array(3);+ skyRadianceAt(d.map((v) => v / n), input, out);+ return [...out];+};++describe('sky environment', () => {+ it('is a blue sky by day, bluer overhead than at the horizon', () => {+ const zenith = at(clear(), [0, 1, 0]);+ const horizon = at(clear(), [-1, 0.05, 0]);+ expect(zenith[2]).toBeGreaterThan(zenith[0]!);+ expect(zenith[2]! / zenith[0]!).toBeGreaterThan(horizon[2]! / horizon[0]!);+ });++ it('is brighter toward the sun, and redder there when the sun is low', () => {+ const low = clear(4);+ const toward = at(low, [0, 0.1, 1]);+ const away = at(low, [0, 0.1, -1]);+ expect(toward[0]!).toBeGreaterThan(away[0]! * 1.5);+ expect(toward[0]! / toward[2]!).toBeGreaterThan(away[0]! / away[2]!);+ });++ it('greys and dims under an overcast', () => {+ const sky = at(clear(35), [0, 1, 0]);+ const grey = at(clear(35, { u_overcast: 1 }), [0, 1, 0]);+ const spread = (c: number[]): number => (Math.max(...c) - Math.min(...c)) / Math.max(...c);+ expect(spread(grey)).toBeLessThan(spread(sky));+ });++ it('does not draw the sun disc: the direct light is the directional light\'s', () => {+ const input = clear(35);+ const disc = at(input, input.sun);+ const beside = at(input, [0, Math.sin(37 * Math.PI / 180), Math.cos(37 * Math.PI / 180)]);+ expect(disc[1]!).toBeLessThan(beside[1]! * 1.5);+ });++ it('lights what faces up more than what faces down, in the sky\'s colour', () => {+ const sh = projectIrradianceSH(skyPanorama(clear(35)));+ const up = evalIrradianceSH(sh, 0, 1, 0);+ const down = evalIrradianceSH(sh, 0, -1, 0);+ // Below the horizon is what the effect draws there: the horizon's haze at a quarter, the light a ground sends back.+ expect(up[1]!).toBeGreaterThan(down[1]! * 1.5);+ expect(up[2]!).toBeGreaterThan(up[0]!);+ });++ it('lights the scene with clouds over it as well', () => {+ const cloudy = projectIrradianceSH(skyPanorama({ ...clear(35), params: defaults({ u_clouds: 0.8 }) }));+ const up = evalIrradianceSH(cloudy, 0, 1, 0);+ expect(up.every((v) => Number.isFinite(v) && v > 0)).toBe(true);+ });++ it('keeps its key while nothing visible changes, and changes it when the sun moves', () => {+ const a = clear(35);+ expect(skyEnvironmentKey(a)).toBe(skyEnvironmentKey({ ...a, sun: sunAt(35.01) }));+ expect(skyEnvironmentKey(a)).not.toBe(skyEnvironmentKey({ ...a, sun: sunAt(40) }));+ expect(skyEnvironmentKey(a)).toBe(skyEnvironmentKey({ ...a, params: defaults({ u_clouds: 0, u_cloudDriftX: 0.1 }) }));+ });++ it('follows the directional light when told to, else its own azimuth and elevation', () => {+ const light: [number, number, number] = [1, 0, 0];+ expect(skySunOf(defaults({ u_followSun: 1 }), light)).toEqual(light);+ const own = skySunOf(defaults({ u_followSun: 0, u_sunAzimuth: 0, u_sunElevation: 90 }), light);+ expect(own[1]).toBeCloseTo(1);+ expect(skySunOf(defaults({ u_followSun: 1, u_sunAzimuth: 0, u_sunElevation: 90 }), null)[1]).toBeCloseTo(1);+ });+});diff --git a/src/esengine/bindings/RendererBindings.cpp b/src/esengine/bindings/RendererBindings.cppindex 884b9eed7..fab736743 100644--- a/src/esengine/bindings/RendererBindings.cpp+++ b/src/esengine/bindings/RendererBindings.cpp@@ -30,6 +30,8 @@#include "../core/EntityPose2D.hpp"#include "../ecs/components/Camera.hpp"#include "../ecs/components/Canvas.hpp"+#include "../ecs/components/UINode.hpp"+#include "../ecs/components/Hierarchy.hpp"#include "../ecs/components/Transform.hpp"#include "../ecs/components/Sprite.hpp"#include "../ecs/components/MeshRenderer.hpp"@@ -142,9 +144,34 @@ void renderer_submitSkeletalBatchByEntityEx(auto* vertices = boundarySpan<f32>(verticesPtr, static_cast<u64>(vertexCount) * 8, "renderer_submitSkeletalBatchByEntity.vertices");auto* indices = boundarySpan<u16>(indicesPtr, static_cast<u64>(indexCount), "renderer_submitSkeletalBatchByEntity.indices");if (!vertices || !indices) return;+ // A skeleton a Canvas holds takes what the UI tree above it says, as a control does: the+ // opacity of the nearest UINode (itself included, which already carries every ancestor's)+ // and the culling bit of the Canvas that holds it.+ f32 treeAlpha = 1.0f;+ u32 cullBit = 0;+ if (g_renderFrame->uiTreeHolds(ent)) {+ bool alphaFound = false;+ Entity at = ent;+ for (u32 guard = 0; registry.valid(at) && guard < 4096; ++guard) {+ if (!alphaFound) {+ if (const auto* node = registry.tryGet<ecs::UINode>(at)) {+ treeAlpha = node->alpha_in_tree_;+ alphaFound = true;+ }+ }+ if (const auto* canvas = registry.tryGet<ecs::Canvas>(at)) {+ cullBit = (canvas->layer < 0 || canvas->layer >= 32) ? 0u : (1u << canvas->layer);+ break;+ }+ const auto* parent = registry.tryGet<ecs::Parent>(at);+ if (!parent) break;+ at = parent->entity;+ }+ }g_renderFrame->submitSkeletalBatch(vertices, vertexCount, indices, indexCount,- textureId, blendMode, &model[0][0], ent, layer, depth, materialId, premultipliedColor);+ textureId, blendMode, &model[0][0], ent, layer, depth, materialId, premultipliedColor,+ treeAlpha, cullBit);}/**@@ -161,6 +188,10 @@ void renderer_entityVisibleToCamera(if (!out) return;*out = 1;if (!g_initialized || !g_renderFrame) return;+ // The screen overlay has no camera to be outside of: what it draws is on the screen by+ // construction (RenderCollectContext::visible), and the frustum still in hand is the last+ // camera's, which would cull a skeleton in a screen Canvas by its pixel coordinates.+ if (g_renderFrame->screenOverlayOpen()) return;const Entity ent = Entity::fromRaw(entity);if (!registry.has<ecs::Transform>(ent)) return;@@ -589,6 +620,11 @@ u32 environment_create(uintptr_t shPtr, u32 specularHandle, f32 faceSize, u32 mifaceSize, mipCount, maxRange, columns).id();}+void renderer_setSkyEnvironment(u32 environmentHandle) {+ if (!g_renderFrame) return;+ g_renderFrame->setSkyEnvironment(resource::EnvironmentHandle(environmentHandle));+}+/** @brief Gives an environment the panorama its sky is drawn from. */void environment_setSky(u32 environmentHandle, u32 skyHandle) {auto* rm = ctx().tryGet<resource::ResourceManager>();diff --git a/src/esengine/bindings/RendererBindings.hpp b/src/esengine/bindings/RendererBindings.hppindex 82645546f..2fce2971e 100644--- a/src/esengine/bindings/RendererBindings.hpp+++ b/src/esengine/bindings/RendererBindings.hpp@@ -168,6 +168,10 @@ void environment_setSun(u32 environmentHandle, uintptr_t skyShPtr, f32 dx, f32 d/** @brief Releases an environment; its atlas is an ordinary texture and outlives it. */void environment_release(u32 environmentHandle);+/** @brief The environment the sky lights the scene with, 0 for none: an Ambient light that names no+ * environment of its own lights with it (the Sky Atmosphere's Light the Scene). */+void renderer_setSkyEnvironment(u32 environmentHandle);+/** @brief Registers a grid of baked irradiance: `x*y*z*27` floats, x fastest. */u32 probe_volume_create(i32 resX, i32 resY, i32 resZ, uintptr_t shPtr);diff --git a/src/esengine/bindings/WebSDKEntry.cpp b/src/esengine/bindings/WebSDKEntry.cppindex deeb3ff0a..31a2400ba 100644--- a/src/esengine/bindings/WebSDKEntry.cpp+++ b/src/esengine/bindings/WebSDKEntry.cpp@@ -548,6 +548,7 @@ EMSCRIPTEN_BINDINGS(esengine_renderer) {emscripten::function("environment_setSky", &esengine::environment_setSky);emscripten::function("environment_setSun", &esengine::environment_setSun);emscripten::function("environment_release", &esengine::environment_release);+ emscripten::function("renderer_setSkyEnvironment", &esengine::renderer_setSkyEnvironment);emscripten::function("probe_volume_create", &esengine::probe_volume_create);emscripten::function("probe_volume_release", &esengine::probe_volume_release);emscripten::function("meshRenderer_localBounds", &esengine::meshRenderer_localBounds);diff --git a/src/esengine/renderer/frame/RenderFrame.cpp b/src/esengine/renderer/frame/RenderFrame.cppindex 21e278abc..c999a7f9e 100644--- a/src/esengine/renderer/frame/RenderFrame.cpp+++ b/src/esengine/renderer/frame/RenderFrame.cpp@@ -1645,8 +1645,8 @@ void RenderFrame::collectLights(ecs::Registry& registry) {if (!light.enabled || light.intensity <= 0.0f) continue;const auto type = static_cast<ecs::LightType>(light.type);if (type == ecs::LightType::Directional && light.followEnvironmentSun) sunFollowed = true;- if (sky || type != ecs::LightType::Ambient || !light.environment.isValid()) continue;- if (const Environment* environment = resource_manager_.getEnvironment(light.environment)) {+ if (sky || type != ecs::LightType::Ambient || !environmentOf(light).isValid()) continue;+ if (const Environment* environment = resource_manager_.getEnvironment(environmentOf(light))) {sky = environment;skyLight = entity;const glm::vec3 rgb = linear_color_ ? srgbToLinearCpu(glm::vec3{light.color})@@ -1924,10 +1924,15 @@ void RenderFrame::collectStudioLights(ecs::Registry& registry) {collectShape2D(registry);}+resource::EnvironmentHandle RenderFrame::environmentOf(const ecs::Light& light) const {+ return light.environment.isValid() ? light.environment : sky_environment_;+}+bool RenderFrame::collectEnvironment(const ecs::Light& light, const glm::vec3& scale,bool withoutSun) {- if (!light.environment.isValid()) return false;- const Environment* environment = resource_manager_.getEnvironment(light.environment);+ const resource::EnvironmentHandle handle = environmentOf(light);+ if (!handle.isValid()) return false;+ const Environment* environment = resource_manager_.getEnvironment(handle);if (!environment) return false;u32 textureId = 0;diff --git a/src/esengine/renderer/frame/RenderFrame.hpp b/src/esengine/renderer/frame/RenderFrame.hppindex 90b1c6fd2..ded6b8db8 100644--- a/src/esengine/renderer/frame/RenderFrame.hpp+++ b/src/esengine/renderer/frame/RenderFrame.hpp@@ -123,6 +123,11 @@ public:/// Draws the opaque scene twice, depth alone first (see DrawList::DrawPass). Off unless asked: where a GPU already shades each pixel once/// (a tiled one), the second pass is geometry paid for twice.void setDepthPrepass(bool on) { depth_prepass_ = on; }+ /**+ * @brief The environment the sky lights the scene with (the Sky Atmosphere's, worked out by the SDK as the sky changes), or an+ * invalid handle for none. An Ambient light that names no environment of its own lights with it.+ */+ void setSkyEnvironment(resource::EnvironmentHandle environment) { sky_environment_ = environment; }void setLightingDirect(bool on);bool lightingDirect() const { return lighting_direct_; }void setPlanarQuality(f32 scale, u32 maxSize, f32 updatesPerSecond);@@ -307,15 +312,27 @@ public:* @details Serves every such runtime — Spine and DragonBones both arrive here — and* links none of them: what crosses is x,y,u,v,r,g,b,a per vertex. @p materialId* is the entity's material, resolved the way a Sprite's is (0 = the batch shader).+ *+ * A skeleton a Canvas holds paints by its place in the tree, like the controls round+ * it (unless its author named a layer), and one a SCREEN Canvas holds is drawn by the+ * screen overlay and by no camera: each call lands only in the collect it belongs to.+ * @p treeAlpha is the opacity the UI tree above it multiplies in, and @p cullBit its+ * Canvas' layer bit, as text carries them (0 = drawn by every camera).*/void submitSkeletalBatch(const f32* vertices, i32 vertexCount,const u16* indices, i32 indexCount,u32 textureId, i32 blendMode,const f32* transform16,- Entity entity, i32 layer, f32 depth, u32 materialId = 0, bool premultipliedColor = false+ Entity entity, i32 layer, f32 depth, u32 materialId = 0, bool premultipliedColor = false,+ f32 treeAlpha = 1.0f, u32 cullBit = 0);+ /** @brief Whether a Canvas holds @p entity with no uiOrder of its own (an emitter, a skeleton, a plain Sprite). */+ bool uiTreeHolds(Entity entity) const {+ return ui_tree_layers_ && ui_tree_layers_->count(entity.id()) != 0;+ }+void setStage(RenderStage stage) { current_stage_ = stage; }RenderStage getStage() const { return current_stage_; }@@ -792,6 +809,9 @@ private:/// @p withoutSun lights with the sky alone, where a light casts its sun./// @return false when it names none, leaving the caller to add a flat term.bool collectEnvironment(const ecs::Light& light, const glm::vec3& scale, bool withoutSun);+ /// The environment an Ambient light lights with: its own, else the sky's (setSkyEnvironment).+ resource::EnvironmentHandle environmentOf(const ecs::Light& light) const;+ resource::EnvironmentHandle sky_environment_{};/*** @brief Decides what the shadow pass will draw, without drawing any of it.*diff --git a/tools/renderScenes.mjs b/tools/renderScenes.mjsindex 600a60fb8..e66bf7e19 100644--- a/tools/renderScenes.mjs+++ b/tools/renderScenes.mjs@@ -883,6 +883,9 @@ export const SCENES = [// Wet ground under a roof stays dry: reflections read the rain's map of what stands over each place, as the rain does. A floor too rough// to reflect dry, wet by the reflections' own Wetness, under a roof over its left half: only the open right half mirrors the red wall. Reading no map, the left half reads 148,40,40 too.{ id: "ssr-shelter", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/ssr-shelter.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/mesh-backface.textures.json", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "6", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.25,\"y\":0.5,\"rgb\":[53,53,53],\"tol\":12},{\"x\":0.75,\"y\":0.5,\"rgb\":[147,39,39],\"tol\":15}]" } },+ // Sky Atmosphere's Light the Scene: a white diffuse quad lit by nothing but an Ambient light that names no environment, under a clear+ // sky with the sun up behind it. The sky lights it as an environment, the blue of the dome it faces; off, it is the flat white 255.+ { id: "sky-lights-scene", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_COLORSPACE: "linear", ESTELLA_VERIFY_SCENE: "/scenes/sky-lights-scene.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/mesh-backface.textures.json", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "6", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.5,\"y\":0.5,\"rgb\":[96,113,115],\"tol\":12}]" } },{ id: "sky-fog", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/sky-fog.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/depth-outline.textures.json", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "4", ESTELLA_VERIFY_EXPECT: "[{\"x\": 0.2, \"y\": 0.1, \"rgb\": [144, 175, 187], \"tol\": 12}, {\"x\": 0.5, \"y\": 0.1, \"rgb\": [141, 174, 183], \"tol\": 12}, {\"x\": 0.8, \"y\": 0.2, \"rgb\": [143, 174, 186], \"tol\": 12}, {\"x\": 0.5, \"y\": 0.4, \"rgb\": [139, 171, 180], \"tol\": 12}, {\"x\": 0.2, \"y\": 0.8, \"rgb\": [62, 70, 70], \"tol\": 12}, {\"x\": 0.8, \"y\": 0.8, \"rgb\": [57, 64, 67], \"tol\": 12}]" } },// SSAO: one unlit grey floor read at seven places. Contact, corner and// step come back darker than the open floor they are made of, the floating