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(worldgen): a plant of a generated world leans with the ground where its member says attach: align

yhhac3728f533ae
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0bed16011..0b1a73800 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -17,7 +17,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. A plant with no cards of its own may use its cheaper mesh as its far version and set `farKeep`, the share of its plants that version draws, so ground cover far off costs a share of what it does near; the far versions are laid out in cells as wide as the shortest distance they are shown over allows, which took the Terrain & Water example's draws from about 1,800 to about 1,100. 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`.
+- **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. A plant with no cards of its own may use its cheaper mesh as its far version and set `farKeep`, the share of its plants that version draws, so ground cover far off costs a share of what it does near; a member with `attach: 'align'` leans a plant with the ground, so a stone on a slope sits as the slope lies; the far versions are laid out in cells as wide as the shortest distance they are shown over allows, which took the Terrain & Water example's draws from about 1,800 to about 1,100. 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.
- **Water zones.** Oceans, lakes and rivers are now drawn as one surface. A `WaterBody` says what water is where (its form, outline or Spline, shore width, current and how high its waves stand), and a new `WaterZone` bakes every body over its region into one field: the surface's height, the distance to the shore, the waves' height, the current and the depth over the terrain. One mesh of rings that follows the camera reads it, so a river runs into a lake or the sea at one height with its banks running on into the shore, its current fades into the still water, and no shore foams across its mouth; a lake or a river over the sea is the lake's, not the sea's, and the sea's waves calm and foam where it shallows over the terrain. The zone holds what the bodies share: the material, the waves' length, speed and heading, the mesh's detail and the ripples. A scene without one gets a zone over its lakes and rivers, and the ocean goes on past it. `Waters.sample` reads the same field, so what floats or looks out from under the water meets the surface that is drawn. In the editor the zone's region is outlined in the viewport.
diff --git a/docs/astro/src/content/docs/world/generation.mdx b/docs/astro/src/content/docs/world/generation.mdx
index a2295658e..601cb7c6e 100644
--- a/docs/astro/src/content/docs/world/generation.mdx
+++ b/docs/astro/src/content/docs/world/generation.mdx
@@ -85,7 +85,7 @@ A candidate takes **one biome, by weight, and then the recipe that biome has in
A recipe is a group: an **anchor** and **members** placed round it. Each member says its mesh and material (asset paths, or handles
already loaded), how many (`count`), how far from the anchor and at what angles (`ring`, `arc`), its `scale`, the ground it takes
(`footprint`: a trunk) apart from how far it spreads overhead (`canopy`: a crown), whether it stands upright or leans with the
-ground (`attach`), how steep (`minUp`) and how deep in water (`waterDepth`) it may stand, the `chance` it is placed at all, and its far
+ground (`attach`, which a member that names a `plant` follows too: a stone sits on a slope as the slope lies), how steep (`minUp`) and how deep in water (`waterDepth`) it may stand, the `chance` it is placed at all, and its far
version (`far`: the rectangle of its texture two crossed cards show, or a tent of them for a conifer, drawn past its layer's `lodDistance`). A
member that cannot stand (no ground, too steep, under water, kept out by a zone, on something placed before it) is left out; the
group stands.
diff --git a/docs/astro/src/content/docs/zh-cn/world/generation.mdx b/docs/astro/src/content/docs/zh-cn/world/generation.mdx
index ae97f7226..93b2b06ad 100644
--- a/docs/astro/src/content/docs/zh-cn/world/generation.mdx
+++ b/docs/astro/src/content/docs/zh-cn/world/generation.mdx
@@ -65,7 +65,7 @@ registerWorldRules({
### 配方
-配方是一个组:一个**锚点**和围绕它放置的**成员**。每个成员说明它的网格和材质(资源路径,或已加载的句柄)、数量(`count`)、离锚点多远和在什么角度(`ring`、`arc`)、`scale`、它在地面上占的范围(`footprint`:树干),与它在头顶伸展的范围(`canopy`:树冠)分开记录;它是直立还是随地面倾斜(`attach`)、允许多陡(`minUp`)和多深的水里站立(`waterDepth`)、被放置的概率 `chance`,以及它的远景版本(`far`:两张十字交叉卡片显示的贴图矩形,针叶树可用帐篷形,在所在层的 `lodDistance` 之外绘制)。站不住的成员(没有地面、太陡、在水下、被区域排除、压在先放的东西上)会被省去,组仍然成立。
+配方是一个组:一个**锚点**和围绕它放置的**成员**。每个成员说明它的网格和材质(资源路径,或已加载的句柄)、数量(`count`)、离锚点多远和在什么角度(`ring`、`arc`)、`scale`、它在地面上占的范围(`footprint`:树干),与它在头顶伸展的范围(`canopy`:树冠)分开记录;它是直立还是随地面倾斜(`attach`,指定了 `plant` 的成员也遵循它:石头顺着坡面躺放)、允许多陡(`minUp`)和多深的水里站立(`waterDepth`)、被放置的概率 `chance`,以及它的远景版本(`far`:两张十字交叉卡片显示的贴图矩形,针叶树可用帐篷形,在所在层的 `lodDistance` 之外绘制)。站不住的成员(没有地面、太陡、在水下、被区域排除、压在先放的东西上)会被省去,组仍然成立。
`version` 是每个放置物 ID 的一部分:配方放置的东西变了就把它加一。
diff --git a/sdk/src/foliage/builder.ts b/sdk/src/foliage/builder.ts
index 2b91e5482..96f9dc42f 100644
--- a/sdk/src/foliage/builder.ts
+++ b/sdk/src/foliage/builder.ts
@@ -244,7 +244,7 @@ export function buildInstancedMesh(source: MeshData, plants: readonly Plant[], p
/**
* Copies of an authored mesh, one per plant, as one mesh, with every channel of the source kept: the colour, the second uv and the tangent that a
* normal map reads are what the artist made, and the wind's painted weights do not replace them (see buildInstancedMesh for a mesh that is painted).
- * Each copy is turned about the vertical, scaled and placed; positions, normals and tangents are carried, other channels are copied as they are.
+ * Each copy is turned about the vertical, scaled, leaned with the ground where it has an `up`, and placed; positions, normals and tangents are carried, other channels are copied as they are.
*/
export function buildPlacedMesh(source: MeshData, plants: readonly Plant[]): MeshData {
const stride = source.vertexStride, count = source.vertexCount;
@@ -265,25 +265,31 @@ export function buildPlacedMesh(source: MeshData, plants: readonly Plant[]): Mes
const hasNormal = normalAt >= 0, hasTangent = tangentAt >= 0;
plants.forEach((plant, n) => {
const cos = Math.cos(plant.yaw), sin = Math.sin(plant.yaw), scale = plant.scale;
+ // A plant on a slope that leans with it (a stone), turned after its yaw about the vertical; most stand upright, and skip it.
+ const lean = plant.up ? leanTo(plant.up) : null;
const first = n * count * words;
// Every channel copied as it is; the three that move are then rewritten.
raw.set(rawBase, first);
for (let v = 0, o = first; v < count; v++, o += words) {
if (posAt >= 0) {
const x = base[v * words + p]! * scale, y = base[v * words + p + 1]! * scale, z = base[v * words + p + 2]! * scale;
- const wx = x * cos + z * sin + plant.x, wy = y + plant.y, wz = -x * sin + z * cos + plant.z;
+ let wx = x * cos + z * sin, wy = y, wz = -x * sin + z * cos;
+ if (lean) { const q = [wx, wy, wz]; lean(q); wx = q[0]!; wy = q[1]!; wz = q[2]!; }
+ wx += plant.x; wy += plant.y; wz += plant.z;
f32[o + p] = wx; f32[o + p + 1] = wy; f32[o + p + 2] = wz;
if (wx < min[0]) min[0] = wx; if (wx > max[0]) max[0] = wx;
if (wy < min[1]) min[1] = wy; if (wy > max[1]) max[1] = wy;
if (wz < min[2]) min[2] = wz; if (wz > max[2]) max[2] = wz;
}
if (hasNormal) {
- const x = base[v * words + nr]!, z = base[v * words + nr + 2]!;
+ const x = base[v * words + nr]!, y = base[v * words + nr + 1]!, z = base[v * words + nr + 2]!;
f32[o + nr] = x * cos + z * sin; f32[o + nr + 2] = -x * sin + z * cos;
+ if (lean) { const q = [f32[o + nr]!, y, f32[o + nr + 2]!]; lean(q); f32[o + nr] = q[0]!; f32[o + nr + 1] = q[1]!; f32[o + nr + 2] = q[2]!; }
}
if (hasTangent) {
- const x = base[v * words + tg]!, z = base[v * words + tg + 2]!;
+ const x = base[v * words + tg]!, y = base[v * words + tg + 1]!, z = base[v * words + tg + 2]!;
f32[o + tg] = x * cos + z * sin; f32[o + tg + 2] = -x * sin + z * cos;
+ if (lean) { const q = [f32[o + tg]!, y, f32[o + tg + 2]!]; lean(q); f32[o + tg] = q[0]!; f32[o + tg + 1] = q[1]!; f32[o + tg + 2] = q[2]!; }
}
}
const firstIndex = n * source.indices.length, shift = n * count;
diff --git a/sdk/src/worldgen/worldgenPlugin.ts b/sdk/src/worldgen/worldgenPlugin.ts
index d99aa0409..0389bbaa7 100644
--- a/sdk/src/worldgen/worldgenPlugin.ts
+++ b/sdk/src/worldgen/worldgenPlugin.ts
@@ -565,7 +565,8 @@ export class WorldGenPlugin implements Plugin {
if (k < 0) continue;
let list = by.get(k);
if (!list) by.set(k, list = []);
- list.push({ x: p.x - out.at[0], y: p.y - plants.sinkOf(p.plant), z: p.z - out.at[2], yaw: p.yaw, scale: p.scale * plants.unitOf(p.plant), phase: 0, shade: 1 });
+ list.push({ x: p.x - out.at[0], y: p.y - plants.sinkOf(p.plant), z: p.z - out.at[2], yaw: p.yaw, scale: p.scale * plants.unitOf(p.plant), phase: 0, shade: 1,
+ ...(p.attach === 'align' ? { up: p.normal } : {}) });
}
if (by.size > 0) out.planted = by;
}
diff --git a/sdk/tests/foliage-builder.test.ts b/sdk/tests/foliage-builder.test.ts
index b7330b0a6..b304ec73b 100644
--- a/sdk/tests/foliage-builder.test.ts
+++ b/sdk/tests/foliage-builder.test.ts
@@ -181,6 +181,21 @@ describe('placed meshes', () => {
expect(colorOf(m as never, 5)).toEqual([10, 20, 30, 255]);
});
+ it('leans a copy with the ground it stands on, its normal and tangent with it, and leaves an upright one as it is', () => {
+ const m = buildPlacedMesh(source, [
+ { x: 3, y: 0, z: 0, yaw: 0, scale: 1, phase: 0, shade: 1, up: [1, 0, 0] },
+ { x: 3, y: 0, z: 0, yaw: 0, scale: 1, phase: 0, shade: 1, up: [0, 1, 0] },
+ ]);
+ // Up turned to the east takes (1, 0, 0), which points east, to point down; the normal and the tangent go with it.
+ const leaned = positionOf(m, 0);
+ expect(leaned[0]).toBeCloseTo(3, 5);
+ expect(leaned[1]).toBeCloseTo(-1, 5);
+ expect(readF(m, 0, MeshChannel.Normal, 0)).toBeCloseTo(0, 5);
+ expect(readF(m, 0, MeshChannel.Normal, 1)).toBeCloseTo(-1, 5);
+ expect(readF(m, 0, MeshChannel.Tangent, 1)).toBeCloseTo(-1, 5);
+ expect(positionOf(m, 3)).toEqual([4, 0, 0]);
+ });
+
it('bounds what it placed, and is an empty mesh for no plants', () => {
const m = buildPlacedMesh(source, [{ x: 5, y: 1, z: 0, yaw: 0, scale: 2, phase: 0, shade: 1 }]);
expect(m.aabbMin).toEqual([5, 1, 0]);
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index e017dbb78..f951a1407 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -2832,6 +2832,8 @@ export const NOTED = {
{"internal":"An observation seam for capture tooling; no game behaves differently."},
"feat(worldgen): the far versions of a world's plants are laid out in cells as wide as their shortest span allows, so ground cover far off costs far fewer draws":
{"note":"A generated world's plants."},
+ "feat(worldgen): a plant of a generated world leans with the ground where its member says attach: align":
+ {"note":"A generated world's plants."},
"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":