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(water): a camera under the surface sees through the water, fogged and tinted by what it has crossed
yhh73990e8cebdc
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex a79017dc7..488bdb52c 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -35,6 +35,7 @@ published separately; it ships inside the editor.- **Contact shadows and screen-space bounce light.** Contact Shadows and Screen Space GI effects add small sharp shadows at contacts and one bounce of colour between surfaces, and the weather softens the sun's shadows. `contactShadows` marches a short ray toward the scene's sun in the depth buffer; `ssgi` gathers eight rays a pixel over the G-buffer's normals at half size into a float target and averages the neighbours on the same surface before laying the light, times the receiver's colour, over the picture. The Weather component raises the sun's `sourceAngle` and lowers its `shadowStrength` as the sky clouds over.- **Terrain and Foliage.** A Terrain component makes ground from a heightmap or noise, paints it with grass, dirt, snow and rock layers and draws it in chunks that coarsen with distance; a Foliage component scatters grass or a mesh over it, swaying in the wind and thinning out with distance.- **Separate material maps packed on import.** Importing an FBX with separate metalness, roughness and occlusion images now packs them into the one map the Model shader samples, instead of dropping them. Occlusion goes in red, roughness in green and metal in blue, each from its image's red channel (a glossiness map is inverted); a channel with no image stays at full so the material's own value speaks. Only PNG and DDS can be read.+- **Underwater view.** A camera under water sees through it. Whenever the active camera is below a water body's surface an Underwater effect is added to the post-process volumes: the light of each pixel is taken out colour by colour (red first) by the distance it crossed, with the same absorption and density the surface's material draws with, and the water gives back its own colour, dimmer the deeper the camera is. The surface seen from below turns over and, past the critical angle, reflects whole (Snell's window).- **Floating bodies.** Water holds things up. A Floating component on an entity with a RigidBody3D floats it: a buoyant force against gravity (`buoyancy` is the water's density against the body's, so 2 floats it half under) and a drag against its velocity relative to the water, which brings it to rest in a lake and carries it with a river's current, applied at a few points of the body so waves tip it. It works from the CPU's own water surface, so it needs no renderer, and it needs the 3D physics module, which gains force and mass queries.- **Rivers and splines.** A WaterBody can be a river: put a Spline on its entity and it lays a ribbon along the curve, as wide as the curve says at each point and at its height, with a current (`flowSpeed`, faster where it narrows) that the shader carries the waves and ripples along and that `Waters.sample` reports as `flow`. Splines are a new optional module (`esengine/spline`): a curve through points with a width each, measured by the distance along it.- **Lake outlines and shores.** A lake can have an outline of its own and knows its shore. `boundary` cuts it to a polygon on its plane (crisp at the pixel, not at the grid's cells), `shoreWidth` calms its waves toward the edge and where it is shallow over a Terrain, and the shore foams along the outline. `Waters.sample` answers with the same calmed waves and says a point in the notch of a concave lake is not inside.diff --git a/desktop b/desktopindex eb78c6afc..eabc5c63d 160000--- a/desktop+++ b/desktop@@ -1 +1 @@-Subproject commit eb78c6afcfc0d54fe86c59b845d22ca6413e1c0f+Subproject commit eabc5c63dee90ec69a53a2e49f3099b481e0fa60diff --git a/docs/astro/src/content/docs/graphics/water.mdx b/docs/astro/src/content/docs/graphics/water.mdxindex 64ebda9e7..8070df6e7 100644--- a/docs/astro/src/content/docs/graphics/water.mdx+++ b/docs/astro/src/content/docs/graphics/water.mdx@@ -95,6 +95,22 @@ It needs the 3D physics module, and a build of it with the force functions (`_phfloats nothing. Floating is one rigid body in one fluid: there is no added mass, no lift from the shape of a hull, and a body that is wholly under is not pushedtoward anything but by the current.+## Under the surface++When the active camera is under a body of water the picture is the water's. The water module reports where the camera is each frame (from [`Waters.sample`](#asking-the-surface))+and the post-process volume system adds an **Underwater** effect for as long as it is, the way a weather adds its rain:++- **Fog by water crossed.** The light of each pixel has crossed the distance from the eye to what it came from (the sky, which has no surface, the longest the water is seen+ through, `u_range`), and the water takes it out colour by colour, red first, by the same `u_absorption` and `u_density` the surface's material draws with, and gives back+ its own colour. A white wall under water is blue-green, and a far one more than a near one.+- **Dimmer with depth.** The colour the water gives back dims with how far down the camera is (`u_lightFalloff`), as the light that reaches it comes from above.+- **No pop.** The effect ramps in over the first stretch below the surface (half the wave height, at least one unit), so crossing it is a fade and not a cut.+- **Yours if you wrote it.** A scene that authors an `underwater` effect in a volume keeps its numbers; only the camera's depth and how wholly it is under are filled in.++The surface itself, seen from below, is turned over and light goes the other way through it: from out of the water rays past the critical angle (about 49 degrees) are reflected+whole, so the water above is a window of sky overhead in a mirror, and the Fresnel term follows. The window's edge is not drawn as a circle on its own: it is where the+refraction runs out.+## Splines`Spline` is data and nothing draws it: `points` (each an `x`, `y`, `z` in the entity's own space and a `width`) and `closed`. A river reads the one on its@@ -156,6 +172,7 @@ What is not there yet, so nobody is surprised:- A river does not carve the ground, rapids and falls are not foamed by how fast or steep the water runs, and two bodies do not blend where they meet.A lake's outline is a polygon on a plane: it does not follow a curved shore, and the waves die toward the shore without breaking on it.- Things float (see [Floating](#floating)); nothing swims yet, and a body in the water makes no ripple or wake.-- A camera under the surface sees the water turned over, and nothing else changes: no underwater fog or tint.+- Under the surface there is fog and tint but no light: no caustics on what lies below, no shafts of sun through the surface, and the surface seen from below mirrors the fog, not the+ water's own picture of itself. Each camera is under or not as a whole: there is no waterline across the lens.- It does not react to what moves through it: no ripples, no wake.- The waves are the four peaked sines, not a spectrum, and they lift the surface without pushing it sideways.diff --git a/docs/astro/src/content/docs/zh-cn/graphics/water.mdx b/docs/astro/src/content/docs/zh-cn/graphics/water.mdxindex c1d83d5bd..913c3f9bd 100644--- a/docs/astro/src/content/docs/zh-cn/graphics/water.mdx+++ b/docs/astro/src/content/docs/zh-cn/graphics/water.mdx@@ -66,6 +66,17 @@ description: 一个 WaterBody 组件,构建海洋或湖泊,用 CPU 能读回的它需要 3D 物理模块,并且是带有施力函数(`_physics3d_addForce`、`_physics3d_getBodyDynamics`)的那一版;没有这些函数的构建会警告一次,什么也不会漂。漂浮是一个刚体在一种流体里:没有附加质量,没有船体形状带来的升力,完全没入的物体除了水流外不会被推向任何方向。+## 水面之下++当活动相机在一个水体之下时,画面就是水的。水模块每帧报告相机在哪儿(来自 [`Waters.sample`](#查询表面)),后处理体积系统只要相机还在水下,就像天气带来雨一样,加上一个 **Underwater** 效果:++- **按穿过的水雾化。** 每个像素的光穿过了从眼睛到它出处的距离(天空没有表面,取水能被看穿的最长距离 `u_range`),水按颜色把光吸走,红色最先,用的是和水面材质绘制时相同的 `u_absorption` 和 `u_density`,再还给你它自己的颜色。水下一面白墙是蓝绿色的,远的比近的更甚。+- **越深越暗。** 水还回来的颜色随相机下沉的深度变暗(`u_lightFalloff`),因为到达它那里的光来自上方。+- **没有突变。** 效果在水面以下的第一段距离里渐入(波高的一半,至少一个单位),所以穿过水面是淡入而不是硬切。+- **你写了就用你的。** 在体积里自己写了 `underwater` 效果的场景,保留它的数值;只会填入相机的深度和它完全没入的程度。++水面本身从下面看是翻过来的,光穿过它的方向也反了:从水里出来,超过临界角(约 49 度)的光线被整个反射,所以上面的水是头顶一扇天空的窗户,窗户之外是水下世界的镜子,菲涅尔项也随之改变。窗户的边缘并不是自己画出来的圆:它就是折射走到尽头的地方。+## 样条`Spline` 是数据,什么也不画:`points`(每个点是实体自身空间里的 `x`、`y`、`z` 和一个 `width`)和 `closed`。河流读取它实体上的那一个;任何沿路径走的东西都可以用 `SplineCurve` 读它:@@ -111,6 +122,6 @@ curve.nearest(x, z); // 在 xz 平面上离它最近的地方:s、距离、在- 与玻璃一样,它只折射不透明场景:透过它能看到船体,但看不到另一个透明表面。- 河流不会切削地面,急流和瀑布不会按水流的快慢或陡度起泡沫,两个水体相接处也不会融合。湖泊的轮廓是平面上的多边形:它不跟随弯曲的岸线,波浪向岸边消失而不是在岸上破碎。- 东西可以漂浮(见[漂浮](#漂浮));还没有东西能游泳,水里的物体也不会激起涟漪或尾迹。-- 相机在水面以下时,看到的是翻过来的水,别的没有变化:没有水下的雾和染色。+- 水下有雾和染色,但没有光:水下的物体上没有焦散,没有穿过水面的阳光束,从下面看水面时镜子里映的是雾,而不是水自己的画面。相机整个在水下或整个不在:镜头上没有横过的水线。- 它不会对穿过它的东西作出反应:没有涟漪,没有尾迹。- 波浪是这四道波峰尖的正弦,不是波谱,并且只把表面抬起,不会把它推向一侧。diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.jsonindex 002ddf0e6..7ee18b547 100644--- a/docs/astro/src/data/apiStability.generated.json+++ b/docs/astro/src/data/apiStability.generated.json@@ -3,10 +3,10 @@"counts": {"public": 115,"beta": 171,- "experimental": 2374,+ "experimental": 2376,"deprecated": 3},- "total": 2660,+ "total": 2662,"subsystems": [{"id": "mobile-controls",diff --git a/pipeline/src/project/targetSupport.ts b/pipeline/src/project/targetSupport.tsindex 81b87e993..4a4a1338d 100644--- a/pipeline/src/project/targetSupport.ts+++ b/pipeline/src/project/targetSupport.ts@@ -87,6 +87,7 @@ export const POST_PROCESS_EFFECT_GROUP: Readonly<Record<string, Subsystem>> = {voxelGI: 'fxLighting', ssgi: 'fxLighting', contactShadows: 'fxLighting', lightShafts: 'fxLighting',autoExposure: 'fxLighting', depthOfField: 'fxLighting', ssao: 'fxLighting', subsurface: 'fxLighting',gtao: 'fxLighting', ssr: 'fxLighting', taa: 'fxLighting',+ underwater: 'water',};/** Human name, for a message someone packaging a game has to act on. */diff --git a/sdk/etc/water.api.md b/sdk/etc/water.api.mdindex 3c7e794bc..4d8ec1198 100644--- a/sdk/etc/water.api.md+++ b/sdk/etc/water.api.md@@ -1,7 +1,7 @@# API surface — esengine/water<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 0 public · 0 beta · 33 experimental · 0 deprecated+Symbols: 0 public · 0 beta · 35 experimental · 0 deprecated## Floating — const @experimental```@@ -79,6 +79,15 @@ static prototype: ShoreField1000000000```+## UnderwaterPlugin — class @experimental+```+build: (app: App) => void+cleanup: () => void+name: string+static new (): UnderwaterPlugin+static prototype: UnderwaterPlugin+```+## WAVE_SET — const @experimental```readonly (readonly [number, number, number, number])[]@@ -199,6 +208,11 @@ speed: number(poly: readonly Point2[], x: number, z: number): number```+## registerUnderwaterEffect — function @experimental+```+(): void+```+## shoreDamp — function @experimental```(reach: number, width: number): numberdiff --git a/sdk/src/app/pluginSets.ts b/sdk/src/app/pluginSets.tsindex 013cd15f6..6a51d1e83 100644--- a/sdk/src/app/pluginSets.ts+++ b/sdk/src/app/pluginSets.ts@@ -67,7 +67,7 @@ export const presentationBasePlugins = (): Plugin[] => [*/export const PLUGIN_BUILD_ORDER: readonly string[] = ['Diagnostics', 'timer', 'velocity', 'lifecycle', 'animation', 'audio', 'video',- 'particle', 'trail', 'meshRenderer', 'staticBatch', 'terrain', 'foliage', 'spline', 'water', 'floating', 'tilemap', 'postProcess', 'timeline',+ 'particle', 'trail', 'meshRenderer', 'staticBatch', 'terrain', 'foliage', 'spline', 'water', 'floating', 'underwater', 'tilemap', 'postProcess', 'timeline','gameplay','perception', 'fsm', 'bt', 'scriptGraph', 'nav', 'eventBinding', 'replication','services',diff --git a/sdk/src/postprocess/underwater.ts b/sdk/src/postprocess/underwater.tsnew file mode 100644index 000000000..33fd1d9b0--- /dev/null+++ b/sdk/src/postprocess/underwater.ts@@ -0,0 +1,73 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file underwater.ts+ * @brief What a camera under water sees: the state a water body reports, and the effect the volume system adds for it.+ *+ * @details Being under water is not authored into a volume: it is a fact about where the camera is. The water module reports it (the camera is this+ * deep under a surface whose water absorbs like this and glows like that) and this adds an `underwater` effect to whatever the volumes+ * resolved, the way a weather adds its rain. A scene that authors an `underwater` effect of its own keeps its numbers and only has the+ * depth and the amount filled in; one that does not gets the numbers of the water it is under, so the world below the surface and+ * the surface seen from above agree.+ *+ * The effect itself (its shader and its definition) is registered by the water module: a build with no water has no state to report+ * and carries none of it.+ */+import type { BlendedEffect, Rgba } from './volumeBlending';++/** How a camera is under water. */+export interface UnderwaterState {+ /** How wholly the camera is under the surface, 0 to 1: it ramps in over the first stretch below it, so the cut is not a pop. */+ amount: number;+ /** How far under the surface the camera is, in world units. */+ depth: number;+ /** How fast each colour is absorbed per world unit of water (red first), and the water's density: the numbers of the surface's own material. */+ absorption: [number, number, number];+ density: number;+ /** The colour the water gives back, at the camera's depth, before the light fades with depth. */+ scatter: [number, number, number];+}++let current: UnderwaterState | null = null;++/** Reports the camera under water, or (null) out of it. Called by the water module each frame. */+export function setUnderwaterState(state: UnderwaterState | null): void {+ current = state;+}++/** What the water module last reported. */+export function currentUnderwater(): UnderwaterState | null {+ return current;+}++/**+ * Adds the underwater effect to what the volumes resolved: filled in from the state where the scene authored none of its own, its depth and amount+ * always. Does nothing out of the water.+ */+export function applyUnderwaterToEffects(effects: Map<string, BlendedEffect>, state: UnderwaterState | null): void {+ if (!state || state.amount <= 0) return;+ let effect = effects.get('underwater');+ const authored = !!effect;+ if (!effect) {+ effect = { enabled: true, uniforms: new Map(), textures: new Map(), colors: new Map() };+ effects.set('underwater', effect);+ }+ if (!effect.enabled) return;+ const colour = (c: [number, number, number]): Rgba => ({ r: c[0], g: c[1], b: c[2], a: 1 });+ if (!authored) {+ effect.colors.set('u_absorption', colour(state.absorption));+ effect.colors.set('u_scatterColor', colour(state.scatter));+ effect.uniforms.set('u_density', state.density);+ }+ effect.uniforms.set('u_amount', Math.min(Math.max(state.amount, 0), 1) * (effect.uniforms.get('u_amount') ?? 1));+ effect.uniforms.set('u_cameraDepth', state.depth);+}++/**+ * How wholly a camera `depth` under a surface is under it: 0 at the surface, 1 from `fade` down. `depth` is positive under the surface; a camera above it+ * is not under it at all.+ */+export function submersion(depth: number, fade: number): number {+ if (!(depth > 0)) return 0;+ return Math.min(depth / Math.max(fade, 1e-6), 1);+}diff --git a/sdk/src/postprocess/volumeSystem.ts b/sdk/src/postprocess/volumeSystem.tsindex 099182ed5..be2ba16f1 100644--- a/sdk/src/postprocess/volumeSystem.ts+++ b/sdk/src/postprocess/volumeSystem.ts@@ -11,6 +11,7 @@ import { blendVolumeEffects, computeVolumeFactor, type ActiveVolume, type Blendeimport type { ShaderHandle } from '../render/material';import { Material } from '../render/material';import { applyWeatherToEffects, currentWeather, currentWeatherDrive } from './weather';+import { applyUnderwaterToEffects, currentUnderwater } from './underwater';import { applyTimeToEffects, currentTimeOfDay, currentTimeDrive, timeLightsApplied } from './timeOfDay';export interface PostProcessVolumeConfig {@@ -251,6 +252,8 @@ export const postProcessVolumeSystem = defineSystem(if (weather) applyWeatherToEffects(blended, weather, currentWeatherDrive());const clock = currentTimeOfDay();if (clock) applyTimeToEffects(blended, clock, currentTimeDrive(), timeLightsApplied());+ // A camera under water: the effect the water module says it needs.+ applyUnderwaterToEffects(blended, currentUnderwater());applyBlendedEffects(api, cameraEntity, blended);}diff --git a/sdk/src/render/builtinShaders.ts b/sdk/src/render/builtinShaders.tsindex d7e505bac..f4a0001a7 100644--- a/sdk/src/render/builtinShaders.ts+++ b/sdk/src/render/builtinShaders.ts@@ -928,8 +928,9 @@ void main() {N = perturbNormal(Ngeo, P, v_texCoord, normalize(vec3(-slope.x, -slope.y, 1.0)));}#endif- // Seen from below, the surface turns over.- if (dot(viewDir, Ngeo) < 0.0) { N = -N; Ngeo = -Ngeo; }+ // Seen from below, the surface turns over, and light goes the other way through it: out of the water, into the air.+ bool below = dot(viewDir, Ngeo) < 0.0;+ if (below) { N = -N; Ngeo = -Ngeo; }// What is behind the water: the picture and the distance, where the frame took them.bool haveColor = texture(u_sceneColor, vec2(0.5)).a < 0.75;@@ -940,9 +941,11 @@ void main() {float column0 = max(behindDist - waterDist, 0.0);// Bent by the waves: the ray through the tilted surface against the ray through a flat one, over as much water as there is.- const float RATIO = 1.0 / 1.333;+ float RATIO = below ? 1.333 : 1.0 / 1.333;vec3 bentWave = refract(-viewDir, N, RATIO);vec3 bentFlat = refract(-viewDir, Ngeo, RATIO);+ // Past the critical angle (about 49 degrees) nothing gets out of the water: refract gives nothing, and the surface is a mirror.+ if (below && (dot(bentWave, bentWave) < 0.5 || dot(bentFlat, bentFlat) < 0.5)) { bentWave = bentFlat = vec3(0.0); }float reach = min(column0, u_distortionRange) * u_refractionStrength;vec4 clip1 = u_projection * vec4(P + (bentWave - bentFlat) * reach, 1.0);vec2 uv1 = clip1.xy / max(clip1.w, 1e-4) * 0.5 + 0.5;@@ -959,6 +962,8 @@ void main() {// The water in between takes the light out of it, red first, and gives back its own colour: more of it the deeper it goes.vec3 transmit = exp(-u_absorption.rgb * (u_density * column));+ // From below the water between the eye and the surface is the camera's own medium (the underwater effect fogs it), not a column behind the surface.+ if (below) transmit = vec3(1.0);float murk = 1.0 - dot(transmit, vec3(1.0 / 3.0));vec3 scatterColor = mix(u_shallowColor.rgb, u_deepColor.rgb, 1.0 - exp(-column * u_density * 0.5));@@ -982,6 +987,12 @@ void main() {vec3 lit = applyLightingSurface(albedo, N, P, viewDir, 0.0, roughness, 1.0, 1.0, ext);float cosV = clamp(dot(N, viewDir), 0.0, 1.0);float fresnel = 0.0204 + (1.0 - 0.0204) * pow(1.0 - cosV, 5.0);+ if (below) {+ // Out of the water the glancing rays are reflected whole: Snell's window, a cone of sky overhead in a mirror of the water below it.+ float sinT = 1.333 * sqrt(max(1.0 - cosV * cosV, 0.0));+ float cosT = sqrt(max(1.0 - sinT * sinT, 0.0));+ fresnel = sinT >= 1.0 ? 1.0 : 0.0204 + (1.0 - 0.0204) * pow(1.0 - cosT, 5.0);+ }vec3 seen = behind * transmit * (1.0 - fresnel) * (1.0 - foam);// Outside the lake's outline there is no water.if (u_shoreOn > 0.5 && shoreDist < 0.0) discard;@@ -1114,7 +1125,8 @@ fn waterSurface(p : vec2f, time : f32, dist : f32) -> vec3f {N = perturbNormal(Ngeo, P, v.v_texCoord, normalize(vec3f(-slope.x, -slope.y, 1.0)));}#endif- if (dot(viewDir, Ngeo) < 0.0) { N = -N; Ngeo = -Ngeo; }+ let below = dot(viewDir, Ngeo) < 0.0;+ if (below) { N = -N; Ngeo = -Ngeo; }let haveColor = textureSampleLevel(u_sceneColor, u_sceneColor_s, vec2f(0.5), 0.0).a < 0.75;let haveDepth = haveColor && textureSampleLevel(u_sceneDepthMap, u_sceneDepthMap_s, vec2f(0.5), 0.0).a < 0.75;@@ -1126,9 +1138,11 @@ fn waterSurface(p : vec2f, time : f32, dist : f32) -> vec3f {if (haveDepth) { behindDist = textureSampleLevel(u_sceneDepthMap, u_sceneDepthMap_s, clamp(uv0, vec2f(0.001), vec2f(0.999)), 0.0).r; }let column0 = max(behindDist - waterDist, 0.0);- let ratio = 1.0 / 1.333;- let bentWave = refract(-viewDir, N, ratio);- let bentFlat = refract(-viewDir, Ngeo, ratio);+ var ratio = 1.0 / 1.333;+ if (below) { ratio = 1.333; }+ var bentWave = refract(-viewDir, N, ratio);+ var bentFlat = refract(-viewDir, Ngeo, ratio);+ if (below && (dot(bentWave, bentWave) < 0.5 || dot(bentFlat, bentFlat) < 0.5)) { bentWave = vec3f(0.0); bentFlat = vec3f(0.0); }let reach = min(column0, mc.u_distortionRange) * mc.u_refractionStrength;let clip1 = frame.projection * vec4f(P + (bentWave - bentFlat) * reach, 1.0);let w1 = max(clip1.w, 1e-4);@@ -1144,7 +1158,8 @@ fn waterSurface(p : vec2f, time : f32, dist : f32) -> vec3f {column = max(dist1 - waterDist, 0.0);}- let transmit = exp(-mc.u_absorption.rgb * (mc.u_density * column));+ var transmit = exp(-mc.u_absorption.rgb * (mc.u_density * column));+ if (below) { transmit = vec3f(1.0); }let murk = 1.0 - dot(transmit, vec3f(1.0 / 3.0));let scatterColor = mix(mc.u_shallowColor.rgb, mc.u_deepColor.rgb, vec3f(1.0 - exp(-column * mc.u_density * 0.5)));@@ -1167,7 +1182,12 @@ fn waterSurface(p : vec2f, time : f32, dist : f32) -> vec3f {let roughness = mix(mc.u_roughness, 0.7, foam);let lit = applyLightingSurface(albedo, N, P, viewDir, 0.0, roughness, 1.0, 1.0, ext);let cosV = clamp(dot(N, viewDir), 0.0, 1.0);- let fresnel = 0.0204 + (1.0 - 0.0204) * pow(1.0 - cosV, 5.0);+ var fresnel = 0.0204 + (1.0 - 0.0204) * pow(1.0 - cosV, 5.0);+ if (below) {+ let sinT = 1.333 * sqrt(max(1.0 - cosV * cosV, 0.0));+ let cosT = sqrt(max(1.0 - sinT * sinT, 0.0));+ if (sinT >= 1.0) { fresnel = 1.0; } else { fresnel = 0.0204 + (1.0 - 0.0204) * pow(1.0 - cosT, 5.0); }+ }let seen = behind * transmit * (1.0 - fresnel) * (1.0 - foam);var alpha = 0.85;if (haveColor) { alpha = 1.0; }diff --git a/sdk/src/water/index.ts b/sdk/src/water/index.tsindex ad44fb528..95b12a63f 100644--- a/sdk/src/water/index.ts+++ b/sdk/src/water/index.ts@@ -4,6 +4,7 @@ export {WaterBody, WaterForm, Waters, WatersRes, WaterPlugin, waterPlugin, type WaterBodyData, type WaterSample,} from './waterPlugin';export { WAVE_SET, waveFade, waveHeight, waveSlope, type WaveParams } from './waves';+export { UnderwaterPlugin, registerUnderwaterEffect } from './underwater';export { Floating, FloatingPlugin, floatingForce, type FloatingBody, type FloatingData, type FloatingForce } from './floating';export { buildRiverMesh, currentShare } from './riverMesh';export { buildBoxMesh, buildOceanMesh, buildRectMesh, oceanReach, oceanSnap, type RectOptions } from './waterMesh';diff --git a/sdk/src/water/underwater.ts b/sdk/src/water/underwater.tsnew file mode 100644index 000000000..95c0a64f6--- /dev/null+++ b/sdk/src/water/underwater.ts@@ -0,0 +1,172 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file underwater.ts+ * @brief Seeing from under the water: the effect that fogs the world by how much water the light has crossed, and the system that says when.+ *+ * @details The effect is the water's own: its definition and shader are registered here, with the rest of the water module, so a build with no water carries+ * none of it. Every pixel's light has crossed the distance from the eye to what it came from (the far range for the sky), and the+ * water takes it out colour by colour (red first: the same absorption and density the surface's material draws with) and gives back its own+ * colour, which dims with the camera's depth. The system reads the camera's place in the water from {@link Waters.sample} each frame+ * and tells the post-process volume system (see postprocess/underwater.ts), which adds the effect for as long as the camera is under.+ */+import type { App, Plugin } from '../app/app';+import { defineSystem, Schedule } from '../ecs/system';+import { Camera, Transform, type CameraData, type TransformData } from '../ecs/component';+import { Material } from '../render/material';+import { registerEffect } from '../postprocess/effects';+import { setUnderwaterState, submersion } from '../postprocess/underwater';+import { WatersRes } from './waterPlugin';++const SOURCE = `#pragma shader "PP Underwater"+#pragma version 300 es+#pragma domain PostProcess+#pragma param u_absorption color default(0.45,0.09,0.05,1)+#pragma param u_scatterColor color default(0.03,0.2,0.28,1)+#pragma param u_density float default(0.12) range(0,4)+#pragma param u_amount float default(1) range(0,1)+#pragma param u_cameraDepth float default(0) range(0,100000)+#pragma param u_lightFalloff float default(0.004) range(0,1)+#pragma param u_range float default(4000) range(10,100000)++#pragma fragment+precision highp float;++in vec2 v_texCoord;+uniform sampler2D u_texture;+uniform highp sampler2D u_sceneDepth;+out vec4 fragColor;++void main() {+ vec4 src = texture(u_texture, v_texCoord);+ float depth = texelFetch(u_sceneDepth, ivec2(gl_FragCoord.xy), 0).r;+ // How much water the light of this pixel has crossed: the distance from the eye to the surface it came off, and for the sky (no surface) the longest+ // the water is seen through.+ float dist = u_range;+ if (depth < 1.0) {+ vec3 world = worldFromDepth(v_texCoord, depth);+ vec3 entry = worldFromDepth(v_texCoord, 0.0);+ dist = min(length(world - entry), u_range);+ }+ vec3 transmit = exp(-u_absorption.rgb * (u_density * dist));+ // The water gives back its own colour, less of it the deeper the camera is: the light it scatters is what reached it from above.+ vec3 scatter = u_scatterColor.rgb;+#ifdef ES_LINEAR+ scatter = srgbToLinear(scatter);+#endif+ scatter *= exp(-u_lightFalloff * u_cameraDepth);+ vec3 col = src.rgb * transmit + scatter * (1.0 - dot(transmit, vec3(1.0 / 3.0)));+ fragColor = vec4(mix(src.rgb, col, u_amount), src.a);+}+#pragma end++#pragma fragment wgsl+@fragment fn fs_main(v : VSOut) -> @location(0) vec4f {+ let src = textureSampleLevel(t0, s0, v.v_texCoord, 0.0);+ let depth = textureLoad(t7, vec2i(v.pos.xy), 0);+ var dist = mc.u_range;+ if (depth < 1.0) {+ let world = worldFromDepth(v.v_texCoord, depth);+ let entry = worldFromDepth(v.v_texCoord, 0.0);+ dist = min(length(world - entry), mc.u_range);+ }+ let transmit = exp(-mc.u_absorption.rgb * (mc.u_density * dist));+ var scatter = mc.u_scatterColor.rgb;+#ifdef ES_LINEAR+ scatter = srgbToLinear(scatter);+#endif+ scatter = scatter * exp(-mc.u_lightFalloff * mc.u_cameraDepth);+ let col = src.rgb * transmit + scatter * (1.0 - dot(transmit, vec3f(1.0 / 3.0)));+ return vec4f(mix(src.rgb, col, vec3f(mc.u_amount)), src.a);+}+#pragma end+`;++let registered = false;++/** Registers the effect with the post-process registry, once. */+export function registerUnderwaterEffect(): void {+ if (registered) return;+ registered = true;+ registerEffect({+ type: 'underwater',+ label: 'Underwater',+ category: 'atmosphere',+ factory: () => Material.compileShader(SOURCE),+ uniforms: [+ // Per WORLD unit of water: how much of the light a unit takes out (times each colour's absorption).+ { name: 'u_density', label: 'Density', min: 0, max: 4, step: 0.005, defaultValue: 0.12, neutralValue: 0 },+ { name: 'u_amount', label: 'Amount', min: 0, max: 1, step: 0.01, defaultValue: 1, neutralValue: 0 },+ // How far under the surface the camera is; the water module sets it.+ { name: 'u_cameraDepth', label: 'Camera Depth', min: 0, max: 100000, step: 1, defaultValue: 0 },+ // How fast the water's own light dims with the camera's depth, per world unit.+ { name: 'u_lightFalloff', label: 'Light Falloff', min: 0, max: 1, step: 0.0005, defaultValue: 0.004 },+ // The longest the water is seen through: what the sky, which has no surface, is fogged by.+ { name: 'u_range', label: 'Range', min: 10, max: 100000, step: 10, defaultValue: 4000 },+ ],+ colors: [+ { name: 'u_absorption', label: 'Absorption', defaultValue: { r: 0.45, g: 0.09, b: 0.05, a: 1 } },+ { name: 'u_scatterColor', label: 'Colour', defaultValue: { r: 0.03, g: 0.2, b: 0.28, a: 1 } },+ ],+ });+}++type Triple = [number, number, number];++/** A colour or vector uniform of a material as three numbers, or the fallback where it says nothing readable. */+function triple(instance: number, name: string, fallback: Triple): Triple {+ if (!instance) return fallback;+ const v = Material.getUniform(instance, name) as unknown;+ if (Array.isArray(v) && v.length >= 3) return [Number(v[0]), Number(v[1]), Number(v[2])];+ if (v && typeof v === 'object') {+ const o = v as Record<string, number>;+ if ('r' in o) return [o.r!, o.g!, o.b!];+ if ('x' in o) return [o.x!, o.y!, o.z!];+ }+ return fallback;+}++function single(instance: number, name: string, fallback: number): number {+ if (!instance) return fallback;+ const v = Material.getUniform(instance, name);+ return typeof v === 'number' ? v : fallback;+}++/** The plugin that keeps the post-process volume system told whether the camera is under water. */+export class UnderwaterPlugin implements Plugin {+ name = 'underwater';+ build(app: App): void {+ app.addSystemToSchedule(Schedule.Update, defineSystem([], () => {+ if (!app.hasResource(WatersRes)) return;+ const waters = app.getResource(WatersRes);+ let eye: [number, number, number] | null = null;+ for (const entity of app.world.getEntitiesWithComponents([Camera, Transform])) {+ if (!(app.world.get(entity, Camera) as CameraData).isActive) continue;+ const t = app.world.get(entity, Transform) as TransformData;+ eye = [t.worldPosition.x, t.worldPosition.y, t.worldPosition.z];+ break;+ }+ const sample = eye ? waters.sample(eye[0], eye[1], eye[2]) : null;+ if (!sample || !(sample.depth < 0)) { setUnderwaterState(null); return; }+ const built = waters.built_.get(sample.entity);+ const instance = built?.instance ?? 0;+ const depth = -sample.depth;+ const density = single(instance, 'u_density', 0.12);+ const shallow = triple(instance, 'u_shallowColor', [0.10, 0.42, 0.46]);+ const deep = triple(instance, 'u_deepColor', [0.01, 0.08, 0.15]);+ // Deeper, the water gives back more of its deep colour: the same blend the surface draws.+ const toDeep = 1 - Math.exp(-depth * density * 0.5);+ setUnderwaterState({+ amount: submersion(depth, Math.max(1, (built?.data.waveHeight ?? 0) * 0.5)),+ depth,+ absorption: triple(instance, 'u_absorption', [0.45, 0.09, 0.05]),+ density,+ scatter: [shallow[0] + (deep[0] - shallow[0]) * toDeep, shallow[1] + (deep[1] - shallow[1]) * toDeep, shallow[2] + (deep[2] - shallow[2]) * toDeep],+ });+ }, { name: 'UnderwaterSystem' }));+ }++ cleanup(): void {+ setUnderwaterState(null);+ }+}diff --git a/sdk/src/water/waterSupport.ts b/sdk/src/water/waterSupport.tsindex 6b3de0dfc..825a90811 100644--- a/sdk/src/water/waterSupport.ts+++ b/sdk/src/water/waterSupport.ts@@ -8,8 +8,11 @@import { addEntryPlugin } from '../runtime/entryPlugins';import { WaterPlugin } from './waterPlugin';import { FloatingPlugin } from './floating';+import { UnderwaterPlugin, registerUnderwaterEffect } from './underwater';export function registerWaterSupport(): void {addEntryPlugin('water', () => new WaterPlugin());addEntryPlugin('floating', () => new FloatingPlugin());+ addEntryPlugin('underwater', () => new UnderwaterPlugin());+ registerUnderwaterEffect();}diff --git a/sdk/tests/water-underwater.test.ts b/sdk/tests/water-underwater.test.tsnew file mode 100644index 000000000..00ed83dd7--- /dev/null+++ b/sdk/tests/water-underwater.test.ts@@ -0,0 +1,72 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+import { describe, expect, it } from 'vitest';+import { applyUnderwaterToEffects, setUnderwaterState, currentUnderwater, submersion, type UnderwaterState } from '../src/postprocess/underwater';+import type { BlendedEffect } from '../src/postprocess/volumeBlending';++const state = (extra: Partial<UnderwaterState> = {}): UnderwaterState => ({+ amount: 1, depth: 40, absorption: [0.4, 0.1, 0.05], density: 0.02, scatter: [0.02, 0.2, 0.3], ...extra,+});+const blank = (): BlendedEffect => ({ enabled: true, uniforms: new Map(), textures: new Map(), colors: new Map() });++describe('submersion', () => {+ it('is none above the surface and at it, and whole from the fade down', () => {+ expect(submersion(-5, 2)).toBe(0);+ expect(submersion(0, 2)).toBe(0);+ expect(submersion(1, 2)).toBe(0.5);+ expect(submersion(2, 2)).toBe(1);+ expect(submersion(50, 2)).toBe(1);+ });+});++describe('applyUnderwaterToEffects', () => {+ it('does nothing out of the water', () => {+ const effects = new Map<string, BlendedEffect>();+ applyUnderwaterToEffects(effects, null);+ applyUnderwaterToEffects(effects, state({ amount: 0 }));+ expect(effects.size).toBe(0);+ });++ it('brings the effect, with the water\'s own numbers, to a scene that authored none', () => {+ const effects = new Map<string, BlendedEffect>();+ applyUnderwaterToEffects(effects, state());+ const e = effects.get('underwater')!;+ expect(e.enabled).toBe(true);+ expect(e.uniforms.get('u_density')).toBe(0.02);+ expect(e.uniforms.get('u_amount')).toBe(1);+ expect(e.uniforms.get('u_cameraDepth')).toBe(40);+ expect(e.colors.get('u_absorption')).toEqual({ r: 0.4, g: 0.1, b: 0.05, a: 1 });+ expect(e.colors.get('u_scatterColor')).toEqual({ r: 0.02, g: 0.2, b: 0.3, a: 1 });+ });++ it('keeps the numbers a scene authored, and only fills in the depth and the amount', () => {+ const authored = blank();+ authored.uniforms.set('u_density', 0.5);+ authored.uniforms.set('u_amount', 0.5);+ authored.colors.set('u_absorption', { r: 1, g: 1, b: 1, a: 1 });+ const effects = new Map<string, BlendedEffect>([['underwater', authored]]);+ applyUnderwaterToEffects(effects, state({ amount: 0.5, depth: 7 }));+ expect(authored.uniforms.get('u_density')).toBe(0.5);+ expect(authored.colors.get('u_absorption')).toEqual({ r: 1, g: 1, b: 1, a: 1 });+ // The authored amount is a ceiling on how much the effect shows, and the camera's own submersion scales it.+ expect(authored.uniforms.get('u_amount')).toBeCloseTo(0.25, 10);+ expect(authored.uniforms.get('u_cameraDepth')).toBe(7);+ });++ it('leaves an effect the scene switched off alone', () => {+ const off = blank();+ off.enabled = false;+ const effects = new Map<string, BlendedEffect>([['underwater', off]]);+ applyUnderwaterToEffects(effects, state());+ expect(off.uniforms.size).toBe(0);+ });+});++describe('the reported state', () => {+ it('is what was last set, and none after null', () => {+ setUnderwaterState(state({ depth: 12 }));+ expect(currentUnderwater()?.depth).toBe(12);+ setUnderwaterState(null);+ expect(currentUnderwater()).toBeNull();+ });+});diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjsindex ba48a3e8e..8b9e7d386 100644--- a/tools/releaseNotes.mjs+++ b/tools/releaseNotes.mjs@@ -2565,6 +2565,8 @@ export const NOTED = {{"note":"A WaterBody can be a river: put a Spline on its entity and it lays a ribbon along the curve, as wide as the curve says at each point and at its height, with a current (`flowSpeed`, faster where it narrows) that the shader carries the waves and ripples along and that `Waters.sample` reports as `flow`. Splines are a new optional module (`esengine/spline`): a curve through points with a width each, measured by the distance along it."},"feat(water): a Floating component holds a rigid body up in water and carries it with the current":{"note":"Water holds things up. A Floating component on an entity with a RigidBody3D floats it: a buoyant force against gravity (`buoyancy` is the water's density against the body's, so 2 floats it half under) and a drag against its velocity relative to the water, which brings it to rest in a lake and carries it with a river's current, applied at a few points of the body so waves tip it. It works from the CPU's own water surface, so it needs no renderer, and it needs the 3D physics module, which gains force and mass queries."},+ "feat(water): a camera under the surface sees through the water, fogged and tinted by what it has crossed":+ {"note":"A camera under water sees through it. Whenever the active camera is below a water body's surface an Underwater effect is added to the post-process volumes: the light of each pixel is taken out colour by colour (red first) by the distance it crossed, with the same absorption and density the surface's material draws with, and the water gives back its own colour, dimmer the deeper the camera is. The surface seen from below turns over and, past the critical angle, reflects whole (Snell's window)."},"chore(tools): the gates run in parallel with --jobs, and the reds a full run gathered are cleared":{"internal":"tooling for the static gates, and fixes to checks that had drifted from the code they guard"},"fix(render): a wire narrower than a pixel is no longer painted over by the sky in dashes":