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.

chore(gates): the note, the reference and the API surface for Foliage's instance, widening and palette

yhhea91f627fa8b
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 5d664811e..160c0260d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -19,6 +19,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.
- **A sea is eight waves spread about the wind.** Water's waves were four peaked sines, the longest far taller than the rest, and from any height the sea read as regular curved bands. The set is now eight: the first heads with the wind, each after it is 0.78 of the length before, nearly as steep, and off the wind by a golden-ratio step within 65 degrees, each at the speed its length gives deep water. Their heights add up to what the four's did, so `waveHeight` raises a crest as high as before and nothing built on the old bound moves. `Waters.sample`, `Floating` and the drawn surface still share one formula: the shader's waves are now written out from the table in `water/waves.ts` (`WAVE_SET`) when its source is assembled, where the same numbers were kept by hand in five places. A quality level's `waterWaves` is 3 / 5 / 8 (was 2 / 3 / 4), longest first. A scene tuned against the old four will look different: the same height spread over more, smaller waves.
+- **A Foliage field has its own material instance, grass that widens as it thins, and a palette.** Three things a meadow of several kinds of flower needed. A field wrote what it alone says (where it thins, its colour map) onto the material it was given, so two fields on one material, or on two material files with the same contents, drew with whichever wrote last: each field now draws with an instance of its own, and edits to the material still reach it. Grass thinned between its far versions and stayed as narrow, so the ground showed through until the next version took over: a blade now widens in the shader by as much as its neighbours are left out, up to `farGrow`, and the field covers the same ground from the near blades to the draw distance. And `Foliage.palette` is a strip of colours each plant takes the colour of its top from, by a number of its own: as wide a share of the strip, as many of the plants.
- **Foliage thins plant by plant with distance, and is grown only where it is drawn.** A cell of `Foliage` had one far version (every third blade of grass, or a tree's cards), every cell held its full near mesh however far off it stood, and a field ended in a line at its draw distance. A cell now has up to three far versions (`farLevels`), each keeping `farKeep` of the plants of the one before, grown by up to `farGrow` to cover the same ground, and taking over `farStep` times further out. Every plant has a number of its own: the shader thins by it with distance, and a far version holds exactly the plants still drawn where it takes over, so nothing jumps at the switch and the field fades to none at `drawDistance`. With a material, each version is a layer of cells of its own, grown only as far out as it is drawn: a meadow drawn to 300 m is whole within the first tens of metres and a fraction of itself beyond, where before it would not fit in memory. `farCards` says whether a mesh's far version is crossed cards (a tree, as before) or the plant itself, fewer and larger (a flower). The Foliage shader also gains `u_tipFrom`: how far up a plant the tip's colour begins, for a stem under a flower's head. The defaults keep one far version at a third, so a field's look changes only at its far edge, which now fades.
- **A meadow: a density map and a colour map for Foliage.** `Foliage` scattered its plants evenly over its area, and every plant of a field was the one colour its material gave. `densityMap` is an image over the area whose red says how many of them stand where (none at black, all of `count` at white), so flowers grow in drifts and grass thins toward a path; a place keeps or loses its plant by a lot of its own, the same on every thread and in every cell. `colorMap` is a picture that colours the plants by where they stand, mixed in by its alpha from `colorMapFrom` up the plant, with `colorMapStrength`: one flower mesh and one material are pink here and yellow there. The density map is numbers (its Use is Data, set when the field is); the colour map is read each frame and grows nothing again.
- **A colour map over the ground.** Layers paint a terrain by kind of ground, and a meadow painted with one grass layer is one green from end to end. `Terrain.colorMap` is a picture laid over a whole area and mixed into the ground's colour by its alpha (the flowers of a meadow, the regions of a map, scorched ground), on the plain Terrain shader and on Terrain Layers alike; `colorMapStrength` says how much, and is read each frame. It is one more texture on the ground's material (the seventh on Terrain Layers, whose eight layers are three arrays). A material of your own on those shaders has it as `u_colorMap`, `u_colorMapStrength` and `u_colorMapArea`.
diff --git a/docs/astro/src/data/components.generated.json b/docs/astro/src/data/components.generated.json
index 535030ba7..14167f346 100644
--- a/docs/astro/src/data/components.generated.json
+++ b/docs/astro/src/data/components.generated.json
@@ -2443,6 +2443,12 @@
"doc": "How far up a plant the colour map begins: 0 colours it whole, higher only its top.",
"range": "0–1, step 0.01"
},
+ {
+ "key": "palette",
+ "type": "Asset<texture>",
+ "default": "none",
+ "doc": "A strip of colours each plant takes the colour of its top from, by a number of its own: as wide a share of the strip, as many of the plants. Needs a material; the top begins at its Tip From."
+ },
{
"key": "farLevels",
"type": "number",
@@ -2642,6 +2648,7 @@
"colorMap",
"colorMapStrength",
"colorMapFrom",
+ "palette",
"farLevels",
"farKeep",
"farStep",
diff --git a/sdk/etc/foliage.api.md b/sdk/etc/foliage.api.md
index ee0d8a716..347a1af99 100644
--- a/sdk/etc/foliage.api.md
+++ b/sdk/etc/foliage.api.md
@@ -69,6 +69,7 @@ maxScale: number
mesh: number
minScale: number
minUp: number
+palette: number
seed: number
sizeX: number
sizeZ: number
@@ -86,7 +87,7 @@ zoneWorld: string
@internal landed_: (() => void)[]
cellCount: number
pending: number
-washed_: Set<number>
+retired_: { instance: number; frames: number; }[]
static new (): FoliageField
static prototype: FoliageField
```
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 9344dab47..89359ec08 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -4640,6 +4640,7 @@ maxScale: number
mesh: number
minScale: number
minUp: number
+palette: number
seed: number
sizeX: number
sizeZ: number
@@ -4657,7 +4658,7 @@ zoneWorld: string
@internal landed_: (() => void)[]
cellCount: number
pending: number
-washed_: Set<number>
+retired_: { instance: number; frames: number; }[]
static new (): FoliageField
static prototype: FoliageField
```
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index f52d26ffe..c44e086fd 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -4648,6 +4648,7 @@ maxScale: number
mesh: number
minScale: number
minUp: number
+palette: number
seed: number
sizeX: number
sizeZ: number
@@ -4665,7 +4666,7 @@ zoneWorld: string
@internal landed_: (() => void)[]
cellCount: number
pending: number
-washed_: Set<number>
+retired_: { instance: number; frames: number; }[]
static new (): FoliageField
static prototype: FoliageField
```
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index a268af947..5186d89eb 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -4635,6 +4635,7 @@ maxScale: number
mesh: number
minScale: number
minUp: number
+palette: number
seed: number
sizeX: number
sizeZ: number
@@ -4652,7 +4653,7 @@ zoneWorld: string
@internal landed_: (() => void)[]
cellCount: number
pending: number
-washed_: Set<number>
+retired_: { instance: number; frames: number; }[]
static new (): FoliageField
static prototype: FoliageField
```
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 65db51a99..171f9fbf0 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -4635,6 +4635,7 @@ maxScale: number
mesh: number
minScale: number
minUp: number
+palette: number
seed: number
sizeX: number
sizeZ: number
@@ -4652,7 +4653,7 @@ zoneWorld: string
@internal landed_: (() => void)[]
cellCount: number
pending: number
-washed_: Set<number>
+retired_: { instance: number; frames: number; }[]
static new (): FoliageField
static prototype: FoliageField
```
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index c88e2be6a..8de8392cd 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -4635,6 +4635,7 @@ maxScale: number
mesh: number
minScale: number
minUp: number
+palette: number
seed: number
sizeX: number
sizeZ: number
@@ -4652,7 +4653,7 @@ zoneWorld: string
@internal landed_: (() => void)[]
cellCount: number
pending: number
-washed_: Set<number>
+retired_: { instance: number; frames: number; }[]
static new (): FoliageField
static prototype: FoliageField
```
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index 6a042c409..bdd593de9 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -4550,6 +4550,8 @@ export const NOTED = {
{"note": "Foliage thins plant by plant with distance, and is grown only where it is drawn."},
"feat(gates): --suites related runs of an owed suite only the tests that reach what changed - where its runner can follow imports from every changed file, and the whole suite where it cannot; the run names each suite it ran in part":
{"internal": "How the repository's own checks are run before a push; nothing a creator sees."},
+ "feat(foliage): a field draws with its own instance of its material, grass widens as it thins, and a palette colours each plant - two fields on one material wrote their own values over each other's; a blade now widens by as much as its neighbours are left out so the field covers the same ground at every distance; and Foliage.palette is a strip each plant takes the colour of its top from":
+ {"note": "A Foliage field has its own material instance, grass that widens as it thins, and a palette."},
"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."},
};