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(sky): the sky's lower half is the sunlit ground
yhhd9d7ae336d65
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex cbcd437c7..42d0c1721 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -23,7 +23,7 @@ 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.+- **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. Below the horizon it is the ground, lit by the sky's sun and dome and giving back **Ground Albedo** of it (0.2 by default, as Unreal's), so a wall in shadow takes the sunlit ground's bounce as well as the sky's: under a high clear sun that doubles its fill, under a low hazy one it adds little. Off by default, so a scene already lit by hand looks as it did.- **Rooms stay dark under a sky that changes (sky occlusion).** With **Sky occlusion** on in the Lighting settings (`BakedLighting.skyOcclusion`), a probe bake keeps how much of the sky each probe sees instead of the sky itself: the probes hold the lights and their bounces, and the sky the frame has now (a live Sky Atmosphere, a weather, an environment) is added through what each probe sees of it, to the diffuse light and to the sky's reflection. A ball inside a roofed room measured 119 where the baked sky gave it 150, and a ball outside kept its light. A `.esprobes` baked this way carries `skyVisibility`; one without it lights as before. Probes are read per object, as Unity's light probes are: one large mesh spanning indoors and out takes one value.- **Direct Lighting Only and Indirect Lighting Only view modes.** Beside Clay in the viewport's Show menu (and `Renderer.setViewShading(view, 'directLighting' | 'indirectLighting')`), as Unreal's lighting components: clay lit by the lights alone, or by everything that is not a light (ambient, sky, reflections, probes, bakes). The two add up to Clay, so a dark shadow says at once whether its fill is missing or merely weak.- **A post-process pass can read an earlier pass of its own effect.** A texture param named `u_pass_<name>` is bound to the output of the sub-pass called `<name>`, which the chain keeps alive until it has been read, so an effect can be a pyramid (down, then up, adding each level back) and not only a line of passes.diff --git a/sdk/src/postprocess/effects.ts b/sdk/src/postprocess/effects.tsindex 763fde536..08e79fd02 100644--- a/sdk/src/postprocess/effects.ts+++ b/sdk/src/postprocess/effects.ts@@ -441,6 +441,10 @@ registerEffect({{ 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.{ name: 'u_overcast', label: 'Overcast', min: 0, max: 1, step: 0.01, defaultValue: 0 },+ // How much of the sun and sky the ground gives back, when this sky lights the scene: the lower half of its light, so+ // a wall in shadow takes the sunlit ground's bounce as well as the sky's. Unreal's Ground Albedo. Lighting only:+ // the sky drawn below the horizon is behind the ground anyway.+ { name: 'u_groundAlbedo', label: 'Ground Albedo', min: 0, max: 1, step: 0.01, defaultValue: 0.2 },// How much haze (Mie scattering) the air holds: more is a whiter, glarier sky and a redder sunset.{ name: 'u_haze', label: 'Haze', min: 0, max: 8, step: 0.05, defaultValue: 1 },// The camera's height above the ground the sky is seen from, in kilometres.diff --git a/sdk/src/postprocess/skyEnvironment.ts b/sdk/src/postprocess/skyEnvironment.tsindex 65bf50a7c..3dc5ee45e 100644--- a/sdk/src/postprocess/skyEnvironment.ts+++ b/sdk/src/postprocess/skyEnvironment.ts@@ -254,6 +254,12 @@ function cloudLayer(dir: readonly number[], sun: readonly number[], dome: Float6* 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 {+ skyRadianceAndClouds(dir, input, out);+}++/** {@link skyRadianceAt}, answering also how much of the light behind the clouds along dir comes through them (1 = clear). */+function skyRadianceAndClouds(dir: readonly number[], input: SkyEnvironmentInput, out: Float64Array): number {+ let through = 1;const P = input.params;const sun = input.sun;const overcast = clamp01(P('u_overcast'));@@ -288,9 +294,27 @@ export function skyRadianceAt(dir: readonly number[], input: SkyEnvironmentInputdriftX: 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]!;+ through = T;}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);+ return through;+}++/**+ * What lights the ground under this sky, as irradiance over pi (the unit an environment's coefficients and a light's colour+ * times intensity are in): the sky's own sun — the brightness its scattering is computed from, through the air at its+ * elevation and through the clouds as much as they let through on average — and the dome above, `skyAbove`.+ */+function groundIrradiance(input: SkyEnvironmentInput, skyAbove: readonly number[], cloudsThrough: number, out: Float64Array): void {+ const P = input.params;+ const sun = input.sun;+ const dome = new Float64Array(3);+ const sunTrans = new Float64Array(3);+ scatter([0, 1, 0], sun, P('u_altitude'), P('u_haze') * (1 + clamp01(P('u_overcast')) * 2), dome, sunTrans);+ // The sun the dome was scattered from, scaled as the dome is (0.55 x Brightness), over pi, onto level ground.+ const sunOverPi = SUN_I * 0.55 * P('u_intensity') / Math.PI * Math.max(sun[1]!, 0) * cloudsThrough;+ for (let c = 0; c < 3; c++) out[c] = sunOverPi * sunTrans[c]! + skyAbove[c]!;}/** The sky as an equirectangular panorama of radiance, `width` by `width / 2` (panoramaDirection's mapping). */@@ -298,11 +322,38 @@ export function skyPanorama(input: SkyEnvironmentInput, width = SKY_PANORAMA_WIDconst height = Math.max(2, width >> 1);const rgb = new Float32Array(width * height * 3);const c = new Float64Array(3);+ // Above the horizon: the sky, and as it goes, what it gives level ground (cosine-weighted, over pi) and how much the+ // clouds let through on average (by solid angle, away from the horizon where the slab is thinnest).+ const skyAbove = [0, 0, 0];+ let through = 0, throughWeight = 0;+ const cellAngle = (2 * Math.PI / width) * (Math.PI / height);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 dir = panoramaDirection((x + 0.5) / width, (y + 0.5) / height);+ if (dir[1]! < 0) continue;+ const t = skyRadianceAndClouds(dir, input, c);const o = (y * width + x) * 3;rgb[o] = c[0]!; rgb[o + 1] = c[1]!; rgb[o + 2] = c[2]!;+ const solid = cellAngle * Math.sqrt(Math.max(1 - dir[1]! * dir[1]!, 0));+ for (let k = 0; k < 3; k++) skyAbove[k]! += c[k]! * dir[1]! * solid / Math.PI;+ if (dir[1]! > 0.1) { through += t * solid; throughWeight += solid; }+ }+ }+ // Below it: the ground, lit by that sun and that sky (Ground Albedo of it given back, as a matte surface does), fading+ // into the horizon's own colour toward the horizon, as distant ground does through the haze between.+ const ground = new Float64Array(3);+ groundIrradiance(input, skyAbove, throughWeight > 0 ? through / throughWeight : 1, ground);+ const albedo = clamp01(input.params('u_groundAlbedo'));+ const horizon = new Float64Array(3);+ for (let y = 0; y < height; y++) {+ for (let x = 0; x < width; x++) {+ const dir = panoramaDirection((x + 0.5) / width, (y + 0.5) / height);+ if (dir[1]! >= 0) continue;+ const flat = Math.hypot(dir[0]!, dir[2]!) || 1;+ skyRadianceAt([dir[0]! / flat, 0, dir[2]! / flat], input, horizon);+ const t = smoothstep(0, -0.2, dir[1]!);+ const o = (y * width + x) * 3;+ for (let k = 0; k < 3; k++) rgb[o + k] = mix(horizon[k]!, albedo * ground[k]!, t);}}return { width, height, rgb };@@ -336,7 +387,7 @@ export function skyEnvironmentKey(input: SkyEnvironmentInput): string {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_intensity'), 0.01), r(P('u_haze'), 0.02), r(P('u_overcast'), 0.01), r(P('u_altitude'), 0.05), r(P('u_groundAlbedo'), 0.01),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),diff --git a/sdk/tests/sky-environment.test.ts b/sdk/tests/sky-environment.test.tsindex 15e3f07d0..64cde1541 100644--- a/sdk/tests/sky-environment.test.ts+++ b/sdk/tests/sky-environment.test.ts@@ -54,13 +54,23 @@ describe('sky environment', () => {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 what faces up in the sky\'s colour, and what faces down by the sunlit ground', () => {+ const at = (albedo: number, elevation = 35) => {+ const sh = projectIrradianceSH(skyPanorama(clear(elevation, { u_groundAlbedo: albedo })));+ return { up: evalIrradianceSH(sh, 0, 1, 0), down: evalIrradianceSH(sh, 0, -1, 0) };+ };+ const black = at(0), grey = at(0.2), light = at(0.4);+ expect(black.up[2]!).toBeGreaterThan(black.up[0]!);+ // A black ground sends nothing back: what faces down sees only the haze at the horizon's edge.+ expect(black.down[1]!).toBeLessThan(black.up[1]! * 0.25);+ // The bounce is the albedo's share of what reaches the ground, so it grows with it, about in step.+ const bounce = (r: { down: number[] }) => r.down[1]! - black.down[1]!;+ expect(bounce(grey)).toBeGreaterThan(0.05);+ expect(bounce(light) / bounce(grey)).toBeCloseTo(2, 0);+ // And with the sun: ground under a high sun is brighter than under a low one.+ expect(bounce(at(0.2, 60))).toBeGreaterThan(bounce(at(0.2, 12)) * 2);+ // What faces up does not depend on the ground.+ expect(Math.abs(light.up[1]! - black.up[1]!)).toBeLessThan(black.up[1]! * 0.1);});it('lights the scene with clouds over it as well', () => {diff --git a/tools/renderScenes.mjs b/tools/renderScenes.mjsindex e27dd2fb8..4a513ca90 100644--- a/tools/renderScenes.mjs+++ b/tools/renderScenes.mjs@@ -907,8 +907,9 @@ export const SCENES = [// keeps the floor under it as dry as an opaque one; the cover map is the rain's, not the sun's, and alpha is not what stops rain.{ id: "ssr-shelter-glass", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/ssr-shelter-glass.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}]" } },+ // sky with the sun up behind it. The sky lights it as an environment: the blue of the dome above it and, below, the sunlit ground's+ // bounce (Ground Albedo 0.2), which lifts it and warms it a little; 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\":[142,150,150],\"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