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
chore(gates): the note, the reference and the API surface for the ground's occlusion map
yhh8877caa76259
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 160c0260d..8d3e65ef8 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -22,6 +22,7 @@ published separately; it ships inside the editor.- **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 baked occlusion over the ground.** A terrain's large folds (a gully, a hollow, the foot of a cliff) get less of the sky than open ground, and they are too large for a screen-space occlusion pass to see across. `Terrain.occlusionMap` is an image over the whole area whose red says how much of the sky reaches the ground, with `occlusionStrength`; it dims the light that comes from all round and leaves the sun's own to the shadows, on both terrain shaders (`u_occlusionMap`, `u_occlusionStrength` on a material of your own). It is numbers: its Use is Data, set when the field is. In full sun it is quiet, as it should be; it tells in shade and under an overcast sky.- **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`.- **Water is a body and a surface.** The water's own colour was lit by the ripples' normal, as a painted surface is, so every ripple had a dark far side and a sea was blotched with dark patches no real water has. It is two layers now, as Unreal's single-layer water is: the body is lit as light from under the surface, and the surface is a coat over it that mirrors by the ripples (a coat may now state its reflectance, `coat.z` in a shader's `SurfaceExt`; 0 stays a varnish's 0.04). `u_bodyShading` says how much the ripples still shade the colour (0.25; 1 is the old look), `u_reflectance` what the surface mirrors seen straight on.- **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 three layers of a tiling normal map the engine makes from 96 waves at every heading, read with mips at sizes that share no multiple (so no one size's repeat shows) and scrolled downwind, as Unreal's water reads its normal maps, with gusts across them: slow patches where the wind ruffles the water and slicks where it does not. No lattice, nothing finer than a pixel, three texture reads where there were six waves. Every number of it is a material param: `u_rippleTile`, `u_rippleFineSize`, `u_rippleWideSize`, the three weights, `u_rippleTurn`, `u_rippleGusts`, `u_gustCalm`, `u_gustRuffle`, `u_gustSize`. `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.diff --git a/docs/astro/src/data/components.generated.json b/docs/astro/src/data/components.generated.jsonindex 14167f346..ca62b7af5 100644--- a/docs/astro/src/data/components.generated.json+++ b/docs/astro/src/data/components.generated.json@@ -7989,6 +7989,19 @@"doc": "How much of the colour map is mixed in where its alpha is whole.","range": "0–1, step 0.01"},+ {+ "key": "occlusionMap",+ "type": "Asset<texture>",+ "default": "none",+ "doc": "An image over the whole area whose red says how much of the sky reaches the ground: white all of it, black none. It dims the light from all round, not the sun's. Its Use is Data."+ },+ {+ "key": "occlusionStrength",+ "type": "number",+ "default": "1",+ "doc": "How much of the occlusion map is applied.",+ "range": "0–1, step 0.01"+ },{"key": "layers","type": "array",@@ -8179,6 +8192,8 @@"splatmap2","colorMap","colorMapStrength",+ "occlusionMap",+ "occlusionStrength","material","sizeX","sizeZ",diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 89359ec08..a8542e7aa 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -11508,6 +11508,8 @@ layerColor2: ColorlayerColor3: Colorlayers: string[]material: number+occlusionMap: number+occlusionStrength: numberoctaves: numberpersistence: numberprovider: stringdiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex c44e086fd..2c4895375 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -11730,6 +11730,8 @@ layerColor2: ColorlayerColor3: Colorlayers: string[]material: number+occlusionMap: number+occlusionStrength: numberoctaves: numberpersistence: numberprovider: stringdiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 5186d89eb..c639aeb29 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -11503,6 +11503,8 @@ layerColor2: ColorlayerColor3: Colorlayers: string[]material: number+occlusionMap: number+occlusionStrength: numberoctaves: numberpersistence: numberprovider: stringdiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 171f9fbf0..9ab5657b5 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -11800,6 +11800,8 @@ layerColor2: ColorlayerColor3: Colorlayers: string[]material: number+occlusionMap: number+occlusionStrength: numberoctaves: numberpersistence: numberprovider: stringdiff --git a/sdk/etc/terrain.api.md b/sdk/etc/terrain.api.mdindex e93e93674..3ce7bad57 100644--- a/sdk/etc/terrain.api.md+++ b/sdk/etc/terrain.api.md@@ -490,6 +490,8 @@ layerColor2: ColorlayerColor3: Colorlayers: string[]material: number+occlusionMap: number+occlusionStrength: numberoctaves: numberpersistence: numberprovider: stringdiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 8de8392cd..9e5cbef28 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -11510,6 +11510,8 @@ layerColor2: ColorlayerColor3: Colorlayers: string[]material: number+occlusionMap: number+occlusionStrength: numberoctaves: numberpersistence: numberprovider: stringdiff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjsindex bdd593de9..2dd689e0e 100644--- a/tools/releaseNotes.mjs+++ b/tools/releaseNotes.mjs@@ -4552,6 +4552,8 @@ export const NOTED = {{"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."},+ "feat(terrain): a baked occlusion over the ground - Terrain.occlusionMap is an image whose red says how much of the sky reaches the ground, for the gullies and cliff feet no screen-space pass sees across; it dims the light from all round and leaves the sun's to the shadows":+ {"note": "A baked occlusion over the ground."},"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."},};