Skip to content

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.

docs(materials): default(ripples), and the note for the water's ripple map

yhhebd56d66dfe4
diff --git a/CHANGELOG.md b/CHANGELOG.md
index bc683a683..f7b8842c5 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -18,6 +18,7 @@ published separately; it ships inside the editor.
- **A texture says whether it is a picture or numbers.** Import settings have a **Use**: Colour, or Data for an image read a number a texel (a heightmap, a mask of measured values, a lookup table). A build treats Data as what it is: never compressed, never decoded as sRGB or filled, kept at its depth, and at its own size unless Max Size (which now offers Source size) says otherwise, in which case it is resampled at 16 bits and not through 8. Nobody has to know to set it: a PNG of 16 bits a sample is imported as Data from the editor and the CLI alike, a texture put in a `Terrain`'s heightmap or splatmap is marked Data there and then (a splatmap cooked as a picture had its weights overwritten wherever the fourth was 0, and the ground fell back to grass everywhere), and Project Health lists textures a component reads as numbers that are still set up as pictures, with the fix on the row.
- **An ocean reaches the horizon.** The sea's surface is rings of mesh round the camera, and it ended where they did: from a hill, or with a small `cells` and `rings`, a straight edge with nothing past it. A flat apron now carries it on to 80 km, at the cost of one row of quads.
+- **The wind's ripples are a map of many waves.** The small ripples on water were six straight wave trains summed in the shader. Low across the water the short ones faded and the two longest crossed in a regular board of dark spots. They are now two fields of a tiling normal map the engine makes from 96 waves at every heading, read with mips and scrolled downwind, as Unreal's water reads its normal maps: no lattice, nothing finer than a pixel, and two texture reads where there were six waves. `u_rippleStrength`, `u_rippleLength`, the wind's direction and speed mean what they did. The map is `default(ripples)`, a built-in a shader of your own can name; water's `u_detailMap` defaults to it, so a material that sets its own detail map gets its ripples from that map.
- **A shader param's range is where its slider runs.** `range(min,max)` on a `#pragma param` set the slider in the material inspector and also clamped the number typed beside it, so a value the shader's author had not thought of could not be entered. The range is now the slider's reach only, as a UI range is in Unreal: the box takes any number, and the thumb rests at the end of the track.
- **One setting says what a unit is, for materials too.** A shader param declares `unit(length)` or `unit(perLength)` and its default and range follow the project's Units per Metre, as a component's lengths and a post-process effect's already did; the inspector shows the project's numbers. The water was the reason: its shader, `WaterBody`, `WaterZone` and the sky's World Units per km held their defaults in metres while the engine's reference is centimetres, so stock water in a default project was a hundredth of its size and a scene in metres copied from one in centimetres drew clear water. They are now written once, at the reference, and are the same water in either. **A scene that relied on the old defaults in a centimetre project** (a `WaterBody` or `WaterZone` field left unset, a Water material with unset lengths, clouds with World Units per km unset) draws them a hundred times larger than before, which is what they were meant to be; state the values, or set Units per Metre to 1 if the scene is in metres.
diff --git a/docs/astro/src/content/docs/graphics/materials.mdx b/docs/astro/src/content/docs/graphics/materials.mdx
index 093f4a647..be874ee93 100644
--- a/docs/astro/src/content/docs/graphics/materials.mdx
+++ b/docs/astro/src/content/docs/graphics/materials.mdx
@@ -118,7 +118,7 @@ The **Model** shader is a metal/rough surface with layers on top. Each is off at
Everything here is written by model import from the glTF extensions of the same names (`KHR_materials_clearcoat`, `_sheen`, `_anisotropy`, `_ior`, `_specular`, `_iridescence`, `_transmission`, `_volume`, `_diffuse_transmission`) — see [Models](/docs/assets/models/).
In the editor a Model material shows each layer as a section of its own with a switch in the header: off sets the layer's
-strength to 0 (its colour to black for sheen), on gives it a strength where it looks like itself, and the section's fields tune
+strength to 0 (its colour to`default(white | black | flatnormal | ripples)` fallback when unset (`ripples` is the engine's tiling map of wind ripples: two fields of normals, in rg and in ba).for sheen), on gives it a strength where it looks like itself, and the section's fields tune
it. Reflectance, the index of refraction and the specular scale, has no switch.
**Limits.** These are cheap, real-time models, and say where they stop:
@@ -248,7 +248,7 @@ says which one found no unit.
| `float` / `int` | `float` / `int` | `number` | Scalar knob; `range(min,max)` + `ui(slider)` for the inspector. |
| `vec2` / `vec3` / `vec4` | same | `[x, y, …]` | Vector knob. |
| `color` | `vec4` | `[r, g, b, a]` | RGBA, 0..1; color picker in the inspector. |
-| `texture` | `sampler2D` | texture handle | `default(white \| black \| flatnormal)` fallback when unset. Add `texel(data)` when the shader reads the texels as numbers (a normal map, packed roughness): Project Health then flags a texture bound there that is still marked sRGB, which the linear pipeline would decode as colour. |
+| `texture` | `sampler2D` | texture handle | `default(white | black | flatnormal | ripples)` fallback when unset (`ripples` is the engine's tiling map of wind ripples: two fields of normals, in rg and in ba).\| black \| flatnormal)` fallback when unset. Add `texel(data)` when the shader reads the texels as numbers (a normal map, packed roughness): Project Health then flags a texture bound there that is still marked sRGB, which the linear pipeline would decode as colour. |
Params live in an engine-generated std140 block, initialized from their `default(…)`
values — a material that never sets a param still draws correctly.
diff --git a/docs/astro/src/content/docs/zh-cn/graphics/materials.mdx b/docs/astro/src/content/docs/zh-cn/graphics/materials.mdx
index b2db2e429..89281d1d5 100644
--- a/docs/astro/src/content/docs/zh-cn/graphics/materials.mdx
+++ b/docs/astro/src/content/docs/zh-cn/graphics/materials.mdx
@@ -208,7 +208,7 @@ WGSL。不用自己写:编辑器读取 shader 时会从 GLSL 自动派生,每次
| `float` / `int` | `float` / `int` | `number` | 标量旋钮;`range(min,max)` + `ui(slider)` 控制检视器。 |
| `vec2` / `vec3` / `vec4` | 同名 | `[x, y, …]` | 向量旋钮。 |
| `color` | `vec4` | `[r, g, b, a]` | RGBA,0..1;检视器里是取色器。 |
-| `texture` | `sampler2D` | 纹理句柄 | `default(white \| black \| flatnormal)` 未设置时的回退。着色器把贴图当数值读(法线贴图、打包的粗糙度)时加 `texel(data)`:项目健康检查会指出绑在这里却仍标为 sRGB 的贴图,线性管线会把它当颜色解码。 |
+| `texture` | `sampler2D` | 纹理句柄 | `default(white | black | flatnormal | ripples)` 未设置时的回退(`ripples` 是引擎自带的可平铺风浪波纹图:rg 和 ba 各一组法线)。\| black \| flatnormal)` 未设置时的回退。着色器把贴图当数值读(法线贴图、打包的粗糙度)时加 `texel(data)`:项目健康检查会指出绑在这里却仍标为 sRGB 的贴图,线性管线会把它当颜色解码。 |
参数存在引擎生成的 std140 块里,并从 `default(…)` 初始化——材质从未设置某参数也能正确绘制。
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index 2b834fd0a..6bdcf5fcb 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -4530,6 +4530,8 @@ export const NOTED = {
{"note": "Water mirrors only what is there."},
"feat(material): a shader param's range is where its slider runs, not a limit - a typed value may go past it":
{"note": "A shader param's range is where its slider runs."},
+ "feat(water): the wind's ripples are a map of many waves, not six - two fields of a built-in tiling normal map, default(ripples), read with mips, where six straight wave trains crossed in a board of dark spots once the short ones had faded":
+ {"note": "The wind's ripples are a map of many waves."},
"fix(terrain): a splatmap is numbers too - cooked as a picture its three weights were overwritten wherever the fourth was 0, and the whole ground was painted as grass; it is marked Data when it is set, as the heightmap is":
{"note": "A texture says whether it is a picture or numbers."},
};