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
fix(water): crests bend and ripples spread wider, so a sea from above is no longer scored with straight parallel strokes that turn with the wind
yhhfb2526ca1a1b
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex b39913ff4..36d172e3a 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -23,6 +23,7 @@ published separately; it ships inside the editor.### Fixed+- **A sea seen from above is no longer scored with straight lines.** Its waves were straight sines a few directions apart, whose crests add up to long parallel strokes that turn with the wind. Each wave is now read at a place bent by a slow sine, in the shader and in the CPU's formula alike, so what floats still sits on what is drawn, and the ripples spread over 74 degrees either side of the wind rather than 41. It adds nothing measurable to a frame on a phone. The detail map in the Terrain & Water example was mostly one wave and drew its own fine lines over all that: it has waves in every direction now, from `tools/render-lab/water_detail.py`. A project that copied the old map should take the new one.- **Quality high no longer costs a phone 40 ms a frame.** The render target pool keeps at most 256 MB of targets nobody has borrowed, and it counted what the frame had just given back as nobody's. A frame's own targets past that size were destroyed and allocated again every frame: a 4096 shadow atlas and a 4x MSAA scene target at 2670x1200 come to 320 MB. On a Snapdragon 8 Elite `high` went from 50 to 10.5 ms with GI off, level with no quality setting at all. Any platform with targets that large paid the same.- **A linear project on a native build is no longer far too dark.** A native host read only half of the packaged config. The colour space, output transform, MSAA, quality, y-sort and depth layers and camera fit never reached it, with no error. A linear game ran as gamma and showed its linear values with no encode: a grey of 0.2 read 51 instead of 124, on Android, Windows and every other native build. Web and native now apply these through one function, and the colour space is read before the first shader compiles. A native build matches the web to about one level in the test room. Linear costs a phone 2.7 ms a frame at 2670x1200 with nothing else on. A project that declares a quality level now gets it on a device.- **Voxel GI no longer changes with the size of the picture.** It took the same one pixel in four for its cache every frame, so a face a few rows tall (the top of a block seen nearly edge on) landed in it at one row or two according to the window's size, and the light around it moved: a wall read 18% apart across sizes, up to 11% for a window one pixel taller. The pixel now changes each frame. Across eight of nine sizes the same wall is within 7%, one size with an odd width and height still reads higher, and the light against Cycles and the frame-to-frame stability are unchanged.diff --git a/sdk/src/water/waterShader.ts b/sdk/src/water/waterShader.tsindex b110b40c6..abec046d0 100644--- a/sdk/src/water/waterShader.ts+++ b/sdk/src/water/waterShader.ts@@ -119,7 +119,16 @@ const WATER = `#pragma shader "Water"#pragma vertexbounds 16#pragma vertexoffset// The height of the waves at p: the same four peaked sines the fragment takes its slope from, so the surface that is lit is the one that is drawn.+// Where the waves are read for the true place p, bent by the given span (waves.ts: waveBend): crests of straight sines a few directions apart+// add up to long parallel lines, a sea scored with strokes that turn with the wind. xy to read at; zw dx/dz and dz/dx, for a slope. One+// sine an axis: this runs for every pixel of the water, and with a term more a phone paid 11 ms a frame for it.+vec4 waterBend(vec2 p, float span) {+ vec2 q = p / span;+ return vec4(p.x + span * 0.45 * sin(q.y * 0.73 + 1.3), p.y + span * 0.45 * sin(q.x * 0.61 + 2.7),+ 0.3285 * cos(q.y * 0.73 + 1.3), 0.2745 * cos(q.x * 0.61 + 2.7));+}float waterWaveHeight(vec2 p, float time, float cell) {+ vec2 at = waterBend(p, u_waveLength).xy;const vec4 SET[4] = vec4[4](vec4(0.0, 1.0, 1.0, 1.0), vec4(28.0, 0.62, 0.55, 1.1), vec4(-37.0, 0.37, 0.3, 1.2), vec4(71.0, 0.21, 0.15, 1.35));float height = 0.0;float base = radians(u_waveDirection);@@ -131,7 +140,7 @@ float waterWaveHeight(vec2 p, float time, float cell) {vec2 d = vec2(sin(a), cos(a));float omega = sqrt(9.8 * k) * u_waveSpeed * SET[i].w;float fade = cell > 0.0 ? clamp((length_ / cell - 3.0) / 3.0, 0.0, 1.0) : 1.0;- height += u_waveHeight * SET[i].z * exp(sin(k * dot(d, p) - omega * time) - 1.0) * fade;+ height += u_waveHeight * SET[i].z * exp(sin(k * dot(d, at) - omega * time) - 1.0) * fade;}return height;}@@ -217,7 +226,13 @@ void esMaterialVertex(inout vec3 local, inout vec3 localNormal, in vec2 uv) {#pragma end#pragma vertexoffset wgsl+fn waterBend(p : vec2f, span : f32) -> vec4f {+ let q = p / span;+ return vec4f(p.x + span * 0.45 * sin(q.y * 0.73 + 1.3), p.y + span * 0.45 * sin(q.x * 0.61 + 2.7),+ 0.3285 * cos(q.y * 0.73 + 1.3), 0.2745 * cos(q.x * 0.61 + 2.7));+}fn waterWaveHeight(p : vec2f, time : f32, cell : f32) -> f32 {+ let at = waterBend(p, mc.u_waveLength).xy;var wave = array<vec4f, 4>(vec4f(0.0, 1.0, 1.0, 1.0), vec4f(28.0, 0.62, 0.55, 1.1), vec4f(-37.0, 0.37, 0.3, 1.2), vec4f(71.0, 0.21, 0.15, 1.35));var height = 0.0;let base = radians(mc.u_waveDirection);@@ -231,7 +246,7 @@ fn waterWaveHeight(p : vec2f, time : f32, cell : f32) -> f32 {let omega = sqrt(9.8 * k) * mc.u_waveSpeed * spec.w;var fade = 1.0;if (cell > 0.0) { fade = clamp((span / cell - 3.0) / 3.0, 0.0, 1.0); }- height = height + mc.u_waveHeight * spec.z * exp(sin(k * dot(d, p) - omega * time) - 1.0) * fade;+ height = height + mc.u_waveHeight * spec.z * exp(sin(k * dot(d, at) - omega * time) - 1.0) * fade;}return height;}@@ -347,6 +362,14 @@ vec2 packNormal(vec3 n) {out vec4 fragColor;#endif+// Where the waves are read for the true place p, bent by the given span (waves.ts: waveBend): crests of straight sines a few directions apart+// add up to long parallel lines, a sea scored with strokes that turn with the wind. xy to read at; zw dx/dz and dz/dx, for a slope. One+// sine an axis: this runs for every pixel of the water, and with a term more a phone paid 11 ms a frame for it.+vec4 waterBend(vec2 p, float span) {+ vec2 q = p / span;+ return vec4(p.x + span * 0.45 * sin(q.y * 0.73 + 1.3), p.y + span * 0.45 * sin(q.x * 0.61 + 2.7),+ 0.3285 * cos(q.y * 0.73 + 1.3), 0.2745 * cos(q.x * 0.61 + 2.7));+}float waterHash(vec2 p) {p = fract(p * vec2(0.1031, 0.1030));p += dot(p, p.yx + 33.33);@@ -359,12 +382,12 @@ float waterNoise(vec2 p) {return mix(mix(waterHash(i), waterHash(i + vec2(1.0, 0.0)), f.x),mix(waterHash(i + vec2(0.0, 1.0)), waterHash(i + vec2(1.0, 1.0)), f.x), f.y);}-/// The slope of the ripples the wind raises at p: six short waves within forty degrees of it, from u_rippleLength down to a fifth of it, each+/// The slope of the ripples the wind raises at p: six short waves within seventy-five degrees of it, from u_rippleLength down to a fifth of it, each/// running at the speed its length gives deep water and at a phase of its own, each as steep as u_rippleStrength a third. A sum of waves/// has no cells or blobs, which drifting noise has. A ripple shorter than a pixel would shimmer: each fades out with distance.vec2 rippleSlope(vec2 p, float time, float dist) {- const vec3 SET[6] = vec3[6](vec3(-12.0, 1.0, 0.0), vec3(23.0, 0.71, 1.7), vec3(-35.0, 0.53, 3.1),- vec3(8.0, 0.39, 4.4), vec3(41.0, 0.29, 0.9), vec3(-27.0, 0.21, 2.6));+ const vec3 SET[6] = vec3[6](vec3(-14.0, 1.0, 0.0), vec3(33.0, 0.71, 1.7), vec3(-58.0, 0.53, 3.1),+ vec3(11.0, 0.39, 4.4), vec3(74.0, 0.29, 0.9), vec3(-41.0, 0.21, 2.6));float base = radians(u_waveDirection);vec2 slope = vec2(0.0);for (int i = 0; i < 6; ++i) {@@ -414,6 +437,7 @@ vec2 waveSlope(vec2 p, float time, float dist, out float crest) {float crestSum = 0.0;float weightSum = 0.0;float base = radians(u_waveDirection);+ vec4 bend = waterBend(p, u_waveLength);for (int i = 0; i < 4; ++i) {if (float(i) >= u_waveCount) break;float length_ = u_waveLength * SET[i].y;@@ -421,7 +445,7 @@ vec2 waveSlope(vec2 p, float time, float dist, out float crest) {float a = base + radians(SET[i].x);vec2 d = vec2(sin(a), cos(a));float omega = sqrt(9.8 * k) * u_waveSpeed * SET[i].w;- float theta = k * dot(d, p) - omega * time;+ float theta = k * dot(d, bend.xy) - omega * time;float e = exp(sin(theta) - 1.0);// A wave much shorter than a pixel is noise, not a wave: it fades out with distance.float seen = clamp(1.0 - dist / (length_ * 220.0), 0.0, 1.0);@@ -429,6 +453,7 @@ vec2 waveSlope(vec2 p, float time, float dist, out float crest) {crestSum += e * SET[i].z;weightSum += SET[i].z;}+ slope = vec2(slope.x + slope.y * bend.w, slope.y + slope.x * bend.z);crest = crestSum / weightSum;return slope;}@@ -821,6 +846,11 @@ fn packNormal(n : vec3f) -> vec2f {}#endif+fn waterBend(p : vec2f, span : f32) -> vec4f {+ let q = p / span;+ return vec4f(p.x + span * 0.45 * sin(q.y * 0.73 + 1.3), p.y + span * 0.45 * sin(q.x * 0.61 + 2.7),+ 0.3285 * cos(q.y * 0.73 + 1.3), 0.2745 * cos(q.x * 0.61 + 2.7));+}fn waterHash(p0 : vec2f) -> f32 {var p = fract(p0 * vec2f(0.1031, 0.1030));p = p + dot(p, p.yx + 33.33);@@ -834,8 +864,8 @@ fn waterNoise(p : vec2f) -> f32 {mix(waterHash(i + vec2f(0.0, 1.0)), waterHash(i + vec2f(1.0, 1.0)), f.x), f.y);}fn rippleSlope(p : vec2f, time : f32, dist : f32) -> vec2f {- let SET = array<vec3f, 6>(vec3f(-12.0, 1.0, 0.0), vec3f(23.0, 0.71, 1.7), vec3f(-35.0, 0.53, 3.1),- vec3f(8.0, 0.39, 4.4), vec3f(41.0, 0.29, 0.9), vec3f(-27.0, 0.21, 2.6));+ let SET = array<vec3f, 6>(vec3f(-14.0, 1.0, 0.0), vec3f(33.0, 0.71, 1.7), vec3f(-58.0, 0.53, 3.1),+ vec3f(11.0, 0.39, 4.4), vec3f(74.0, 0.29, 0.9), vec3f(-41.0, 0.21, 2.6));let base = radians(mc.u_waveDirection);var slope = vec2f(0.0);for (var i = 0; i < 6; i++) {@@ -884,6 +914,7 @@ fn waveSlope(p : vec2f, time : f32, dist : f32) -> Waves {var crestSum = 0.0;var weightSum = 0.0;let base = radians(mc.u_waveDirection);+ let bend = waterBend(p, mc.u_waveLength);for (var i : i32 = 0; i < 4; i = i + 1) {if (f32(i) >= mc.u_waveCount) { break; }let spec = wave[i];@@ -892,7 +923,7 @@ fn waveSlope(p : vec2f, time : f32, dist : f32) -> Waves {let a = base + radians(spec.x);let d = vec2f(sin(a), cos(a));let omega = sqrt(9.8 * k) * mc.u_waveSpeed * spec.w;- let theta = k * dot(d, p) - omega * time;+ let theta = k * dot(d, bend.xy) - omega * time;let e = exp(sin(theta) - 1.0);let seen = clamp(1.0 - dist / (span * 220.0), 0.0, 1.0);slope = slope + d * (mc.u_waveHeight * spec.z * e * cos(theta) * k * seen);@@ -900,7 +931,7 @@ fn waveSlope(p : vec2f, time : f32, dist : f32) -> Waves {weightSum = weightSum + spec.z;}var out : Waves;- out.slope = slope;+ out.slope = vec2f(slope.x + slope.y * bend.w, slope.y + slope.x * bend.z);out.crest = crestSum / weightSum;return out;}diff --git a/sdk/src/water/waves.ts b/sdk/src/water/waves.tsindex 85f442c93..3f3da3d38 100644--- a/sdk/src/water/waves.ts+++ b/sdk/src/water/waves.ts@@ -9,6 +9,10 @@* GLSL and WGSL, so what a floating object reads here is what is drawn there. Change a constant in one place and the other* two places have to change with it; the table below is the one the shaders repeat.*+ * Each wave is taken at a place bent off the true one (`waveBend`). Straight sines a few directions apart add up to crests+ * that are long parallel lines, which is how a sea of them looked from above: scored with diagonal strokes, turning with the+ * wind.+ ** Everything here is in the body's own space: x and z along its surface, the height along its up.*/@@ -37,6 +41,26 @@ export interface WaveParams {const TAU = Math.PI * 2;const GRAVITY = 9.8;+/** How far a crest is bent, as a share of the longest wave. Its slope is this times the bend's frequency, about 0.33 at most. */+const BEND = 0.45;++/**+ * Where the waves are read for the true place (x, z), bent by a span of `length`: a slow sine of z moves x and one of x moves z, at+ * frequencies that share no multiple, repeating every 8.6 and 10.3 lengths. Each axis depends only on the other, so the two terms a slope needs (how x's bend changes along z,+ * z's along x) are all of its Jacobian. The shader's `waterBend` is the same arithmetic.+ *+ * @returns x and z to read at, then dx/dz and dz/dx.+ */+export function waveBend(x: number, z: number, length: number): [number, number, number, number] {+ const u = x / length, v = z / length;+ return [+ x + length * BEND * Math.sin(v * 0.73 + 1.3),+ z + length * BEND * Math.sin(u * 0.61 + 2.7),+ BEND * 0.73 * Math.cos(v * 0.73 + 1.3),+ BEND * 0.61 * Math.cos(u * 0.61 + 2.7),+ ];+}+/*** How much of a wave a mesh of `cell`-sized cells can draw: none below three cells to a wavelength, all of it from six. The shader applies the* same ramp per vertex with the cell size of the ring the vertex is in, so a coarse far ring does not alias; `cell` 0 draws every wave.@@ -55,6 +79,7 @@ export function waveCount(p: WaveParams): number {export function waveHeight(p: WaveParams, x: number, z: number, time: number, cell = 0): number {let height = 0;const base = p.direction * Math.PI / 180;+ const [bx, bz] = waveBend(x, z, p.length);let used = waveCount(p);for (const [heading, lengthShare, heightShare, speedShare] of WAVE_SET) {if (used-- <= 0) break;@@ -62,7 +87,7 @@ export function waveHeight(p: WaveParams, x: number, z: number, time: number, ceconst k = TAU / length;const a = base + heading * Math.PI / 180;const omega = Math.sqrt(GRAVITY * k) * p.speed * speedShare;- const theta = k * (Math.sin(a) * x + Math.cos(a) * z) - omega * time;+ const theta = k * (Math.sin(a) * bx + Math.cos(a) * bz) - omega * time;height += p.height * heightShare * Math.exp(Math.sin(theta) - 1) * waveFade(length, cell);}return height;@@ -72,6 +97,7 @@ export function waveHeight(p: WaveParams, x: number, z: number, time: number, ceexport function waveSlope(p: WaveParams, x: number, z: number, time: number): [number, number] {let sx = 0, sz = 0;const base = p.direction * Math.PI / 180;+ const [bx, bz, xAlongZ, zAlongX] = waveBend(x, z, p.length);let used = waveCount(p);for (const [heading, lengthShare, heightShare, speedShare] of WAVE_SET) {if (used-- <= 0) break;@@ -79,12 +105,12 @@ export function waveSlope(p: WaveParams, x: number, z: number, time: number): [nconst a = base + heading * Math.PI / 180;const dx = Math.sin(a), dz = Math.cos(a);const omega = Math.sqrt(GRAVITY * k) * p.speed * speedShare;- const theta = k * (dx * x + dz * z) - omega * time;+ const theta = k * (dx * bx + dz * bz) - omega * time;const rise = p.height * heightShare * Math.exp(Math.sin(theta) - 1) * Math.cos(theta) * k;sx += dx * rise;sz += dz * rise;}- return [sx, sz];+ return [sx + sz * zAlongX, sz + sx * xAlongZ];}/**diff --git a/sdk/tests/water-quality.test.ts b/sdk/tests/water-quality.test.tsindex c1aa595bc..8ab15a1dd 100644--- a/sdk/tests/water-quality.test.ts+++ b/sdk/tests/water-quality.test.ts@@ -1,7 +1,7 @@// SPDX-License-Identifier: Apache-2.0// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Teamimport { describe, expect, it } from 'vitest';-import { waveHeight, waveSlope, waveCount, type WaveParams } from '../src/water/waves';+import { waveBend, waveHeight, waveSlope, waveCount, type WaveParams } from '../src/water/waves';import { FULL_WATER, waterQualityOf } from '../src/water/waterPlugin';import { defaultQualityProfile, resolveQualityProfile, parseQualityConfig } from '../src/render/quality';import { applyUnderwaterToEffects, type UnderwaterState } from '../src/postprocess/underwater';@@ -25,7 +25,8 @@ describe('the wave count', () => {expect(waveHeight({ ...params, count: 4 }, x, z, t)).toBe(all);// The one wave is the set's first, at its own length and height.const k = 2 * Math.PI / 20, a = 30 * Math.PI / 180;- const theta = k * (Math.sin(a) * x + Math.cos(a) * z) - Math.sqrt(9.8 * k) * t;+ const [bx, bz] = waveBend(x, z, 20);+ const theta = k * (Math.sin(a) * bx + Math.cos(a) * bz) - Math.sqrt(9.8 * k) * t;expect(one).toBeCloseTo(Math.exp(Math.sin(theta) - 1), 9);});diff --git a/sdk/tests/water.test.ts b/sdk/tests/water.test.tsindex 2d17a3406..81b1b4a92 100644--- a/sdk/tests/water.test.ts+++ b/sdk/tests/water.test.ts@@ -1,7 +1,8 @@// SPDX-License-Identifier: Apache-2.0// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Teamimport { describe, expect, it } from 'vitest';-import { WAVE_SET, waveFade, waveHeight, waveSlope, type WaveParams } from '../src/water/waves';+import { WAVE_SET, waveBend, waveFade, waveHeight, waveSlope, type WaveParams } from '../src/water/waves';+import { WATER_SHADER_TEMPLATE } from '../src/water/waterShader';import { buildOceanMesh, oceanReach, oceanSnap } from '../src/water/waterMesh';import { MeshChannel } from '../src/asset/meshFormat';import type { MeshData } from '../src/asset/meshFormat';@@ -32,7 +33,8 @@ function facing(p: Float32Array, a: number, b: number, c: number): number {describe('the waves', () => {it('is the sum of the set\'s four peaked sines', () => {- const x = 3.7, z = -2.2, t = 1.3;+ const t = 1.3;+ const [x, z] = waveBend(3.7, -2.2, params.length);let expected = 0;for (const [heading, lengthShare, heightShare, speedShare] of WAVE_SET) {const k = 2 * Math.PI / (params.length * lengthShare);@@ -40,7 +42,37 @@ describe('the waves', () => {const theta = k * (Math.sin(a) * x + Math.cos(a) * z) - Math.sqrt(9.8 * k) * params.speed * speedShare * t;expected += params.height * heightShare * Math.exp(Math.sin(theta) - 1);}- expect(waveHeight(params, x, z, t)).toBeCloseTo(expected, 10);+ expect(waveHeight(params, 3.7, -2.2, t)).toBeCloseTo(expected, 10);+ });++ it("bends its crests: one wave's crest is no straight line", () => {+ // Walk along the first wave's crest line as a straight sine would have it, and read how far the phase moves off it.+ const a = params.direction * Math.PI / 180;+ const along = [Math.cos(a), -Math.sin(a)];+ const k = 2 * Math.PI / params.length;+ const phases: number[] = [];+ for (let s = 0; s <= 40; ++s) {+ const [bx, bz] = waveBend(along[0]! * s * params.length, along[1]! * s * params.length, params.length);+ phases.push(k * (Math.sin(a) * bx + Math.cos(a) * bz));+ }+ expect(Math.max(...phases) - Math.min(...phases)).toBeGreaterThan(Math.PI);+ });++ it('bends by no more than keeps the surface from folding over itself', () => {+ for (let u = -50; u < 50; u += 0.37) {+ const [, , xAlongZ, zAlongX] = waveBend(u * params.length, -u * 1.7 * params.length, params.length);+ expect(Math.abs(xAlongZ)).toBeLessThan(0.4);+ expect(Math.abs(zAlongX)).toBeLessThan(0.4);+ }+ });++ it('is bent by the same numbers in the shader, in both languages and both stages', () => {+ const source = JSON.stringify(WATER_SHADER_TEMPLATE);+ for (const term of ['span * 0.45 * sin(q.y * 0.73 + 1.3)', 'span * 0.45 * sin(q.x * 0.61 + 2.7)', '0.3285 * cos(q.y * 0.73 + 1.3)', '0.2745 * cos(q.x * 0.61 + 2.7)']) {+ expect(source.split(term).length - 1, term).toBeGreaterThanOrEqual(4);+ }+ expect(source.split('vec4 waterBend(').length - 1).toBe(2);+ expect(source.split('fn waterBend(').length - 1).toBe(2);});it('has a slope that is the derivative of its height', () => {diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjsindex 55c033bec..5b24c40b8 100644--- a/tools/releaseNotes.mjs+++ b/tools/releaseNotes.mjs@@ -3860,4 +3860,8 @@ export const NOTED = {{"internal":"broke after 0.98.0 and before any release, so no creator ever had it"},"fix(render): the target pool no longer destroys a frame's own targets every frame once they add up past its idle budget, which cost a phone 40 ms at quality high":{"note":"Quality high no longer costs a phone 40 ms a frame."},+ "fix(water): crests bend and ripples spread wider, so a sea from above is no longer scored with straight parallel strokes that turn with the wind":+ {"note":"A sea seen from above is no longer scored with straight lines."},+ "fix(examples): Terrain & Water's detail map has waves in every direction, where one wave laid fine diagonal lines across its whole sea":+ {"note":"A sea seen from above is no longer scored with straight lines."},};