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.

feat(editor): the points of a lake and a river are edited with handles in the viewport, and Details shows only what the form uses

yhh03ee0696e2ab
diff --git a/CHANGELOG.md b/CHANGELOG.md
index d0b8ce360..66ecdf5b6 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.
+- **Water editing in the viewport.** Select a lake or a river and its points are handles in the viewport: drag a point to move it on the body's own plane, drag the circle on an edge to insert one, press and release a point to delete it (a lake keeps three, a river two), and drag the handle beside a river's point to set its width there. Each gesture is one undo step. Details shows a water body only the fields its form uses, with a Boundary row for a lake's outline and the point count and the pressed point's width under a Spline. Also: the move gizmo now travels with the entity while an axis is dragged, instead of staying where the grab began.
- **Blended surfaces ordered against water.** A blended surface (a pane, a particle, a leaf card) is now ordered against water and glass by the pixel and not by when it was drawn: one under the surface is seen through the water, one in front of it lies on the water instead of being covered, and where there is no water it is blended once. The frame is drawn in layers only when it holds both a refracting surface and a blended draw.
- **Ripples and wakes.** A body of water keeps what disturbs it. With `ripples` above 0 the water steps a window of its surface (that follows the camera) with the wave equation: `Waters.disturb(x, y, z, radius, strength)` and a `Floating` body's wake (`wake`) put in bumps that spread as rings, fade, and bend the shading and the reflection, and leave foam that lingers and thins (`rippleSpeed`, `rippleDamping`, `foamFade`). `Waters.sample` carries the ripples, and `Waters.rippleAt` gives them alone.
- **Waterline, caustics, shafts and a mirror under the water.** Under water the picture is lit and bounded like water. A camera with its lens half in the water has a waterline across it, soft and sliding as it dips; what it sees is lit by the web of caustics the waves focus the sun into (the Water material's `u_causticStrength`, `u_causticScale` and `u_causticSpeed`, also drawn on what lies under the water seen from above); the water along each ray scatters the sun into shafts (`u_shaftStrength`); and the surface seen from below, past the critical angle, mirrors the world beneath it.
diff --git a/desktop b/desktop
index b8832e2ea..373ce7ffa 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit b8832e2eacec0efb8703e1d28d792f898d0bbd3e
+Subproject commit 373ce7ffafcdc91a20bf8cb3f3ad03d1f61d9831
diff --git a/docs/astro/src/content/docs/graphics/water.mdx b/docs/astro/src/content/docs/graphics/water.mdx
index 4fe6b13da..b6509cfd2 100644
--- a/docs/astro/src/content/docs/graphics/water.mdx
+++ b/docs/astro/src/content/docs/graphics/water.mdx
@@ -159,6 +159,20 @@ It is a centripetal Catmull-Rom curve (it passes through every point, and does n
measured by distance along it, so a place on it is `s` units from its start and not a parameter that runs fast where the points are close. Past either
end of an open curve it is the end; a closed curve goes round. Splines are an optional module (`esengine/spline`).
+## In the editor
+
+Details shows a water body only what its form uses: a lake has its size, boundary and shore width, an ocean its cells and rings, a river its flow speed; the waves, ripples and
+look are common. A lake's **Boundary** row says how many points its outline has (or that it is the rectangle of its size) and resets it to the rectangle.
+
+Select a lake or a river and its points are handles in the viewport, the way a polygon collider's vertices are:
+
+- **Lake.** A square on each point of the outline and a circle in the middle of each edge. Drag a point to move it on the lake's own plane (the plane of its transform, so a tilted
+ lake is edited tilted); drag an edge's circle to insert a point there; press a point and release it in place to delete it. A lake keeps at least three points, and with none the
+ four corners of its rectangle are the points: pulling one turns the outline into a boundary of its own.
+- **River.** The same on the curve of its `Spline`, with a second handle at each point, offset across the river by half its width: drag it to set the width there. A river keeps at least two
+ points. The point last pressed shows its width in Details under the Spline, where it can be typed.
+- Each gesture is one undo step, and the points are written back as they are dragged, so the water follows. The handles are the **Water** entry of the Gizmo menu.
+
## Asking the surface
`Waters.sample(x, y, z)` (the `WatersRes` resource) answers for the body that holds a point:
diff --git a/docs/astro/src/content/docs/zh-cn/graphics/water.mdx b/docs/astro/src/content/docs/zh-cn/graphics/water.mdx
index f37ffbce4..e9420f6b7 100644
--- a/docs/astro/src/content/docs/zh-cn/graphics/water.mdx
+++ b/docs/astro/src/content/docs/zh-cn/graphics/water.mdx
@@ -106,6 +106,16 @@ curve.nearest(x, z); // 在 xz 平面上离它最近的地方:s、距离、在
它是向心 Catmull-Rom 曲线(穿过每一个点,点在一头密、另一头疏时也不会打圈或出尖),按沿曲线的距离来度量,所以曲线上的位置是离起点 `s` 个单位,而不是在点靠得近的地方跑得很快的参数。开放曲线越过两端就停在端点;闭合曲线会绕回去。样条是一个可选模块(`esengine/spline`)。
+## 在编辑器里
+
+Details 只显示水体这种形态用得到的字段:湖有尺寸、边界和岸线宽度,海有格子数和环数,河有流速;波浪、涟漪和外观是共有的。湖的 **边界** 一行说明它的轮廓有多少个点(或者说它就是按尺寸画出的矩形),并可以重置回矩形。
+
+选中湖或河,它的点就成为视口里的手柄,和多边形碰撞体的顶点一样:
+
+- **湖。** 轮廓每个点上一个方块,每条边中间一个圆。拖动点,在湖自己的平面上移动它(也就是它的变换所在的平面,所以倾斜的湖是倾斜着编辑的);拖动边上的圆,在那里插入一个点;按住一个点、原地松开,删除它。湖至少保留三个点;没有点时,矩形的四个角就是这些点:拉动其中一个,轮廓就变成它自己的边界。
+- **河。** 在它的 `Spline` 曲线上同样操作,每个点上还有第二个手柄,沿河的横向偏出宽度的一半:拖动它来设置那里的宽度。河至少保留两个点。最后按下的点,会在 Details 的 Spline 下显示它的宽度,可以直接输入。
+- 每次手势是一步撤销,点是边拖边写回的,所以水会跟着变。这些手柄是 Gizmo 菜单里的 **Water** 一项。
+
## 查询表面
`Waters.sample(x, y, z)`(资源 `WatersRes`)为包含这个点的水体作答:
diff --git a/sdk/rolldown.config.js b/sdk/rolldown.config.js
index 9dcf9cd2e..1a3d13f05 100644
--- a/sdk/rolldown.config.js
+++ b/sdk/rolldown.config.js
@@ -103,6 +103,8 @@ export default defineConfig([
'fx-atmosphere/index': 'src/postprocess/fxAtmosphere.ts',
'fx-lighting/index': 'src/postprocess/fxLighting.ts',
'foliage/index': 'src/foliage/index.ts',
+ 'water/index': 'src/water/index.ts',
+ 'spline/index': 'src/spline/index.ts',
'logic/index': 'src/logic/index.ts',
'debug-channel/index': 'src/debug-channel/index.ts',
'ai/index': 'src/ai/index.ts',
diff --git a/sdk/rollup.config.js b/sdk/rollup.config.js
index 58e3337d1..d0c3094c6 100644
--- a/sdk/rollup.config.js
+++ b/sdk/rollup.config.js
@@ -25,6 +25,8 @@ export default [
'openpaas/index': 'src/openpaas/index.ts',
'spine/index': 'src/spine/index.ts',
'tilemap/index': 'src/tilemap/index.ts',
+ 'water/index': 'src/water/index.ts',
+ 'spline/index': 'src/spline/index.ts',
'logic/index': 'src/logic/index.ts',
'debug-channel/index': 'src/debug-channel/index.ts',
'ai/index': 'src/ai/index.ts',
diff --git a/sdk/src/water/waterPlugin.ts b/sdk/src/water/waterPlugin.ts
index 3b08adf7c..1a6b79ebf 100644
--- a/sdk/src/water/waterPlugin.ts
+++ b/sdk/src/water/waterPlugin.ts
@@ -87,15 +87,15 @@ export const WaterBody: ComponentDef<WaterBodyData> = defineComponent<WaterBodyD
assetFields: [{ field: 'material', type: 'material' }],
fields: {
form: { enum: [{ label: 'Ocean', value: WaterForm.Ocean }, { label: 'Lake', value: WaterForm.Lake }, { label: 'River', value: WaterForm.River }], category: 'Shape', tooltip: 'An ocean is without edge and follows the camera; a lake is a rectangle or an outline of its own; a river follows the Spline on the same entity.' },
- flowSpeed: { min: 0, max: 50, category: 'Waves', tooltip: 'A river\'s current, in world units a second where it is as wide as its widest. A narrower reach runs faster.' },
+ flowSpeed: { min: 0, max: 50, category: 'Waves', tooltip: 'A river\'s current, in world units a second where it is as wide as its widest. A narrower reach runs faster.', shownWhen: { field: 'form', values: [WaterForm.River] } },
material: { category: 'Look', tooltip: 'A material on the Water shader. Empty uses the stock water.' },
- sizeX: { min: 1, category: 'Shape', tooltip: 'A lake\'s size along x.' },
- sizeZ: { min: 1, category: 'Shape', tooltip: 'A lake\'s size along z.' },
- boundary: { category: 'Shape', tooltip: 'The outline of a lake: points round it on its own xz plane. Empty is the rectangle of its size.' },
- shoreWidth: { min: 0, category: 'Shape', tooltip: 'How far in from the edge, and how deep, the waves take to come to full height. 0 leaves them whole to the edge.' },
+ sizeX: { min: 1, category: 'Shape', tooltip: 'A lake\'s size along x.', shownWhen: { field: 'form', values: [WaterForm.Lake] } },
+ sizeZ: { min: 1, category: 'Shape', tooltip: 'A lake\'s size along z.', shownWhen: { field: 'form', values: [WaterForm.Lake] } },
+ boundary: { category: 'Shape', tooltip: 'The outline of a lake: points round it on its own xz plane. Empty is the rectangle of its size.', shownWhen: { field: 'form', values: [WaterForm.Lake] } },
+ shoreWidth: { min: 0, category: 'Shape', tooltip: 'How far in from the edge, and how deep, the waves take to come to full height. 0 leaves them whole to the edge.', shownWhen: { field: 'form', values: [WaterForm.Lake] } },
cellSize: { min: 0.05, category: 'Detail', tooltip: 'The cell size of the finest ring. Waves shorter than six cells are not drawn as geometry there (the shading still shows them).' },
- cells: { min: 4, max: 256, step: 4, category: 'Detail', tooltip: 'Cells along a ring\'s side (an ocean).' },
- rings: { min: 1, max: 8, step: 1, category: 'Detail', tooltip: 'Rings of an ocean, each twice as coarse as the one inside it.' },
+ cells: { min: 4, max: 256, step: 4, category: 'Detail', tooltip: 'Cells along a ring\'s side (an ocean).', shownWhen: { field: 'form', values: [WaterForm.Ocean] } },
+ rings: { min: 1, max: 8, step: 1, category: 'Detail', tooltip: 'Rings of an ocean, each twice as coarse as the one inside it.', shownWhen: { field: 'form', values: [WaterForm.Ocean] } },
waveHeight: { min: 0, max: 8, category: 'Waves', tooltip: 'The height of the tallest wave, in world units.' },
waveLength: { min: 0.5, max: 300, category: 'Waves', tooltip: 'The length of the longest wave.' },
waveSpeed: { min: 0, max: 4, category: 'Waves', tooltip: 'A multiplier on how fast the waves travel.' },
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index be23daaf8..a4c312ac3 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -2567,6 +2567,8 @@ export const NOTED = {
{"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)."},
+ "feat(editor): the points of a lake and a river are edited with handles in the viewport, and Details shows only what the form uses":
+ {"note":"Select a lake or a river and its points are handles in the viewport: drag a point to move it on the body's own plane, drag the circle on an edge to insert one, press and release a point to delete it (a lake keeps three, a river two), and drag the handle beside a river's point to set its width there. Each gesture is one undo step. Details shows a water body only the fields its form uses, with a Boundary row for a lake's outline and the point count and the pressed point's width under a Spline. Also: the move gizmo now travels with the entity while an axis is dragged, instead of staying where the grab began."},
"fix(render): a blended surface is ordered against water and glass by the pixel, so a pane in front of water is no longer covered by it":
{"note":"A blended surface (a pane, a particle, a leaf card) is now ordered against water and glass by the pixel and not by when it was drawn: one under the surface is seen through the water, one in front of it lies on the water instead of being covered, and where there is no water it is blended once. The frame is drawn in layers only when it holds both a refracting surface and a blended draw."},
"feat(water): water keeps ripples and foam, a disturbance spreads as a ring, and what moves in it makes a wake":