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): two tiled, scrolling detail normal maps give the surface its sparkle
yhh97c7d33a1e5f
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 348770cae..c45c0bc0e 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -16,6 +16,7 @@ published separately; it ships inside the editor.### Added+- **Sparkle on the water.** The Water shader reads two tiled normal maps that scroll over the surface (`u_detailMap`, `u_detailTile0/1`, `u_detailStrength0/1`, `u_detailFlow0/1`), packed into the one texture a material has room for, so the sun's glints on small slopes come from lit specular response and not a white texture; a material that sets no strength is unchanged.- **A generated world's plants.** A recipe's members can name a **plant** in the rules' `plants` (a `.esworld` file holds them): several parts (a trunk and its crown), a cheaper mesh and a far version, the colourings the art gives it, how far it is sunk and its `unit` (100 for metres in a world of centimetres). The world is laid out from the rules as the eye moves, the plants grown a cell at a time by the machinery a `PlacedFoliage` uses: a chunk stands at once and fills in over the frames after it inside the frame's budget, a cheaper mesh stands in at the middle distance, and a tree's crossed cards, laid out as a layer of their own, stand for it far off. The terrain's paint is a field each of its layers (`paint.grass`), a rules file names noise fields of its own, and fields are worked out only where a condition reads them. The Terrain & Water example's woods, shrubs, stones, grass, flowers and reeds are laid out this way from `assets/worlds/plants.esworld`.- **Each terrain layer says how it meets the others.** A `.esterrainlayer` may name a `heightBlend`: 0 blends by the paint alone (grass into sand), 1 by the layers' heights (stones standing through grass), weighted by how much of each layer is there; absent, it is the material's `u_heightBlend`. The editor's layer panel sets it.- **Placed plants.** `PlacedFoliage` keeps every plant an artist placed by hand as data in one entity, a table of kinds and six numbers a plant, instead of an entity, a renderer and a draw each. The engine cuts the area into cells and grows only those round the eye, each as one mesh for every part of every kind in it, a few milliseconds a piece of the frame's budget so a cell fills in over the frames after it appears, and lets them go past their distance. A kind keeps the mesh as made (normal map, second uv, vertex colour), has a cheaper mesh for the middle distance and a far version, a tree's crossed cards, drawn out to a far distance: a hierarchical level of detail that makes the whole area stand at once. The Terrain & Water example now grows its woods, shrubs, stones, grass, flowers and reeds this way from the lakewood plant set, and its grass and sand are that set's terrain layers.diff --git a/docs/astro/src/content/docs/graphics/water.mdx b/docs/astro/src/content/docs/graphics/water.mdxindex cfe73b5ce..75ec55e7e 100644--- a/docs/astro/src/content/docs/graphics/water.mdx+++ b/docs/astro/src/content/docs/graphics/water.mdx@@ -305,6 +305,12 @@ is its x and z, `u_origin` is where the mesh was moved to as it follows the came`u_rippleLength`, more of them the harder it rains, and the surface a little less sharp. They are drawn, not simulated: they put nothing in the zone's ripplesand make no foam, and they fade out with distance. On a zone's surface the zone writes the four every frame (its own length, speed and heading, andthe weather's share as the height, which each place's height in the field multiplies), so the material's values for them are not used there.+- **Sparkle.** The sun's glints on small slopes come from two tiled normal maps that scroll over the surface, in the one texture a material has room for:+ `u_detailMap`, whose red and green are the first map's slope (x and z, 0.5 flat) and whose blue and alpha are the second's, read as data. Each has+ its `u_detailTile` (world units to a repeat), `u_detailStrength` (how many times as steep as drawn; 0 leaves it out, which is how a material that sets+ none stays as it was) and `u_detailFlow` (world units a second it drifts). The glints are the lit specular response of those slopes, not a white+ texture drawn on, so they appear where the sun, the eye and the slope line up and fade as the light does. They are fragment-only: the geometry and+ `Waters.sample` do not carry them.- **Refraction and depth.** What is under the water is the picture of the opaque scene, shifted by the waves in proportion to how much water thereis. The depth is **measured**: before the water is drawn the frame takes a copy of how far each pixel of the scene is from the eye, so the water ata pixel is the difference between that and the water's own distance. The light is absorbed along that column, red first (`u_absorption`,diff --git a/docs/astro/src/content/docs/zh-cn/graphics/water.mdx b/docs/astro/src/content/docs/zh-cn/graphics/water.mdxindex 3c42d83ef..e1e896100 100644--- a/docs/astro/src/content/docs/zh-cn/graphics/water.mdx+++ b/docs/astro/src/content/docs/zh-cn/graphics/water.mdx@@ -201,6 +201,7 @@ Details 只显示水体这种形态用得到的字段:湖有尺寸和边界,河- **焦散。** `u_causticStrength`(0 关掉它)、`u_causticScale`(一格的大小,世界单位)和 `u_causticSpeed` 决定水下东西上那张光网的样子,从上面看是这样,通过效果从下面看也是这样。- **波浪。** `u_waveLength`、`u_waveHeight`、`u_waveSpeed`、`u_waveDirection`;风吹起的涟漪(`u_rippleStrength`、`u_rippleLength`)骑在它们上面:围绕风向的六道短波,从 `u_rippleLength` 到它的五分之一,每道在会闪烁之前随距离淡出。- **雨。** `Weather` 驱动雨时,雨滴在水面上激起环纹(`u_rain`,由区域写入):向外扩散然后消失的圆环,每个 `u_rippleLength` 里有几个,雨越大越多,水面也稍微变得不那么锐利。它们是画出来的而不是模拟的:不会往区域的涟漪里放任何东西,也不产生泡沫,并随距离淡出。在区域的水面上,这四个由区域每帧写入(它自己的波长、速度和方向,高度则是天气的份额,再乘以场里每一处的高度),所以材质里这四个值在那里不起作用。+- **碎闪。** 阳光在细小坡面上的亮点来自两张可平铺、在表面上滚动的法线图,它们打包在材质唯一容得下的那一张纹理 `u_detailMap` 里:红绿是第一张的坡度(x 和 z,0.5 为平),蓝和透明是第二张的,按数据读取。每张有自己的 `u_detailTile`(重复一次的世界单位)、`u_detailStrength`(比图上画的陡多少倍;0 表示不用,没设置的材质因此保持原样)和 `u_detailFlow`(每秒漂移的世界单位)。亮点是这些坡面受光后的镜面反应,不是画上去的白色贴图,所以只出现在太阳、眼睛和坡面对齐的地方,光变弱它们也跟着淡出。它们只在片元里计算:几何体和 `Waters.sample` 不带它们。- **折射与水深。** 水下看到的是不透明场景的画面,被波浪按水量多少偏移。水深是**量出来的**:绘制水之前,帧会拷贝一份场景每个像素离眼睛多远,水在某个像素处的深度就是那个距离与水面自己的距离之差。光沿着这段水柱被吸收——红色最先(`u_absorption`、`u_density`)——水再还给你它自己的颜色,随水变深从 `u_shallowColor` 过渡到 `u_deepColor`。- **反射。** 天空、灯光和环境按菲涅尔项反射(水是 1.333),所以俯视时清澈、掠射时像镜子。想要场景本身的倒影,在体积里加上屏幕空间反射。- **泡沫。** 水柱浅于 `u_foamWidth` 的地方(岸边、礁石、桥墩脚下)和波峰上(`u_foamCrest`)出现泡沫,由流动的噪声打散。在区域的水面上,烘好的岸线也起泡沫,范围是离岸边或浅水 `u_foamWidth` 以内,所以量不出深度的地方岸边也有泡沫。diff --git a/sdk/src/water/waterShader.ts b/sdk/src/water/waterShader.tsindex 1cae5aa1d..d211d8e4a 100644--- a/sdk/src/water/waterShader.ts+++ b/sdk/src/water/waterShader.ts@@ -91,6 +91,16 @@ const WATER = `#pragma shader "Water"// The disturbance the water keeps (WaterZone ripples): a window of the xz plane, red the height of the ripples (0.5 at rest, u_rippleRange above or below at 1 and 0)// and green the foam they left, as the CPU stepped them. u_rippleSize is the window's side, u_rippleTexel one texel of it.#pragma param u_rippleOn float default(0) range(0,1) ui(slider)+// Two tiled normal maps that scroll over the surface, for the sparkle the sun makes of a water's small slopes, in the one texture a material has room+// for: red and green the first's slope (x and z, 0.5 flat), blue and alpha the second's, read as data. Each is u_detailTile world units to a repeat,+// u_detailStrength times as steep as drawn (0 leaves it out), and slides u_detailFlow world units a second.+#pragma param u_detailMap texture default(flatnormal) texel(data)+#pragma param u_detailTile0 float default(2) range(0.01,100000) ui(slider)+#pragma param u_detailTile1 float default(4.3) range(0.01,100000) ui(slider)+#pragma param u_detailStrength0 float default(0) range(0,8) ui(slider)+#pragma param u_detailStrength1 float default(0) range(0,8) ui(slider)+#pragma param u_detailFlow0 vec2 default(0.05,0.02)+#pragma param u_detailFlow1 vec2 default(-0.03,0.04)#pragma param u_rippleMap texture default(white) texel(data)#pragma param u_rippleOrigin vec2 default(0,0)#pragma param u_rippleSize float default(64) range(0.01,100000) ui(slider)@@ -543,6 +553,21 @@ vec4 waterReflect(vec3 p, vec3 r, float eyeDist) {return vec4(0.0);}+/// The slope the two detail normal maps add at p: each read at its own tile and drift, its z made from its x and z, mips flattening+/// what a pixel is too far to see. Fragment only: a vertex cannot take the derivatives a map is read with.+vec2 detailSlope(vec2 p, float time) {+ vec2 slope = vec2(0.0);+ if (u_detailStrength0 > 0.0) {+ vec2 n = texture(u_detailMap, (p + u_detailFlow0 * time) / u_detailTile0).rg * 2.0 - 1.0;+ slope += n / sqrt(max(1.0 - dot(n, n), 0.0625)) * u_detailStrength0;+ }+ if (u_detailStrength1 > 0.0) {+ vec2 n = texture(u_detailMap, (p + u_detailFlow1 * time) / u_detailTile1).ba * 2.0 - 1.0;+ slope += n / sqrt(max(1.0 - dot(n, n), 0.0625)) * u_detailStrength1;+ }+ return slope;+}+/// The slope of the surface at p and how near it is to a crest: the waves, amp times as high as u_waveHeight says, and the ripples they carry,/// calm of their strength, flattened with distance.vec2 waterSurface(vec2 p, float time, float dist, float amp, float calm, out float crest) {@@ -621,7 +646,7 @@ void main() {}// Rain rings are fine: where a pixel grows past a ring's crests they would shimmer, so they fade out before it.float rainFade = 1.0 - smoothstep(u_rippleLength * 8.0, u_rippleLength * 20.0, waterDist);- slope += ripSlope + toSea * (surfRise * u_geoWaves) + rainRings(wp, time, u_rain) * rainFade;+ slope += ripSlope + toSea * (surfRise * u_geoWaves) + rainRings(wp, time, u_rain) * rainFade + detailSlope(wp, time) * calm;vec3 N = normalize(vec3(-slope.x, 1.0, -slope.y));vec3 Ngeo = vec3(0.0, 1.0, 0.0);#ifdef MESH_NORMALS@@ -990,6 +1015,20 @@ fn waterReflect(p : vec3f, r : vec3f, eyeDist : f32) -> vec4f {return vec4f(0.0);}+/// The slope the two detail normal maps add at p: each read at its own tile and drift, mips flattening what a pixel is too far to see. Fragment only.+fn detailSlope(p : vec2f, time : f32) -> vec2f {+ var slope = vec2f(0.0);+ if (mc.u_detailStrength0 > 0.0) {+ let n = textureSample(u_detailMap, u_detailMap_s, (p + mc.u_detailFlow0 * time) / mc.u_detailTile0).rg * 2.0 - vec2f(1.0);+ slope = slope + n / sqrt(max(1.0 - dot(n, n), 0.0625)) * mc.u_detailStrength0;+ }+ if (mc.u_detailStrength1 > 0.0) {+ let n = textureSample(u_detailMap, u_detailMap_s, (p + mc.u_detailFlow1 * time) / mc.u_detailTile1).ba * 2.0 - vec2f(1.0);+ slope = slope + n / sqrt(max(1.0 - dot(n, n), 0.0625)) * mc.u_detailStrength1;+ }+ return slope;+}+/// The slope of the surface at p (x, y) and how near it is to a crest (z): the waves, and the ripples they carry, flattened with distance.fn waterSurface(p : vec2f, time : f32, dist : f32, amp : f32, calm : f32) -> vec3f {let waves = waveSlope(p, time, dist);@@ -1076,7 +1115,7 @@ fn waterSurface(p : vec2f, time : f32, dist : f32, amp : f32, calm : f32) -> vecvar waves : Waves;waves.crest = surface.z;let rainFade = 1.0 - smoothstep(mc.u_rippleLength * 8.0, mc.u_rippleLength * 20.0, waterDist);- var slope = surface.xy + ripSlope + toSea * (surfRise * mc.u_geoWaves) + rainRings(wp, time, mc.u_rain) * rainFade;+ var slope = surface.xy + ripSlope + toSea * (surfRise * mc.u_geoWaves) + rainRings(wp, time, mc.u_rain) * rainFade + detailSlope(wp, time) * calm;var N = normalize(vec3f(-slope.x, 1.0, -slope.y));var Ngeo = vec3f(0.0, 1.0, 0.0);#ifdef MESH_NORMALSdiff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjsindex 809fbbd44..7f04aca9d 100644--- a/tools/releaseNotes.mjs+++ b/tools/releaseNotes.mjs@@ -2822,6 +2822,8 @@ export const NOTED = {{"note":"Foam is where waves burst, not along every shore."},"fix(water): a gentle beach keeps less of the breakers' white than rock does":{"note":"Foam is where waves burst, not along every shore."},+ "feat(water): two tiled, scrolling detail normal maps give the surface its sparkle":+ {"note":"Sparkle on the water."},"fix(lod): a LODGroup with only a cull size is no longer ignored":{"note":"A level-of-detail group with only a cull size is no longer ignored."},"feat(terrain): each terrain layer says how it meets the others, and the terrain's paint and bounds can be asked":