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
feat(terrain): up to eight terrain layers with normal and mask maps, from .esterrainlayer files, blended by height
yhh5f14255ade68
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex b0bd99e7b..8edbc592a 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -31,6 +31,7 @@ published separately; it ships inside the editor.- **Rays against the terrain, anywhere.** `Terrains.raycast(origin, direction, maxDistance)` meets the ground's triangles exactly (the ones collision and `heightAt` use) wherever the ray goes, with no physics world and no collision tile there, for a line of sight, a pick or a landing spot.- **Far versions for generated decoration.** A recipe member can name its far version (`far`: crossed cards, or a tent for a conifer, showing a rectangle of its texture), drawn past its layer's `lodDistance`, and decoration that leans with the ground (`attach: 'align'`) now leans in its merged mesh too.- **Terrain modifiers, and zones that level their ground.** `Terrains.setModifier` lays a change over the ground (`flattenModifier` levels a circle or a turned box, blending back over its edge) that what is drawn, the queries, rays and collision all follow, remaking only the pages and collision tiles it reaches; `heightBeneathAt` reads the ground as it was made. A `WorldZone` with `flatten` levels its plot to the ground's height at its centre.+- **Terrain layers: up to eight kinds of ground, each with its normal and mask maps.** A terrain layer (`.esterrainlayer`, with an editor of its own) names the albedo, normal and mask (occlusion, roughness, height) an artist made for one kind of ground, and how it is laid; a Terrain lists up to eight (`layers`), weighed by its splatmap and a second one (`splatmap2`). They are drawn by the new Terrain Layers shader from texture arrays: where layers meet the higher one shows, near the eye they are read without repeat, on slopes they are projected from the sides, and their normals, occlusion and roughness light the ground. Biomes can paint all eight. The four-layer Terrain shader is unchanged for materials that use it.- **Foam is where waves burst, not along every shore.** The zone bakes how steep each shore is: against rock and cliffs the shore foams and the breakers burst white; up a gentle beach the waves wash in a thin line only and run up a short way rather than spreading a white sheet over the sand; and the less room the wind has to raise them (a sheltered lake), the less of either.- **Surf comes in from open water as lines.** Its crests followed every turn of the shore, bending into a river's mouth from far out; they now follow a distance of their own, the open water's edge with a river's water taken for land, smoothed over the surf's length, so they come in straight and turn to the shore only as they near it. Where the surf rises, breaks and runs up is still the real shore's, and a river's current calms it over a spread past the mouth rather than cutting it off at the river's side.- **A river gives way where it runs into the sea or a lake.** Over half its width past their shore it fades into them, its current with it, where it used to stop within a texel and a half and leave its sides running on into the open water: the surf, which no current carries, broke off along those lines. The surf now runs on along the coast and round into the mouth.diff --git a/desktop b/desktopindex bc9a9eaa9..5aa40fd78 160000--- a/desktop+++ b/desktop@@ -1 +1 @@-Subproject commit bc9a9eaa963069e2ce073851e0b8734c9c1c6ad9+Subproject commit 5aa40fd786a19d8964080ad9f84cb46c12576cf2diff --git a/docs/WORLD_GENERATION_PLAN.md b/docs/WORLD_GENERATION_PLAN.mdindex c6bfd20c5..02c2e1770 100644--- a/docs/WORLD_GENERATION_PLAN.md+++ b/docs/WORLD_GENERATION_PLAN.md@@ -79,7 +79,7 @@| 优先级 | 项目 || --- | --- |-| P1 | 地形分层法线/粗糙度(每层 normal/ORM);当前地形着色器仅四张颜色图与统一粗糙度 |+| P1 | 地形分层法线/粗糙度(每层 normal/ORM);当前地形着色器仅四张颜色图与统一粗糙度。已完成:纹理数组(渲染底层)、`.esterrainlayer` 地形层资源与编辑器、Terrain `layers`/`splatmap2`(最多 8 层)、Terrain Layers 着色器(按遮罩高度交界、近处去重复、坡面三向投影、法线与遮蔽/粗糙度参与光照);terrain-water 示例改用 4 个程序生成的地形层 || P1 | 高度图显式格式字段(取代按 G 通道猜 R8/RG16),数据图无色彩转换/预乘/有损压缩。已完成:`Terrain.heightmapFormat`(Grey:按文件位深,16 位 PNG 全精度读取;RedGreen16),PNG 数据读取支持 16 位通道;高度图按原始字节读取(无色彩转换/预乘),被压缩时地形失败并说明原因 || P1 | 河床与岸线生成配合(生成器形成岸线后提供湖泊边界/河流样条) || P2 | 球面与极远坐标(平面 XZ 的局限、原点精度) |diff --git a/docs/astro/src/content/docs/graphics/terrain.mdx b/docs/astro/src/content/docs/graphics/terrain.mdxindex e04734d5e..5e2eb2c73 100644--- a/docs/astro/src/content/docs/graphics/terrain.mdx+++ b/docs/astro/src/content/docs/graphics/terrain.mdx@@ -37,10 +37,12 @@ The ground is one of two kinds, chosen by `extent`:| `resolution` | Area only. Samples along each side of an area's noise ground. || `warp` | 0 to 1: how far the noise is bent by noise of its own, which gives winding valleys and bent ridges instead of round hills. || `erosion` | 0 to 4: how much rain wears the ground (below). 0 leaves it as made. |-| `splatmap` | Area only. An image whose four channels are the weights of the four layers. Empty paints by height and slope. |+| `splatmap` | Area only. An image whose four channels are the weights of layers 1 to 4. Empty paints by height and slope. |+| `splatmap2` | Area only. The weights of layers 5 to 8, read with the first. |+| `layers` | The [terrain layers](#terrain-layers) the ground is drawn with, up to eight, in the order the paint weighs them. Empty draws the four layer colours or the Terrain material's textures. || `rockSlope`, `dirtHeight`, `snowHeight` | How steep ground must be to turn to rock, and the heights, as a share of `height`, where grass gives way to dirt and where snow begins. || `layerColor0`–`3` | Grass, dirt, snow, rock: the colours the ground is drawn in when it has no material. |-| `material` | A material on the **Terrain** shader (below). Empty draws the layer colours straight onto the ground. |+| `material` | A material on the **Terrain** shader (below), or on **Terrain Layers** when the ground has layers. Empty uses the stock one. |Changing `detail`, `drawDistance` or a layer colour takes effect on the next frame. Changing any other field builds the ground again.@@ -56,6 +58,34 @@ Infinite ground has no edge for rain to run off, so its erosion is the noise's ooctaves under it are already steep. That leaves smooth valleys between sharp ridges, much as rain would, at no cost beyond the noise.It paints no dirt channels.+## Terrain layers++A terrain layer (a `.esterrainlayer` file; **New → New Terrain Layer** in the editor) is one kind of ground — grass, a path's dirt,+sand, rock — as the textures an artist made for it. A Terrain lists the layers it is drawn with (`layers`, up to eight), and its+splatmaps weigh them: the first's red, green, blue and alpha are layers 1 to 4, the second's layers 5 to 8. Without splatmaps the+first four are painted by height and slope as grass, dirt, snow and rock, and a [generated world](/docs/world/generation/)'s biomes can+paint all eight.++| Field | What it is |+|---|---|+| `albedo` | The colour, sRGB. Empty is white, coloured by the tint. |+| `normal` | A tangent-space normal map, green up (the OpenGL convention). Empty is flat. |+| `mask` | Red the ambient occlusion, green the roughness, blue the height. Empty: no occlusion, `roughness`, and the albedo's brightness as height. |+| `tile` | How many world units one repeat of the textures covers. |+| `tint` | Multiplies the albedo. |+| `roughness` | The roughness where there is no mask. |+| `normalStrength` | How strongly the normal map bends the light: 1 as drawn, 0 flat. |++The ground is drawn by the **Terrain Layers** shader (`builtin:terrain-layers`). Every layer is read by world position without repeat+near the eye, with a wider tile mixed in far off; where layers meet, the one whose mask stands higher shows (stones through grass, sand+between stones); on a slope each is also projected from the sides, so a cliff is not stretched. The normal maps and the masks'+occlusion and roughness light it. Its material sets how: `u_sharpness`, `u_heightBlend`, `u_blendNoise`, `u_antiTile`, `u_farScale`,+`u_macroVariation`, `u_triplanarFrom` (how steep before the sides are read) and `u_wetLevel`/`u_wetBand`, as the Terrain shader's below.++What an artist delivers, per layer: the three textures, square, a power of two (1024 is plenty; they are packed at the largest+layer's size, at most 1024, 512 on a minigame), tiling seamlessly, the normal and mask saved as data (not colour-managed). A layer's+textures are packed into texture arrays when the terrain is built, and again whenever a layer file or one of its textures is saved.+## Layers and the Terrain materialThe four layers are grass, dirt, snow and rock. Every point of ground has a weight of each layer, from the splatmap or from how highdiff --git a/docs/astro/src/content/docs/zh-cn/graphics/terrain.mdx b/docs/astro/src/content/docs/zh-cn/graphics/terrain.mdxindex 98be431ef..d0372fc5f 100644--- a/docs/astro/src/content/docs/zh-cn/graphics/terrain.mdx+++ b/docs/astro/src/content/docs/zh-cn/graphics/terrain.mdx@@ -29,10 +29,12 @@ description: 一个 Terrain 组件,用高度图或噪声生成地面,可以是| `resolution` | 仅区域。区域噪声地面每边的采样数。 || `warp` | 0 到 1:噪声被它自己的另一层噪声扭曲多远,得到蜿蜒的山谷和弯折的山脊,而不是圆圆的山丘。 || `erosion` | 0 到 4:雨水把地面侵蚀多少(见下)。0 保持生成时的样子。 |-| `splatmap` | 仅区域。一张图,四个通道是四个图层的权重。为空则按高度和坡度上色。 |+| `splatmap` | 仅区域。一张图,四个通道是第 1 到 4 层的权重。为空则按高度和坡度上色。 |+| `splatmap2` | 仅区域。第 5 到 8 层的权重,与第一张一起读取。 |+| `layers` | 绘制地面所用的[地形层](#地形层),最多八个,按地表图权重的顺序。为空则用四种图层颜色或 Terrain 材质的贴图。 || `rockSlope`、`dirtHeight`、`snowHeight` | 地面要多陡才变成岩石,以及草地转为泥土、雪开始出现的高度(占 `height` 的比例)。 || `layerColor0`–`3` | 草、泥土、雪、岩石:没有材质时地面绘制用的颜色。 |-| `material` | 用 **Terrain** 着色器的材质(见下)。为空则直接把图层颜色画在地面上。 |+| `material` | 用 **Terrain** 着色器的材质(见下);地面有地形层时用 **Terrain Layers** 着色器。为空则用内置材质。 |改 `detail`、`drawDistance` 或图层颜色在下一帧生效。改其他任何字段都会重新构建地面。@@ -42,6 +44,24 @@ description: 一个 Terrain 组件,用高度图或噪声生成地面,可以是无限地面没有让雨水流走的边缘,所以它的侵蚀是噪声自己的:噪声的每个八度在它下面的八度已经很陡的地方被压低。这样会在尖锐的山脊之间留下平缓的山谷,和雨水的效果很像,除了噪声本身之外不花额外代价。它不画泥土水道。+## 地形层++地形层(`.esterrainlayer` 文件;编辑器里 **新建 → 新建地形层**)是一种地面——草、土路、沙、岩石——由美术为它制作的贴图组成。Terrain 列出它所用的地形层(`layers`,最多八个),地表图给出权重:第一张的红、绿、蓝、透明通道是第 1 到 4 层,第二张是第 5 到 8 层。没有地表图时,前四层按高度和坡度作为草、土、雪、岩上色;[生成世界](/docs/zh-cn/world/generation/)的群落可以为全部八层上色。++| 字段 | 含义 |+|---|---|+| `albedo` | 颜色贴图,sRGB。为空则为白色,由色调着色。 |+| `normal` | 切线空间法线贴图,绿色朝上(OpenGL 约定)。为空则平坦。 |+| `mask` | 红为环境遮蔽,绿为粗糙度,蓝为高度。为空:无遮蔽,用 `roughness`,高度取颜色亮度。 |+| `tile` | 贴图重复一次覆盖的世界单位。 |+| `tint` | 与颜色相乘。 |+| `roughness` | 没有遮罩贴图时的粗糙度。 |+| `normalStrength` | 法线贴图的强度:1 为原样,0 为平坦。 |++地面由 **Terrain Layers** 着色器(`builtin:terrain-layers`)绘制。每一层按世界位置铺设,近处去除重复,远处混入更大的平铺;层与层交界处遮罩高度更高的一层显露(草间露出石头、石缝里填着沙);坡面上同时从侧面投影,悬崖不会被拉伸。法线贴图和遮罩的遮蔽、粗糙度参与光照。材质控制效果:`u_sharpness`、`u_heightBlend`、`u_blendNoise`、`u_antiTile`、`u_farScale`、`u_macroVariation`、`u_triplanarFrom`(多陡开始读侧面)和 `u_wetLevel`/`u_wetBand`,含义同下文 Terrain 着色器。++美术每层交付:三张贴图,正方形,边长为 2 的幂(1024 足够;打包时取最大一层的尺寸,最大 1024,小游戏上 512),四方连续,法线和遮罩按数据保存(不做色彩管理)。地形构建时各层贴图会打包成纹理数组,地形层文件或其贴图保存后会重新打包。+## 图层与 Terrain 材质四个图层是草、泥土、雪和岩石。地面每一点在每个图层上都有一个权重,来自 splatmap 或来自那里有多高多陡,**Terrain** 着色器(`builtin:terrain`)把它们画出来。纹理按*世界位置*平铺,所以不管地面怎么切分,图层都连续不断;岩石从三个方向投影,所以悬崖不会被拉成一团。diff --git a/docs/astro/src/data/components.generated.json b/docs/astro/src/data/components.generated.jsonindex 243b79288..7a3ec1981 100644--- a/docs/astro/src/data/components.generated.json+++ b/docs/astro/src/data/components.generated.json@@ -5308,11 +5308,23 @@"default": "none","doc": "An image whose red, green, blue and alpha are the weights of grass, dirt, snow and rock."},+ {+ "key": "splatmap2",+ "type": "Asset<texture>",+ "default": "none",+ "doc": "An image whose red, green, blue and alpha are the weights of layers 5 to 8."+ },+ {+ "key": "layers",+ "type": "array",+ "default": "empty",+ "doc": "The terrain layers (.esterrainlayer, up to eight) the ground is drawn with, in the order the paint weighs them. Empty draws the four layer colours."+ },{"key": "material","type": "Asset<material>","default": "none",- "doc": "A material on the Terrain shader. Empty draws the layer colours onto the ground."+ "doc": "A material on the Terrain shader (on Terrain Layers when the ground has layers). Empty uses the stock one."},{"key": "sizeX",@@ -5489,6 +5501,7 @@"heightmap","heightmapFormat","splatmap",+ "splatmap2","material","sizeX","sizeZ",diff --git a/examples/terrain-water/assets/materials/ground.esmaterial b/examples/terrain-water/assets/materials/ground.esmaterialindex ec03edefa..5048217fa 100644--- a/examples/terrain-water/assets/materials/ground.esmaterial+++ b/examples/terrain-water/assets/materials/ground.esmaterial@@ -1,51 +1,17 @@{"version": "1.0","type": "material",- "shader": "builtin:terrain",+ "shader": "builtin:terrain-layers","blendMode": 0,"depthTest": true,"depthWrite": true,"cull": 0,"properties": {- "u_layer0": "assets/textures/grass.png",- "u_layer1": "assets/textures/sand.png",- "u_layer2": "assets/textures/snow.png",- "u_layer3": "assets/textures/rock.png",- "u_tint0": {- "r": 1,- "g": 1,- "b": 1,- "a": 1- },- "u_tint1": {- "r": 1,- "g": 1,- "b": 1,- "a": 1- },- "u_tint2": {- "r": 1,- "g": 1,- "b": 1,- "a": 1- },- "u_tint3": {- "r": 1,- "g": 1,- "b": 1,- "a": 1- },- "u_tile0": 900,- "u_tile1": 700,- "u_tile2": 1100,- "u_tile3": 1400,"u_macroVariation": 0.45,"u_sharpness": 1.4,"u_blendNoise": 0.6,- "u_roughness": 0.95,- "u_heightBlend": 0.55,+ "u_heightBlend": 0.8,"u_antiTile": 0.7,- "u_relief": 8,"u_wetLevel": 0,"u_wetBand": 60}diff --git a/examples/terrain-water/assets/scenes/main.esscene b/examples/terrain-water/assets/scenes/main.essceneindex 92f0e40ec..b614e9bb9 100644--- a/examples/terrain-water/assets/scenes/main.esscene+++ b/examples/terrain-water/assets/scenes/main.esscene@@ -264,7 +264,13 @@"heightmap": "assets/textures/height.png","heightmapFormat": 1,"splatmap": "assets/textures/splat.png",- "material": "assets/materials/ground.esmaterial"+ "material": "assets/materials/ground.esmaterial",+ "layers": [+ "assets/terrain/grass.esterrainlayer",+ "assets/terrain/sand.esterrainlayer",+ "assets/terrain/snow.esterrainlayer",+ "assets/terrain/rock.esterrainlayer"+ ]}}]diff --git a/examples/terrain-water/assets/terrain/grass.esterrainlayer b/examples/terrain-water/assets/terrain/grass.esterrainlayernew file mode 100644index 000000000..cfcfd627a--- /dev/null+++ b/examples/terrain-water/assets/terrain/grass.esterrainlayer@@ -0,0 +1,13 @@+{+ "albedo": "assets/textures/grass.png",+ "normal": "assets/textures/grass_normal.png",+ "mask": "assets/textures/grass_mask.png",+ "tile": 900,+ "tint": [+ 1,+ 1,+ 1+ ],+ "roughness": 0.95,+ "normalStrength": 1+}diff --git a/examples/terrain-water/assets/terrain/grass.esterrainlayer.meta b/examples/terrain-water/assets/terrain/grass.esterrainlayer.metanew file mode 100644index 000000000..661c4aa72--- /dev/null+++ b/examples/terrain-water/assets/terrain/grass.esterrainlayer.meta@@ -0,0 +1,6 @@+{+ "uuid": "106ce7ed-1cde-46ff-85f0-b6c64ea85ddd",+ "version": "2.0",+ "type": "terrain-layer",+ "importer": {}+}diff --git a/examples/terrain-water/assets/terrain/rock.esterrainlayer b/examples/terrain-water/assets/terrain/rock.esterrainlayernew file mode 100644index 000000000..45df74db7--- /dev/null+++ b/examples/terrain-water/assets/terrain/rock.esterrainlayer@@ -0,0 +1,13 @@+{+ "albedo": "assets/textures/rock.png",+ "normal": "assets/textures/rock_normal.png",+ "mask": "assets/textures/rock_mask.png",+ "tile": 1400,+ "tint": [+ 1,+ 1,+ 1+ ],+ "roughness": 0.75,+ "normalStrength": 1+}diff --git a/examples/terrain-water/assets/terrain/rock.esterrainlayer.meta b/examples/terrain-water/assets/terrain/rock.esterrainlayer.metanew file mode 100644index 000000000..3e6ecb5e1--- /dev/null+++ b/examples/terrain-water/assets/terrain/rock.esterrainlayer.meta@@ -0,0 +1,6 @@+{+ "uuid": "d6991480-c6fa-41af-ae73-40d4bfb275ff",+ "version": "2.0",+ "type": "terrain-layer",+ "importer": {}+}diff --git a/examples/terrain-water/assets/terrain/sand.esterrainlayer b/examples/terrain-water/assets/terrain/sand.esterrainlayernew file mode 100644index 000000000..9804f449b--- /dev/null+++ b/examples/terrain-water/assets/terrain/sand.esterrainlayer@@ -0,0 +1,13 @@+{+ "albedo": "assets/textures/sand.png",+ "normal": "assets/textures/sand_normal.png",+ "mask": "assets/textures/sand_mask.png",+ "tile": 700,+ "tint": [+ 1,+ 1,+ 1+ ],+ "roughness": 0.85,+ "normalStrength": 1+}diff --git a/examples/terrain-water/assets/terrain/sand.esterrainlayer.meta b/examples/terrain-water/assets/terrain/sand.esterrainlayer.metanew file mode 100644index 000000000..136479996--- /dev/null+++ b/examples/terrain-water/assets/terrain/sand.esterrainlayer.meta@@ -0,0 +1,6 @@+{+ "uuid": "3c1d09e6-ae77-4c4e-b706-ca1f843434be",+ "version": "2.0",+ "type": "terrain-layer",+ "importer": {}+}diff --git a/examples/terrain-water/assets/terrain/snow.esterrainlayer b/examples/terrain-water/assets/terrain/snow.esterrainlayernew file mode 100644index 000000000..889aadd0b--- /dev/null+++ b/examples/terrain-water/assets/terrain/snow.esterrainlayer@@ -0,0 +1,13 @@+{+ "albedo": "assets/textures/snow.png",+ "normal": "assets/textures/snow_normal.png",+ "mask": "assets/textures/snow_mask.png",+ "tile": 1100,+ "tint": [+ 1,+ 1,+ 1+ ],+ "roughness": 0.55,+ "normalStrength": 1+}diff --git a/examples/terrain-water/assets/terrain/snow.esterrainlayer.meta b/examples/terrain-water/assets/terrain/snow.esterrainlayer.metanew file mode 100644index 000000000..78ebc6dd9--- /dev/null+++ b/examples/terrain-water/assets/terrain/snow.esterrainlayer.meta@@ -0,0 +1,6 @@+{+ "uuid": "4c9f4f65-8813-43cd-82a2-811291d7359a",+ "version": "2.0",+ "type": "terrain-layer",+ "importer": {}+}diff --git a/examples/terrain-water/assets/textures/grass_mask.png b/examples/terrain-water/assets/textures/grass_mask.pngnew file mode 100644index 000000000..5a1d2cf47Binary files /dev/null and b/examples/terrain-water/assets/textures/grass_mask.png differdiff --git a/examples/terrain-water/assets/textures/grass_mask.png.meta b/examples/terrain-water/assets/textures/grass_mask.png.metanew file mode 100644index 000000000..af28773d4--- /dev/null+++ b/examples/terrain-water/assets/textures/grass_mask.png.meta@@ -0,0 +1,9 @@+{+ "uuid": "43542119-9d09-4155-be3f-de95353c7267",+ "version": "2.0",+ "type": "texture",+ "importer": {+ "wrapMode": "repeat",+ "sRGB": false+ }+}diff --git a/examples/terrain-water/assets/textures/grass_normal.png b/examples/terrain-water/assets/textures/grass_normal.pngnew file mode 100644index 000000000..714eb8eeeBinary files /dev/null and b/examples/terrain-water/assets/textures/grass_normal.png differdiff --git a/examples/terrain-water/assets/textures/grass_normal.png.meta b/examples/terrain-water/assets/textures/grass_normal.png.metanew file mode 100644index 000000000..d3ae325b9--- /dev/null+++ b/examples/terrain-water/assets/textures/grass_normal.png.meta@@ -0,0 +1,9 @@+{+ "uuid": "6aa85d7b-28d1-474f-b88b-e7ace38cb2af",+ "version": "2.0",+ "type": "texture",+ "importer": {+ "wrapMode": "repeat",+ "sRGB": false+ }+}diff --git a/examples/terrain-water/assets/textures/rock_mask.png b/examples/terrain-water/assets/textures/rock_mask.pngnew file mode 100644index 000000000..9797483c8Binary files /dev/null and b/examples/terrain-water/assets/textures/rock_mask.png differdiff --git a/examples/terrain-water/assets/textures/rock_mask.png.meta b/examples/terrain-water/assets/textures/rock_mask.png.metanew file mode 100644index 000000000..dd3bf39fe--- /dev/null+++ b/examples/terrain-water/assets/textures/rock_mask.png.meta@@ -0,0 +1,9 @@+{+ "uuid": "2bddfcf4-e8c9-48e0-96a3-504974aac333",+ "version": "2.0",+ "type": "texture",+ "importer": {+ "wrapMode": "repeat",+ "sRGB": false+ }+}diff --git a/examples/terrain-water/assets/textures/rock_normal.png b/examples/terrain-water/assets/textures/rock_normal.pngnew file mode 100644index 000000000..4264b6e59Binary files /dev/null and b/examples/terrain-water/assets/textures/rock_normal.png differdiff --git a/examples/terrain-water/assets/textures/rock_normal.png.meta b/examples/terrain-water/assets/textures/rock_normal.png.metanew file mode 100644index 000000000..908c5507f--- /dev/null+++ b/examples/terrain-water/assets/textures/rock_normal.png.meta@@ -0,0 +1,9 @@+{+ "uuid": "d6e3e9ed-b6da-40d1-8a45-506ba4a2dc36",+ "version": "2.0",+ "type": "texture",+ "importer": {+ "wrapMode": "repeat",+ "sRGB": false+ }+}diff --git a/examples/terrain-water/assets/textures/sand_mask.png b/examples/terrain-water/assets/textures/sand_mask.pngnew file mode 100644index 000000000..c25849306Binary files /dev/null and b/examples/terrain-water/assets/textures/sand_mask.png differdiff --git a/examples/terrain-water/assets/textures/sand_mask.png.meta b/examples/terrain-water/assets/textures/sand_mask.png.metanew file mode 100644index 000000000..d58522f58--- /dev/null+++ b/examples/terrain-water/assets/textures/sand_mask.png.meta@@ -0,0 +1,9 @@+{+ "uuid": "1ac1e7c8-f460-40aa-8ff3-c10716440f15",+ "version": "2.0",+ "type": "texture",+ "importer": {+ "wrapMode": "repeat",+ "sRGB": false+ }+}diff --git a/examples/terrain-water/assets/textures/sand_normal.png b/examples/terrain-water/assets/textures/sand_normal.pngnew file mode 100644index 000000000..f68b4dee1Binary files /dev/null and b/examples/terrain-water/assets/textures/sand_normal.png differdiff --git a/examples/terrain-water/assets/textures/sand_normal.png.meta b/examples/terrain-water/assets/textures/sand_normal.png.metanew file mode 100644index 000000000..2181b199f--- /dev/null+++ b/examples/terrain-water/assets/textures/sand_normal.png.meta@@ -0,0 +1,9 @@+{+ "uuid": "c4776d13-80f1-4280-80d2-96ea1919ad6b",+ "version": "2.0",+ "type": "texture",+ "importer": {+ "wrapMode": "repeat",+ "sRGB": false+ }+}diff --git a/examples/terrain-water/assets/textures/snow_mask.png b/examples/terrain-water/assets/textures/snow_mask.pngnew file mode 100644index 000000000..26740dd98Binary files /dev/null and b/examples/terrain-water/assets/textures/snow_mask.png differdiff --git a/examples/terrain-water/assets/textures/snow_mask.png.meta b/examples/terrain-water/assets/textures/snow_mask.png.metanew file mode 100644index 000000000..0927fa163--- /dev/null+++ b/examples/terrain-water/assets/textures/snow_mask.png.meta@@ -0,0 +1,9 @@+{+ "uuid": "9c476d06-ebe8-42a0-8636-6197e67b553a",+ "version": "2.0",+ "type": "texture",+ "importer": {+ "wrapMode": "repeat",+ "sRGB": false+ }+}diff --git a/examples/terrain-water/assets/textures/snow_normal.png b/examples/terrain-water/assets/textures/snow_normal.pngnew file mode 100644index 000000000..06da8f4d8Binary files /dev/null and b/examples/terrain-water/assets/textures/snow_normal.png differdiff --git a/examples/terrain-water/assets/textures/snow_normal.png.meta b/examples/terrain-water/assets/textures/snow_normal.png.metanew file mode 100644index 000000000..4ab5cbfaf--- /dev/null+++ b/examples/terrain-water/assets/textures/snow_normal.png.meta@@ -0,0 +1,9 @@+{+ "uuid": "f358f47c-1ec5-4f78-a75c-0c5b167a6d2c",+ "version": "2.0",+ "type": "texture",+ "importer": {+ "wrapMode": "repeat",+ "sRGB": false+ }+}diff --git a/examples/terrain-water/tools/build.mjs b/examples/terrain-water/tools/build.mjsindex d5f9b7e87..068c7b7f3 100644--- a/examples/terrain-water/tools/build.mjs+++ b/examples/terrain-water/tools/build.mjs@@ -274,16 +274,50 @@ function splatmap() {const mix = (a, b, t) => a.map((c, i) => c + (b[i] - c) * t);-function texture(name, seed, shade) {+function texture(name, seed, shade, layer) {const size = 512;- const image = png(size, size, (x, y) => {+ const rgb = new Float64Array(size * size * 3);+ for (let y = 0; y < size; y++) for (let x = 0; x < size; x++) {const u = x / size, v = y / size;- const rgb = shade(u, v, (s, o, b) => fractal(u, v, seed + s, o, b));- return [rgb[0], rgb[1], rgb[2], 255];- });+ const c = shade(u, v, (s, o, b) => fractal(u, v, seed + s, o, b));+ rgb.set([c[0], c[1], c[2]], (y * size + x) * 3);+ }+ const image = png(size, size, (x, y) => { const k = (y * size + x) * 3; return [rgb[k], rgb[k + 1], rgb[k + 2], 255]; });write(`assets/textures/${name}.png`, image);// Tiled by world position across the whole ground: it must repeat, or every texel past the first tile is its edge stretched.meta(`assets/textures/${name}.png`, 'texture', { wrapMode: 'repeat' });+ if (layer) terrainLayer(name, size, rgb, layer);+}++/**+ * The textures of a terrain layer made from its colour: its relief taken as how bright it is (stones stand up, cracks sink), the normal+ * map from that relief's slope, and the mask (occlusion deeper in the low places, the layer's roughness varied a little, the relief as+ * height). And the `.esterrainlayer` file that names them.+ */+function terrainLayer(name, size, rgb, { tile, roughness, relief }) {+ const h = new Float64Array(size * size);+ for (let k = 0; k < size * size; k++) h[k] = (rgb[k * 3] * 0.299 + rgb[k * 3 + 1] * 0.587 + rgb[k * 3 + 2] * 0.114) / 255;+ const at = (x, y) => h[((y + size) % size) * size + ((x + size) % size)];+ const normal = png(size, size, (x, y) => {+ // Green up (OpenGL): +y in the texture is up the image, which is -y in rows.+ const dx = (at(x + 1, y) - at(x - 1, y)) * relief, dy = (at(x, y - 1) - at(x, y + 1)) * relief;+ const len = Math.hypot(dx, dy, 1);+ return [(-dx / len * 0.5 + 0.5) * 255, (-dy / len * 0.5 + 0.5) * 255, (1 / len * 0.5 + 0.5) * 255, 255];+ });+ const mask = png(size, size, (x, y) => {+ const v = at(x, y);+ return [(0.55 + 0.45 * smooth(0.1, 0.6, v)) * 255, Math.min(1, roughness + (0.5 - v) * 0.1) * 255, v * 255, 255];+ });+ for (const [suffix, data] of [['normal', normal], ['mask', mask]]) {+ write(`assets/textures/${name}_${suffix}.png`, data);+ meta(`assets/textures/${name}_${suffix}.png`, 'texture', { wrapMode: 'repeat', sRGB: false });+ }+ const file = `assets/terrain/${name}.esterrainlayer`;+ write(file, `${JSON.stringify({+ albedo: `assets/textures/${name}.png`, normal: `assets/textures/${name}_normal.png`, mask: `assets/textures/${name}_mask.png`,+ tile, tint: [1, 1, 1], roughness, normalStrength: 1,+ }, null, 2)}\n`);+ meta(file, 'terrain-layer');}/** Cellular noise that wraps every `period` cells: the distance to the nearest and the second-nearest feature point, for stones and cracks. */@@ -311,7 +345,7 @@ function textures() {c = mix(c, [146, 140, 70], dry * 0.7);c = mix(c, [86, 70, 44], earth);return c.map((x) => x * (0.62 + 0.38 * clump) * (0.82 + 0.3 * blade));- });+ }, { tile: 900, roughness: 0.95, relief: 3 });// Sand: low ripples the wind combed across it, running one way and only gently bent (a contour of noise reads as rings), fading// in and out in patches; pebbles and broken shell scattered over.texture('sand', 2, (u, v, n) => {@@ -323,12 +357,12 @@ function textures() {let c = mix([170, 150, 114], [222, 204, 164], n(10, 4, 4));c = c.map((x) => x * (0.93 + 0.07 * ripple) * (0.93 + 0.1 * grain));return mix(c, mix([110, 104, 96], [196, 188, 172], stones.id), pebble * (stones.id > 0.55 ? 1 : 0));- });+ }, { tile: 700, roughness: 0.85, relief: 4 });// Snow: windblown, bluish in its hollows, with the odd glint.texture('snow', 3, (u, v, n) => {const drift = n(0, 4, 4), sparkle = hash(Math.floor(u * 512), Math.floor(v * 512), 7) > 0.985 ? 1.08 : 1;return mix([196, 210, 230], [252, 253, 255], smooth(0.2, 0.75, drift)).map((x) => Math.min(255, x * sparkle));- });+ }, { tile: 1100, roughness: 0.55, relief: 2 });// Rock: strata running across it, cracks between blocks, weathered lighter on the faces, lichen in patches.texture('rock', 4, (u, v, n) => {const block = cells(u, v, 6, 31);@@ -339,7 +373,7 @@ function textures() {let c = mix([70, 68, 66], [138, 134, 126], face * 0.6 + strata * 0.25 + block.id * 0.25);c = mix(c, [118, 124, 82], lichen * 0.55);return c.map((x) => x * (0.35 + 0.65 * crack) * (0.85 + 0.25 * n(60, 3, 64)));- });+ }, { tile: 1400, roughness: 0.75, relief: 6 });// The pine's colour: bark at the foot, then needles that darken toward the shade under each tier.const strip = png(8, 128, (x, y) => {const v = 1 - y / 127;@@ -416,10 +450,9 @@ function material(name, shader, properties) {function materials() {const white = { r: 1, g: 1, b: 1, a: 1 };- material('ground', 'builtin:terrain', {- u_layer0: 'assets/textures/grass.png', u_layer1: 'assets/textures/sand.png', u_layer2: 'assets/textures/snow.png', u_layer3: 'assets/textures/rock.png',- u_tint0: white, u_tint1: white, u_tint2: white, u_tint3: white,- u_tile0: 900, u_tile1: 700, u_tile2: 1100, u_tile3: 1400, u_macroVariation: 0.45, u_sharpness: 1.4, u_blendNoise: 0.6, u_roughness: 0.95, u_heightBlend: 0.55, u_antiTile: 0.7, u_relief: 8,+ // The ground's look: its layers (the Terrain's `layers`) are the textures, this how they meet and wear.+ material('ground', 'builtin:terrain-layers', {+ u_macroVariation: 0.45, u_sharpness: 1.4, u_blendNoise: 0.6, u_heightBlend: 0.8, u_antiTile: 0.7,u_wetLevel: WORLD.sea, u_wetBand: 60,});// The stock water, scaled from metres to this world's centimetres: the same colours, absorbed over a hundred times the distance.@@ -495,7 +528,9 @@ function scene() {{ type: 'Transform', data: { position: { x: 0, y: WORLD.base, z: 0 } } },{ type: 'Terrain', data: {sizeX: WORLD.size, sizeZ: WORLD.size, height: WORLD.height, cellSize: 30, detail: 1,- heightmap: 'assets/textures/height.png', heightmapFormat: 1, splatmap: 'assets/textures/splat.png', material: 'assets/materials/ground.esmaterial' } },+ heightmap: 'assets/textures/height.png', heightmapFormat: 1, splatmap: 'assets/textures/splat.png', material: 'assets/materials/ground.esmaterial',+ // In the splatmap's order: grass, sand, snow, rock.+ layers: ['grass', 'sand', 'snow', 'rock'].map((n) => `assets/terrain/${n}.esterrainlayer`) } },]);// The water: one zone over the whole island, which the sea, the lake and the two rivers are baked into and drawn from as one surface.add('Water', [diff --git a/pipeline/src/assets/addressableManifest.ts b/pipeline/src/assets/addressableManifest.tsindex f052229ee..fdef6ab30 100644--- a/pipeline/src/assets/addressableManifest.ts+++ b/pipeline/src/assets/addressableManifest.ts@@ -38,7 +38,7 @@ interface FlatManifest {const ADDRESSABLE_TYPE: Record<string, string> = {texture: 'texture', material: 'material', audio: 'audio', 'bitmap-font': 'bitmap-font',prefab: 'prefab', spine: 'spine',- scene: 'json', 'anim-clip': 'json', tilemap: 'json', timeline: 'json', json: 'json', 'sound-event': 'json', 'world-rules': 'json', shader: 'text',+ scene: 'json', 'anim-clip': 'json', tilemap: 'json', timeline: 'json', json: 'json', 'sound-event': 'json', 'world-rules': 'json', 'terrain-layer': 'json', shader: 'text',};export const addrType = (editorType: string): string => ADDRESSABLE_TYPE[editorType] ?? 'binary';diff --git a/pipeline/src/assets/assetDb.ts b/pipeline/src/assets/assetDb.tsindex 05284ccf8..8697297f2 100644--- a/pipeline/src/assets/assetDb.ts+++ b/pipeline/src/assets/assetDb.ts@@ -234,7 +234,7 @@ const JSON_REF_TYPES = new Set(['scene', 'prefab', 'material', 'tileset', 'tilemap', 'animclip', 'animation', 'statemachine', 'behaviortree','scriptgraph','environment', 'animatorcontroller', 'avatar',- 'json', 'sound-event', 'world-rules',+ 'json', 'sound-event', 'world-rules', 'terrain-layer',]);/**diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 6f2a9509e..cc651933e 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -1,7 +1,7 @@# API surface — esengine/index<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 115 public · 159 beta · 1834 experimental · 3 deprecated+Symbols: 115 public · 159 beta · 1843 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental```@@ -1665,7 +1665,7 @@ min: number | undefined```conditions: readonly BiomeCondition[]id: string-paint: readonly [number, number, number, number] | undefined+paint: readonly number[] | undefinedpaintStrength: number | undefinedrecipes: readonly BiomeRecipe[]transition: number | undefined@@ -3639,7 +3639,7 @@ Step = 15```| 'texture' | 'material' | 'shader' | 'spine-atlas' | 'spine-skeleton'| 'dragonbones-atlas' | 'dragonbones-skeleton'- | 'bitmap-font' | 'font' | 'prefab' | 'json' | 'audio' | 'sound-event' | 'world-rules' | 'video' | 'scene' | 'anim-clip'+ | 'bitmap-font' | 'font' | 'prefab' | 'json' | 'audio' | 'sound-event' | 'world-rules' | 'terrain-layer' | 'video' | 'scene' | 'anim-clip'| 'tilemap' | 'tileset' | 'timeline' | 'mesh'| 'unknown'```@@ -4064,8 +4064,8 @@ infinite: falsemaxHeight: numberminHeight: numbernormal: (x: number, z: number) => [number, number, number] | null-paint: (x: number, z: number, h: number, ny: number) => [number, number, number, number]-static new (field: Heightfield, data: Pick<TerrainData, "sizeX" | "sizeZ" | "height" | "rockSlope" | "dirtHeight" | "snowHeight">, splat: Splat | null, flow: Float32Array | null, range?: readonly [number, number]): FieldSource+paint: (x: number, z: number, h: number, ny: number) => LayerWeights+static new (field: Heightfield, data: Pick<TerrainData, "sizeX" | "sizeZ" | "height" | "rockSlope" | "dirtHeight" | "snowHeight">, splat: Splat | null, flow: Float32Array | null, range?: readonly [number, number], splat2?: Splat | null): FieldSourcestatic prototype: FieldSource```@@ -5071,6 +5071,13 @@ Readonly<Vec3>ThemeTokens```+## LayerImage — interface @experimental+```+height: number+pixels: Uint8Array<ArrayBufferLike>+width: number+```+## LayerOrder — enum @experimental```Depth = 2@@ -5083,6 +5090,19 @@ YSort = 1admits: (track: PoseTrack) => boolean```+## LayerSource — interface @experimental+```+albedo: LayerImage | null+def: TerrainLayerDef+mask: LayerImage | null+normal: LayerImage | null+```++## LayerWeights — type @experimental+```+readonly number[]+```+## LayoutProvider — interface @experimental```getContentSize: (count: number) => Vec2@@ -5779,8 +5799,8 @@ maxHeight: numberminHeight: numbernormal: (x: number, z: number) => [number, number, number] | nullorigin: { x: number; y: number; z: number; }-paint: (x: number, z: number, h: number, ny: number) => [number, number, number, number]-region: ((x0: number, z0: number, spacing: number, count: number) => { heights: Float32Array; paint?: Float32Array; } | Promise<{ heights: Float32Array; paint?: Float32Array; }>) | undefined+paint: (x: number, z: number, h: number, ny: number) => LayerWeights+region: ((x0: number, z0: number, spacing: number, count: number) => TerrainRegionSamples | Promise<TerrainRegionSamples>) | undefinedtouched: (x0: number, z0: number, x1: number, z1: number) => booleanstatic new (base: TerrainSource, modifiers: () => Iterable<TerrainModifier>, origin: { x: number; y: number; z: number; }, step: number): ModifiedSourcestatic prototype: ModifiedSource@@ -6091,6 +6111,15 @@ worlds: { scene: string; manifest: string; }[] | undefinedySortLayers: number | undefined```+## PackedLayers — interface @experimental+```+albedo: Uint8Array<ArrayBufferLike>[]+mask: Uint8Array<ArrayBufferLike>[]+normal: Uint8Array<ArrayBufferLike>[]+size: number+tiles: number[]+```+## Page — interface @experimental```max: number@@ -6104,6 +6133,7 @@ used: numberheights: Uint8Array<ArrayBufferLike>max: numbermin: number+paint2: Uint8Array<ArrayBufferLike>paint: Uint8Array<ArrayBufferLike>```@@ -10016,6 +10046,7 @@ layerColor0: ColorlayerColor1: ColorlayerColor2: ColorlayerColor3: Color+layers: string[]material: numberoctaves: numberpersistence: number@@ -10027,6 +10058,7 @@ seed: numbersizeX: numbersizeZ: numbersnowHeight: number+splatmap2: numbersplatmap: numberwarp: numberworld: string@@ -10037,6 +10069,27 @@ world: string{ readonly Area: 0; readonly Infinite: 1; }```+## TerrainLayerAssetLoader — class @experimental+```+extensions: string[]+load: (path: string, ctx: LoadContext) => Promise<TerrainLayerDef>+type: "terrain-layer"+unload: () => void+static new (): TerrainLayerAssetLoader+static prototype: TerrainLayerAssetLoader+```++## TerrainLayerDef — interface @experimental+```+albedo: string | undefined+mask: string | undefined+normal: string | undefined+normalStrength: number+roughness: number+tile: number+tint: [number, number, number]+```+## TerrainModifier — interface @experimental```apply: (x: number, z: number, h: number) => number@@ -10083,6 +10136,13 @@ x0: numberz0: number```+## TerrainRegionSamples — interface @experimental+```+heights: Float32Array<ArrayBufferLike>+paint2: Float32Array<ArrayBufferLike> | undefined+paint: Float32Array<ArrayBufferLike> | undefined+```+## TerrainSamples — interface @experimental```heights: Float32Array<ArrayBufferLike>@@ -10097,8 +10157,8 @@ infinite: booleanmaxHeight: numberminHeight: numbernormal: (x: number, z: number) => [number, number, number] | null-paint: (x: number, z: number, h: number, ny: number) => [number, number, number, number]-region: ((x0: number, z0: number, spacing: number, count: number) => { heights: Float32Array; paint?: Float32Array; } | Promise<{ heights: Float32Array; paint?: Float32Array; }>) | undefined+paint: (x: number, z: number, h: number, ny: number) => LayerWeights+region: ((x0: number, z0: number, spacing: number, count: number) => TerrainRegionSamples | Promise<TerrainRegionSamples>) | undefined```## TerrainStatus — interface @experimental@@ -12230,7 +12290,7 @@ group: (li: number, gx: number, gz: number) => Group | RejectiongroupsIn: (layer: string, x0: number, z0: number, x1: number, z1: number) => Group[]invalidate: () => voidlayerIndex: (id: string) => number-paint: (x: number, z: number, base: readonly [number, number, number, number]) => [number, number, number, number]+paint: (x: number, z: number, base: readonly number[]) => number[]placementsIn: (x0: number, z0: number, x1: number, z1: number, layers?: readonly string[]) => Placement[]rules: WorldRulesseed: number@@ -14485,6 +14545,11 @@ MeshRendererPlugin(semantics: { semantic: number; components: number; type: number; }[]): { channels: MeshChannelDesc[]; vertexStride: number; }```+## packLayers — function @experimental+```+(layers: readonly LayerSource[], maxSize?: number): PackedLayers+```+## packagedAppOptions — function @experimental```(config: Pick<PackagedGameConfig, "ySortLayers" | "depthLayers" | "colorSpace" | "outputTransform" | "screenFit" | "msaaSamples" | "quality">): { ySortLayers?: number; depthLayers?: number; colorSpace?: "gamma" | "linear"; outputTransform?: "none" | "aces" | "neutral"; msaaSamples?: number; quality?: QualityConfig; renderBackend?: "webgl2" | "webgpu"; screenFit?: PackagedGameConfig["screenFit"]; }@@ -14580,6 +14645,11 @@ MeshRendererPlugin(value: unknown): SoundEventAsset```+## parseTerrainLayer — function @experimental+```+(json: unknown, file?: string): TerrainLayerDef+```+## parseThemeOverrides — function @experimental```(colors?: Record<string, string>): ThemeOverrides | undefineddiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex fad13b103..730478eae 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -1,7 +1,7 @@# API surface — esengine/index.native<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 115 public · 164 beta · 1853 experimental · 3 deprecated+Symbols: 115 public · 164 beta · 1862 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental```@@ -1665,7 +1665,7 @@ min: number | undefined```conditions: readonly BiomeCondition[]id: string-paint: readonly [number, number, number, number] | undefined+paint: readonly number[] | undefinedpaintStrength: number | undefinedrecipes: readonly BiomeRecipe[]transition: number | undefined@@ -3647,7 +3647,7 @@ Step = 15```| 'texture' | 'material' | 'shader' | 'spine-atlas' | 'spine-skeleton'| 'dragonbones-atlas' | 'dragonbones-skeleton'- | 'bitmap-font' | 'font' | 'prefab' | 'json' | 'audio' | 'sound-event' | 'world-rules' | 'video' | 'scene' | 'anim-clip'+ | 'bitmap-font' | 'font' | 'prefab' | 'json' | 'audio' | 'sound-event' | 'world-rules' | 'terrain-layer' | 'video' | 'scene' | 'anim-clip'| 'tilemap' | 'tileset' | 'timeline' | 'mesh'| 'unknown'```@@ -4072,8 +4072,8 @@ infinite: falsemaxHeight: numberminHeight: numbernormal: (x: number, z: number) => [number, number, number] | null-paint: (x: number, z: number, h: number, ny: number) => [number, number, number, number]-static new (field: Heightfield, data: Pick<TerrainData, "sizeX" | "sizeZ" | "height" | "rockSlope" | "dirtHeight" | "snowHeight">, splat: Splat | null, flow: Float32Array | null, range?: readonly [number, number]): FieldSource+paint: (x: number, z: number, h: number, ny: number) => LayerWeights+static new (field: Heightfield, data: Pick<TerrainData, "sizeX" | "sizeZ" | "height" | "rockSlope" | "dirtHeight" | "snowHeight">, splat: Splat | null, flow: Float32Array | null, range?: readonly [number, number], splat2?: Splat | null): FieldSourcestatic prototype: FieldSource```@@ -5079,6 +5079,13 @@ Readonly<Vec3>ThemeTokens```+## LayerImage — interface @experimental+```+height: number+pixels: Uint8Array<ArrayBufferLike>+width: number+```+## LayerOrder — enum @experimental```Depth = 2@@ -5091,6 +5098,19 @@ YSort = 1admits: (track: PoseTrack) => boolean```+## LayerSource — interface @experimental+```+albedo: LayerImage | null+def: TerrainLayerDef+mask: LayerImage | null+normal: LayerImage | null+```++## LayerWeights — type @experimental+```+readonly number[]+```+## LayoutProvider — interface @experimental```getContentSize: (count: number) => Vec2@@ -5792,8 +5812,8 @@ maxHeight: numberminHeight: numbernormal: (x: number, z: number) => [number, number, number] | nullorigin: { x: number; y: number; z: number; }-paint: (x: number, z: number, h: number, ny: number) => [number, number, number, number]-region: ((x0: number, z0: number, spacing: number, count: number) => { heights: Float32Array; paint?: Float32Array; } | Promise<{ heights: Float32Array; paint?: Float32Array; }>) | undefined+paint: (x: number, z: number, h: number, ny: number) => LayerWeights+region: ((x0: number, z0: number, spacing: number, count: number) => TerrainRegionSamples | Promise<TerrainRegionSamples>) | undefinedtouched: (x0: number, z0: number, x1: number, z1: number) => booleanstatic new (base: TerrainSource, modifiers: () => Iterable<TerrainModifier>, origin: { x: number; y: number; z: number; }, step: number): ModifiedSourcestatic prototype: ModifiedSource@@ -6294,6 +6314,15 @@ worlds: { scene: string; manifest: string; }[] | undefinedySortLayers: number | undefined```+## PackedLayers — interface @experimental+```+albedo: Uint8Array<ArrayBufferLike>[]+mask: Uint8Array<ArrayBufferLike>[]+normal: Uint8Array<ArrayBufferLike>[]+size: number+tiles: number[]+```+## Page — interface @experimental```max: number@@ -6307,6 +6336,7 @@ used: numberheights: Uint8Array<ArrayBufferLike>max: numbermin: number+paint2: Uint8Array<ArrayBufferLike>paint: Uint8Array<ArrayBufferLike>```@@ -10229,6 +10259,7 @@ layerColor0: ColorlayerColor1: ColorlayerColor2: ColorlayerColor3: Color+layers: string[]material: numberoctaves: numberpersistence: number@@ -10240,6 +10271,7 @@ seed: numbersizeX: numbersizeZ: numbersnowHeight: number+splatmap2: numbersplatmap: numberwarp: numberworld: string@@ -10250,6 +10282,27 @@ world: string{ readonly Area: 0; readonly Infinite: 1; }```+## TerrainLayerAssetLoader — class @experimental+```+extensions: string[]+load: (path: string, ctx: LoadContext) => Promise<TerrainLayerDef>+type: "terrain-layer"+unload: () => void+static new (): TerrainLayerAssetLoader+static prototype: TerrainLayerAssetLoader+```++## TerrainLayerDef — interface @experimental+```+albedo: string | undefined+mask: string | undefined+normal: string | undefined+normalStrength: number+roughness: number+tile: number+tint: [number, number, number]+```+## TerrainModifier — interface @experimental```apply: (x: number, z: number, h: number) => number@@ -10296,6 +10349,13 @@ x0: numberz0: number```+## TerrainRegionSamples — interface @experimental+```+heights: Float32Array<ArrayBufferLike>+paint2: Float32Array<ArrayBufferLike> | undefined+paint: Float32Array<ArrayBufferLike> | undefined+```+## TerrainSamples — interface @experimental```heights: Float32Array<ArrayBufferLike>@@ -10310,8 +10370,8 @@ infinite: booleanmaxHeight: numberminHeight: numbernormal: (x: number, z: number) => [number, number, number] | null-paint: (x: number, z: number, h: number, ny: number) => [number, number, number, number]-region: ((x0: number, z0: number, spacing: number, count: number) => { heights: Float32Array; paint?: Float32Array; } | Promise<{ heights: Float32Array; paint?: Float32Array; }>) | undefined+paint: (x: number, z: number, h: number, ny: number) => LayerWeights+region: ((x0: number, z0: number, spacing: number, count: number) => TerrainRegionSamples | Promise<TerrainRegionSamples>) | undefined```## TerrainStatus — interface @experimental@@ -12443,7 +12503,7 @@ group: (li: number, gx: number, gz: number) => Group | RejectiongroupsIn: (layer: string, x0: number, z0: number, x1: number, z1: number) => Group[]invalidate: () => voidlayerIndex: (id: string) => number-paint: (x: number, z: number, base: readonly [number, number, number, number]) => [number, number, number, number]+paint: (x: number, z: number, base: readonly number[]) => number[]placementsIn: (x0: number, z0: number, x1: number, z1: number, layers?: readonly string[]) => Placement[]rules: WorldRulesseed: number@@ -14748,6 +14808,11 @@ MeshRendererPlugin(semantics: { semantic: number; components: number; type: number; }[]): { channels: MeshChannelDesc[]; vertexStride: number; }```+## packLayers — function @experimental+```+(layers: readonly LayerSource[], maxSize?: number): PackedLayers+```+## packagedAppOptions — function @experimental```(config: Pick<PackagedGameConfig, "ySortLayers" | "depthLayers" | "colorSpace" | "outputTransform" | "screenFit" | "msaaSamples" | "quality">): { ySortLayers?: number; depthLayers?: number; colorSpace?: "gamma" | "linear"; outputTransform?: "none" | "aces" | "neutral"; msaaSamples?: number; quality?: QualityConfig; renderBackend?: "webgl2" | "webgpu"; screenFit?: PackagedGameConfig["screenFit"]; }@@ -14843,6 +14908,11 @@ MeshRendererPlugin(value: unknown): SoundEventAsset```+## parseTerrainLayer — function @experimental+```+(json: unknown, file?: string): TerrainLayerDef+```+## parseThemeOverrides — function @experimental```(colors?: Record<string, string>): ThemeOverrides | undefineddiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 061e65349..af49c058f 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -1,7 +1,7 @@# API surface — esengine/index.node<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 115 public · 161 beta · 1833 experimental · 3 deprecated+Symbols: 115 public · 161 beta · 1842 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -1660,7 +1660,7 @@ min: number | undefined```conditions: readonly BiomeCondition[]id: string-paint: readonly [number, number, number, number] | undefined+paint: readonly number[] | undefinedpaintStrength: number | undefinedrecipes: readonly BiomeRecipe[]transition: number | undefined@@ -3634,7 +3634,7 @@ Step = 15```| 'texture' | 'material' | 'shader' | 'spine-atlas' | 'spine-skeleton'| 'dragonbones-atlas' | 'dragonbones-skeleton'- | 'bitmap-font' | 'font' | 'prefab' | 'json' | 'audio' | 'sound-event' | 'world-rules' | 'video' | 'scene' | 'anim-clip'+ | 'bitmap-font' | 'font' | 'prefab' | 'json' | 'audio' | 'sound-event' | 'world-rules' | 'terrain-layer' | 'video' | 'scene' | 'anim-clip'| 'tilemap' | 'tileset' | 'timeline' | 'mesh'| 'unknown'```@@ -4059,8 +4059,8 @@ infinite: falsemaxHeight: numberminHeight: numbernormal: (x: number, z: number) => [number, number, number] | null-paint: (x: number, z: number, h: number, ny: number) => [number, number, number, number]-static new (field: Heightfield, data: Pick<TerrainData, "sizeX" | "sizeZ" | "height" | "rockSlope" | "dirtHeight" | "snowHeight">, splat: Splat | null, flow: Float32Array | null, range?: readonly [number, number]): FieldSource+paint: (x: number, z: number, h: number, ny: number) => LayerWeights+static new (field: Heightfield, data: Pick<TerrainData, "sizeX" | "sizeZ" | "height" | "rockSlope" | "dirtHeight" | "snowHeight">, splat: Splat | null, flow: Float32Array | null, range?: readonly [number, number], splat2?: Splat | null): FieldSourcestatic prototype: FieldSource```@@ -5066,6 +5066,13 @@ Readonly<Vec3>ThemeTokens```+## LayerImage — interface @experimental+```+height: number+pixels: Uint8Array<ArrayBufferLike>+width: number+```+## LayerOrder — enum @experimental```Depth = 2@@ -5078,6 +5085,19 @@ YSort = 1admits: (track: PoseTrack) => boolean```+## LayerSource — interface @experimental+```+albedo: LayerImage | null+def: TerrainLayerDef+mask: LayerImage | null+normal: LayerImage | null+```++## LayerWeights — type @experimental+```+readonly number[]+```+## LayoutProvider — interface @experimental```getContentSize: (count: number) => Vec2@@ -5774,8 +5794,8 @@ maxHeight: numberminHeight: numbernormal: (x: number, z: number) => [number, number, number] | nullorigin: { x: number; y: number; z: number; }-paint: (x: number, z: number, h: number, ny: number) => [number, number, number, number]-region: ((x0: number, z0: number, spacing: number, count: number) => { heights: Float32Array; paint?: Float32Array; } | Promise<{ heights: Float32Array; paint?: Float32Array; }>) | undefined+paint: (x: number, z: number, h: number, ny: number) => LayerWeights+region: ((x0: number, z0: number, spacing: number, count: number) => TerrainRegionSamples | Promise<TerrainRegionSamples>) | undefinedtouched: (x0: number, z0: number, x1: number, z1: number) => booleanstatic new (base: TerrainSource, modifiers: () => Iterable<TerrainModifier>, origin: { x: number; y: number; z: number; }, step: number): ModifiedSourcestatic prototype: ModifiedSource@@ -6086,6 +6106,15 @@ worlds: { scene: string; manifest: string; }[] | undefinedySortLayers: number | undefined```+## PackedLayers — interface @experimental+```+albedo: Uint8Array<ArrayBufferLike>[]+mask: Uint8Array<ArrayBufferLike>[]+normal: Uint8Array<ArrayBufferLike>[]+size: number+tiles: number[]+```+## Page — interface @experimental```max: number@@ -6099,6 +6128,7 @@ used: numberheights: Uint8Array<ArrayBufferLike>max: numbermin: number+paint2: Uint8Array<ArrayBufferLike>paint: Uint8Array<ArrayBufferLike>```@@ -10011,6 +10041,7 @@ layerColor0: ColorlayerColor1: ColorlayerColor2: ColorlayerColor3: Color+layers: string[]material: numberoctaves: numberpersistence: number@@ -10022,6 +10053,7 @@ seed: numbersizeX: numbersizeZ: numbersnowHeight: number+splatmap2: numbersplatmap: numberwarp: numberworld: string@@ -10032,6 +10064,27 @@ world: string{ readonly Area: 0; readonly Infinite: 1; }```+## TerrainLayerAssetLoader — class @experimental+```+extensions: string[]+load: (path: string, ctx: LoadContext) => Promise<TerrainLayerDef>+type: "terrain-layer"+unload: () => void+static new (): TerrainLayerAssetLoader+static prototype: TerrainLayerAssetLoader+```++## TerrainLayerDef — interface @experimental+```+albedo: string | undefined+mask: string | undefined+normal: string | undefined+normalStrength: number+roughness: number+tile: number+tint: [number, number, number]+```+## TerrainModifier — interface @experimental```apply: (x: number, z: number, h: number) => number@@ -10078,6 +10131,13 @@ x0: numberz0: number```+## TerrainRegionSamples — interface @experimental+```+heights: Float32Array<ArrayBufferLike>+paint2: Float32Array<ArrayBufferLike> | undefined+paint: Float32Array<ArrayBufferLike> | undefined+```+## TerrainSamples — interface @experimental```heights: Float32Array<ArrayBufferLike>@@ -10092,8 +10152,8 @@ infinite: booleanmaxHeight: numberminHeight: numbernormal: (x: number, z: number) => [number, number, number] | null-paint: (x: number, z: number, h: number, ny: number) => [number, number, number, number]-region: ((x0: number, z0: number, spacing: number, count: number) => { heights: Float32Array; paint?: Float32Array; } | Promise<{ heights: Float32Array; paint?: Float32Array; }>) | undefined+paint: (x: number, z: number, h: number, ny: number) => LayerWeights+region: ((x0: number, z0: number, spacing: number, count: number) => TerrainRegionSamples | Promise<TerrainRegionSamples>) | undefined```## TerrainStatus — interface @experimental@@ -12225,7 +12285,7 @@ group: (li: number, gx: number, gz: number) => Group | RejectiongroupsIn: (layer: string, x0: number, z0: number, x1: number, z1: number) => Group[]invalidate: () => voidlayerIndex: (id: string) => number-paint: (x: number, z: number, base: readonly [number, number, number, number]) => [number, number, number, number]+paint: (x: number, z: number, base: readonly number[]) => number[]placementsIn: (x0: number, z0: number, x1: number, z1: number, layers?: readonly string[]) => Placement[]rules: WorldRulesseed: number@@ -14490,6 +14550,11 @@ NodePlatformAdapter(semantics: { semantic: number; components: number; type: number; }[]): { channels: MeshChannelDesc[]; vertexStride: number; }```+## packLayers — function @experimental+```+(layers: readonly LayerSource[], maxSize?: number): PackedLayers+```+## packagedAppOptions — function @experimental```(config: Pick<PackagedGameConfig, "ySortLayers" | "depthLayers" | "colorSpace" | "outputTransform" | "screenFit" | "msaaSamples" | "quality">): { ySortLayers?: number; depthLayers?: number; colorSpace?: "gamma" | "linear"; outputTransform?: "none" | "aces" | "neutral"; msaaSamples?: number; quality?: QualityConfig; renderBackend?: "webgl2" | "webgpu"; screenFit?: PackagedGameConfig["screenFit"]; }@@ -14585,6 +14650,11 @@ NodePlatformAdapter(value: unknown): SoundEventAsset```+## parseTerrainLayer — function @experimental+```+(json: unknown, file?: string): TerrainLayerDef+```+## parseThemeOverrides — function @experimental```(colors?: Record<string, string>): ThemeOverrides | undefineddiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex a6f23b2a7..a805c06d7 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -1,7 +1,7 @@# API surface — esengine/minigame<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 115 public · 159 beta · 1855 experimental · 3 deprecated+Symbols: 115 public · 159 beta · 1864 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -1660,7 +1660,7 @@ min: number | undefined```conditions: readonly BiomeCondition[]id: string-paint: readonly [number, number, number, number] | undefined+paint: readonly number[] | undefinedpaintStrength: number | undefinedrecipes: readonly BiomeRecipe[]transition: number | undefined@@ -3634,7 +3634,7 @@ Step = 15```| 'texture' | 'material' | 'shader' | 'spine-atlas' | 'spine-skeleton'| 'dragonbones-atlas' | 'dragonbones-skeleton'- | 'bitmap-font' | 'font' | 'prefab' | 'json' | 'audio' | 'sound-event' | 'world-rules' | 'video' | 'scene' | 'anim-clip'+ | 'bitmap-font' | 'font' | 'prefab' | 'json' | 'audio' | 'sound-event' | 'world-rules' | 'terrain-layer' | 'video' | 'scene' | 'anim-clip'| 'tilemap' | 'tileset' | 'timeline' | 'mesh'| 'unknown'```@@ -4059,8 +4059,8 @@ infinite: falsemaxHeight: numberminHeight: numbernormal: (x: number, z: number) => [number, number, number] | null-paint: (x: number, z: number, h: number, ny: number) => [number, number, number, number]-static new (field: Heightfield, data: Pick<TerrainData, "sizeX" | "sizeZ" | "height" | "rockSlope" | "dirtHeight" | "snowHeight">, splat: Splat | null, flow: Float32Array | null, range?: readonly [number, number]): FieldSource+paint: (x: number, z: number, h: number, ny: number) => LayerWeights+static new (field: Heightfield, data: Pick<TerrainData, "sizeX" | "sizeZ" | "height" | "rockSlope" | "dirtHeight" | "snowHeight">, splat: Splat | null, flow: Float32Array | null, range?: readonly [number, number], splat2?: Splat | null): FieldSourcestatic prototype: FieldSource```@@ -5066,6 +5066,13 @@ Readonly<Vec3>ThemeTokens```+## LayerImage — interface @experimental+```+height: number+pixels: Uint8Array<ArrayBufferLike>+width: number+```+## LayerOrder — enum @experimental```Depth = 2@@ -5078,6 +5085,19 @@ YSort = 1admits: (track: PoseTrack) => boolean```+## LayerSource — interface @experimental+```+albedo: LayerImage | null+def: TerrainLayerDef+mask: LayerImage | null+normal: LayerImage | null+```++## LayerWeights — type @experimental+```+readonly number[]+```+## LayoutProvider — interface @experimental```getContentSize: (count: number) => Vec2@@ -6067,8 +6087,8 @@ maxHeight: numberminHeight: numbernormal: (x: number, z: number) => [number, number, number] | nullorigin: { x: number; y: number; z: number; }-paint: (x: number, z: number, h: number, ny: number) => [number, number, number, number]-region: ((x0: number, z0: number, spacing: number, count: number) => { heights: Float32Array; paint?: Float32Array; } | Promise<{ heights: Float32Array; paint?: Float32Array; }>) | undefined+paint: (x: number, z: number, h: number, ny: number) => LayerWeights+region: ((x0: number, z0: number, spacing: number, count: number) => TerrainRegionSamples | Promise<TerrainRegionSamples>) | undefinedtouched: (x0: number, z0: number, x1: number, z1: number) => booleanstatic new (base: TerrainSource, modifiers: () => Iterable<TerrainModifier>, origin: { x: number; y: number; z: number; }, step: number): ModifiedSourcestatic prototype: ModifiedSource@@ -6379,6 +6399,15 @@ worlds: { scene: string; manifest: string; }[] | undefinedySortLayers: number | undefined```+## PackedLayers — interface @experimental+```+albedo: Uint8Array<ArrayBufferLike>[]+mask: Uint8Array<ArrayBufferLike>[]+normal: Uint8Array<ArrayBufferLike>[]+size: number+tiles: number[]+```+## Page — interface @experimental```max: number@@ -6392,6 +6421,7 @@ used: numberheights: Uint8Array<ArrayBufferLike>max: numbermin: number+paint2: Uint8Array<ArrayBufferLike>paint: Uint8Array<ArrayBufferLike>```@@ -10304,6 +10334,7 @@ layerColor0: ColorlayerColor1: ColorlayerColor2: ColorlayerColor3: Color+layers: string[]material: numberoctaves: numberpersistence: number@@ -10315,6 +10346,7 @@ seed: numbersizeX: numbersizeZ: numbersnowHeight: number+splatmap2: numbersplatmap: numberwarp: numberworld: string@@ -10325,6 +10357,27 @@ world: string{ readonly Area: 0; readonly Infinite: 1; }```+## TerrainLayerAssetLoader — class @experimental+```+extensions: string[]+load: (path: string, ctx: LoadContext) => Promise<TerrainLayerDef>+type: "terrain-layer"+unload: () => void+static new (): TerrainLayerAssetLoader+static prototype: TerrainLayerAssetLoader+```++## TerrainLayerDef — interface @experimental+```+albedo: string | undefined+mask: string | undefined+normal: string | undefined+normalStrength: number+roughness: number+tile: number+tint: [number, number, number]+```+## TerrainModifier — interface @experimental```apply: (x: number, z: number, h: number) => number@@ -10371,6 +10424,13 @@ x0: numberz0: number```+## TerrainRegionSamples — interface @experimental+```+heights: Float32Array<ArrayBufferLike>+paint2: Float32Array<ArrayBufferLike> | undefined+paint: Float32Array<ArrayBufferLike> | undefined+```+## TerrainSamples — interface @experimental```heights: Float32Array<ArrayBufferLike>@@ -10385,8 +10445,8 @@ infinite: booleanmaxHeight: numberminHeight: numbernormal: (x: number, z: number) => [number, number, number] | null-paint: (x: number, z: number, h: number, ny: number) => [number, number, number, number]-region: ((x0: number, z0: number, spacing: number, count: number) => { heights: Float32Array; paint?: Float32Array; } | Promise<{ heights: Float32Array; paint?: Float32Array; }>) | undefined+paint: (x: number, z: number, h: number, ny: number) => LayerWeights+region: ((x0: number, z0: number, spacing: number, count: number) => TerrainRegionSamples | Promise<TerrainRegionSamples>) | undefined```## TerrainStatus — interface @experimental@@ -12524,7 +12584,7 @@ group: (li: number, gx: number, gz: number) => Group | RejectiongroupsIn: (layer: string, x0: number, z0: number, x1: number, z1: number) => Group[]invalidate: () => voidlayerIndex: (id: string) => number-paint: (x: number, z: number, base: readonly [number, number, number, number]) => [number, number, number, number]+paint: (x: number, z: number, base: readonly number[]) => number[]placementsIn: (x0: number, z0: number, x1: number, z1: number, layers?: readonly string[]) => Placement[]rules: WorldRulesseed: number@@ -14794,6 +14854,11 @@ MeshRendererPlugin(semantics: { semantic: number; components: number; type: number; }[]): { channels: MeshChannelDesc[]; vertexStride: number; }```+## packLayers — function @experimental+```+(layers: readonly LayerSource[], maxSize?: number): PackedLayers+```+## packagedAppOptions — function @experimental```(config: Pick<PackagedGameConfig, "ySortLayers" | "depthLayers" | "colorSpace" | "outputTransform" | "screenFit" | "msaaSamples" | "quality">): { ySortLayers?: number; depthLayers?: number; colorSpace?: "gamma" | "linear"; outputTransform?: "none" | "aces" | "neutral"; msaaSamples?: number; quality?: QualityConfig; renderBackend?: "webgl2" | "webgpu"; screenFit?: PackagedGameConfig["screenFit"]; }@@ -14889,6 +14954,11 @@ MeshRendererPlugin(value: unknown): SoundEventAsset```+## parseTerrainLayer — function @experimental+```+(json: unknown, file?: string): TerrainLayerDef+```+## parseThemeOverrides — function @experimental```(colors?: Record<string, string>): ThemeOverrides | undefineddiff --git a/sdk/etc/terrain.api.md b/sdk/etc/terrain.api.mdindex 3177624ba..6e46fd2d5 100644--- a/sdk/etc/terrain.api.md+++ b/sdk/etc/terrain.api.md@@ -1,7 +1,7 @@# API surface — esengine/terrain<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 0 public · 0 beta · 57 experimental · 0 deprecated+Symbols: 0 public · 0 beta · 66 experimental · 0 deprecated## Eroded — interface @experimental```@@ -27,8 +27,8 @@ infinite: falsemaxHeight: numberminHeight: numbernormal: (x: number, z: number) => [number, number, number] | null-paint: (x: number, z: number, h: number, ny: number) => [number, number, number, number]-static new (field: Heightfield, data: Pick<TerrainData, "sizeX" | "sizeZ" | "height" | "rockSlope" | "dirtHeight" | "snowHeight">, splat: Splat | null, flow: Float32Array | null, range?: readonly [number, number]): FieldSource+paint: (x: number, z: number, h: number, ny: number) => LayerWeights+static new (field: Heightfield, data: Pick<TerrainData, "sizeX" | "sizeZ" | "height" | "rockSlope" | "dirtHeight" | "snowHeight">, splat: Splat | null, flow: Float32Array | null, range?: readonly [number, number], splat2?: Splat | null): FieldSourcestatic prototype: FieldSource```@@ -44,6 +44,26 @@ width: number{ readonly Grey: 0; readonly RedGreen16: 1; }```+## LayerImage — interface @experimental+```+height: number+pixels: Uint8Array<ArrayBufferLike>+width: number+```++## LayerSource — interface @experimental+```+albedo: LayerImage | null+def: TerrainLayerDef+mask: LayerImage | null+normal: LayerImage | null+```++## LayerWeights — type @experimental+```+readonly number[]+```+## ModifiedSource — class @experimental```base: TerrainSource@@ -54,8 +74,8 @@ maxHeight: numberminHeight: numbernormal: (x: number, z: number) => [number, number, number] | nullorigin: { x: number; y: number; z: number; }-paint: (x: number, z: number, h: number, ny: number) => [number, number, number, number]-region: ((x0: number, z0: number, spacing: number, count: number) => { heights: Float32Array; paint?: Float32Array; } | Promise<{ heights: Float32Array; paint?: Float32Array; }>) | undefined+paint: (x: number, z: number, h: number, ny: number) => LayerWeights+region: ((x0: number, z0: number, spacing: number, count: number) => TerrainRegionSamples | Promise<TerrainRegionSamples>) | undefinedtouched: (x0: number, z0: number, x1: number, z1: number) => booleanstatic new (base: TerrainSource, modifiers: () => Iterable<TerrainModifier>, origin: { x: number; y: number; z: number; }, step: number): ModifiedSourcestatic prototype: ModifiedSource@@ -101,6 +121,15 @@ number32```+## PackedLayers — interface @experimental+```+albedo: Uint8Array<ArrayBufferLike>[]+mask: Uint8Array<ArrayBufferLike>[]+normal: Uint8Array<ArrayBufferLike>[]+size: number+tiles: number[]+```+## Page — interface @experimental```max: number@@ -114,6 +143,7 @@ used: numberheights: Uint8Array<ArrayBufferLike>max: numbermin: number+paint2: Uint8Array<ArrayBufferLike>paint: Uint8Array<ArrayBufferLike>```@@ -228,6 +258,7 @@ layerColor0: ColorlayerColor1: ColorlayerColor2: ColorlayerColor3: Color+layers: string[]material: numberoctaves: numberpersistence: number@@ -239,6 +270,7 @@ seed: numbersizeX: numbersizeZ: numbersnowHeight: number+splatmap2: numbersplatmap: numberwarp: numberworld: string@@ -249,6 +281,27 @@ world: string{ readonly Area: 0; readonly Infinite: 1; }```+## TerrainLayerAssetLoader — class @experimental+```+extensions: string[]+load: (path: string, ctx: LoadContext) => Promise<TerrainLayerDef>+type: "terrain-layer"+unload: () => void+static new (): TerrainLayerAssetLoader+static prototype: TerrainLayerAssetLoader+```++## TerrainLayerDef — interface @experimental+```+albedo: string | undefined+mask: string | undefined+normal: string | undefined+normalStrength: number+roughness: number+tile: number+tint: [number, number, number]+```+## TerrainModifier — interface @experimental```apply: (x: number, z: number, h: number) => number@@ -295,6 +348,13 @@ x0: numberz0: number```+## TerrainRegionSamples — interface @experimental+```+heights: Float32Array<ArrayBufferLike>+paint2: Float32Array<ArrayBufferLike> | undefined+paint: Float32Array<ArrayBufferLike> | undefined+```+## TerrainSamples — interface @experimental```heights: Float32Array<ArrayBufferLike>@@ -309,8 +369,8 @@ infinite: booleanmaxHeight: numberminHeight: numbernormal: (x: number, z: number) => [number, number, number] | null-paint: (x: number, z: number, h: number, ny: number) => [number, number, number, number]-region: ((x0: number, z0: number, spacing: number, count: number) => { heights: Float32Array; paint?: Float32Array; } | Promise<{ heights: Float32Array; paint?: Float32Array; }>) | undefined+paint: (x: number, z: number, h: number, ny: number) => LayerWeights+region: ((x0: number, z0: number, spacing: number, count: number) => TerrainRegionSamples | Promise<TerrainRegionSamples>) | undefined```## TerrainStatus — interface @experimental@@ -416,6 +476,11 @@ ResourceDef<Terrains>(x: number, y: number, seed: number): [number, number, number]```+## packLayers — function @experimental+```+(layers: readonly LayerSource[], maxSize?: number): PackedLayers+```+## paintWeights — function @experimental```(h: number, ny: number, t: Pick<TerrainData, "rockSlope" | "dirtHeight" | "snowHeight">): [number, number, number, number]@@ -426,6 +491,11 @@ ResourceDef<Terrains>(n: TerrainNode, leafSize: number): TerrainNode```+## parseTerrainLayer — function @experimental+```+(json: unknown, file?: string): TerrainLayerDef+```+## proceduralHeightfield — function @experimental```(p: ProceduralParams): Heightfielddiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 1a074e8ce..97c0a929b 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -1,7 +1,7 @@# API surface — esengine/wechat<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 115 public · 159 beta · 1846 experimental · 3 deprecated+Symbols: 115 public · 159 beta · 1855 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -1660,7 +1660,7 @@ min: number | undefined```conditions: readonly BiomeCondition[]id: string-paint: readonly [number, number, number, number] | undefined+paint: readonly number[] | undefinedpaintStrength: number | undefinedrecipes: readonly BiomeRecipe[]transition: number | undefined@@ -3634,7 +3634,7 @@ Step = 15```| 'texture' | 'material' | 'shader' | 'spine-atlas' | 'spine-skeleton'| 'dragonbones-atlas' | 'dragonbones-skeleton'- | 'bitmap-font' | 'font' | 'prefab' | 'json' | 'audio' | 'sound-event' | 'world-rules' | 'video' | 'scene' | 'anim-clip'+ | 'bitmap-font' | 'font' | 'prefab' | 'json' | 'audio' | 'sound-event' | 'world-rules' | 'terrain-layer' | 'video' | 'scene' | 'anim-clip'| 'tilemap' | 'tileset' | 'timeline' | 'mesh'| 'unknown'```@@ -4059,8 +4059,8 @@ infinite: falsemaxHeight: numberminHeight: numbernormal: (x: number, z: number) => [number, number, number] | null-paint: (x: number, z: number, h: number, ny: number) => [number, number, number, number]-static new (field: Heightfield, data: Pick<TerrainData, "sizeX" | "sizeZ" | "height" | "rockSlope" | "dirtHeight" | "snowHeight">, splat: Splat | null, flow: Float32Array | null, range?: readonly [number, number]): FieldSource+paint: (x: number, z: number, h: number, ny: number) => LayerWeights+static new (field: Heightfield, data: Pick<TerrainData, "sizeX" | "sizeZ" | "height" | "rockSlope" | "dirtHeight" | "snowHeight">, splat: Splat | null, flow: Float32Array | null, range?: readonly [number, number], splat2?: Splat | null): FieldSourcestatic prototype: FieldSource```@@ -5073,6 +5073,13 @@ Readonly<Vec3>ThemeTokens```+## LayerImage — interface @experimental+```+height: number+pixels: Uint8Array<ArrayBufferLike>+width: number+```+## LayerOrder — enum @experimental```Depth = 2@@ -5085,6 +5092,19 @@ YSort = 1admits: (track: PoseTrack) => boolean```+## LayerSource — interface @experimental+```+albedo: LayerImage | null+def: TerrainLayerDef+mask: LayerImage | null+normal: LayerImage | null+```++## LayerWeights — type @experimental+```+readonly number[]+```+## LayoutProvider — interface @experimental```getContentSize: (count: number) => Vec2@@ -5781,8 +5801,8 @@ maxHeight: numberminHeight: numbernormal: (x: number, z: number) => [number, number, number] | nullorigin: { x: number; y: number; z: number; }-paint: (x: number, z: number, h: number, ny: number) => [number, number, number, number]-region: ((x0: number, z0: number, spacing: number, count: number) => { heights: Float32Array; paint?: Float32Array; } | Promise<{ heights: Float32Array; paint?: Float32Array; }>) | undefined+paint: (x: number, z: number, h: number, ny: number) => LayerWeights+region: ((x0: number, z0: number, spacing: number, count: number) => TerrainRegionSamples | Promise<TerrainRegionSamples>) | undefinedtouched: (x0: number, z0: number, x1: number, z1: number) => booleanstatic new (base: TerrainSource, modifiers: () => Iterable<TerrainModifier>, origin: { x: number; y: number; z: number; }, step: number): ModifiedSourcestatic prototype: ModifiedSource@@ -6093,6 +6113,15 @@ worlds: { scene: string; manifest: string; }[] | undefinedySortLayers: number | undefined```+## PackedLayers — interface @experimental+```+albedo: Uint8Array<ArrayBufferLike>[]+mask: Uint8Array<ArrayBufferLike>[]+normal: Uint8Array<ArrayBufferLike>[]+size: number+tiles: number[]+```+## Page — interface @experimental```max: number@@ -6106,6 +6135,7 @@ used: numberheights: Uint8Array<ArrayBufferLike>max: numbermin: number+paint2: Uint8Array<ArrayBufferLike>paint: Uint8Array<ArrayBufferLike>```@@ -10018,6 +10048,7 @@ layerColor0: ColorlayerColor1: ColorlayerColor2: ColorlayerColor3: Color+layers: string[]material: numberoctaves: numberpersistence: number@@ -10029,6 +10060,7 @@ seed: numbersizeX: numbersizeZ: numbersnowHeight: number+splatmap2: numbersplatmap: numberwarp: numberworld: string@@ -10039,6 +10071,27 @@ world: string{ readonly Area: 0; readonly Infinite: 1; }```+## TerrainLayerAssetLoader — class @experimental+```+extensions: string[]+load: (path: string, ctx: LoadContext) => Promise<TerrainLayerDef>+type: "terrain-layer"+unload: () => void+static new (): TerrainLayerAssetLoader+static prototype: TerrainLayerAssetLoader+```++## TerrainLayerDef — interface @experimental+```+albedo: string | undefined+mask: string | undefined+normal: string | undefined+normalStrength: number+roughness: number+tile: number+tint: [number, number, number]+```+## TerrainModifier — interface @experimental```apply: (x: number, z: number, h: number) => number@@ -10085,6 +10138,13 @@ x0: numberz0: number```+## TerrainRegionSamples — interface @experimental+```+heights: Float32Array<ArrayBufferLike>+paint2: Float32Array<ArrayBufferLike> | undefined+paint: Float32Array<ArrayBufferLike> | undefined+```+## TerrainSamples — interface @experimental```heights: Float32Array<ArrayBufferLike>@@ -10099,8 +10159,8 @@ infinite: booleanmaxHeight: numberminHeight: numbernormal: (x: number, z: number) => [number, number, number] | null-paint: (x: number, z: number, h: number, ny: number) => [number, number, number, number]-region: ((x0: number, z0: number, spacing: number, count: number) => { heights: Float32Array; paint?: Float32Array; } | Promise<{ heights: Float32Array; paint?: Float32Array; }>) | undefined+paint: (x: number, z: number, h: number, ny: number) => LayerWeights+region: ((x0: number, z0: number, spacing: number, count: number) => TerrainRegionSamples | Promise<TerrainRegionSamples>) | undefined```## TerrainStatus — interface @experimental@@ -12256,7 +12316,7 @@ group: (li: number, gx: number, gz: number) => Group | RejectiongroupsIn: (layer: string, x0: number, z0: number, x1: number, z1: number) => Group[]invalidate: () => voidlayerIndex: (id: string) => number-paint: (x: number, z: number, base: readonly [number, number, number, number]) => [number, number, number, number]+paint: (x: number, z: number, base: readonly number[]) => number[]placementsIn: (x0: number, z0: number, x1: number, z1: number, layers?: readonly string[]) => Placement[]rules: WorldRulesseed: number@@ -14521,6 +14581,11 @@ MeshRendererPlugin(semantics: { semantic: number; components: number; type: number; }[]): { channels: MeshChannelDesc[]; vertexStride: number; }```+## packLayers — function @experimental+```+(layers: readonly LayerSource[], maxSize?: number): PackedLayers+```+## packagedAppOptions — function @experimental```(config: Pick<PackagedGameConfig, "ySortLayers" | "depthLayers" | "colorSpace" | "outputTransform" | "screenFit" | "msaaSamples" | "quality">): { ySortLayers?: number; depthLayers?: number; colorSpace?: "gamma" | "linear"; outputTransform?: "none" | "aces" | "neutral"; msaaSamples?: number; quality?: QualityConfig; renderBackend?: "webgl2" | "webgpu"; screenFit?: PackagedGameConfig["screenFit"]; }@@ -14616,6 +14681,11 @@ MeshRendererPlugin(value: unknown): SoundEventAsset```+## parseTerrainLayer — function @experimental+```+(json: unknown, file?: string): TerrainLayerDef+```+## parseThemeOverrides — function @experimental```(colors?: Record<string, string>): ThemeOverrides | undefineddiff --git a/sdk/etc/worldgen.api.md b/sdk/etc/worldgen.api.mdindex bfdec4bb6..470e522d3 100644--- a/sdk/etc/worldgen.api.md+++ b/sdk/etc/worldgen.api.md@@ -15,7 +15,7 @@ min: number | undefined```conditions: readonly BiomeCondition[]id: string-paint: readonly [number, number, number, number] | undefined+paint: readonly number[] | undefinedpaintStrength: number | undefinedrecipes: readonly BiomeRecipe[]transition: number | undefined@@ -247,7 +247,7 @@ group: (li: number, gx: number, gz: number) => Group | RejectiongroupsIn: (layer: string, x0: number, z0: number, x1: number, z1: number) => Group[]invalidate: () => voidlayerIndex: (id: string) => number-paint: (x: number, z: number, base: readonly [number, number, number, number]) => [number, number, number, number]+paint: (x: number, z: number, base: readonly number[]) => number[]placementsIn: (x0: number, z0: number, x1: number, z1: number, layers?: readonly string[]) => Placement[]rules: WorldRulesseed: numberdiff --git a/sdk/src/assetTypes.ts b/sdk/src/assetTypes.tsindex bd8e7cd22..3334e7b78 100644--- a/sdk/src/assetTypes.ts+++ b/sdk/src/assetTypes.ts@@ -9,7 +9,7 @@ export type AddressableAssetType =export type EditorAssetType =| 'texture' | 'material' | 'shader' | 'spine-atlas' | 'spine-skeleton'| 'dragonbones-atlas' | 'dragonbones-skeleton'- | 'bitmap-font' | 'font' | 'prefab' | 'json' | 'audio' | 'sound-event' | 'world-rules' | 'video' | 'scene' | 'anim-clip'+ | 'bitmap-font' | 'font' | 'prefab' | 'json' | 'audio' | 'sound-event' | 'world-rules' | 'terrain-layer' | 'video' | 'scene' | 'anim-clip'| 'tilemap' | 'tileset' | 'timeline' | 'mesh'| 'unknown';@@ -80,6 +80,8 @@ const ASSET_TYPE_REGISTRY: readonly AssetTypeEntry[] = [{ extensions: ['esaudioevent'], contentType: 'json', editorType: 'sound-event', addressableType: 'json', wechatPackInclude: true, hasTransitiveDeps: true },// World rules (WorldRulesAssetLoader): biomes, recipes and layers as data, naming the meshes and materials they place by path.{ extensions: ['esworld'], contentType: 'json', editorType: 'world-rules', addressableType: 'json', wechatPackInclude: true, hasTransitiveDeps: true },+ // Terrain layers (TerrainLayerAssetLoader): one kind of ground, naming the albedo, normal and mask textures it is drawn with.+ { extensions: ['esterrainlayer'], contentType: 'json', editorType: 'terrain-layer', addressableType: 'json', wechatPackInclude: true, hasTransitiveDeps: true },// Locale string table (LocaleAssetLoader → Localization.addCatalog) — one locale per file.{ extensions: ['eslocale'], contentType: 'json', editorType: 'json', addressableType: 'json', wechatPackInclude: true, hasTransitiveDeps: false },// State machine (registerFsm / FsmAssetLoader) — data-driven FSM definition.diff --git a/sdk/src/core-content.ts b/sdk/src/core-content.tsindex 504b8c0f6..29e09cc8d 100644--- a/sdk/src/core-content.ts+++ b/sdk/src/core-content.ts@@ -834,7 +834,8 @@ export {erodeHeightfield, erosionJob, heightfieldFromPixels, HeightmapFormat, proceduralHeightfield, sampleHeight, terrainNormal,type Eroded, type ErosionParams, type Heightfield, type ProceduralParams,} from './terrain/heightfield';-export { FieldSource, NoiseSource, ModifiedSource, flattenModifier, noised, type NoiseParams, type Splat, type TerrainSource, type TerrainModifier } from './terrain/source';+export { FieldSource, NoiseSource, ModifiedSource, flattenModifier, noised, type LayerWeights, type NoiseParams, type Splat, type TerrainRegionSamples, type TerrainSource, type TerrainModifier } from './terrain/source';+export { packLayers, parseTerrainLayer, TerrainLayerAssetLoader, type LayerImage, type LayerSource, type PackedLayers, type TerrainLayerDef } from './terrain/layers';export { boxDistance, levelRange, nodeKey, parentOf, selectNodes, type QuadtreeParams, type TerrainNode } from './terrain/quadtree';export { makePage, PageTable, PAGE_SIDE, PAGE_TEXELS, PATCH_CELLS, type Page, type PageImage } from './terrain/pages';export { buildPatchMesh } from './terrain/patch';diff --git a/sdk/src/terrain/index.ts b/sdk/src/terrain/index.tsindex 3950447c7..ff29b00a9 100644--- a/sdk/src/terrain/index.ts+++ b/sdk/src/terrain/index.ts@@ -7,10 +7,11 @@ export {erodeHeightfield, erosionJob, heightfieldFromPixels, HeightmapFormat, proceduralHeightfield, sampleHeight, terrainNormal,type Eroded, type ErosionParams, type Heightfield, type ProceduralParams,} from './heightfield';-export { FieldSource, NoiseSource, ModifiedSource, flattenModifier, noised, type NoiseParams, type Splat, type TerrainSource, type TerrainModifier } from './source';+export { FieldSource, NoiseSource, ModifiedSource, flattenModifier, noised, type LayerWeights, type NoiseParams, type Splat, type TerrainRegionSamples, type TerrainSource, type TerrainModifier } from './source';export { boxDistance, levelRange, nodeKey, parentOf, selectNodes, type QuadtreeParams, type TerrainNode } from './quadtree';export { makePage, PageTable, PAGE_SIDE, PAGE_TEXELS, PATCH_CELLS, type Page, type PageImage } from './pages';export { buildPatchMesh } from './patch';+export { packLayers, parseTerrainLayer, TerrainLayerAssetLoader, type LayerImage, type LayerSource, type PackedLayers, type TerrainLayerDef } from './layers';export { findGroundPath, type ReachGround, type ReachOptions, type ReachResult } from './reach';export {noiseProvider, ProviderSource, registerTerrainProvider, terrainProvider, TerrainUnavailable,diff --git a/sdk/src/terrain/layers.ts b/sdk/src/terrain/layers.tsnew file mode 100644index 000000000..d71148269--- /dev/null+++ b/sdk/src/terrain/layers.ts@@ -0,0 +1,155 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file layers.ts+ * @brief A terrain layer (`.esterrainlayer`): one kind of ground (grass, a path's dirt, sand, rock) as the textures an artist made for it,+ * and how they are laid; and the layers of a terrain packed into the texture arrays its shader reads.+ *+ * @details A layer names up to three textures, read as data and laid by world position:+ * - albedo: the colour (sRGB);+ * - normal: a tangent-space normal map, green up (the OpenGL convention);+ * - mask: red the ambient occlusion, green the roughness, blue the height (where two layers meet, the higher shows).+ * A texture a layer leaves out is made up: white albedo, a flat normal, and a mask of no occlusion, the layer's `roughness` and+ * half height. The layers are packed at one size (the largest of their textures, to a power of two within `maxSize`), the tint+ * multiplied into the albedo and the normal's strength into its slope, so the shader reads three arrays and nothing per layer+ * but its tile.+ */+import type { AssetLoader, LoadContext } from '../asset/AssetLoader';++/** One kind of ground, as a `.esterrainlayer` file holds it. @experimental */+export interface TerrainLayerDef {+ /** Project paths of the textures (see the file's notes); an empty or missing one is made up. */+ albedo?: string;+ normal?: string;+ mask?: string;+ /** How many world units one repeat of the textures covers. */+ tile: number;+ /** Multiplies the albedo, 0 to 1 a channel. */+ tint: [number, number, number];+ /** The roughness where there is no mask, 0 to 1. */+ roughness: number;+ /** How strongly the normal map bends the light: 1 as drawn, 0 flat. */+ normalStrength: number;+}++const DEFAULTS: TerrainLayerDef = { tile: 4, tint: [1, 1, 1], roughness: 0.9, normalStrength: 1 };++/** A layer from a file's JSON, with what it leaves out at its defaults; throws naming the first field it cannot take. */+export function parseTerrainLayer(json: unknown, file = 'terrain layer'): TerrainLayerDef {+ if (!json || typeof json !== 'object') throw new Error(`${file}: an object`);+ const o = json as Record<string, unknown>;+ const num = (key: string, fallback: number, min: number, max: number): number => {+ const v = o[key];+ if (v === undefined) return fallback;+ if (typeof v !== 'number' || !Number.isFinite(v) || v < min || v > max) throw new Error(`${file}.${key}: a number from ${min} to ${max}, not ${JSON.stringify(v)}`);+ return v;+ };+ const path = (key: string): string | undefined => {+ const v = o[key];+ if (v === undefined || v === '') return undefined;+ if (typeof v !== 'string') throw new Error(`${file}.${key}: a texture path, not ${JSON.stringify(v)}`);+ return v;+ };+ const tint = o.tint === undefined ? DEFAULTS.tint : o.tint;+ if (!Array.isArray(tint) || tint.length !== 3 || tint.some((c) => typeof c !== 'number' || !Number.isFinite(c)))+ throw new Error(`${file}.tint: three numbers, red, green and blue`);+ return {+ albedo: path('albedo'), normal: path('normal'), mask: path('mask'),+ tile: num('tile', DEFAULTS.tile, 1e-3, 1e6),+ tint: tint as [number, number, number],+ roughness: num('roughness', DEFAULTS.roughness, 0, 1),+ normalStrength: num('normalStrength', DEFAULTS.normalStrength, 0, 4),+ };+}++/** Loads `.esterrainlayer` files as checked layers. @experimental */+export class TerrainLayerAssetLoader implements AssetLoader<TerrainLayerDef> {+ readonly type = 'terrain-layer';+ readonly extensions = ['.esterrainlayer'];++ async load(path: string, ctx: LoadContext): Promise<TerrainLayerDef> {+ const text = await ctx.loadText(ctx.catalog.getBuildPath(path));+ return parseTerrainLayer(JSON.parse(text), path);+ }++ unload(): void {+ // A layer is plain data; the arrays made from it belong to the terrain that packed them.+ }+}++/** An image read as data: RGBA, top row first. */+export interface LayerImage { width: number; height: number; pixels: Uint8Array }++/** A layer with its textures read (null where it has none). */+export interface LayerSource { def: TerrainLayerDef; albedo: LayerImage | null; normal: LayerImage | null; mask: LayerImage | null }++/** The layers packed: one image a layer in each of the three arrays, all `size` by `size`. */+export interface PackedLayers { size: number; albedo: Uint8Array[]; normal: Uint8Array[]; mask: Uint8Array[]; tiles: number[] }++/** `image` resampled (bilinear, wrapping, as the layer tiles) to `size` by `size`. */+function resample(image: LayerImage, size: number): Uint8Array {+ if (image.width === size && image.height === size) return image.pixels;+ const out = new Uint8Array(size * size * 4);+ const { width: w, height: h, pixels: p } = image;+ for (let y = 0; y < size; y++) {+ const fy = ((y + 0.5) / size) * h - 0.5, y0 = Math.floor(fy), ty = fy - y0;+ const ya = ((y0 % h) + h) % h, yb = (ya + 1) % h;+ for (let x = 0; x < size; x++) {+ const fx = ((x + 0.5) / size) * w - 0.5, x0 = Math.floor(fx), tx = fx - x0;+ const xa = ((x0 % w) + w) % w, xb = (xa + 1) % w;+ for (let c = 0; c < 4; c++) {+ const a = p[(ya * w + xa) * 4 + c]!, b = p[(ya * w + xb) * 4 + c]!, d = p[(yb * w + xa) * 4 + c]!, e = p[(yb * w + xb) * 4 + c]!;+ out[(y * size + x) * 4 + c] = Math.round((a + (b - a) * tx) * (1 - ty) + (d + (e - d) * tx) * ty);+ }+ }+ }+ return out;+}++/** Packs `layers` into the three arrays, at the size of their largest texture to a power of two no larger than `maxSize`. */+export function packLayers(layers: readonly LayerSource[], maxSize = 1024): PackedLayers {+ let largest = 16;+ for (const l of layers) for (const img of [l.albedo, l.normal, l.mask]) if (img) largest = Math.max(largest, img.width, img.height);+ const size = Math.min(2 ** Math.ceil(Math.log2(largest)), Math.max(maxSize, 16));+ const n = size * size;+ const albedo: Uint8Array[] = [], normal: Uint8Array[] = [], mask: Uint8Array[] = [];+ for (const { def, albedo: a, normal: nm, mask: m } of layers) {+ const colour = a ? new Uint8Array(resample(a, size)) : new Uint8Array(n * 4).fill(255);+ // The tint is in linear light; the albedo bytes are sRGB, so it multiplies them through its own sRGB encoding.+ const tint = def.tint.map((c) => Math.pow(Math.min(Math.max(c, 0), 1), 1 / 2.2));+ for (let k = 0; k < n; k++) {+ for (let c = 0; c < 3; c++) colour[k * 4 + c] = Math.round(colour[k * 4 + c]! * tint[c]!);+ colour[k * 4 + 3] = 255;+ }+ albedo.push(colour);+ const bend = new Uint8Array(n * 4);+ const src = nm ? resample(nm, size) : null;+ for (let k = 0; k < n; k++) {+ // The slope scaled by the strength, the normal made whole again.+ const x = src ? (src[k * 4]! / 255 * 2 - 1) * def.normalStrength : 0;+ const y = src ? (src[k * 4 + 1]! / 255 * 2 - 1) * def.normalStrength : 0;+ const z = Math.sqrt(Math.max(1 - Math.min(x * x + y * y, 1), 0));+ const len = Math.hypot(x, y, z) || 1;+ bend[k * 4] = Math.round((x / len * 0.5 + 0.5) * 255);+ bend[k * 4 + 1] = Math.round((y / len * 0.5 + 0.5) * 255);+ bend[k * 4 + 2] = Math.round((z / len * 0.5 + 0.5) * 255);+ bend[k * 4 + 3] = 255;+ }+ normal.push(bend);+ if (m) {+ mask.push(new Uint8Array(resample(m, size)));+ } else {+ // Without a mask the layer stands as high as its colour is bright, as a ground of stones between sand does.+ const made = new Uint8Array(n * 4);+ const rough = Math.round(def.roughness * 255);+ for (let k = 0; k < n; k++) {+ made[k * 4] = 255;+ made[k * 4 + 1] = rough;+ made[k * 4 + 2] = a ? Math.round(colour[k * 4]! * 0.299 + colour[k * 4 + 1]! * 0.587 + colour[k * 4 + 2]! * 0.114) : 128;+ made[k * 4 + 3] = 255;+ }+ mask.push(made);+ }+ }+ return { size, albedo, normal, mask, tiles: layers.map((l) => l.def.tile) };+}diff --git a/sdk/src/terrain/pages.ts b/sdk/src/terrain/pages.tsindex 363648b8a..9061e2ecc 100644--- a/sdk/src/terrain/pages.ts+++ b/sdk/src/terrain/pages.ts@@ -5,14 +5,14 @@* @brief The ground's height, slope and paint in pages: one per quadtree node, made from the source and kept in two atlas textures.** @details A page is a node's square sampled `PAGE_TEXELS` times along each side (two samples to a cell of its patch), with one sample- * more past each edge so the slope at the edge is known and a filtered read there stays inside the page. Its two images:+ * more past each edge so the slope at the edge is known and a filtered read there stays inside the page. Its three images:* - heights: red and green the height over the source's range, high byte then low (read texel by texel and blended in the* shader, as a filtered pair of bytes is no number); blue and alpha the normal's x and z (filtered);- * - paint: the weights of the four layers (filtered).+ * - paint and paint2: the weights of layers 1 to 4 and 5 to 8 (filtered).* Pages are made as the tree asks for them, coarse ones first, within a time budget a frame, and the least recently drawn give* their slot up when the atlas is full. A node whose page is not made yet is drawn by an ancestor's.*/-import type { TerrainSource } from './source';+import type { LayerWeights, TerrainRegionSamples, TerrainSource } from './source';/** Cells along a patch's side, and samples along a page's (two to a cell). */export const PATCH_CELLS = 32;@@ -31,7 +31,7 @@ export interface Page {}/** The pixels of one page. */-export interface PageImage { heights: Uint8Array; paint: Uint8Array; min: number; max: number }+export interface PageImage { heights: Uint8Array; paint: Uint8Array; paint2: Uint8Array; min: number; max: number }/*** Samples a node's page from `source`: square (x0, z0) to (x0 + size, z0 + size) in the terrain's space. Heights are encoded over@@ -43,8 +43,8 @@ export function makePage(source: TerrainSource, x0: number, z0: number, size: nuconst n = PAGE_SIDE, step = size / PAGE_TEXELS;if (source.region) {const got = source.region(x0 - step, z0 - step, step, n);- return got instanceof Promise ? got.then((r) => encodePage(source, x0, z0, step, r.heights, r.paint, repaint))- : encodePage(source, x0, z0, step, got.heights, got.paint, repaint);+ return got instanceof Promise ? got.then((r) => encodePage(source, x0, z0, step, r.heights, r, repaint))+ : encodePage(source, x0, z0, step, got.heights, got, repaint);}const h = new Float32Array(n * n);const [bx0, bz0, bx1, bz1] = source.bounds ?? [-Infinity, -Infinity, Infinity, Infinity];@@ -56,16 +56,16 @@ export function makePage(source: TerrainSource, x0: number, z0: number, size: nu}/** The paint of a sample at (x, z) in the terrain's space, `h` high and facing `ny` up, from what it would otherwise be. */-export type Repaint = (x: number, z: number, h: number, ny: number, w: [number, number, number, number]) => [number, number, number, number];+export type Repaint = (x: number, z: number, h: number, ny: number, w: LayerWeights) => LayerWeights;/** Encodes a page's samples (row by row, one past each edge): heights and normals into one image, the paint into the other. */-function encodePage(source: TerrainSource, x0: number, z0: number, step: number, h: Float32Array, given?: Float32Array, repaint?: Repaint): PageImage {+function encodePage(source: TerrainSource, x0: number, z0: number, step: number, h: Float32Array, given?: TerrainRegionSamples, repaint?: Repaint): PageImage {const n = PAGE_SIDE;const [bx0, bz0, bx1, bz1] = source.bounds ?? [-Infinity, -Infinity, Infinity, Infinity];let min = Infinity, max = -Infinity;for (let j = 1; j <= n - 2; j++) for (let i = 1; i <= n - 2; i++) { const v = h[j * n + i]!; min = Math.min(min, v); max = Math.max(max, v); }const span = Math.max(source.maxHeight - source.minHeight, 1e-6);- const heights = new Uint8Array(n * n * 4), paint = new Uint8Array(n * n * 4);+ const heights = new Uint8Array(n * n * 4), paint = new Uint8Array(n * n * 4), paint2 = new Uint8Array(n * n * 4);for (let j = 0; j < n; j++) for (let i = 0; i < n; i++) {const k = j * n + i;const enc = Math.round(Math.min(Math.max((h[k]! - source.minHeight) / span, 0), 1) * 65535);@@ -79,11 +79,17 @@ function encodePage(source: TerrainSource, x0: number, z0: number, step: number,heights[k * 4 + 2] = Math.round((nx * 0.5 + 0.5) * 255);heights[k * 4 + 3] = Math.round((nz * 0.5 + 0.5) * 255);const x = Math.min(Math.max(x0 + (i - 1) * step, bx0), bx1), z = Math.min(Math.max(z0 + (j - 1) * step, bz0), bz1);- let w: [number, number, number, number] = given ? [given[k * 4]!, given[k * 4 + 1]!, given[k * 4 + 2]!, given[k * 4 + 3]!] : source.paint(x, z, h[k]!, ny);+ const p1 = given?.paint, p2 = given?.paint2;+ let w: LayerWeights = p1+ ? [p1[k * 4]!, p1[k * 4 + 1]!, p1[k * 4 + 2]!, p1[k * 4 + 3]!, ...(p2 ? [p2[k * 4]!, p2[k * 4 + 1]!, p2[k * 4 + 2]!, p2[k * 4 + 3]!] : [])]+ : source.paint(x, z, h[k]!, ny);if (repaint) w = repaint(x, z, h[k]!, ny, w);- for (let c = 0; c < 4; c++) paint[k * 4 + c] = Math.round(Math.min(Math.max(w[c]!, 0), 1) * 255);+ for (let c = 0; c < 4; c++) {+ paint[k * 4 + c] = Math.round(Math.min(Math.max(w[c] ?? 0, 0), 1) * 255);+ paint2[k * 4 + c] = Math.round(Math.min(Math.max(w[c + 4] ?? 0, 0), 1) * 255);+ }}- return { heights, paint, min: Number.isFinite(min) ? min : source.minHeight, max: Number.isFinite(max) ? max : source.maxHeight };+ return { heights, paint, paint2, min: Number.isFinite(min) ? min : source.minHeight, max: Number.isFinite(max) ? max : source.maxHeight };}/** Where the pages live: slots in a square atlas, given out and taken back by key. */diff --git a/sdk/src/terrain/source.ts b/sdk/src/terrain/source.tsindex afc9d8f40..fc6b2f685 100644--- a/sdk/src/terrain/source.ts+++ b/sdk/src/terrain/source.ts@@ -29,15 +29,21 @@ export interface TerrainSource {height(x: number, z: number): number | null;/** The ground's unit normal at (x, z), or null where the height is not known. */normal(x: number, z: number): [number, number, number] | null;- /** The weights of the four layers (grass, dirt, snow, rock) at (x, z), where the ground there is `h` high and faces `ny` up. */- paint(x: number, z: number, h: number, ny: number): [number, number, number, number];+ /** The weights of the layers (up to eight; the first four by default grass, dirt, snow, rock) at (x, z), where the ground there is `h` high and faces `ny` up. */+ paint(x: number, z: number, h: number, ny: number): LayerWeights;/*** The ground over a grid of `count` by `count` samples `spacing` apart from (x0, z0), when the source samples whole regions (a* provider, which may answer later); without it the pages read `height` and `paint` point by point.*/- region?(x0: number, z0: number, spacing: number, count: number): { heights: Float32Array; paint?: Float32Array } | Promise<{ heights: Float32Array; paint?: Float32Array }>;+ region?(x0: number, z0: number, spacing: number, count: number): TerrainRegionSamples | Promise<TerrainRegionSamples>;}+/** A region's samples: heights, and the weights of layers 1 to 4 (`paint`) and 5 to 8 (`paint2`), four a sample. */+export interface TerrainRegionSamples { heights: Float32Array; paint?: Float32Array; paint2?: Float32Array }++/** The weights of a terrain's layers at a point, in order: four or eight of them (a missing one weighs nothing). */+export type LayerWeights = readonly number[];+/** The pixels of a splatmap, as the terrain read them. */export interface Splat { width: number; height: number; pixels: Uint8Array }@@ -57,6 +63,7 @@ export class FieldSource implements TerrainSource {private readonly splat: Splat | null,private readonly flow: Float32Array | null,range: readonly [number, number] = [0, data.height],+ private readonly splat2: Splat | null = null,) {this.bounds = [-data.sizeX / 2, -data.sizeZ / 2, data.sizeX / 2, data.sizeZ / 2];[this.minHeight, this.maxHeight] = range;@@ -79,22 +86,27 @@ export class FieldSource implements TerrainSource {return terrainNormal(this.field, u, v, this.data.sizeX, this.data.sizeZ, this.span);}- paint(x: number, z: number, h: number, ny: number): [number, number, number, number] {+ paint(x: number, z: number, h: number, ny: number): LayerWeights {const u = Math.min(Math.max(x / this.data.sizeX + 0.5, 0), 1), v = Math.min(Math.max(z / this.data.sizeZ + 0.5, 0), 1);- let w = paintWeights((h - this.minHeight) / this.span, ny, this.data);- const splat = this.splat;- if (splat) {+ let w: number[] = [...paintWeights((h - this.minHeight) / this.span, ny, this.data)];+ // The splatmaps, where they say anything, say all of it: layers 1 to 4 from the first, 5 to 8 from the second.+ const read = (splat: Splat | null): number[] => {+ if (!splat) return [0, 0, 0, 0];const sx = Math.round(u * (splat.width - 1)), sy = Math.round(v * (splat.height - 1));const at = (sy * splat.width + sx) * 4;- const s: [number, number, number, number] = [splat.pixels[at]! / 255, splat.pixels[at + 1]! / 255, splat.pixels[at + 2]! / 255, splat.pixels[at + 3]! / 255];- const sum = s[0] + s[1] + s[2] + s[3];- if (sum > 0.001) w = [s[0] / sum, s[1] / sum, s[2] / sum, s[3] / sum];+ return [splat.pixels[at]! / 255, splat.pixels[at + 1]! / 255, splat.pixels[at + 2]! / 255, splat.pixels[at + 3]! / 255];+ };+ if (this.splat || this.splat2) {+ const s = [...read(this.splat), ...(this.splat2 ? read(this.splat2) : [])];+ const sum = s.reduce((a, b) => a + b, 0);+ if (sum > 0.001) w = s.map((c) => c / sum);}if (this.flow) {- // Where the rain ran it took the grass and left dirt; snow and rock stay as they are.+ // Where the rain ran it took the grass and left dirt; the other layers stay as they are.const fx = Math.round(u * (this.field.width - 1)), fy = Math.round(v * (this.field.height - 1));- const channel = smooth(0.45, 0.85, this.flow[fy * this.field.width + fx]!) * 0.8 * w[0];- w = [w[0] - channel, w[1] + channel, w[2], w[3]];+ const channel = smooth(0.45, 0.85, this.flow[fy * this.field.width + fx]!) * 0.8 * w[0]!;+ w[0] = w[0]! - channel;+ w[1] = w[1]! + channel;}return w;}@@ -247,7 +259,7 @@ export class ModifiedSource implements TerrainSource {return [-sx / len, 1 / len, -sz / len];}- paint(x: number, z: number, h: number, ny: number): [number, number, number, number] {+ paint(x: number, z: number, h: number, ny: number): LayerWeights {return this.base.paint(x, z, h, ny);}@@ -256,7 +268,7 @@ export class ModifiedSource implements TerrainSource {if (!region) return undefined;return (x0, z0, spacing, count) => {const got = region(x0, z0, spacing, count);- const lay = (r: { heights: Float32Array; paint?: Float32Array }) => {+ const lay = (r: TerrainRegionSamples) => {if (!this.touched(x0, z0, x0 + spacing * (count - 1), z0 + spacing * (count - 1))) return r;const heights = new Float32Array(r.heights);for (let j = 0; j < count; j++) for (let i = 0; i < count; i++) {diff --git a/sdk/src/terrain/terrainPlugin.ts b/sdk/src/terrain/terrainPlugin.tsindex 0e2712b4a..650f13c72 100644--- a/sdk/src/terrain/terrainPlugin.ts+++ b/sdk/src/terrain/terrainPlugin.ts@@ -29,7 +29,7 @@ import { decodeImagePixels } from '../asset/imageDecode';import { decodePngData } from '../asset/pngData';import { Material, MATERIAL_FORMAT_VERSION } from '../render/material';import { BlendMode } from '../render/blend';-import { createTextureFromPixels, updateTextureSubregion } from '../runtime/runtimeAssets';+import { createTextureArrayFromPixels, createTextureFromPixels, updateTextureSubregion } from '../runtime/runtimeAssets';import { getResourceManager, provideTextureContent, withdrawTextureContent } from '../wasm/resourceManager';import { TextureContent } from '../wasm';import { EditorView, editorViewEye } from '../camera/EditorView';@@ -43,6 +43,8 @@ import { levelRange, nodeKey, parentOf, selectNodes, type QuadtreeParams, type Timport { makePage, PageTable, PAGE_SIDE, PAGE_TEXELS, PATCH_CELLS, type PageImage, type Repaint } from './pages';import { noiseProvider, ProviderSource, terrainProvider, terrainProvidersRevision, TerrainUnavailable, type TerrainProvider } from './provider';import { buildPatchMesh } from './patch';+import { isMiniGame } from '../platform';+import { packLayers, type LayerImage, type LayerSource, type TerrainLayerDef } from './layers';import { TerrainSurface, TILE_CELLS, type SurfaceTile } from './surface';import { collisionGeometryOf } from '../runtime/collisionGeometry';import { chunksOf, ProceduralChunksRes, type ChunkSource } from '../residency/chunks';@@ -70,8 +72,15 @@ export interface TerrainData {heightmap: number;/** How the heightmap holds its heights: a {@link HeightmapFormat}. */heightmapFormat: number;- /** An image whose four channels are the weights of the four layers; empty paints by height and slope. */+ /** An image whose four channels are the weights of layers 1 to 4; empty paints by height and slope. */splatmap: number;+ /** An image whose four channels are the weights of layers 5 to 8, read with the first. */+ splatmap2: number;+ /**+ * The terrain layers (`.esterrainlayer` files, up to eight) the ground is drawn with, in the order the paint weighs them. With any,+ * the ground is drawn on the Terrain Layers shader (its material, if one is named, must be on it); with none, by the four colours.+ */+ layers: string[];/** A material on the Terrain shader. Empty draws the layer colours onto the ground. */material: number;/** An area's size along x and z, centred on its entity; for ground without end, the span `frequency` hills are spread over. */@@ -120,14 +129,14 @@ const rgb = (r: number, g: number, b: number): Color => ({ r, g, b, a: 1 });* @experimental*/export const Terrain: ComponentDef<TerrainData> = defineComponent<TerrainData>('Terrain', {- extent: TerrainExtent.Area, provider: NOISE_PROVIDER, world: '', generatorVersion: 1, heightmap: 0, heightmapFormat: HeightmapFormat.Grey, splatmap: 0, material: 0,+ extent: TerrainExtent.Area, provider: NOISE_PROVIDER, world: '', generatorVersion: 1, heightmap: 0, heightmapFormat: HeightmapFormat.Grey, splatmap: 0, splatmap2: 0, layers: [] as string[], material: 0,sizeX: 1000, sizeZ: 1000, height: 150, cellSize: 2, detail: 1, drawDistance: 4000,collision: true, collisionDistance: 64, collisionLayer: 0, friction: 0.6,seed: 1, frequency: 3, octaves: 5, persistence: 0.5, ridged: 0.35, resolution: 257, warp: 0, erosion: 0,rockSlope: 0.35, dirtHeight: 0.62, snowHeight: 0.88,layerColor0: rgb(0.28, 0.46, 0.2), layerColor1: rgb(0.45, 0.36, 0.24), layerColor2: rgb(0.93, 0.95, 0.98), layerColor3: rgb(0.4, 0.38, 0.36),}, {- assetFields: [{ field: 'heightmap', type: 'texture' }, { field: 'splatmap', type: 'texture' }, { field: 'material', type: 'material' }],+ assetFields: [{ field: 'heightmap', type: 'texture' }, { field: 'splatmap', type: 'texture' }, { field: 'splatmap2', type: 'texture' }, { field: 'material', type: 'material' }],fields: {extent: { enum: [{ label: 'Area', value: TerrainExtent.Area }, { label: 'Infinite', value: TerrainExtent.Infinite }], category: 'Shape', tooltip: 'An area of its own size, from a heightmap or noise; or ground that goes on for ever, from noise read anywhere (the same seed is the same ground).' },provider: { category: 'Shape', tooltip: 'The generator the ground is made by, without end or (with no heightmap) in an area: estella:noise, or one the game registers. The same provider, world, seed and version are the same ground on every machine, and two areas side by side join.' },@@ -136,7 +145,9 @@ export const Terrain: ComponentDef<TerrainData> = defineComponent<TerrainData>('heightmap: { tooltip: 'A heightmap image, read as data (shipped as the PNG it is). Empty makes the ground from noise; a heightmap that cannot be read fails the terrain instead.', category: 'Shape', shownWhen: { field: 'extent', values: [TerrainExtent.Area] } },heightmapFormat: { enum: [{ label: 'Grey (8 or 16 bit)', value: HeightmapFormat.Grey }, { label: 'Red + green (16 bit)', value: HeightmapFormat.RedGreen16 }], category: 'Shape', tooltip: 'How the heightmap holds its heights: grey (or red) at the depth of the file, 16 bits from a 16-bit PNG; or sixteen bits across red (high byte) and green (low byte) of an 8-bit image.', shownWhen: { field: 'extent', values: [TerrainExtent.Area] } },splatmap: { tooltip: 'An image whose red, green, blue and alpha are the weights of grass, dirt, snow and rock.', category: 'Layers', shownWhen: { field: 'extent', values: [TerrainExtent.Area] } },- material: { tooltip: 'A material on the Terrain shader. Empty draws the layer colours onto the ground.', category: 'Layers' },+ splatmap2: { tooltip: 'An image whose red, green, blue and alpha are the weights of layers 5 to 8.', category: 'Layers', shownWhen: { field: 'extent', values: [TerrainExtent.Area] } },+ layers: { tooltip: 'The terrain layers (.esterrainlayer, up to eight) the ground is drawn with, in the order the paint weighs them. Empty draws the four layer colours.', category: 'Layers' },+ material: { tooltip: 'A material on the Terrain shader (on Terrain Layers when the ground has layers). Empty uses the stock one.', category: 'Layers' },sizeX: { min: 1, category: 'Shape', tooltip: 'An area\'s size along x; for ground without end, the span its hills are spread over.' },sizeZ: { min: 1, category: 'Shape', tooltip: 'An area\'s size along z.', shownWhen: { field: 'extent', values: [TerrainExtent.Area] } },height: { min: 0, category: 'Shape', tooltip: 'World height of the highest ground.' },@@ -182,6 +193,8 @@ export function paintWeights(h: number, ny: number, t: Pick<TerrainData, 'rockSl/** The side of the atlases the pages are kept in, in texels: 900 pages of 67 by 67. */const ATLAS_SIZE = 2048;+/** The most layers a terrain draws: two paint atlases of four weights. */+const MAX_LAYERS = 8;/** The chunk layer a terrain's collision is, and the key of one tile's piece of collision geometry. */const collisionLayerOf = (entity: Entity): string => `terrain-collision:${entity}`;const tileKey = (entity: Entity, tx: number, tz: number): string => `terrain:${entity}:${tx}:${tz}`;@@ -218,6 +231,12 @@ interface Built {failure: string | null;/** Bumped whenever modifiers change the ground under it: a page asked for before is thrown away when it lands. */edits: number;+ /** The atlas of layers 5 to 8's paint, with layers. */+ paint2: number;+ /** The layers packed (albedo, normal and mask arrays), what they were packed from, and whether a packing is in hand. */+ arrays: number[];+ packed: string;+ packing: boolean;}/** Where a terrain's ground stands: still being made, ready, or failed (with why). */@@ -432,7 +451,9 @@ export const TerrainsRes = defineResource<Terrains>(new Terrains(), 'Terrains');/** What, changed, rebuilds the ground: everything but the colours, the detail and the collision, which are read each frame. */function signatureOf(data: TerrainData, at: { x: number; z: number }): string {const { layerColor0: _a, layerColor1: _b, layerColor2: _c, layerColor3: _d, detail: _e, drawDistance: _f,- collision: _g, collisionDistance: _h, collisionLayer: _i, friction: _j, ...shape } = data;+ collision: _g, collisionDistance: _h, collisionLayer: _i, friction: _j, layers, ...rest } = data;+ // Which layers are only what the arrays are packed from; whether there are any is which shader the ground is drawn with.+ const shape = { ...rest, layered: (layers?.length ?? 0) > 0 };// Ground read from a provider is the world's where the terrain stands: moved, it is read again; and a game's own provider is read// again when one is registered under its name.const fromProvider = data.extent === TerrainExtent.Infinite || !data.heightmap;@@ -490,8 +511,12 @@ function movers(app: App): ChunkSource[] {export class TerrainPlugin implements Plugin {name = 'terrain';- /** The stock material a terrain with none of its own is an instance of. */+ /** The stock materials a terrain with none of its own is an instance of: without layers, and with. */private stock_ = 0;+ private stockLayers_ = 0;+ /** Bumped when an asset is edited and saved, so layers are packed again; and the listener that bumps it. */+ private layerEdits_ = 0;+ private watching_: (() => void) | null = null;build(app: App): void {const terrains = new Terrains();@@ -512,6 +537,7 @@ export class TerrainPlugin implements Plugin {signature, data: { ...data }, source: null, surface: null, epoch: (built?.epoch ?? 0) + 1, loading: true, cancel: null,table: new PageTable(ATLAS_SIZE), heights: 0, paint: 0, mesh: 0, instance: 0,nodes: new Map(), spare: [], wanted: new Map(), asked: new Set(), pending: false, failure: null, edits: 0,+ paint2: 0, arrays: [], packed: '', packing: false,};terrains.built_.set(entity, built);void this.load(app, entity, built);@@ -532,6 +558,7 @@ export class TerrainPlugin implements Plugin {if (!built.pending) void this.prepare(app, built);continue;}+ this.pack(app, built);this.draw(app, entity, built);}}, { name: 'TerrainSystem' }));@@ -547,6 +574,10 @@ export class TerrainPlugin implements Plugin {terrains.built_.clear();if (this.stock_) Material.release(this.stock_);this.stock_ = 0;+ if (this.stockLayers_) Material.release(this.stockLayers_);+ this.stockLayers_ = 0;+ this.watching_?.();+ this.watching_ = null;}/** Reads the images the terrain names (or makes its noise, and wears it), and makes its source. */@@ -564,6 +595,7 @@ export class TerrainPlugin implements Plugin {const height = await this.pixelsOf(app, data.heightmap);if (data.heightmap && !height) throw new TerrainUnavailable(`the heightmap (texture ${data.heightmap}) could not be read: it is read as data, so it must ship as the PNG it is (not compressed)`);const splat = await this.pixelsOf(app, data.splatmap);+ const splat2 = await this.pixelsOf(app, data.splatmap2);if (built.epoch !== epoch || !app.world.valid(entity)) return;// Without a heightmap an area is a window on its provider's ground, read where it stands in the world: two areas side by// side are one ground, and the area is the same ground the provider gives without end.@@ -590,7 +622,7 @@ export class TerrainPlugin implements Plugin {field = worn.field;flow = worn.flow;}- built.source = new FieldSource(field, data, splat, flow, range);+ built.source = new FieldSource(field, data, splat, flow, range, splat2);}// The modifiers set on the ground (a plot levelled, a bed cut) are laid over it, for the pages, the queries and collision alike.const terrains = app.getResource(TerrainsRes);@@ -607,9 +639,15 @@ export class TerrainPlugin implements Plugin {private async pixelsOf(app: App, handle: number): Promise<{ width: number; height: number; pixels: Uint8Array; wide?: Uint16Array } | null> {if (!handle || !app.hasResource(Assets)) return null;- const assets = app.getResource(Assets);- const path = assets.pathForHandle('texture', handle);+ const path = app.getResource(Assets).pathForHandle('texture', handle);if (!path) { log.warn('terrain', `no source image is known for texture ${handle}`); return null; }+ return this.pixelsAt(app, path);+ }++ /** An image file's pixels exactly as stored (no premultiply, no colour conversion), by its project path or reference. */+ private async pixelsAt(app: App, path: string): Promise<{ width: number; height: number; pixels: Uint8Array; wide?: Uint16Array } | null> {+ if (!app.hasResource(Assets)) return null;+ const assets = app.getResource(Assets);try {// The bytes the asset layer would load, decoded unmodified (no premultiply, no colour conversion): a height is data.if (typeof createImageBitmap === 'function' && typeof Blob !== 'undefined') {@@ -637,12 +675,92 @@ export class TerrainPlugin implements Plugin {return this.stock_;}+ /** The stock material for ground with layers: the Terrain Layers shader, compiled once. */+ private async stockLayers(app: App): Promise<number> {+ if (this.stockLayers_) return this.stockLayers_;+ const source = await app.getResource(Assets).load<MaterialShaderSource>('material-shader', 'builtin:terrain-layers');+ const shader = source.compile([]);+ if (this.stockLayers_) return this.stockLayers_;+ this.stockLayers_ = Material.createFromAsset({+ version: MATERIAL_FORMAT_VERSION, type: 'material', shader: 'builtin:terrain-layers', blendMode: BlendMode.None,+ depthTest: true, depthWrite: true, cull: 0, properties: {},+ }, shader);+ return this.stockLayers_;+ }++ /**+ * Packs the terrain's layers into the arrays its material reads, when what they name changed (or a layer file was saved): the+ * ground keeps the arrays it has until the new ones are made.+ */+ private pack(app: App, built: Built): void {+ const refs = built.data.layers ?? [];+ if (refs.length === 0 || built.packing) return;+ const assets = app.getResource(Assets);+ const wanted = `${JSON.stringify(refs)}#${this.layerEdits_}`;+ if (wanted === built.packed) return;+ built.packing = true;+ const epoch = built.epoch;+ if (!this.watching_) {+ // A layer file edited and saved, or a texture it names, is packed again.+ this.watching_ = assets.onInvalidate(() => { this.layerEdits_++; });+ }+ void (async () => {+ try {+ if (refs.length > MAX_LAYERS) log.warn('terrain', `a terrain draws ${MAX_LAYERS} layers at most; it names ${refs.length}`);+ const sources: LayerSource[] = [];+ for (const ref of refs.slice(0, MAX_LAYERS)) {+ const def = await assets.load<TerrainLayerDef>('terrain-layer', ref);+ const image = async (path: string | undefined): Promise<LayerImage | null> => {+ if (!path) return null;+ const got = await this.pixelsAt(app, path);+ if (!got) log.warn('terrain', `the texture ${path} of terrain layer ${ref} could not be read`);+ return got;+ };+ sources.push({ def, albedo: await image(def.albedo), normal: await image(def.normal), mask: await image(def.mask) });+ }+ if (built.epoch !== epoch || !built.instance) return;+ // A minigame's memory holds the layers at half the size.+ const packed = packLayers(sources, isMiniGame() ? 512 : 1024);+ const made = (layers: Uint8Array[], srgb: boolean): number => createTextureArrayFromPixels(app.wasmModule,+ { width: packed.size, height: packed.size, layers }, TextureContent.Retained,+ { filterMode: 'linear', wrapMode: 'repeat', mipmaps: true, srgb });+ const arrays = [made(packed.albedo, true), made(packed.normal, false), made(packed.mask, false)];+ if (arrays.some((h) => !h)) {+ log.warn('terrain', 'the engine refused the terrain layers\' texture arrays');+ this.releaseArrays(arrays);+ return;+ }+ this.releaseArrays(built.arrays);+ built.arrays = arrays;+ const set = (name: string, value: Parameters<typeof Material.setUniform>[2]): void => { Material.setUniform(built.instance, name, value); };+ set('u_albedoLayers', Material.tex(arrays[0]!));+ set('u_normalLayers', Material.tex(arrays[1]!));+ set('u_maskLayers', Material.tex(arrays[2]!));+ set('u_layerCount', packed.tiles.length);+ const t = (i: number): number => packed.tiles[i] ?? 4;+ set('u_tiles0', { x: t(0), y: t(1), z: t(2), w: t(3) });+ set('u_tiles1', { x: t(4), y: t(5), z: t(6), w: t(7) });+ } catch (e) {+ log.error('terrain', 'packing the terrain layers failed', e);+ } finally {+ built.packed = wanted;+ built.packing = false;+ }+ })();+ }++ private releaseArrays(arrays: readonly number[]): void {+ const rm = getResourceManager();+ for (const handle of arrays) if (handle) rm?.releaseTexture(handle);+ }+/** Makes what the ground is drawn with: the patch, the atlases and an instance of its material. */private async prepare(app: App, built: Built): Promise<void> {built.pending = true;const epoch = built.epoch;try {- const material = built.data.material || await this.stock(app);+ const layered = (built.data.layers?.length ?? 0) > 0;+ const material = built.data.material || (layered ? await this.stockLayers(app) : await this.stock(app));if (built.epoch !== epoch) return;const assets = app.getResource(Assets);built.mesh = assets.createMesh(buildPatchMesh(PATCH_CELLS));@@ -650,8 +768,9 @@ export class TerrainPlugin implements Plugin {const params = { filterMode: 'linear', wrapMode: 'clamp', srgb: false } as const;built.heights = createTextureFromPixels(app.wasmModule, { width: ATLAS_SIZE, height: ATLAS_SIZE, pixels: blank }, TextureContent.Transient, false, params);built.paint = createTextureFromPixels(app.wasmModule, { width: ATLAS_SIZE, height: ATLAS_SIZE, pixels: blank }, TextureContent.Transient, false, params);+ if (layered) built.paint2 = createTextureFromPixels(app.wasmModule, { width: ATLAS_SIZE, height: ATLAS_SIZE, pixels: blank }, TextureContent.Transient, false, params);// A device that lost the atlases has lost every page in them: they are made again as they are wanted.- for (const handle of [built.heights, built.paint]) {+ for (const handle of [built.heights, built.paint, built.paint2].filter(Boolean)) {provideTextureContent(handle, () => { built.table.clear(); return true; });}built.instance = Material.createInstance(material);@@ -662,6 +781,17 @@ export class TerrainPlugin implements Plugin {const set = (name: string, value: Parameters<typeof Material.setUniform>[2]): void => { Material.setUniform(built.instance, name, value); };set('u_heightPages', Material.tex(built.heights));set('u_paintPages', Material.tex(built.paint));+ if (built.paint2) {+ set('u_paintPages2', Material.tex(built.paint2));+ // Until the layers are packed the ground is one plain layer: an array left unset reads black on some devices.+ const one = (rgba: number[], srgb: boolean): number => createTextureArrayFromPixels(app.wasmModule,+ { width: 1, height: 1, layers: [new Uint8Array(rgba)] }, TextureContent.Retained, { filterMode: 'linear', wrapMode: 'repeat', srgb });+ built.arrays = [one([150, 150, 140, 255], true), one([128, 128, 255, 255], false), one([255, 230, 128, 255], false)];+ set('u_albedoLayers', Material.tex(built.arrays[0]!));+ set('u_normalLayers', Material.tex(built.arrays[1]!));+ set('u_maskLayers', Material.tex(built.arrays[2]!));+ set('u_layerCount', 1);+ }set('u_terrainPages', 1);set('u_atlasTexels', ATLAS_SIZE);set('u_pageTexels', PAGE_TEXELS);@@ -808,6 +938,7 @@ export class TerrainPlugin implements Plugin {const [ox, oy] = built.table.origin(page.slot);updateTextureSubregion(app.wasmModule, built.heights, ox, oy, PAGE_SIDE, PAGE_SIDE, image.heights);updateTextureSubregion(app.wasmModule, built.paint, ox, oy, PAGE_SIDE, PAGE_SIDE, image.paint);+ if (built.paint2) updateTextureSubregion(app.wasmModule, built.paint2, ox, oy, PAGE_SIDE, PAGE_SIDE, image.paint2);return true;};const epoch = built.epoch, edits = built.edits;@@ -889,12 +1020,15 @@ export class TerrainPlugin implements Plugin {built.spare.length = 0;built.wanted.clear();const rm = getResourceManager();- for (const handle of [built.heights, built.paint]) {+ for (const handle of [built.heights, built.paint, built.paint2]) {if (!handle) continue;withdrawTextureContent(handle);rm?.releaseTexture(handle);}- built.heights = built.paint = 0;+ built.heights = built.paint = built.paint2 = 0;+ this.releaseArrays(built.arrays);+ built.arrays = [];+ built.packed = '';if (built.instance) Material.release(built.instance);built.instance = 0;if (built.mesh && app.hasResource(Assets)) app.getResource(Assets).releaseBuiltMesh(built.mesh);diff --git a/sdk/src/terrain/terrainShader.ts b/sdk/src/terrain/terrainShader.tsindex 7ed33b3ed..3a2b0c13b 100644--- a/sdk/src/terrain/terrainShader.ts+++ b/sdk/src/terrain/terrainShader.ts@@ -9,60 +9,9 @@import { makeBuiltinShaderTemplate } from '../render/builtinShaders';-// Ground painted by four layers (grass, dirt, snow, rock), their weights read from the Terrain's paint pages (or, on a plain mesh, its-// vertex colour). Each layer is a texture laid by world position without repeat, and the rock is projected from three sides on a cliff.-const TERRAIN = `#pragma shader "Terrain"-#pragma version 300 es-#pragma domain Lit-#pragma param u_layer0 texture default(white)-#pragma param u_layer1 texture default(white)-#pragma param u_layer2 texture default(white)-#pragma param u_layer3 texture default(white)-// Each layer's colour, which multiplies its texture, and how many world units one repeat of it covers.-#pragma param u_tint0 color default(0.28,0.46,0.2,1)-#pragma param u_tint1 color default(0.45,0.36,0.24,1)-#pragma param u_tint2 color default(0.93,0.95,0.98,1)-#pragma param u_tint3 color default(0.4,0.38,0.36,1)-#pragma param u_tile0 float default(24) range(1,800) ui(slider)-#pragma param u_tile1 float default(24) range(1,800) ui(slider)-#pragma param u_tile2 float default(24) range(1,800) ui(slider)-#pragma param u_tile3 float default(40) range(1,800) ui(slider)-// How much a layer with more weight takes over from the others at the seam: 1 is a plain blend, higher a harder edge.-#pragma param u_sharpness float default(1.6) range(1,8) ui(slider)-// How much the seams follow the layers' own relief (their brightness): rock shows through the gaps in the grass before the grass gives way,-// and sand fills the low places between stones. 0 is a plain blend of the weights.-#pragma param u_heightBlend float default(0.7) range(0,1) ui(slider)-// How much each layer's weight is broken up by slow noise of its own before the strongest wins: the line where grass meets sand wanders-// instead of following the paint's smooth gradient.-#pragma param u_blendNoise float default(0.5) range(0,1) ui(slider)-// From the middle distance on, each layer is also read on a tile u_farScale times as wide and mixed in, so its repeat is lost far off.-#pragma param u_farScale float default(4.3) range(1,32) ui(slider)-// How strongly each layer is read without repeat near the eye (hex tiling: every hexagonal cell shifted and turned at random), so no tile is seen.-#pragma param u_antiTile float default(0.6) range(0,1) ui(slider)-// The wide, slow variation in brightness laid over every layer so a big meadow is not one colour.-#pragma param u_macroVariation float default(0.35) range(0,1) ui(slider)-// How deep, in world units, the layers' relief is drawn into the light (their brightness taken as height); 0 leaves the ground smooth.-#pragma param u_relief float default(0.05) range(0,100000) ui(slider)-// Ground at the water: below u_wetLevel + u_wetBand (world heights) it darkens and shines, most at the waterline. A band of 0 draws none.-#pragma param u_wetLevel float default(0) range(-100000,100000) ui(slider)-#pragma param u_wetBand float default(0) range(0,100000) ui(slider)-#pragma param u_roughness float default(0.92) range(0,1) ui(slider)-// The ground in pages (pages.ts; the Terrain component writes these): heights and normals, and the paint, in two atlases; heights over-// u_heightRange above u_terrainOrigin; level 0 drawn out to u_lodRange0, each level twice as far; nothing off u_terrainBounds.-// u_terrainEye is the eye the nodes were chosen for: every pass (a shadow's too) slides the vertices by it, so all draw one ground.-#pragma param u_terrainPages float default(0) range(0,1) ui(slider)-#pragma param u_heightPages texture default(white) texel(data)-#pragma param u_paintPages texture default(white) texel(data)-#pragma param u_atlasTexels float default(2048) range(1,16384) ui(slider)-#pragma param u_pageTexels float default(64) range(1,1024) ui(slider)-#pragma param u_patchCells float default(32) range(1,512) ui(slider)-#pragma param u_heightRange vec2 default(0,1)-#pragma param u_lodRange0 float default(100) range(0,1000000) ui(slider)-#pragma param u_terrainOrigin vec4 default(0,0,0,0)-#pragma param u_terrainEye vec4 default(0,0,0,0)-#pragma param u_terrainBounds vec4 default(-1000000000,-1000000000,1000000000,1000000000)--#pragma vertexoffset+// The ground's vertices from its pages (pages.ts), shared by both terrain shaders: a node's patch placed and sized by its instance, its+// heights read from the atlas, and each vertex slid onto the coarser level's grid toward the end of its range.+const TERRAIN_VERTEX = `#pragma vertexoffset// The node's page (pages.ts): its height decoded texel by texel and blended (a filtered pair of bytes is no number).float tnPageHeight(vec2 texel) {vec2 f = texel - 0.5;@@ -142,7 +91,62 @@ fn esMaterialVertex(local : ptr<function, vec3f>, localNormal : ptr<function, ve}#pragma end-#pragma fragment+`;++// Ground painted by four layers (grass, dirt, snow, rock), their weights read from the Terrain's paint pages (or, on a plain mesh, its+// vertex colour). Each layer is a texture laid by world position without repeat, and the rock is projected from three sides on a cliff.+const TERRAIN = `#pragma shader "Terrain"+#pragma version 300 es+#pragma domain Lit+#pragma param u_layer0 texture default(white)+#pragma param u_layer1 texture default(white)+#pragma param u_layer2 texture default(white)+#pragma param u_layer3 texture default(white)+// Each layer's colour, which multiplies its texture, and how many world units one repeat of it covers.+#pragma param u_tint0 color default(0.28,0.46,0.2,1)+#pragma param u_tint1 color default(0.45,0.36,0.24,1)+#pragma param u_tint2 color default(0.93,0.95,0.98,1)+#pragma param u_tint3 color default(0.4,0.38,0.36,1)+#pragma param u_tile0 float default(24) range(1,800) ui(slider)+#pragma param u_tile1 float default(24) range(1,800) ui(slider)+#pragma param u_tile2 float default(24) range(1,800) ui(slider)+#pragma param u_tile3 float default(40) range(1,800) ui(slider)+// How much a layer with more weight takes over from the others at the seam: 1 is a plain blend, higher a harder edge.+#pragma param u_sharpness float default(1.6) range(1,8) ui(slider)+// How much the seams follow the layers' own relief (their brightness): rock shows through the gaps in the grass before the grass gives way,+// and sand fills the low places between stones. 0 is a plain blend of the weights.+#pragma param u_heightBlend float default(0.7) range(0,1) ui(slider)+// How much each layer's weight is broken up by slow noise of its own before the strongest wins: the line where grass meets sand wanders+// instead of following the paint's smooth gradient.+#pragma param u_blendNoise float default(0.5) range(0,1) ui(slider)+// From the middle distance on, each layer is also read on a tile u_farScale times as wide and mixed in, so its repeat is lost far off.+#pragma param u_farScale float default(4.3) range(1,32) ui(slider)+// How strongly each layer is read without repeat near the eye (hex tiling: every hexagonal cell shifted and turned at random), so no tile is seen.+#pragma param u_antiTile float default(0.6) range(0,1) ui(slider)+// The wide, slow variation in brightness laid over every layer so a big meadow is not one colour.+#pragma param u_macroVariation float default(0.35) range(0,1) ui(slider)+// How deep, in world units, the layers' relief is drawn into the light (their brightness taken as height); 0 leaves the ground smooth.+#pragma param u_relief float default(0.05) range(0,100000) ui(slider)+// Ground at the water: below u_wetLevel + u_wetBand (world heights) it darkens and shines, most at the waterline. A band of 0 draws none.+#pragma param u_wetLevel float default(0) range(-100000,100000) ui(slider)+#pragma param u_wetBand float default(0) range(0,100000) ui(slider)+#pragma param u_roughness float default(0.92) range(0,1) ui(slider)+// The ground in pages (pages.ts; the Terrain component writes these): heights and normals, and the paint, in two atlases; heights over+// u_heightRange above u_terrainOrigin; level 0 drawn out to u_lodRange0, each level twice as far; nothing off u_terrainBounds.+// u_terrainEye is the eye the nodes were chosen for: every pass (a shadow's too) slides the vertices by it, so all draw one ground.+#pragma param u_terrainPages float default(0) range(0,1) ui(slider)+#pragma param u_heightPages texture default(white) texel(data)+#pragma param u_paintPages texture default(white) texel(data)+#pragma param u_atlasTexels float default(2048) range(1,16384) ui(slider)+#pragma param u_pageTexels float default(64) range(1,1024) ui(slider)+#pragma param u_patchCells float default(32) range(1,512) ui(slider)+#pragma param u_heightRange vec2 default(0,1)+#pragma param u_lodRange0 float default(100) range(0,1000000) ui(slider)+#pragma param u_terrainOrigin vec4 default(0,0,0,0)+#pragma param u_terrainEye vec4 default(0,0,0,0)+#pragma param u_terrainBounds vec4 default(-1000000000,-1000000000,1000000000,1000000000)++${TERRAIN_VERTEX}#pragma fragmentprecision highp float;in vec4 v_color;@@ -468,3 +472,448 @@ fn packNormal(n : vec3f) -> vec2f {export const TERRAIN_SHADER_TEMPLATE = makeBuiltinShaderTemplate('terrain', 'Terrain','Four texture layers (grass, dirt, snow, rock) weighted by the Terrain component, tiled by world position.', TERRAIN);++// Ground painted by up to eight layers (layers.ts), each an albedo, a normal map and a mask (occlusion, roughness, height) in three+// texture arrays, their weights read from the Terrain's two paint atlases. Where layers meet the higher one shows; near the eye each is+// read without repeat; on a slope it is projected from the sides as well, so a cliff is not stretched.+const TERRAIN_LAYERS = `#pragma shader "Terrain Layers"+#pragma version 300 es+#pragma domain Lit+#pragma param u_albedoLayers textureArray default(white)+#pragma param u_normalLayers textureArray default(white) texel(data)+#pragma param u_maskLayers textureArray default(white) texel(data)+// How many layers there are, and how many world units one repeat of each covers (layers 1 to 4, then 5 to 8).+#pragma param u_layerCount float default(0) range(0,8) ui(slider)+#pragma param u_tiles0 vec4 default(4,4,4,4)+#pragma param u_tiles1 vec4 default(4,4,4,4)+// How much a layer with more weight takes over from the others at the seam: 1 is a plain blend, higher a harder edge.+#pragma param u_sharpness float default(1.6) range(1,8) ui(slider)+// How much the seams follow the layers' heights (their masks' blue): rock shows through the gaps in the grass before the grass gives+// way, and sand fills the low places between stones. 0 is a plain blend of the weights.+#pragma param u_heightBlend float default(0.8) range(0,1) ui(slider)+// How much each layer's weight is broken up by slow noise of its own before the strongest wins.+#pragma param u_blendNoise float default(0.5) range(0,1) ui(slider)+// From the middle distance on, each layer is also read on a tile u_farScale times as wide and mixed in, so its repeat is lost far off.+#pragma param u_farScale float default(4.3) range(1,32) ui(slider)+// How strongly each layer is read without repeat near the eye (hex tiling), so no tile is seen.+#pragma param u_antiTile float default(0.6) range(0,1) ui(slider)+// The wide, slow variation in brightness laid over every layer so a big meadow is not one colour.+#pragma param u_macroVariation float default(0.25) range(0,1) ui(slider)+// How steep the ground must be (1 minus its normal's up) before the layers are also projected from the sides.+#pragma param u_triplanarFrom float default(0.15) range(0,1) ui(slider)+// Ground at the water: below u_wetLevel + u_wetBand (world heights) it darkens and shines, most at the waterline. A band of 0 draws none.+#pragma param u_wetLevel float default(0) range(-100000,100000) ui(slider)+#pragma param u_wetBand float default(0) range(0,100000) ui(slider)+// The ground in pages, as the Terrain shader has them, with the paint of layers 5 to 8 in an atlas of its own.+#pragma param u_terrainPages float default(0) range(0,1) ui(slider)+#pragma param u_heightPages texture default(white) texel(data)+#pragma param u_paintPages texture default(white) texel(data)+#pragma param u_paintPages2 texture default(black) texel(data)+#pragma param u_atlasTexels float default(2048) range(1,16384) ui(slider)+#pragma param u_pageTexels float default(64) range(1,1024) ui(slider)+#pragma param u_patchCells float default(32) range(1,512) ui(slider)+#pragma param u_heightRange vec2 default(0,1)+#pragma param u_lodRange0 float default(100) range(0,1000000) ui(slider)+#pragma param u_terrainOrigin vec4 default(0,0,0,0)+#pragma param u_terrainEye vec4 default(0,0,0,0)+#pragma param u_terrainBounds vec4 default(-1000000000,-1000000000,1000000000,1000000000)++${TERRAIN_VERTEX}#pragma fragment+precision highp float;+precision highp sampler2DArray;++in vec4 v_color;+in vec2 v_texCoord;+in highp vec2 v_worldPos;+#ifdef MESH_NORMALS+in highp vec3 v_worldNormal;+in highp vec3 v_worldXYZ;+#endif++#ifdef ES_GBUFFER+layout(location = 0) out vec4 fragColor;+layout(location = 1) out vec4 fragSurface;++vec2 packNormal(vec3 n) {+ n /= (abs(n.x) + abs(n.y) + abs(n.z));+ vec2 sgn = vec2(n.x >= 0.0 ? 1.0 : -1.0, n.y >= 0.0 ? 1.0 : -1.0);+ vec2 e = n.z >= 0.0 ? n.xy : (1.0 - abs(n.yx)) * sgn;+ return e * 0.5 + 0.5;+}+#else+out vec4 fragColor;+#endif++float tnHash(vec2 p) {+ p = fract(p * vec2(0.1031, 0.1030));+ p += dot(p, p.yx + 33.33);+ return fract((p.x + p.y) * p.x);+}+float tnNoise(vec2 p) {+ vec2 i = floor(p), f = fract(p);+ f = f * f * (3.0 - 2.0 * f);+ return mix(mix(tnHash(i), tnHash(i + vec2(1.0, 0.0)), f.x), mix(tnHash(i + vec2(0.0, 1.0)), tnHash(i + vec2(1.0, 1.0)), f.x), f.y);+}+vec2 tnHash2(vec2 p) {+ return fract(sin(vec2(dot(p, vec2(127.1, 311.7)), dot(p, vec2(269.5, 183.3)))) * 43758.5453);+}+float tnTile(int i) { return i < 4 ? u_tiles0[i] : u_tiles1[i - 4]; }++// One layer read at uv (in repeats) on one plane: its albedo, its tangent normal's slope (x, y) and its mask, from the gradients given.+struct TnTap { vec3 albedo; vec2 slope; vec3 mask; };+TnTap tnPlain(vec2 uv, float layer, vec2 gx, vec2 gy) {+ vec3 at = vec3(uv, layer);+ TnTap t;+ t.albedo = textureGrad(u_albedoLayers, at, gx, gy).rgb;+ t.slope = textureGrad(u_normalLayers, at, gx, gy).rg * 2.0 - 1.0;+ t.mask = textureGrad(u_maskLayers, at, gx, gy).rgb;+ return t;+}+// The same in one hex cell: shifted and turned by the cell's random numbers; the normal's slope turned back with it.+TnTap tnHexTap(vec2 uv, float layer, vec2 cell, vec2 gx, vec2 gy) {+ vec2 r = tnHash2(cell);+ float a = r.x * 6.2831853;+ mat2 turn = mat2(cos(a), -sin(a), sin(a), cos(a));+ TnTap t = tnPlain(turn * uv + r, layer, turn * gx, turn * gy);+ t.slope = t.slope * turn;+ return t;+}+// A layer read without repeat (hex tiling, Mikkelsen 2022): three cells about a point blended by nearness, the higher reading winning.+TnTap tnHex(vec2 uv, float layer, vec2 gx, vec2 gy, float strength) {+ vec2 skewed = mat2(1.0, 0.0, -0.57735027, 1.15470054) * (uv * 3.4641016);+ vec2 base = floor(skewed);+ vec3 f = vec3(fract(skewed), 0.0);+ f.z = 1.0 - f.x - f.y;+ float s = step(0.0, -f.z), s2 = 2.0 * s - 1.0;+ vec3 w = vec3(-f.z * s2, s - f.y * s2, s - f.x * s2);+ TnTap c1 = tnHexTap(uv, layer, base + vec2(s, s), gx, gy);+ TnTap c2 = tnHexTap(uv, layer, base + vec2(s, 1.0 - s), gx, gy);+ TnTap c3 = tnHexTap(uv, layer, base + vec2(1.0 - s, s), gx, gy);+ vec3 h = vec3(c1.mask.b, c2.mask.b, c3.mask.b);+ w = pow(max(w * mix(vec3(1.0), 0.4 + h, strength), vec3(1e-4)), vec3(7.0));+ w /= dot(w, vec3(1.0));+ TnTap t;+ t.albedo = c1.albedo * w.x + c2.albedo * w.y + c3.albedo * w.z;+ t.slope = c1.slope * w.x + c2.slope * w.y + c3.slope * w.z;+ t.mask = c1.mask * w.x + c2.mask * w.y + c3.mask * w.z;+ return t;+}+// A tangent normal's slope laid on a plane whose texture runs along T and B, about the surface's normal N.+vec3 tnBend(vec2 slope, vec3 T, vec3 B, vec3 N) {+ T = normalize(T - N * dot(N, T));+ B = normalize(B - N * dot(N, B));+ return slope.x * T + slope.y * B;+}++void main() {+#ifdef MESH_NORMALS+ highp vec3 P = v_worldXYZ;+ highp vec3 N = normalize(v_worldNormal);+#else+ highp vec3 P = vec3(v_worldPos.x, 0.0, v_worldPos.y);+ highp vec3 N = vec3(0.0, 1.0, 0.0);+#endif+ vec4 paintA = v_color, paintB = vec4(0.0);+ if (u_terrainPages > 0.5) {+ vec2 lp = P.xz - u_terrainOrigin.xz;+ if (lp.x < u_terrainBounds.x || lp.y < u_terrainBounds.y || lp.x > u_terrainBounds.z || lp.y > u_terrainBounds.w) discard;+ paintA = texture(u_paintPages, v_color.xy);+ paintB = texture(u_paintPages2, v_color.xy);+ vec2 nxz = texture(u_heightPages, v_color.xy).ba * 2.0 - 1.0;+ N = normalize(vec3(nxz.x, sqrt(max(1.0 - dot(nxz, nxz), 0.0)), nxz.y));+ }+ int count = int(u_layerCount + 0.5);+ float w[8];+ float sum = 0.0;+ for (int i = 0; i < 8; i++) {+ float raw = i < 4 ? paintA[i] : paintB[i - 4];+ // Each layer's say wanders by slow noise of its own, so where two meet the edge is ragged, not the paint's gradient.+ float wander = tnNoise(P.xz / (tnTile(i) * 2.3) + float(i) * 11.0 + 3.0);+ w[i] = i < count ? max(raw, 0.0) * mix(1.0, 0.35 + 1.3 * wander, u_blendNoise) : 0.0;+ sum += w[i];+ }+ float sharp = 0.0;+ for (int i = 0; i < 8; i++) { w[i] = pow(w[i] / max(sum, 1e-4), u_sharpness); sharp += w[i]; }+ for (int i = 0; i < 8; i++) w[i] /= max(sharp, 1e-4);++ // Gradients taken here, where every lane runs. Near the eye a layer is read without repeat, far off a wider tile is mixed in.+ vec3 dpx = dFdx(P), dpy = dFdy(P);+ float eye = u_camera.w > 0.5 ? length(P - u_camera.xyz) : 0.0;+ float scale = tnTile(0);+ float near = (1.0 - smoothstep(scale * 20.0, scale * 45.0, eye)) * u_antiTile;+ float far = smoothstep(scale * 6.0, scale * 40.0, eye) * 0.65;+ // How much of each plane a slope is seen from: the top alone on gentle ground, the sides too from u_triplanarFrom.+ vec3 axis = pow(abs(N), vec3(4.0));+ axis /= dot(axis, vec3(1.0));+ float side = smoothstep(u_triplanarFrom, u_triplanarFrom + 0.15, 1.0 - abs(N.y));+ vec3 planes = mix(vec3(0.0, 1.0, 0.0), axis, side);++ vec3 albedo[8];+ vec3 bend[8];+ vec3 mask[8];+ for (int i = 0; i < 8; i++) {+ albedo[i] = vec3(0.0); bend[i] = vec3(0.0); mask[i] = vec3(1.0, 1.0, 0.0);+ if (w[i] <= 1e-3) continue;+ float layer = float(i), tile = tnTile(i);+ // WebGL takes no ?: between structures.+ TnTap top;+ if (near > 0.01) top = tnHex(P.xz / tile, layer, dpx.xz / tile, dpy.xz / tile, near);+ else top = tnPlain(P.xz / tile, layer, dpx.xz / tile, dpy.xz / tile);+ if (far > 0.01) {+ float big = tile * u_farScale;+ TnTap wide = tnPlain(P.xz / big + 0.21, layer, dpx.xz / big, dpy.xz / big);+ top.albedo = mix(top.albedo, wide.albedo, far);+ top.mask = mix(top.mask, wide.mask, far);+ }+ albedo[i] = top.albedo * planes.y;+ mask[i] = top.mask * planes.y;+ bend[i] = tnBend(top.slope, vec3(1.0, 0.0, 0.0), vec3(0.0, 0.0, 1.0), N) * planes.y;+ if (planes.x > 0.02) {+ TnTap x = tnPlain(P.zy / tile, layer, dpx.zy / tile, dpy.zy / tile);+ albedo[i] += x.albedo * planes.x; mask[i] += x.mask * planes.x;+ bend[i] += tnBend(x.slope, vec3(0.0, 0.0, 1.0), vec3(0.0, 1.0, 0.0), N) * planes.x;+ }+ if (planes.z > 0.02) {+ TnTap z = tnPlain(P.xy / tile, layer, dpx.xy / tile, dpy.xy / tile);+ albedo[i] += z.albedo * planes.z; mask[i] += z.mask * planes.z;+ bend[i] += tnBend(z.slope, vec3(1.0, 0.0, 0.0), vec3(0.0, 1.0, 0.0), N) * planes.z;+ }+ }+ // Then by height: each layer stands as high as its mask says, and where two meet the higher one shows.+ float top = -1.0;+ for (int i = 0; i < 8; i++) if (w[i] > 1e-3) top = max(top, mask[i].b + w[i] * 1.5);+ float hsum = 0.0;+ float hw[8];+ for (int i = 0; i < 8; i++) { hw[i] = w[i] > 1e-3 ? max(mask[i].b + w[i] * 1.5 - (top - 0.35), 0.0) : 0.0; hsum += hw[i]; }+ vec3 colour = vec3(0.0), slope = vec3(0.0), surface = vec3(0.0);+ for (int i = 0; i < 8; i++) {+ float k = mix(w[i], hw[i] / max(hsum, 1e-4), u_heightBlend);+ colour += albedo[i] * k; slope += bend[i] * k; surface += mask[i] * k;+ }+ float broad = tnNoise(P.xz / (scale * 7.3)) * 0.6 + tnNoise(P.xz / (scale * 29.0) + 5.0) * 0.4;+ colour *= mix(1.0, 0.7 + 0.6 * broad, u_macroVariation);+ N = normalize(N + slope);++ // Wet at the water: darker, and smooth enough to shine.+ float wet = u_wetBand > 0.0 ? 1.0 - smoothstep(u_wetLevel, u_wetLevel + u_wetBand, P.y) : 0.0;+ colour *= mix(1.0, 0.55, wet);+ float roughness = mix(surface.g, 0.3, wet);++ SurfaceExt ext = surfaceExtNone(N);+ vec3 viewDir = viewDirection(P);+ vec3 lit = applyLightingSurface(colour, N, P, viewDir, 0.0, roughness, 0.5, surface.r, ext);+ fragColor = vec4(lit, 1.0);+#ifdef ES_GBUFFER+ fragSurface = vec4(packNormal(N), roughness, 0.75);+#endif+}+#pragma end++#pragma fragment wgsl+fn tnHash(p0 : vec2f) -> f32 {+ var p = fract(p0 * vec2f(0.1031, 0.1030));+ p = p + dot(p, p.yx + 33.33);+ return fract((p.x + p.y) * p.x);+}+fn tnNoise(p : vec2f) -> f32 {+ let i = floor(p);+ var f = fract(p);+ f = f * f * (3.0 - 2.0 * f);+ return mix(mix(tnHash(i), tnHash(i + vec2f(1.0, 0.0)), f.x), mix(tnHash(i + vec2f(0.0, 1.0)), tnHash(i + vec2f(1.0, 1.0)), f.x), f.y);+}+fn tnHash2(p : vec2f) -> vec2f {+ return fract(sin(vec2f(dot(p, vec2f(127.1, 311.7)), dot(p, vec2f(269.5, 183.3)))) * 43758.5453);+}+fn tnTile(i : i32) -> f32 {+ if (i < 4) { return mc.u_tiles0[i]; }+ return mc.u_tiles1[i - 4];+}+struct TnTap { albedo : vec3f, slope : vec2f, mask : vec3f };+fn tnPlain(uv : vec2f, layer : i32, gx : vec2f, gy : vec2f) -> TnTap {+ var t : TnTap;+ t.albedo = textureSampleGrad(u_albedoLayers, u_albedoLayers_s, uv, layer, gx, gy).rgb;+ t.slope = textureSampleGrad(u_normalLayers, u_normalLayers_s, uv, layer, gx, gy).rg * 2.0 - vec2f(1.0);+ t.mask = textureSampleGrad(u_maskLayers, u_maskLayers_s, uv, layer, gx, gy).rgb;+ return t;+}+fn tnHexTap(uv : vec2f, layer : i32, cell : vec2f, gx : vec2f, gy : vec2f) -> TnTap {+ let r = tnHash2(cell);+ let a = r.x * 6.2831853;+ let turn = mat2x2f(cos(a), -sin(a), sin(a), cos(a));+ var t = tnPlain(turn * uv + r, layer, turn * gx, turn * gy);+ t.slope = t.slope * turn;+ return t;+}+fn tnHex(uv : vec2f, layer : i32, gx : vec2f, gy : vec2f, strength : f32) -> TnTap {+ let skewed = mat2x2f(1.0, 0.0, -0.57735027, 1.15470054) * (uv * 3.4641016);+ let base = floor(skewed);+ let fr = fract(skewed);+ let fz = 1.0 - fr.x - fr.y;+ let s = step(0.0, -fz);+ let s2 = 2.0 * s - 1.0;+ var w = vec3f(-fz * s2, s - fr.y * s2, s - fr.x * s2);+ let c1 = tnHexTap(uv, layer, base + vec2f(s, s), gx, gy);+ let c2 = tnHexTap(uv, layer, base + vec2f(s, 1.0 - s), gx, gy);+ let c3 = tnHexTap(uv, layer, base + vec2f(1.0 - s, s), gx, gy);+ let h = vec3f(c1.mask.b, c2.mask.b, c3.mask.b);+ w = pow(max(w * mix(vec3f(1.0), vec3f(0.4) + h, vec3f(strength)), vec3f(1e-4)), vec3f(7.0));+ w = w / dot(w, vec3f(1.0));+ var t : TnTap;+ t.albedo = c1.albedo * w.x + c2.albedo * w.y + c3.albedo * w.z;+ t.slope = c1.slope * w.x + c2.slope * w.y + c3.slope * w.z;+ t.mask = c1.mask * w.x + c2.mask * w.y + c3.mask * w.z;+ return t;+}+fn tnBend(slope : vec2f, T0 : vec3f, B0 : vec3f, N : vec3f) -> vec3f {+ let T = normalize(T0 - N * dot(N, T0));+ let B = normalize(B0 - N * dot(N, B0));+ return slope.x * T + slope.y * B;+}++#ifdef ES_GBUFFER+struct FragOut {+ @location(0) color : vec4f,+ @location(1) surface : vec4f,+};++fn packNormal(n : vec3f) -> vec2f {+ let a = n / (abs(n.x) + abs(n.y) + abs(n.z));+ let sgn = vec2f(select(-1.0, 1.0, a.x >= 0.0), select(-1.0, 1.0, a.y >= 0.0));+ var e = a.xy;+ if (a.z < 0.0) { e = (vec2f(1.0) - abs(a.yx)) * sgn; }+ return e * 0.5 + 0.5;+}++@fragment fn fs_main(v : VSOut) -> FragOut {+#else+@fragment fn fs_main(v : VSOut) -> @location(0) vec4f {+#endif+ g_probeSlot = v.v_probeSlot;+#ifdef MESH_LIGHTMAP+ g_lightmap = v.v_lightmap;+#endif+#ifdef MESH_NORMALS+ let P = v.v_worldXYZ;+ var N = normalize(v.v_worldNormal);+#else+ let P = vec3f(v.v_worldPos.x, 0.0, v.v_worldPos.y);+ var N = vec3f(0.0, 1.0, 0.0);+#endif+ let pageA = textureSample(u_paintPages, u_paintPages_s, v.v_color.xy);+ let pageB = textureSample(u_paintPages2, u_paintPages2_s, v.v_color.xy);+ let pageNormal = textureSample(u_heightPages, u_heightPages_s, v.v_color.xy).ba * 2.0 - vec2f(1.0);+ var paintA = v.v_color;+ var paintB = vec4f(0.0);+ if (mc.u_terrainPages > 0.5) {+ let lp = P.xz - mc.u_terrainOrigin.xz;+ if (lp.x < mc.u_terrainBounds.x || lp.y < mc.u_terrainBounds.y || lp.x > mc.u_terrainBounds.z || lp.y > mc.u_terrainBounds.w) { discard; }+ paintA = pageA;+ paintB = pageB;+ N = normalize(vec3f(pageNormal.x, sqrt(max(1.0 - dot(pageNormal, pageNormal), 0.0)), pageNormal.y));+ }+ let count = i32(mc.u_layerCount + 0.5);+ var w : array<f32, 8>;+ var sum = 0.0;+ for (var i = 0; i < 8; i = i + 1) {+ var raw = 0.0;+ if (i < 4) { raw = paintA[i]; } else { raw = paintB[i - 4]; }+ let wander = tnNoise(P.xz / (tnTile(i) * 2.3) + vec2f(f32(i) * 11.0 + 3.0));+ w[i] = 0.0;+ if (i < count) { w[i] = max(raw, 0.0) * mix(1.0, 0.35 + 1.3 * wander, mc.u_blendNoise); }+ sum = sum + w[i];+ }+ var sharp = 0.0;+ for (var i = 0; i < 8; i = i + 1) { w[i] = pow(w[i] / max(sum, 1e-4), mc.u_sharpness); sharp = sharp + w[i]; }+ for (var i = 0; i < 8; i = i + 1) { w[i] = w[i] / max(sharp, 1e-4); }++ let dpx = dpdx(P);+ let dpy = dpdy(P);+ var eye = 0.0;+ if (frame.camera.w > 0.5) { eye = length(P - frame.camera.xyz); }+ let scale = tnTile(0);+ let near = (1.0 - smoothstep(scale * 20.0, scale * 45.0, eye)) * mc.u_antiTile;+ let far = smoothstep(scale * 6.0, scale * 40.0, eye) * 0.65;+ var axis = pow(abs(N), vec3f(4.0));+ axis = axis / dot(axis, vec3f(1.0));+ let side = smoothstep(mc.u_triplanarFrom, mc.u_triplanarFrom + 0.15, 1.0 - abs(N.y));+ let planes = mix(vec3f(0.0, 1.0, 0.0), axis, vec3f(side));++ var albedo : array<vec3f, 8>;+ var bend : array<vec3f, 8>;+ var mask : array<vec3f, 8>;+ for (var i = 0; i < 8; i = i + 1) {+ albedo[i] = vec3f(0.0);+ bend[i] = vec3f(0.0);+ mask[i] = vec3f(1.0, 1.0, 0.0);+ if (w[i] <= 1e-3) { continue; }+ let tile = tnTile(i);+ var top : TnTap;+ if (near > 0.01) { top = tnHex(P.xz / tile, i, dpx.xz / tile, dpy.xz / tile, near); }+ else { top = tnPlain(P.xz / tile, i, dpx.xz / tile, dpy.xz / tile); }+ if (far > 0.01) {+ let big = tile * mc.u_farScale;+ let wide = tnPlain(P.xz / big + vec2f(0.21), i, dpx.xz / big, dpy.xz / big);+ top.albedo = mix(top.albedo, wide.albedo, vec3f(far));+ top.mask = mix(top.mask, wide.mask, vec3f(far));+ }+ albedo[i] = top.albedo * planes.y;+ mask[i] = top.mask * planes.y;+ bend[i] = tnBend(top.slope, vec3f(1.0, 0.0, 0.0), vec3f(0.0, 0.0, 1.0), N) * planes.y;+ if (planes.x > 0.02) {+ let x = tnPlain(P.zy / tile, i, dpx.zy / tile, dpy.zy / tile);+ albedo[i] = albedo[i] + x.albedo * planes.x;+ mask[i] = mask[i] + x.mask * planes.x;+ bend[i] = bend[i] + tnBend(x.slope, vec3f(0.0, 0.0, 1.0), vec3f(0.0, 1.0, 0.0), N) * planes.x;+ }+ if (planes.z > 0.02) {+ let z = tnPlain(P.xy / tile, i, dpx.xy / tile, dpy.xy / tile);+ albedo[i] = albedo[i] + z.albedo * planes.z;+ mask[i] = mask[i] + z.mask * planes.z;+ bend[i] = bend[i] + tnBend(z.slope, vec3f(1.0, 0.0, 0.0), vec3f(0.0, 1.0, 0.0), N) * planes.z;+ }+ }+ var top = -1.0;+ for (var i = 0; i < 8; i = i + 1) { if (w[i] > 1e-3) { top = max(top, mask[i].b + w[i] * 1.5); } }+ var hsum = 0.0;+ var hw : array<f32, 8>;+ for (var i = 0; i < 8; i = i + 1) {+ hw[i] = 0.0;+ if (w[i] > 1e-3) { hw[i] = max(mask[i].b + w[i] * 1.5 - (top - 0.35), 0.0); }+ hsum = hsum + hw[i];+ }+ var colour = vec3f(0.0);+ var slope = vec3f(0.0);+ var surface = vec3f(0.0);+ for (var i = 0; i < 8; i = i + 1) {+ let k = mix(w[i], hw[i] / max(hsum, 1e-4), mc.u_heightBlend);+ colour = colour + albedo[i] * k;+ slope = slope + bend[i] * k;+ surface = surface + mask[i] * k;+ }+ let broad = tnNoise(P.xz / (scale * 7.3)) * 0.6 + tnNoise(P.xz / (scale * 29.0) + vec2f(5.0)) * 0.4;+ colour = colour * mix(1.0, 0.7 + 0.6 * broad, mc.u_macroVariation);+ N = normalize(N + slope);++ var wet = 0.0;+ if (mc.u_wetBand > 0.0) { wet = 1.0 - smoothstep(mc.u_wetLevel, mc.u_wetLevel + mc.u_wetBand, P.y); }+ colour = colour * mix(1.0, 0.55, wet);+ let roughness = mix(surface.g, 0.3, wet);++ let ext = surfaceExtNone(N);+ let viewDir = viewDirection(P);+ let lit = applyLightingSurface(colour, N, P, viewDir, 0.0, roughness, 0.5, surface.r, ext);+#ifdef ES_GBUFFER+ var frag : FragOut;+ frag.color = vec4f(lit, 1.0);+ frag.surface = vec4f(packNormal(N), roughness, 0.75);+ return frag;+#else+ return vec4f(lit, 1.0);+#endif+}+#pragma end+`;++export const TERRAIN_LAYERS_SHADER_TEMPLATE = makeBuiltinShaderTemplate('terrain-layers', 'Terrain Layers',+ 'Up to eight terrain layers (albedo, normal and mask arrays) weighted by the Terrain component, blended by height, projected on slopes.',+ TERRAIN_LAYERS);diff --git a/sdk/src/terrain/terrainSupport.ts b/sdk/src/terrain/terrainSupport.tsindex 2e6dadbf2..8a19109dd 100644--- a/sdk/src/terrain/terrainSupport.ts+++ b/sdk/src/terrain/terrainSupport.ts@@ -6,11 +6,15 @@* A call, not a file's side effect — see tilemap/tilemapSupport.ts.*/import { addEntryPlugin } from '../runtime/entryPlugins';+import { addAssetLoader } from '../asset/optionalLoaders';import { registerBuiltinShaderTemplate } from '../render/builtinShaders';-import { TERRAIN_SHADER_TEMPLATE } from './terrainShader';+import { TERRAIN_LAYERS_SHADER_TEMPLATE, TERRAIN_SHADER_TEMPLATE } from './terrainShader';import { TerrainPlugin } from './terrainPlugin';+import { TerrainLayerAssetLoader } from './layers';export function registerTerrainSupport(): void {registerBuiltinShaderTemplate(TERRAIN_SHADER_TEMPLATE);+ registerBuiltinShaderTemplate(TERRAIN_LAYERS_SHADER_TEMPLATE);addEntryPlugin('terrain', () => new TerrainPlugin());+ addAssetLoader('terrain', () => new TerrainLayerAssetLoader());}diff --git a/sdk/src/worldgen/plan.ts b/sdk/src/worldgen/plan.tsindex e1ba41e26..8bbdb2964 100644--- a/sdk/src/worldgen/plan.ts+++ b/sdk/src/worldgen/plan.ts@@ -152,16 +152,20 @@ export class WorldPlan {}/** The ground's paint at (x, z): `base` (grass, dirt, snow, rock) pulled toward each biome's paint by its weight and strength. */- paint(x: number, z: number, base: readonly [number, number, number, number]): [number, number, number, number] {- const out: [number, number, number, number] = [base[0], base[1], base[2], base[3]];- for (const { biome, weight } of this.biomeWeights(x, z)) {+ paint(x: number, z: number, base: readonly number[]): number[] {+ // As many layers as the ground or any biome here names (four or eight); one a biome does not name it paints nothing of.+ let n = base.length;+ const here = this.biomeWeights(x, z);+ for (const { biome } of here) n = Math.max(n, this.rules.biomes.find((d) => d.id === biome)?.paint?.length ?? 0);+ const out = Array.from({ length: n }, (_, c) => base[c] ?? 0);+ for (const { biome, weight } of here) {const b = this.rules.biomes.find((d) => d.id === biome);if (!b?.paint) continue;const k = weight * Math.min(Math.max(b.paintStrength ?? 1, 0), 1);- for (let c = 0; c < 4; c++) out[c] = out[c]! + (b.paint[c]! - base[c]!) * k;+ for (let c = 0; c < n; c++) out[c] = out[c]! + ((b.paint[c] ?? 0) - (base[c] ?? 0)) * k;}- const sum = out[0] + out[1] + out[2] + out[3] || 1;- return [out[0] / sum, out[1] / sum, out[2] / sum, out[3] / sum];+ const sum = out.reduce((a, b) => a + b, 0) || 1;+ return out.map((v) => v / sum);}/** The groups of layer `layer` whose anchors stand in [x0, x1) by [z0, z1). */diff --git a/sdk/src/worldgen/rules.ts b/sdk/src/worldgen/rules.tsindex 339fc9a92..b4cf8e210 100644--- a/sdk/src/worldgen/rules.ts+++ b/sdk/src/worldgen/rules.ts@@ -32,8 +32,8 @@ export interface BiomeDef {weight?: number;/** How far its edge wanders, in world units. */transition?: number;- /** How the ground is painted where it holds: grass, dirt, snow, rock; and how much of the ground's own paint it replaces. */- paint?: readonly [number, number, number, number];+ /** How the ground is painted where it holds: the weight of each of the terrain's layers (four, or up to eight), and how much of the ground's own paint it replaces. */+ paint?: readonly number[];paintStrength?: number;recipes: readonly BiomeRecipe[];}diff --git a/sdk/src/worldgen/worldgenPlugin.ts b/sdk/src/worldgen/worldgenPlugin.tsindex ca0cb8b82..dee8a3ab8 100644--- a/sdk/src/worldgen/worldgenPlugin.ts+++ b/sdk/src/worldgen/worldgenPlugin.ts@@ -410,7 +410,7 @@ export class WorldGenPlugin implements Plugin {/** The ground's paint by a plan's biomes. */private painter(plan: WorldPlan) {- return (x: number, z: number, _h: number, _ny: number, w: [number, number, number, number]) => plan.paint(x, z, w);+ return (x: number, z: number, _h: number, _ny: number, w: readonly number[]) => plan.paint(x, z, w);}/** Where the group of placement `id` is anchored, from the layer and grid cell its id names. */diff --git a/sdk/tests/terrain-layers.test.ts b/sdk/tests/terrain-layers.test.tsnew file mode 100644index 000000000..c1685fcc3--- /dev/null+++ b/sdk/tests/terrain-layers.test.ts@@ -0,0 +1,81 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+import { describe, expect, it } from 'vitest';+import { packLayers, parseTerrainLayer, type LayerImage } from '../src/terrain/layers';+import { FieldSource } from '../src/terrain/source';+import { makePage, PAGE_SIDE } from '../src/terrain/pages';++const solid = (size: number, rgba: [number, number, number, number]): LayerImage => {+ const pixels = new Uint8Array(size * size * 4);+ for (let k = 0; k < size * size; k++) pixels.set(rgba, k * 4);+ return { width: size, height: size, pixels };+};++describe('a terrain layer file', () => {+ it('takes what it names and puts the rest at their defaults', () => {+ const l = parseTerrainLayer({ albedo: 'assets/grass.png', tile: 3 });+ expect(l).toMatchObject({ albedo: 'assets/grass.png', normal: undefined, mask: undefined, tile: 3, tint: [1, 1, 1], roughness: 0.9, normalStrength: 1 });+ });++ it('says which field it cannot take', () => {+ expect(() => parseTerrainLayer({ tile: -1 }, 'g.esterrainlayer')).toThrow(/g\.esterrainlayer\.tile/);+ expect(() => parseTerrainLayer({ tint: [1, 1] })).toThrow(/tint/);+ });+});++describe('packing layers', () => {+ const grass = parseTerrainLayer({ tile: 2, tint: [0.5, 1, 1] });+ const rock = parseTerrainLayer({ tile: 8, roughness: 0.4, normalStrength: 0 });++ it('packs every layer at the largest texture\'s size, to a power of two within the limit', () => {+ const packed = packLayers([+ { def: grass, albedo: solid(48, [200, 100, 50, 255]), normal: null, mask: null },+ { def: rock, albedo: null, normal: solid(16, [255, 128, 128, 255]), mask: null },+ ], 1024);+ expect(packed.size).toBe(64);+ expect(packed.albedo).toHaveLength(2);+ expect(packed.albedo[0]!.length).toBe(64 * 64 * 4);+ expect(packed.tiles).toEqual([2, 8]);+ expect(packLayers([{ def: grass, albedo: solid(4096, [0, 0, 0, 255]), normal: null, mask: null }], 512).size).toBe(512);+ });++ it('multiplies the tint into the albedo through sRGB, and makes up what a layer leaves out', () => {+ const packed = packLayers([+ { def: grass, albedo: solid(16, [200, 100, 50, 255]), normal: null, mask: null },+ { def: rock, albedo: null, normal: solid(16, [255, 128, 128, 255]), mask: null },+ ]);+ const [r, g] = packed.albedo[0]!;+ expect(g).toBe(100);+ expect(r).toBe(Math.round(200 * Math.pow(0.5, 1 / 2.2)));+ // No normal: flat. A strength of 0 flattens one that bends.+ expect(Array.from(packed.normal[0]!.slice(0, 3))).toEqual([128, 128, 255]);+ expect(Array.from(packed.normal[1]!.slice(0, 3))).toEqual([128, 128, 255]);+ // No mask: no occlusion, the layer's roughness, the albedo's brightness for height (half way without an albedo).+ expect(packed.mask[1]![0]).toBe(255);+ expect(packed.mask[1]![1]).toBe(Math.round(0.4 * 255));+ expect(packed.mask[1]![2]).toBe(128);+ });+});++describe('eight layers of paint', () => {+ it('reads layers 5 to 8 from the second splatmap and pages them in the second image', () => {+ const field = { width: 2, height: 2, data: new Float32Array(4) };+ const data = { sizeX: 100, sizeZ: 100, height: 10, rockSlope: 0.35, dirtHeight: 0.62, snowHeight: 0.88 };+ const first = solid(2, [0, 0, 0, 0]), second = solid(2, [0, 255, 0, 0]);+ const source = new FieldSource(field, data, first, null, [0, 10], second);+ expect(source.paint(0, 0, 0, 1)).toEqual([0, 0, 0, 0, 0, 1, 0, 0]);+ const page = makePage(source, -50, -50, 100);+ if (page instanceof Promise) throw new Error('a field pages at once');+ const k = (Math.floor(PAGE_SIDE / 2) * PAGE_SIDE + Math.floor(PAGE_SIDE / 2)) * 4;+ expect(Array.from(page.paint.slice(k, k + 4))).toEqual([0, 0, 0, 0]);+ expect(Array.from(page.paint2.slice(k, k + 4))).toEqual([0, 255, 0, 0]);+ });++ it('leaves the second image empty for ground of four layers', () => {+ const field = { width: 2, height: 2, data: new Float32Array(4) };+ const data = { sizeX: 100, sizeZ: 100, height: 10, rockSlope: 0.35, dirtHeight: 0.62, snowHeight: 0.88 };+ const page = makePage(new FieldSource(field, data, null, null), -50, -50, 100);+ if (page instanceof Promise) throw new Error('a field pages at once');+ expect(page.paint2.every((v) => v === 0)).toBe(true);+ });+});diff --git a/tools/assetMetaTable.js b/tools/assetMetaTable.jsindex aba5b2d91..75db8f129 100644--- a/tools/assetMetaTable.js+++ b/tools/assetMetaTable.js@@ -99,6 +99,7 @@ export const EXT_TO_TYPE = Object.freeze({'.eslocale': 'locale','.esaudioevent': 'sound-event','.esworld': 'world-rules',+ '.esterrainlayer': 'terrain-layer','.inputmap': 'inputmap',// Fonts'.fnt': 'bitmapFont',diff --git a/tools/check-corpus-authoring.mjs b/tools/check-corpus-authoring.mjsindex d4493a8f7..8867a77e6 100644--- a/tools/check-corpus-authoring.mjs+++ b/tools/check-corpus-authoring.mjs@@ -66,6 +66,7 @@ const NOT_INSTANCE_FORMATS = {'.esanim': 'a clip: curves over time','.esaudioevent': 'an audio event definition; source instances belong to scenes','.esworld': 'world rules: biomes, recipes and layers as data; the WorldGen that names the file belongs to a scene',+ '.esterrainlayer': 'a terrain layer: the textures one kind of ground is drawn with; the Terrain that lists it belongs to a scene','.esavatar': 'how one rig spells the joints another rig\'s clips name','.esmaterial': 'a material: shader + uniform values','.esshader': 'shader source',diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjsindex f866af997..420cc7cc2 100644--- a/tools/releaseNotes.mjs+++ b/tools/releaseNotes.mjs@@ -2822,6 +2822,10 @@ export const NOTED = {{"note":"Foam is where waves burst, not along every shore."},"fix(water): a gentle beach keeps less of the breakers' white than rock does":{"note":"Foam is where waves burst, not along every shore."},+ "feat(terrain): up to eight terrain layers with normal and mask maps, from .esterrainlayer files, blended by height":+ {"note":"Terrain layers: up to eight kinds of ground, each with its normal and mask maps."},+ "feat(editor): terrain layer editor and a Terrain's list of layers":+ {"note":"Terrain layers: up to eight kinds of ground, each with its normal and mask maps."},"feat(render): 2D texture arrays, created from layers and sampled by textureArray material params":{"internal":"Groundwork for the terrain's layer arrays: a game has no public call that makes an array yet, so the terrain change that uses it carries the note."},};