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): an area's ground can be kept as tiles, read where it is looked at under a memory budget, with an overview for the distance
yhhe6cd2f231794
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 05245acab..3f7a340ad 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -16,6 +16,7 @@ published separately; it ships inside the editor.### Added+- **A terrain can be kept as tiles that are read where they are looked at.** A Terrain's `tiles` names a `.esterrain`: the ground cut into tiles of 513 samples a side and a low-detail overview. Distant ground is drawn from the overview, which is always in memory; full-detail tiles are read near where the view or a moving body is, and the least recently used are let go past 256 MiB. Measured in the editor on a 4096-unit area: an 8193 by 8193 field held as one image is 256 MiB, as tiles it opened holding 36 MiB and 45 MiB close to the ground. **Split into Tiles** in the terrain sculpt panel converts a terrain; tiled ground cannot be sculpted yet. The tile images are referenced only by the `.esterrain`, so they are no longer preloaded and uploaded as textures the way a `heightmap` is. The editor now also waits for ground still being built before it counts itself idle.- **A streamed world opens in the editor without its cells.** Only its `WorldPersistent` entities are in the view when a scene with `StreamedWorld` opens, and the textures and meshes of the rest are not loaded. The World panel loads and unloads cells one at a time or all at once, the viewport marks the loaded ones, and the next session opens with the same cells loaded. The document still holds every entity: an unloaded cell is saved as it is, and Play and export see the whole world. The `get_world_cells` and `set_world_cells_loaded` tools do the same for an agent.- **Hands that hold things.** A `GripPose` holds a rig's hands in a named pose: `pistol`, `handle`, `cup`, `fist` and others, or one a game registers. A pose says how far each finger bends and nothing about bones, so it fits any rig with fingers; a change of pose eases over, a trigger moves the index finger alone, and it goes over what a clip does with the fingers by its weight.- **Clouds that keep time with the game.** Where a Sky Atmosphere's clouds are is now what the wind has done so far, so a wind that changes carries them on instead of moving the whole sky; a Weather's wind reaches them, their shapes change as they go, and a paused game has a still sky. They can have a second layer with its own height, grain and wind, and `skyClockState()` keeps their place in a save. Self-shadowing reaches through a deep cloud, edges wear into billows, and the lit edge near the sun is narrower.diff --git a/desktop b/desktopindex deef867d3..d2c2a706c 160000--- a/desktop+++ b/desktop@@ -1 +1 @@-Subproject commit deef867d3fbea6e49bcbd9228e3359f4d5490337+Subproject commit d2c2a706c8e10e1cae09f20502b1b61a78dcf14cdiff --git a/docs/astro/src/content/docs/graphics/terrain.mdx b/docs/astro/src/content/docs/graphics/terrain.mdxindex 4d868e28c..bed3ec29d 100644--- a/docs/astro/src/content/docs/graphics/terrain.mdx+++ b/docs/astro/src/content/docs/graphics/terrain.mdx@@ -331,6 +331,19 @@ Such a material is drawn after a copy of the opaque scene is taken, the way wate**Snow and wet.** The `snowCover` [post effect](/docs/graphics/post-processing/) lays snow on whatever faces the sky and stands under nothing, the terrain and the rock on it alike, with no material changed: `u_amount`, `u_snowLine` and `u_snowLineBand` (the height it stops at), `u_slopeLimit` and `u_grainScale`. The `Snow` [weather](/docs/graphics/weather/) brings it. The `rain` effect with `u_intensity` at `0` and `u_wetness` up is the same for a wet ground, under no rain.+## Large ground: tiles++A heightmap is read whole: an 8193 by 8193 field is about 256 MiB. Point `tiles` at a `.esterrain` and the ground is kept as tiles of+513 by 513 samples (neighbours share their edge) and a low-detail overview.++- Distant ground is drawn from the overview, which is always in memory.+- Full-detail tiles are read only near the view or a moving body, and past 256 MiB the least recently used are let go. Where no tile has+ been read yet the height is not known, and collision and queries wait for it.+- **Split into Tiles** in the terrain sculpt panel converts a terrain. Tiled ground cannot be sculpted yet.+- The tile images are named only by the `.esterrain`, so they are not preloaded and uploaded as textures the way a `heightmap` is.++Measured in the editor on a 4096-unit area: an 8193 by 8193 field opened as tiles holds 36 MiB, and 45 MiB close to the ground.+## Limits- **It is a height for each place.** A cave, an overhang or a hole needs [Voxel Terrain](/docs/world/voxel-terrain/), a separate ground that is a volume.diff --git a/docs/astro/src/content/docs/zh-cn/graphics/terrain.mdx b/docs/astro/src/content/docs/zh-cn/graphics/terrain.mdxindex 7ad168a07..4ac7b5344 100644--- a/docs/astro/src/content/docs/zh-cn/graphics/terrain.mdx+++ b/docs/astro/src/content/docs/zh-cn/graphics/terrain.mdx@@ -255,6 +255,17 @@ registerPlanetProvider({**积雪和湿润。** `snowCover` [后处理效果](/docs/zh-cn/graphics/post-processing/)把雪铺在朝天且上方没有遮挡的表面上,地形和上面的岩石一视同仁,不用改任何材质:`u_amount`、`u_snowLine` 和 `u_snowLineBand`(雪线高度)、`u_slopeLimit`、`u_grainScale`。`Snow` [天气](/docs/zh-cn/graphics/weather/)会自动带上它。`rain` 效果把 `u_intensity` 设为 `0`、调高 `u_wetness`,就是不下雨的湿地面。+## 大块地面:分块存储++一张高度图会被整张读进内存:8193×8193 的地面约 256 MiB。把 `tiles` 指向一个 `.esterrain`,地面就按分块存储:每块 513×513 个采样(相邻块共用边),外加一张低精度的总览图。++- 远处的地面从总览图画,总览图一直在内存里。+- 视点或运动物体附近才读精细分块;超过 256 MiB 时先放掉最久没用的块。还没读到的地方高度暂时未知,碰撞和查询会等它读到后再算。+- 在地形雕刻面板里点 **拆分为分块**,就能把现有地形转换过去。转换后暂时还不能雕刻。+- 分块图只经 `.esterrain` 引用,不会像 `heightmap` 那样在打开场景时作为贴图预载、上传。++编辑器里实测(4096 单位见方):8193×8193 的地面按分块打开时占 36 MiB,贴近地面时占 45 MiB。+## 限制- **每个位置只有一个高度。** 洞穴、悬垂和孔洞需要[体积地形](/docs/zh-cn/world/voxel-terrain/),它是独立的体积地面。diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.jsonindex f50cbbba9..af2be8411 100644--- a/docs/astro/src/data/apiStability.generated.json+++ b/docs/astro/src/data/apiStability.generated.json@@ -3,10 +3,10 @@"counts": {"public": 115,"beta": 178,- "experimental": 2979,+ "experimental": 2988,"deprecated": 3},- "total": 3272,+ "total": 3281,"subsystems": [{"id": "mobile-controls",diff --git a/docs/astro/src/data/components.generated.json b/docs/astro/src/data/components.generated.jsonindex 5422d34e5..7b95e87de 100644--- a/docs/astro/src/data/components.generated.json+++ b/docs/astro/src/data/components.generated.json@@ -7546,6 +7546,12 @@"default": "none","doc": "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."},+ {+ "key": "tiles",+ "type": "string",+ "default": "empty",+ "doc": "A .esterrain: the ground as tiles, read near where it is looked at and let go far from it, with a coarse overview for the rest. Takes the heightmap's place."+ },{"key": "heightmapFormat","type": "enum",diff --git a/pipeline/src/assets/addressableManifest.ts b/pipeline/src/assets/addressableManifest.tsindex b75d145cd..c25220fb2 100644--- a/pipeline/src/assets/addressableManifest.ts+++ b/pipeline/src/assets/addressableManifest.ts@@ -39,7 +39,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', 'terrain-layer': 'json', shader: 'text',+ scene: 'json', 'anim-clip': 'json', tilemap: 'json', timeline: 'json', json: 'json', 'sound-event': 'json', 'world-rules': 'json', 'terrain-layer': 'json', 'terrain-tiles': '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 02cae3924..3db81cf41 100644--- a/pipeline/src/assets/assetDb.ts+++ b/pipeline/src/assets/assetDb.ts@@ -236,7 +236,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', 'terrain-layer',+ 'json', 'sound-event', 'world-rules', 'terrain-layer', 'terrain-tiles',]);/**diff --git a/pipeline/src/index.ts b/pipeline/src/index.tsindex 1e2a3ca4f..66d1590e1 100644--- a/pipeline/src/index.ts+++ b/pipeline/src/index.ts@@ -25,6 +25,7 @@ export * from './assets/assetDb';export * from './assets/cookAssets';export * from './assets/addressableManifest';export * from './world/staticProxy';+export * from './world/terrainTiles';export * from './bundle/importMap';export * from './bundle/esengineResolve';export * from './bundle/bundleDiagnostics';diff --git a/pipeline/src/world/terrainTiles.ts b/pipeline/src/world/terrainTiles.tsnew file mode 100644index 000000000..be277810a--- /dev/null+++ b/pipeline/src/world/terrainTiles.ts@@ -0,0 +1,86 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file terrainTiles.ts+ * @brief One area's ground cut into the tiles and overview of a `.esterrain`.+ */+import { HeightmapFormat, type Heightfield, type TerrainTilesDocument } from 'esengine';++export interface TerrainSplat { width: number; height: number; pixels: Uint8Array }++export interface SplitTerrainOptions {+ /** Project-relative directory the tiles are written under, and the stem their names start with. */+ dir: string;+ name: string;+ /** Samples along a tile's side, edges shared: a power of two plus one. */+ tileSamples?: number;+ /** Samples along the overview's longer side. */+ overviewSamples?: number;+}++export interface TerrainImageOut { width: number; height: number; rgba: Uint8Array }++export interface SplitTerrain {+ document: TerrainTilesDocument;+ documentPath: string;+ /** Project-relative path → the image to write there as a PNG, exactly (no colour conversion). */+ images: Map<string, TerrainImageOut>;+}++const clamp = (v: number, a: number, b: number): number => Math.min(Math.max(v, a), b);++function heightAt(f: Heightfield, u: number, v: number): number {+ const x = clamp(u, 0, 1) * (f.width - 1), y = clamp(v, 0, 1) * (f.height - 1);+ const i = Math.min(Math.floor(x), f.width - 2), j = Math.min(Math.floor(y), f.height - 2);+ const fx = x - i, fy = y - j, d = f.data, w = f.width;+ const a = d[j * w + i]!, b = d[j * w + i + 1]!, c = d[(j + 1) * w + i]!, e = d[(j + 1) * w + i + 1]!;+ return a + (b - a) * fx + (c - a) * fy + (a - b - c + e) * fx * fy;+}++function heightsPng(width: number, height: number, sample: (i: number, j: number) => number): TerrainImageOut {+ const out = new Uint8Array(width * height * 4);+ for (let j = 0; j < height; j++) for (let i = 0; i < width; i++) {+ const v = Math.round(clamp(sample(i, j), 0, 1) * 65535), k = (j * width + i) * 4;+ out[k] = v >> 8; out[k + 1] = v & 255; out[k + 3] = 255;+ }+ return { width, height, rgba: out };+}++function splatPng(s: TerrainSplat, width: number, height: number, u0: number, v0: number, du: number, dv: number): TerrainImageOut {+ const out = new Uint8Array(width * height * 4);+ for (let j = 0; j < height; j++) for (let i = 0; i < width; i++) {+ const x = Math.round(clamp(u0 + i * du, 0, 1) * (s.width - 1)), y = Math.round(clamp(v0 + j * dv, 0, 1) * (s.height - 1));+ out.set(s.pixels.subarray((y * s.width + x) * 4, (y * s.width + x) * 4 + 4), (j * width + i) * 4);+ }+ return { width, height, rgba: out };+}++/**+ * Cuts `field` (and its splatmaps) into tiles of `tileSamples` a side and an overview. A field whose sides are not a whole number of+ * tiles is resampled up to the next size that is, so the ground keeps its shape and its edges.+ */+export function splitTerrain(field: Heightfield, splat: TerrainSplat | null, splat2: TerrainSplat | null, options: SplitTerrainOptions): SplitTerrain {+ const t = options.tileSamples ?? 513, n = t - 1;+ if (!Number.isInteger(t) || t < 3) throw new Error('tileSamples must be a whole number of at least 3');+ const tilesX = Math.max(1, Math.ceil((field.width - 1) / n)), tilesZ = Math.max(1, Math.ceil((field.height - 1) / n));+ const sx = tilesX * n + 1, sz = tilesZ * n + 1;+ const most = Math.max(sx, sz), overviewMost = Math.min(options.overviewSamples ?? 1025, most);+ const ow = Math.max(2, Math.round((sx - 1) / (most - 1) * (overviewMost - 1)) + 1), oh = Math.max(2, Math.round((sz - 1) / (most - 1) * (overviewMost - 1)) + 1);+ const dir = options.dir.replace(/\/+$/, ''), stem = `${dir}/${options.name}`;+ const files = new Map<string, TerrainImageOut>();+ const overview = `${stem}_overview.png`;+ files.set(overview, heightsPng(ow, oh, (i, j) => heightAt(field, i / (ow - 1), j / (oh - 1))));+ const document: TerrainTilesDocument = { version: 1, tileSamples: t, tilesX, tilesZ, format: HeightmapFormat.RedGreen16, overview, tiles: [] };+ if (splat) files.set(document.overviewSplat = `${stem}_overview_splat.png`, splatPng(splat, ow, oh, 0, 0, 1 / (ow - 1), 1 / (oh - 1)));+ if (splat2) files.set(document.overviewSplat2 = `${stem}_overview_splat2.png`, splatPng(splat2, ow, oh, 0, 0, 1 / (ow - 1), 1 / (oh - 1)));+ for (let tz = 0; tz < tilesZ; tz++) for (let tx = 0; tx < tilesX; tx++) {+ const u0 = tx * n / (sx - 1), v0 = tz * n / (sz - 1), du = 1 / (sx - 1), dv = 1 / (sz - 1);+ const height = `${stem}_${tx}_${tz}.png`;+ files.set(height, heightsPng(t, t, (i, j) => heightAt(field, u0 + i * du, v0 + j * dv)));+ const entry: TerrainTilesDocument['tiles'][number] = { x: tx, z: tz, height };+ if (splat) files.set(entry.splat = `${stem}_${tx}_${tz}_splat.png`, splatPng(splat, t, t, u0, v0, du, dv));+ if (splat2) files.set(entry.splat2 = `${stem}_${tx}_${tz}_splat2.png`, splatPng(splat2, t, t, u0, v0, du, dv));+ document.tiles.push(entry);+ }+ return { document, documentPath: `${stem}.esterrain`, images: files };+}diff --git a/pipeline/tests/terrain-tiles-split.test.ts b/pipeline/tests/terrain-tiles-split.test.tsnew file mode 100644index 000000000..1b729988f--- /dev/null+++ b/pipeline/tests/terrain-tiles-split.test.ts@@ -0,0 +1,41 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+import { describe, expect, it } from 'vitest';+import { parseTerrainTiles, sampleHeight, type Heightfield } from 'esengine';+import { splitTerrain } from '../src/world/terrainTiles';++const field = (w: number, h: number): Heightfield => ({ width: w, height: h,+ data: Float32Array.from({ length: w * h }, (_, k) => 0.5 + 0.4 * Math.sin((k % w) / 13) * Math.cos(Math.floor(k / w) / 9)) });+const heights = (p: { width: number; height: number; rgba: Uint8Array }): Heightfield =>+ ({ width: p.width, height: p.height, data: Float32Array.from({ length: p.width * p.height }, (_, k) => (p.rgba[k * 4]! * 256 + p.rgba[k * 4 + 1]!) / 65535) });++describe('splitTerrain', () => {+ it('cuts a field into tiles that share their edges and give back its heights', () => {+ const f = field(129, 65);+ const out = splitTerrain(f, null, null, { dir: 'assets/ground', name: 'island', tileSamples: 33 });+ const doc = parseTerrainTiles(JSON.parse(JSON.stringify(out.document)));+ expect([doc.tilesX, doc.tilesZ, doc.tiles.length]).toEqual([4, 2, 8]);+ expect(out.documentPath).toBe('assets/ground/island.esterrain');+ const a = heights(out.images.get('assets/ground/island_0_0.png')!), b = heights(out.images.get('assets/ground/island_1_0.png')!);+ for (let j = 0; j < 33; j++) expect(a.data[j * 33 + 32]).toBe(b.data[j * 33]);+ for (let j = 0; j < 33; j += 8) for (let i = 0; i < 33; i += 8) {+ expect(b.data[j * 33 + i]).toBeCloseTo(f.data[j * 129 + 32 + i]!, 4);+ }+ });++ it('resamples a field that is not a whole number of tiles, and keeps its shape', () => {+ const f = field(100, 100);+ const out = splitTerrain(f, null, null, { dir: 'g', name: 'x', tileSamples: 33, overviewSamples: 17 });+ expect([out.document.tilesX, out.document.tilesZ]).toEqual([4, 4]);+ const o = heights(out.images.get(out.document.overview)!);+ expect([o.width, o.height]).toEqual([17, 17]);+ expect(o.data[8 * 17 + 8]).toBeCloseTo(sampleHeight(f, 0.5, 0.5), 4);+ });++ it('cuts the splatmaps with the heights', () => {+ const s = { width: 4, height: 4, pixels: Uint8Array.from({ length: 64 }, (_, k) => k * 4) };+ const out = splitTerrain(field(65, 65), s, null, { dir: 'g', name: 'x', tileSamples: 33 });+ expect(out.document.tiles.every((t) => t.splat && out.images.has(t.splat))).toBe(true);+ expect(out.images.has(out.document.overviewSplat!)).toBe(true);+ });+});diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 132c14bd4..f8fadeb27 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 · 166 beta · 2111 experimental · 3 deprecated+Symbols: 115 public · 166 beta · 2118 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental```@@ -3944,7 +3944,7 @@ Step = 15```| 'texture' | 'material' | 'shader' | 'spine-atlas' | 'spine-skeleton'| 'dragonbones-atlas' | 'dragonbones-skeleton'- | 'bitmap-font' | 'font' | 'prefab' | 'json' | 'audio' | 'sound-event' | 'world-rules' | 'terrain-layer' | 'video' | 'scene' | 'anim-clip'+ | 'bitmap-font' | 'font' | 'prefab' | 'json' | 'audio' | 'sound-event' | 'world-rules' | 'terrain-layer' | 'terrain-tiles' | 'video' | 'scene' | 'anim-clip'| 'tilemap' | 'tileset' | 'timeline' | 'mesh'| 'unknown'```@@ -11153,6 +11153,11 @@ reads: readonly string[] | undefinedwrites: readonly string[] | undefined```+## TERRAIN_TILE_BUDGET — const @experimental+```+number+```+## TEXTURE_STREAMING_DEFAULTS — const @experimental```TextureStreamingOptions@@ -11305,6 +11310,7 @@ sizeZ: numbersnowHeight: numbersplatmap2: numbersplatmap: number+tiles: stringwarp: numberworld: string```@@ -11314,6 +11320,14 @@ world: string{ readonly Area: 0; readonly Infinite: 1; }```+## TerrainImage — interface @experimental+```+height: number+pixels: Uint8Array<ArrayBufferLike>+wide: Uint16Array<ArrayBufferLike> | undefined+width: number+```+## TerrainLayerAssetLoader — class @experimental```extensions: string[]@@ -11414,6 +11428,37 @@ reason: string | undefinedstate: "failed" | "ready" | "loading"```+## TerrainTileEntry — interface @experimental+```+height: string+splat2: string | undefined+splat: string | undefined+x: number+z: number+```++## TerrainTileStats — interface @experimental+```+bytes: number+evictions: number+reading: number+reads: number+resident: number+```++## TerrainTilesDocument — interface @experimental+```+format: number+overview: string+overviewSplat2: string | undefined+overviewSplat: string | undefined+tileSamples: number+tiles: TerrainTileEntry[]+tilesX: number+tilesZ: number+version: 1+```+## TerrainUnavailable — class @experimental```static new (message?: string): TerrainUnavailable@@ -11865,6 +11910,28 @@ label: numbertitle: number```+## TiledSource — class @experimental+```+bounds: readonly [number, number, number, number]+budget: number+doc: TerrainTilesDocument+height: (x: number, z: number) => number | null+infinite: false+maxHeight: number+minHeight: 0+normal: (x: number, z: number) => [number, number, number] | null+overviewBytes: number+overviewSpacing: number+paint: (x: number, z: number, h: number, ny: number) => LayerWeights+region: (x0: number, z0: number, spacing: number, count: number) => TerrainRegionSamples | Promise<TerrainRegionSamples>+samplesX: number+samplesZ: number+stats: () => TerrainTileStats+trim: (keep?: ReadonlySet<string>) => void+static new (doc: TerrainTilesDocument, params: Params, overview: Heightfield, overviewSplat: Splat | null, overviewSplat2: Splat | null, read: (path: string) => Promise<TerrainImage | null>, budget?: number): TiledSource+static prototype: TiledSource+```+## Time — const @public```ResourceDef<TimeData>@@ -16516,6 +16583,11 @@ MeshRendererPlugin(json: unknown, file?: string): TerrainLayerDef```+## parseTerrainTiles — function @experimental+```+(json: unknown, file?: string): TerrainTilesDocument+```+## parseThemeOverrides — function @experimental```(colors?: Record<string, string>): ThemeOverrides | undefineddiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex bde9048ec..a56fa7443 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 · 171 beta · 2130 experimental · 3 deprecated+Symbols: 115 public · 171 beta · 2137 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental```@@ -3952,7 +3952,7 @@ Step = 15```| 'texture' | 'material' | 'shader' | 'spine-atlas' | 'spine-skeleton'| 'dragonbones-atlas' | 'dragonbones-skeleton'- | 'bitmap-font' | 'font' | 'prefab' | 'json' | 'audio' | 'sound-event' | 'world-rules' | 'terrain-layer' | 'video' | 'scene' | 'anim-clip'+ | 'bitmap-font' | 'font' | 'prefab' | 'json' | 'audio' | 'sound-event' | 'world-rules' | 'terrain-layer' | 'terrain-tiles' | 'video' | 'scene' | 'anim-clip'| 'tilemap' | 'tileset' | 'timeline' | 'mesh'| 'unknown'```@@ -11369,6 +11369,11 @@ reads: readonly string[] | undefinedwrites: readonly string[] | undefined```+## TERRAIN_TILE_BUDGET — const @experimental+```+number+```+## TEXTURE_STREAMING_DEFAULTS — const @experimental```TextureStreamingOptions@@ -11521,6 +11526,7 @@ sizeZ: numbersnowHeight: numbersplatmap2: numbersplatmap: number+tiles: stringwarp: numberworld: string```@@ -11530,6 +11536,14 @@ world: string{ readonly Area: 0; readonly Infinite: 1; }```+## TerrainImage — interface @experimental+```+height: number+pixels: Uint8Array<ArrayBufferLike>+wide: Uint16Array<ArrayBufferLike> | undefined+width: number+```+## TerrainLayerAssetLoader — class @experimental```extensions: string[]@@ -11630,6 +11644,37 @@ reason: string | undefinedstate: "failed" | "ready" | "loading"```+## TerrainTileEntry — interface @experimental+```+height: string+splat2: string | undefined+splat: string | undefined+x: number+z: number+```++## TerrainTileStats — interface @experimental+```+bytes: number+evictions: number+reading: number+reads: number+resident: number+```++## TerrainTilesDocument — interface @experimental+```+format: number+overview: string+overviewSplat2: string | undefined+overviewSplat: string | undefined+tileSamples: number+tiles: TerrainTileEntry[]+tilesX: number+tilesZ: number+version: 1+```+## TerrainUnavailable — class @experimental```static new (message?: string): TerrainUnavailable@@ -12081,6 +12126,28 @@ label: numbertitle: number```+## TiledSource — class @experimental+```+bounds: readonly [number, number, number, number]+budget: number+doc: TerrainTilesDocument+height: (x: number, z: number) => number | null+infinite: false+maxHeight: number+minHeight: 0+normal: (x: number, z: number) => [number, number, number] | null+overviewBytes: number+overviewSpacing: number+paint: (x: number, z: number, h: number, ny: number) => LayerWeights+region: (x0: number, z0: number, spacing: number, count: number) => TerrainRegionSamples | Promise<TerrainRegionSamples>+samplesX: number+samplesZ: number+stats: () => TerrainTileStats+trim: (keep?: ReadonlySet<string>) => void+static new (doc: TerrainTilesDocument, params: Params, overview: Heightfield, overviewSplat: Splat | null, overviewSplat2: Splat | null, read: (path: string) => Promise<TerrainImage | null>, budget?: number): TiledSource+static prototype: TiledSource+```+## Time — const @public```ResourceDef<TimeData>@@ -16782,6 +16849,11 @@ MeshRendererPlugin(json: unknown, file?: string): TerrainLayerDef```+## parseTerrainTiles — function @experimental+```+(json: unknown, file?: string): TerrainTilesDocument+```+## parseThemeOverrides — function @experimental```(colors?: Record<string, string>): ThemeOverrides | undefineddiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 898cb732c..7f402230e 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 · 168 beta · 2110 experimental · 3 deprecated+Symbols: 115 public · 168 beta · 2117 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -3939,7 +3939,7 @@ Step = 15```| 'texture' | 'material' | 'shader' | 'spine-atlas' | 'spine-skeleton'| 'dragonbones-atlas' | 'dragonbones-skeleton'- | 'bitmap-font' | 'font' | 'prefab' | 'json' | 'audio' | 'sound-event' | 'world-rules' | 'terrain-layer' | 'video' | 'scene' | 'anim-clip'+ | 'bitmap-font' | 'font' | 'prefab' | 'json' | 'audio' | 'sound-event' | 'world-rules' | 'terrain-layer' | 'terrain-tiles' | 'video' | 'scene' | 'anim-clip'| 'tilemap' | 'tileset' | 'timeline' | 'mesh'| 'unknown'```@@ -11148,6 +11148,11 @@ reads: readonly string[] | undefinedwrites: readonly string[] | undefined```+## TERRAIN_TILE_BUDGET — const @experimental+```+number+```+## TEXTURE_STREAMING_DEFAULTS — const @experimental```TextureStreamingOptions@@ -11300,6 +11305,7 @@ sizeZ: numbersnowHeight: numbersplatmap2: numbersplatmap: number+tiles: stringwarp: numberworld: string```@@ -11309,6 +11315,14 @@ world: string{ readonly Area: 0; readonly Infinite: 1; }```+## TerrainImage — interface @experimental+```+height: number+pixels: Uint8Array<ArrayBufferLike>+wide: Uint16Array<ArrayBufferLike> | undefined+width: number+```+## TerrainLayerAssetLoader — class @experimental```extensions: string[]@@ -11409,6 +11423,37 @@ reason: string | undefinedstate: "failed" | "ready" | "loading"```+## TerrainTileEntry — interface @experimental+```+height: string+splat2: string | undefined+splat: string | undefined+x: number+z: number+```++## TerrainTileStats — interface @experimental+```+bytes: number+evictions: number+reading: number+reads: number+resident: number+```++## TerrainTilesDocument — interface @experimental+```+format: number+overview: string+overviewSplat2: string | undefined+overviewSplat: string | undefined+tileSamples: number+tiles: TerrainTileEntry[]+tilesX: number+tilesZ: number+version: 1+```+## TerrainUnavailable — class @experimental```static new (message?: string): TerrainUnavailable@@ -11860,6 +11905,28 @@ label: numbertitle: number```+## TiledSource — class @experimental+```+bounds: readonly [number, number, number, number]+budget: number+doc: TerrainTilesDocument+height: (x: number, z: number) => number | null+infinite: false+maxHeight: number+minHeight: 0+normal: (x: number, z: number) => [number, number, number] | null+overviewBytes: number+overviewSpacing: number+paint: (x: number, z: number, h: number, ny: number) => LayerWeights+region: (x0: number, z0: number, spacing: number, count: number) => TerrainRegionSamples | Promise<TerrainRegionSamples>+samplesX: number+samplesZ: number+stats: () => TerrainTileStats+trim: (keep?: ReadonlySet<string>) => void+static new (doc: TerrainTilesDocument, params: Params, overview: Heightfield, overviewSplat: Splat | null, overviewSplat2: Splat | null, read: (path: string) => Promise<TerrainImage | null>, budget?: number): TiledSource+static prototype: TiledSource+```+## Time — const @public```ResourceDef<TimeData>@@ -16521,6 +16588,11 @@ NodePlatformAdapter(json: unknown, file?: string): TerrainLayerDef```+## parseTerrainTiles — function @experimental+```+(json: unknown, file?: string): TerrainTilesDocument+```+## parseThemeOverrides — function @experimental```(colors?: Record<string, string>): ThemeOverrides | undefineddiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex bbf57255b..b22feda2d 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 · 166 beta · 2132 experimental · 3 deprecated+Symbols: 115 public · 166 beta · 2139 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -3939,7 +3939,7 @@ Step = 15```| 'texture' | 'material' | 'shader' | 'spine-atlas' | 'spine-skeleton'| 'dragonbones-atlas' | 'dragonbones-skeleton'- | 'bitmap-font' | 'font' | 'prefab' | 'json' | 'audio' | 'sound-event' | 'world-rules' | 'terrain-layer' | 'video' | 'scene' | 'anim-clip'+ | 'bitmap-font' | 'font' | 'prefab' | 'json' | 'audio' | 'sound-event' | 'world-rules' | 'terrain-layer' | 'terrain-tiles' | 'video' | 'scene' | 'anim-clip'| 'tilemap' | 'tileset' | 'timeline' | 'mesh'| 'unknown'```@@ -11444,6 +11444,11 @@ reads: readonly string[] | undefinedwrites: readonly string[] | undefined```+## TERRAIN_TILE_BUDGET — const @experimental+```+number+```+## TEXTURE_STREAMING_DEFAULTS — const @experimental```TextureStreamingOptions@@ -11596,6 +11601,7 @@ sizeZ: numbersnowHeight: numbersplatmap2: numbersplatmap: number+tiles: stringwarp: numberworld: string```@@ -11605,6 +11611,14 @@ world: string{ readonly Area: 0; readonly Infinite: 1; }```+## TerrainImage — interface @experimental+```+height: number+pixels: Uint8Array<ArrayBufferLike>+wide: Uint16Array<ArrayBufferLike> | undefined+width: number+```+## TerrainLayerAssetLoader — class @experimental```extensions: string[]@@ -11705,6 +11719,37 @@ reason: string | undefinedstate: "failed" | "ready" | "loading"```+## TerrainTileEntry — interface @experimental+```+height: string+splat2: string | undefined+splat: string | undefined+x: number+z: number+```++## TerrainTileStats — interface @experimental+```+bytes: number+evictions: number+reading: number+reads: number+resident: number+```++## TerrainTilesDocument — interface @experimental+```+format: number+overview: string+overviewSplat2: string | undefined+overviewSplat: string | undefined+tileSamples: number+tiles: TerrainTileEntry[]+tilesX: number+tilesZ: number+version: 1+```+## TerrainUnavailable — class @experimental```static new (message?: string): TerrainUnavailable@@ -12156,6 +12201,28 @@ label: numbertitle: number```+## TiledSource — class @experimental+```+bounds: readonly [number, number, number, number]+budget: number+doc: TerrainTilesDocument+height: (x: number, z: number) => number | null+infinite: false+maxHeight: number+minHeight: 0+normal: (x: number, z: number) => [number, number, number] | null+overviewBytes: number+overviewSpacing: number+paint: (x: number, z: number, h: number, ny: number) => LayerWeights+region: (x0: number, z0: number, spacing: number, count: number) => TerrainRegionSamples | Promise<TerrainRegionSamples>+samplesX: number+samplesZ: number+stats: () => TerrainTileStats+trim: (keep?: ReadonlySet<string>) => void+static new (doc: TerrainTilesDocument, params: Params, overview: Heightfield, overviewSplat: Splat | null, overviewSplat2: Splat | null, read: (path: string) => Promise<TerrainImage | null>, budget?: number): TiledSource+static prototype: TiledSource+```+## Time — const @public```ResourceDef<TimeData>@@ -16828,6 +16895,11 @@ MeshRendererPlugin(json: unknown, file?: string): TerrainLayerDef```+## parseTerrainTiles — function @experimental+```+(json: unknown, file?: string): TerrainTilesDocument+```+## parseThemeOverrides — function @experimental```(colors?: Record<string, string>): ThemeOverrides | undefineddiff --git a/sdk/etc/terrain.api.md b/sdk/etc/terrain.api.mdindex 39057c8c3..f8ec5388d 100644--- a/sdk/etc/terrain.api.md+++ b/sdk/etc/terrain.api.md@@ -495,6 +495,7 @@ sizeZ: numbersnowHeight: numbersplatmap2: numbersplatmap: number+tiles: stringwarp: numberworld: string```@@ -530,6 +531,7 @@ tint: [number, number, number]```cpuBytes: numberloading: number+tiles: number```## TerrainModifier — interface @experimentaldiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex afd51479a..e4ca341a2 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 · 166 beta · 2123 experimental · 3 deprecated+Symbols: 115 public · 166 beta · 2130 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -3939,7 +3939,7 @@ Step = 15```| 'texture' | 'material' | 'shader' | 'spine-atlas' | 'spine-skeleton'| 'dragonbones-atlas' | 'dragonbones-skeleton'- | 'bitmap-font' | 'font' | 'prefab' | 'json' | 'audio' | 'sound-event' | 'world-rules' | 'terrain-layer' | 'video' | 'scene' | 'anim-clip'+ | 'bitmap-font' | 'font' | 'prefab' | 'json' | 'audio' | 'sound-event' | 'world-rules' | 'terrain-layer' | 'terrain-tiles' | 'video' | 'scene' | 'anim-clip'| 'tilemap' | 'tileset' | 'timeline' | 'mesh'| 'unknown'```@@ -11155,6 +11155,11 @@ reads: readonly string[] | undefinedwrites: readonly string[] | undefined```+## TERRAIN_TILE_BUDGET — const @experimental+```+number+```+## TEXTURE_STREAMING_DEFAULTS — const @experimental```TextureStreamingOptions@@ -11307,6 +11312,7 @@ sizeZ: numbersnowHeight: numbersplatmap2: numbersplatmap: number+tiles: stringwarp: numberworld: string```@@ -11316,6 +11322,14 @@ world: string{ readonly Area: 0; readonly Infinite: 1; }```+## TerrainImage — interface @experimental+```+height: number+pixels: Uint8Array<ArrayBufferLike>+wide: Uint16Array<ArrayBufferLike> | undefined+width: number+```+## TerrainLayerAssetLoader — class @experimental```extensions: string[]@@ -11416,6 +11430,37 @@ reason: string | undefinedstate: "failed" | "ready" | "loading"```+## TerrainTileEntry — interface @experimental+```+height: string+splat2: string | undefined+splat: string | undefined+x: number+z: number+```++## TerrainTileStats — interface @experimental+```+bytes: number+evictions: number+reading: number+reads: number+resident: number+```++## TerrainTilesDocument — interface @experimental+```+format: number+overview: string+overviewSplat2: string | undefined+overviewSplat: string | undefined+tileSamples: number+tiles: TerrainTileEntry[]+tilesX: number+tilesZ: number+version: 1+```+## TerrainUnavailable — class @experimental```static new (message?: string): TerrainUnavailable@@ -11867,6 +11912,28 @@ label: numbertitle: number```+## TiledSource — class @experimental+```+bounds: readonly [number, number, number, number]+budget: number+doc: TerrainTilesDocument+height: (x: number, z: number) => number | null+infinite: false+maxHeight: number+minHeight: 0+normal: (x: number, z: number) => [number, number, number] | null+overviewBytes: number+overviewSpacing: number+paint: (x: number, z: number, h: number, ny: number) => LayerWeights+region: (x0: number, z0: number, spacing: number, count: number) => TerrainRegionSamples | Promise<TerrainRegionSamples>+samplesX: number+samplesZ: number+stats: () => TerrainTileStats+trim: (keep?: ReadonlySet<string>) => void+static new (doc: TerrainTilesDocument, params: Params, overview: Heightfield, overviewSplat: Splat | null, overviewSplat2: Splat | null, read: (path: string) => Promise<TerrainImage | null>, budget?: number): TiledSource+static prototype: TiledSource+```+## Time — const @public```ResourceDef<TimeData>@@ -16554,6 +16621,11 @@ MeshRendererPlugin(json: unknown, file?: string): TerrainLayerDef```+## parseTerrainTiles — function @experimental+```+(json: unknown, file?: string): TerrainTilesDocument+```+## parseThemeOverrides — function @experimental```(colors?: Record<string, string>): ThemeOverrides | undefineddiff --git a/sdk/src/assetTypes.ts b/sdk/src/assetTypes.tsindex 3334e7b78..223fccd3d 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' | 'terrain-layer' | 'video' | 'scene' | 'anim-clip'+ | 'bitmap-font' | 'font' | 'prefab' | 'json' | 'audio' | 'sound-event' | 'world-rules' | 'terrain-layer' | 'terrain-tiles' | 'video' | 'scene' | 'anim-clip'| 'tilemap' | 'tileset' | 'timeline' | 'mesh'| 'unknown';@@ -82,6 +82,7 @@ const ASSET_TYPE_REGISTRY: readonly AssetTypeEntry[] = [{ 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 },+ { extensions: ['esterrain'], contentType: 'json', editorType: 'terrain-tiles', 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 20d7b5d42..66b32597f 100644--- a/sdk/src/core-content.ts+++ b/sdk/src/core-content.ts@@ -878,6 +878,7 @@ export {type Eroded, type ErosionParams, type Heightfield, type ProceduralParams,} from './terrain/heightfield';export { FieldSource, NoiseSource, ModifiedSource, flattenModifier, noised, type LayerWeights, type NoiseParams, type Splat, type TerrainRegionSamples, type TerrainSource, type TerrainModifier } from './terrain/source';+export { TiledSource, parseTerrainTiles, TERRAIN_TILE_BUDGET, type TerrainTilesDocument, type TerrainTileEntry, type TerrainTileStats, type TerrainImage } from './terrain/tiles';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';diff --git a/sdk/src/terrain/terrainPlugin.ts b/sdk/src/terrain/terrainPlugin.tsindex bc3a8a8f2..ff93df0c4 100644--- a/sdk/src/terrain/terrainPlugin.ts+++ b/sdk/src/terrain/terrainPlugin.ts@@ -54,6 +54,7 @@ import { chunksOf, ProceduralChunksRes } from '../residency/chunks';import { movers } from './movers';import { createLayerArrays, imagePixelsAt, readAndPackLayers, releaseLayerArrays } from './layerArrays';import { createPageAtlases } from './atlases';+import { parseTerrainTiles, TiledSource } from './tiles';/** The engine's own provider of ground without end: seeded noise of the world's position. */export const NOISE_PROVIDER = 'estella:noise';@@ -75,6 +76,8 @@ export interface TerrainData {generatorVersion: number;/** A heightmap image, read as {@link heightmapFormat} says. Empty makes the ground from noise. */heightmap: number;+ /** A `.esterrain` (project path): the area's ground as tiles read where they are looked at, and an overview for the rest. Takes the heightmap's place. */+ tiles: string;/** How the heightmap holds its heights: a {@link HeightmapFormat}. */heightmapFormat: number;/** An image whose four channels are the weights of layers 1 to 4; empty paints by height and slope. */@@ -134,7 +137,7 @@ const rgb = (r: number, g: number, b: number): Color => ({ r, g, b, a: 1 });* @experimental*/export const Terrain: ComponentDef<TerrainData> = /* @__PURE__ */ defineComponent<TerrainData>('Terrain', {- extent: TerrainExtent.Area, provider: NOISE_PROVIDER, world: '', generatorVersion: 1, heightmap: 0, heightmapFormat: HeightmapFormat.Grey, splatmap: 0, splatmap2: 0, layers: [] as string[], material: 0,+ extent: TerrainExtent.Area, provider: NOISE_PROVIDER, world: '', generatorVersion: 1, heightmap: 0, tiles: '', 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,@@ -148,6 +151,7 @@ export const Terrain: ComponentDef<TerrainData> = /* @__PURE__ */ defineComponenworld: { category: 'Shape', tooltip: 'The world (a planet, a level) the ground belongs to, as the game names it; handed to the provider.' },generatorVersion: { min: 1, step: 1, category: 'Shape', tooltip: 'The generator version the world was made with. A version the provider no longer has fails the terrain rather than growing other ground under what was built.' },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] } },+ tiles: { category: 'Shape', tooltip: 'A .esterrain: the ground as tiles, read near where it is looked at and let go far from it, with a coarse overview for the rest. Takes the heightmap\'s place.', 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] } },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] } },@@ -234,7 +238,7 @@ interface Built {/** Where a terrain's ground stands: still being made, ready, or failed (with why). */export interface TerrainStatus { state: 'loading' | 'ready' | 'failed'; reason?: string }-export interface TerrainLoad { loading: number; cpuBytes: number }+export interface TerrainLoad { loading: number; cpuBytes: number; tiles: number }/** Run-time access to the ground: how high it is anywhere, for putting things on it. */export class Terrains {@@ -432,15 +436,22 @@ export class Terrains {}load(): TerrainLoad {- let loading = 0, cpuBytes = 0;+ let loading = 0, cpuBytes = 0, tiles = 0;for (const built of this.built_.values()) {if (built.loading) loading++;const source = built.source instanceof ModifiedSource ? built.source.base : built.source;+ if (source instanceof TiledSource) {+ const s = source.stats();+ loading += s.reading;+ cpuBytes += s.bytes + source.overviewBytes;+ tiles += s.resident;+ continue;+ }if (!(source instanceof FieldSource)) continue;const { a, b } = source.splats();cpuBytes += source.field.data.byteLength + (a?.pixels.byteLength ?? 0) + (b?.pixels.byteLength ?? 0);}- return { loading, cpuBytes };+ return { loading, cpuBytes, tiles };}/** @internal The modifiers laid over every terrain's ground, by id, in the order they were set. */@@ -543,12 +554,23 @@ function signatureOf(data: TerrainData, at: { x: number; z: number }): string {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;+ const fromProvider = data.extent === TerrainExtent.Infinite || (!data.heightmap && !data.tiles);const where = fromProvider ? `@${at.x},${at.z}` : '';const late = fromProvider && data.provider !== NOISE_PROVIDER ? `#${terrainProvidersRevision()}` : '';return `${JSON.stringify(shape)}${where}${late}`;}+async function tiledSourceOf(app: App, data: TerrainData): Promise<TiledSource> {+ const assets = app.getResource(Assets);+ const doc = parseTerrainTiles(JSON.parse(await assets.fetchText(data.tiles)), data.tiles);+ const read = (path: string) => imagePixelsAt(app, path);+ const [overview, s1, s2] = await Promise.all([read(doc.overview), doc.overviewSplat ? read(doc.overviewSplat) : null, doc.overviewSplat2 ? read(doc.overviewSplat2) : null]);+ if (!overview) throw new TerrainUnavailable(`the overview of ${data.tiles} (${doc.overview}) could not be read`);+ const field = heightfieldFromPixels(overview.width, overview.height, overview.pixels, doc.format, overview.wide);+ const splat = (s: typeof s1) => s && { width: s.width, height: s.height, pixels: s.pixels };+ return new TiledSource(doc, data, field, splat(s1), splat(s2), read);+}+/** The provider a terrain names, or why it cannot have it. */function providerOf(data: TerrainData): TerrainProvider {const provider = data.provider === NOISE_PROVIDER ? noiseProvider(() => data) : terrainProvider(data.provider);@@ -661,6 +683,9 @@ export class TerrainPlugin implements Plugin {const provider = providerOf(data);built.source = new ProviderSource(provider, data.world, data.seed, data.generatorVersion, t.worldPosition.x, t.worldPosition.z,Math.max(data.cellSize, 1e-3), paintBy(provider, data));+ } else if (data.tiles) {+ built.source = await tiledSourceOf(app, data);+ if (built.epoch !== epoch || !app.world.valid(entity)) return;} else {// A heightmap named and not read is a failure: a world built on that ground must not quietly get other ground.const height = await this.pixelsOf(app, data.heightmap);diff --git a/sdk/src/terrain/tiles.ts b/sdk/src/terrain/tiles.tsnew file mode 100644index 000000000..5b52301d0--- /dev/null+++ b/sdk/src/terrain/tiles.ts@@ -0,0 +1,278 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file tiles.ts+ * @brief An area's ground kept as tiles (`.esterrain`): a coarse overview always in memory, and full-detail tiles read near where+ * they are looked at and let go, least recently used first, past a budget.+ *+ * @details Tiles share their edge samples, so tile (tx, tz) of `tileSamples` a side covers the area's samples+ * [tx (tileSamples - 1), (tx + 1)(tileSamples - 1)] along x and the same along z. A page as coarse as the overview or coarser is+ * made from it alone; a finer one waits for the tiles it covers. A height where no tile is in memory is not known yet (null),+ * as with a provider: collision and queries try again once it is.+ */+import { paintWeights } from './paint';+import { HeightmapFormat, heightfieldFromPixels, type Heightfield } from './heightfield';+import type { TerrainData } from './terrainPlugin';+import type { LayerWeights, Splat, TerrainRegionSamples, TerrainSource } from './source';++/** One tile of a `.esterrain`, by its place in the grid and the project paths of its images. @experimental */+export interface TerrainTileEntry { x: number; z: number; height: string; splat?: string; splat2?: string }++/** A `.esterrain` document. @experimental */+export interface TerrainTilesDocument {+ version: 1;+ /** Samples along a tile's side, its edges shared with its neighbours. */+ tileSamples: number;+ tilesX: number;+ tilesZ: number;+ /** How the tile and overview images hold their heights: a {@link HeightmapFormat}. */+ format: number;+ /** The whole area at low detail, always in memory: what distant ground is drawn from. */+ overview: string;+ overviewSplat?: string;+ overviewSplat2?: string;+ tiles: TerrainTileEntry[];+}++/** An image's pixels as the terrain reads them. */+export interface TerrainImage { width: number; height: number; pixels: Uint8Array; wide?: Uint16Array }++/** What a tiled ground holds in memory and is reading. @experimental */+export interface TerrainTileStats { resident: number; reading: number; bytes: number; reads: number; evictions: number }++/** A `.esterrain` checked, or a message naming what is wrong with it. */+export function parseTerrainTiles(json: unknown, file = 'terrain tiles'): TerrainTilesDocument {+ const o = json as Partial<TerrainTilesDocument> | null;+ if (!o || typeof o !== 'object' || o.version !== 1) throw new Error(`${file}: not a version 1 terrain`);+ const whole = (v: unknown, min: number): v is number => typeof v === 'number' && Number.isInteger(v) && v >= min;+ if (!whole(o.tileSamples, 3) || !whole(o.tilesX, 1) || !whole(o.tilesZ, 1)) throw new Error(`${file}: tileSamples, tilesX and tilesZ must be whole numbers`);+ if (typeof o.overview !== 'string' || !o.overview) throw new Error(`${file}: names no overview image`);+ if (!Array.isArray(o.tiles)) throw new Error(`${file}: has no tile list`);+ const seen = new Set<string>();+ for (const t of o.tiles) {+ if (!whole(t?.x, 0) || !whole(t?.z, 0) || t.x >= o.tilesX || t.z >= o.tilesZ || typeof t.height !== 'string') {+ throw new Error(`${file}: tile ${JSON.stringify(t)} is outside the ${o.tilesX} by ${o.tilesZ} grid or names no heights`);+ }+ if (seen.has(`${t.x}:${t.z}`)) throw new Error(`${file}: tile ${t.x}, ${t.z} is listed twice`);+ seen.add(`${t.x}:${t.z}`);+ }+ return { version: 1, tileSamples: o.tileSamples, tilesX: o.tilesX, tilesZ: o.tilesZ, format: o.format ?? HeightmapFormat.RedGreen16,+ overview: o.overview, overviewSplat: o.overviewSplat, overviewSplat2: o.overviewSplat2, tiles: o.tiles };+}++interface Tile { field: Heightfield; splat: Splat | null; splat2: Splat | null; bytes: number; used: number }++type Params = Pick<TerrainData, 'sizeX' | 'sizeZ' | 'height' | 'rockSlope' | 'dirtHeight' | 'snowHeight'>;++/** The default most a tiled ground keeps of its full-detail tiles in memory. */+export const TERRAIN_TILE_BUDGET = 256 * 1024 * 1024;++/** An area's ground read from tiles. @experimental */+export class TiledSource implements TerrainSource {+ readonly infinite = false;+ readonly bounds: readonly [number, number, number, number];+ readonly minHeight = 0;+ readonly maxHeight: number;+ /** Samples along the whole area's sides. */+ readonly samplesX: number;+ readonly samplesZ: number;+ private readonly entries_ = new Map<string, TerrainTileEntry>();+ private readonly tiles_ = new Map<string, Tile>();+ private readonly reading_ = new Map<string, Promise<Tile | null>>();+ private clock_ = 0;+ private bytes_ = 0;+ private reads_ = 0;+ private evictions_ = 0;++ constructor(+ readonly doc: TerrainTilesDocument,+ private readonly params: Params,+ private readonly overview: Heightfield,+ private readonly overviewSplat: Splat | null,+ private readonly overviewSplat2: Splat | null,+ private readonly read: (path: string) => Promise<TerrainImage | null>,+ readonly budget = TERRAIN_TILE_BUDGET,+ ) {+ this.bounds = [-params.sizeX / 2, -params.sizeZ / 2, params.sizeX / 2, params.sizeZ / 2];+ this.maxHeight = params.height;+ this.samplesX = doc.tilesX * (doc.tileSamples - 1) + 1;+ this.samplesZ = doc.tilesZ * (doc.tileSamples - 1) + 1;+ for (const t of doc.tiles) this.entries_.set(`${t.x}:${t.z}`, t);+ }++ stats(): TerrainTileStats {+ return { resident: this.tiles_.size, reading: this.reading_.size, bytes: this.bytes_, reads: this.reads_, evictions: this.evictions_ };+ }++ /** Bytes the overview holds, which stay for as long as the ground does. */+ get overviewBytes(): number {+ return this.overview.data.byteLength + (this.overviewSplat?.pixels.byteLength ?? 0) + (this.overviewSplat2?.pixels.byteLength ?? 0);+ }++ /** The world-unit spacing of the overview's samples along x: pages this coarse or coarser are made from it alone. */+ get overviewSpacing(): number {+ return this.params.sizeX / Math.max(this.overview.width - 1, 1);+ }++ height(x: number, z: number): number | null {+ const at = this.locate(x, z), tile = this.tile(at.key);+ if (!tile) {+ void this.ensure(at.key);+ return null;+ }+ return this.params.height * bilinear(tile.field.data, tile.field.width, at.lx, at.lz);+ }++ normal(x: number, z: number): [number, number, number] | null {+ const e = this.params.sizeX / (this.samplesX - 1);+ const l = this.height(x - e, z), r = this.height(x + e, z), d = this.height(x, z - e), u = this.height(x, z + e);+ if (l === null || r === null || d === null || u === null) return null;+ const sx = (r - l) / (2 * e), sz = (u - d) / (2 * e), len = Math.hypot(sx, 1, sz);+ return [-sx / len, 1 / len, -sz / len];+ }++ paint(x: number, z: number, h: number, ny: number): LayerWeights {+ const at = this.locate(x, z), tile = this.tile(at.key);+ const u = x / this.params.sizeX + 0.5, v = z / this.params.sizeZ + 0.5;+ if (tile?.splat) return weights(tile.splat, tile.splat2, at.lx / (this.doc.tileSamples - 1), at.lz / (this.doc.tileSamples - 1));+ if (this.overviewSplat) return weights(this.overviewSplat, this.overviewSplat2, u, v);+ return paintWeights((h - this.minHeight) / Math.max(this.maxHeight, 1e-6), ny, this.params);+ }++ region(x0: number, z0: number, spacing: number, count: number): TerrainRegionSamples | Promise<TerrainRegionSamples> {+ if (spacing >= this.overviewSpacing * 0.999) return this.fromOverview(x0, z0, spacing, count);+ const far = x0 + spacing * (count - 1), farZ = z0 + spacing * (count - 1);+ const keys = this.keysOver(x0, z0, far, farZ);+ const missing = keys.filter((k) => !this.tiles_.has(k) && this.entries_.has(k));+ for (const k of keys) this.tile(k);+ if (missing.length === 0) return this.fromTiles(x0, z0, spacing, count);+ return Promise.all(missing.map((k) => this.ensure(k))).then(() => {+ for (const k of keys) this.tile(k);+ return this.fromTiles(x0, z0, spacing, count);+ });+ }++ /** Lets go of tiles, least recently used first, until what is held is within the budget; those in `keep` stay. */+ trim(keep: ReadonlySet<string> = new Set()): void {+ if (this.bytes_ <= this.budget) return;+ const order = [...this.tiles_].filter(([k]) => !keep.has(k)).sort((a, b) => a[1].used - b[1].used);+ for (const [key, tile] of order) {+ if (this.bytes_ <= this.budget) break;+ this.tiles_.delete(key);+ this.bytes_ -= tile.bytes;+ this.evictions_++;+ }+ }++ private tile(key: string): Tile | undefined {+ const t = this.tiles_.get(key);+ if (t) t.used = ++this.clock_;+ return t;+ }++ private ensure(key: string): Promise<Tile | null> {+ const have = this.tiles_.get(key);+ if (have) return Promise.resolve(have);+ const reading = this.reading_.get(key);+ if (reading) return reading;+ const entry = this.entries_.get(key);+ if (!entry) return Promise.resolve(null);+ const job = (async (): Promise<Tile | null> => {+ const [h, a, b] = await Promise.all([this.read(entry.height), entry.splat ? this.read(entry.splat) : null, entry.splat2 ? this.read(entry.splat2) : null]);+ if (!h) throw new Error(`the heights of terrain tile ${key} (${entry.height}) could not be read`);+ if (h.width !== this.doc.tileSamples || h.height !== this.doc.tileSamples) {+ throw new Error(`terrain tile ${key} is ${h.width} by ${h.height}, not ${this.doc.tileSamples} a side`);+ }+ const field = heightfieldFromPixels(h.width, h.height, h.pixels, this.doc.format, h.wide);+ const splat = a && { width: a.width, height: a.height, pixels: a.pixels };+ const splat2 = b && { width: b.width, height: b.height, pixels: b.pixels };+ const tile: Tile = { field, splat, splat2, used: ++this.clock_,+ bytes: field.data.byteLength + (splat?.pixels.byteLength ?? 0) + (splat2?.pixels.byteLength ?? 0) };+ this.tiles_.set(key, tile);+ this.bytes_ += tile.bytes;+ this.reads_++;+ this.trim(new Set([key]));+ return tile;+ })().finally(() => this.reading_.delete(key));+ this.reading_.set(key, job);+ return job;+ }++ /** Where (x, z) falls: its tile's key, and its place in that tile in samples. */+ private locate(x: number, z: number): { key: string; lx: number; lz: number } {+ const n = this.doc.tileSamples - 1;+ const gx = clamp(x / this.params.sizeX + 0.5, 0, 1) * (this.samplesX - 1), gz = clamp(z / this.params.sizeZ + 0.5, 0, 1) * (this.samplesZ - 1);+ const tx = Math.min(Math.floor(gx / n), this.doc.tilesX - 1), tz = Math.min(Math.floor(gz / n), this.doc.tilesZ - 1);+ return { key: `${tx}:${tz}`, lx: gx - tx * n, lz: gz - tz * n };+ }++ private keysOver(x0: number, z0: number, x1: number, z1: number): string[] {+ const a = this.locate(x0, z0), b = this.locate(x1, z1);+ const [ax, az] = a.key.split(':').map(Number), [bx, bz] = b.key.split(':').map(Number);+ const keys: string[] = [];+ for (let tz = az!; tz <= bz!; tz++) for (let tx = ax!; tx <= bx!; tx++) keys.push(`${tx}:${tz}`);+ return keys;+ }++ private fromOverview(x0: number, z0: number, spacing: number, count: number): TerrainRegionSamples {+ const heights = new Float32Array(count * count);+ const p1 = this.overviewSplat ? new Float32Array(count * count * 4) : undefined;+ const p2 = this.overviewSplat2 ? new Float32Array(count * count * 4) : undefined;+ for (let j = 0; j < count; j++) for (let i = 0; i < count; i++) {+ const k = j * count + i;+ const u = clamp((x0 + i * spacing) / this.params.sizeX + 0.5, 0, 1), v = clamp((z0 + j * spacing) / this.params.sizeZ + 0.5, 0, 1);+ heights[k] = this.params.height * bilinear(this.overview.data, this.overview.width, u * (this.overview.width - 1), v * (this.overview.height - 1));+ if (p1) fill(p1, k, this.overviewSplat!, u, v);+ if (p2) fill(p2, k, this.overviewSplat2!, u, v);+ }+ return { heights, ...(p1 ? { paint: p1 } : {}), ...(p2 ? { paint2: p2 } : {}) };+ }++ private fromTiles(x0: number, z0: number, spacing: number, count: number): TerrainRegionSamples {+ const heights = new Float32Array(count * count);+ const painted = this.overviewSplat !== null || [...this.tiles_.values()].some((t) => t.splat);+ const p1 = painted ? new Float32Array(count * count * 4) : undefined;+ const second = this.overviewSplat2 !== null || [...this.tiles_.values()].some((t) => t.splat2);+ const p2 = painted && second ? new Float32Array(count * count * 4) : undefined;+ const n = this.doc.tileSamples - 1;+ for (let j = 0; j < count; j++) for (let i = 0; i < count; i++) {+ const k = j * count + i, x = x0 + i * spacing, z = z0 + j * spacing;+ const at = this.locate(x, z), tile = this.tiles_.get(at.key);+ const u = clamp(x / this.params.sizeX + 0.5, 0, 1), v = clamp(z / this.params.sizeZ + 0.5, 0, 1);+ heights[k] = tile ? this.params.height * bilinear(tile.field.data, tile.field.width, at.lx, at.lz)+ : this.params.height * bilinear(this.overview.data, this.overview.width, u * (this.overview.width - 1), v * (this.overview.height - 1));+ if (!p1) continue;+ const splat = tile?.splat ?? this.overviewSplat, splat2 = tile?.splat ? tile.splat2 : this.overviewSplat2;+ const su = tile?.splat ? at.lx / n : u, sv = tile?.splat ? at.lz / n : v;+ if (splat) fill(p1, k, splat, su, sv);+ if (p2 && splat2) fill(p2, k, splat2, su, sv);+ }+ return { heights, ...(p1 ? { paint: p1 } : {}), ...(p2 ? { paint2: p2 } : {}) };+ }+}++const clamp = (v: number, a: number, b: number): number => Math.min(Math.max(v, a), b);++function bilinear(data: Float32Array, width: number, fx: number, fz: number): number {+ const height = data.length / width;+ const i = clamp(Math.floor(fx), 0, width - 2), j = clamp(Math.floor(fz), 0, height - 2);+ const u = fx - i, v = fz - j;+ const a = data[j * width + i]!, b = data[j * width + i + 1]!, c = data[(j + 1) * width + i]!, d = data[(j + 1) * width + i + 1]!;+ return a + (b - a) * u + (c - a) * v + (a - b - c + d) * u * v;+}++function fill(out: Float32Array, k: number, s: Splat, u: number, v: number): void {+ const i = Math.round(clamp(u, 0, 1) * (s.width - 1)), j = Math.round(clamp(v, 0, 1) * (s.height - 1));+ for (let c = 0; c < 4; c++) out[k * 4 + c] = s.pixels[(j * s.width + i) * 4 + c]! / 255;+}++function weights(a: Splat, b: Splat | null, u: number, v: number): LayerWeights {+ const out = new Float32Array(b ? 8 : 4);+ fill(out, 0, a, u, v);+ if (b) {+ const tmp = new Float32Array(4);+ fill(tmp, 0, b, u, v);+ out.set(tmp, 4);+ }+ return [...out];+}diff --git a/sdk/tests/terrain-sculpt.test.ts b/sdk/tests/terrain-sculpt.test.tsindex 85ec669fe..8241383a5 100644--- a/sdk/tests/terrain-sculpt.test.ts+++ b/sdk/tests/terrain-sculpt.test.ts@@ -117,7 +117,7 @@ describe('Terrains.load', () => {const wrapped = new ModifiedSource(source, () => [], { x: 0, y: 0, z: 0 }, 1);terrains.built_.set(1 as never, { loading: false, source: wrapped } as never);terrains.built_.set(2 as never, { loading: true, source: null } as never);- expect(terrains.load()).toEqual({ loading: 1, cpuBytes: field.data.byteLength + 256 });+ expect(terrains.load()).toEqual({ loading: 1, cpuBytes: field.data.byteLength + 256, tiles: 0 });});});diff --git a/sdk/tests/terrain-tiles.test.ts b/sdk/tests/terrain-tiles.test.tsnew file mode 100644index 000000000..075ebcbc3--- /dev/null+++ b/sdk/tests/terrain-tiles.test.ts@@ -0,0 +1,87 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+import { describe, expect, it } from 'vitest';+import { HeightmapFormat, sampleHeight, type Heightfield } from '../src/terrain/heightfield';+import { TiledSource, parseTerrainTiles, type TerrainImage, type TerrainTilesDocument } from '../src/terrain/tiles';++const T = 9, TILES = 4, N = TILES * (T - 1) + 1, SIZE = 640, HEIGHT = 100;+const ground = (u: number, v: number): number => 0.5 + 0.4 * Math.sin(u * 7) * Math.cos(v * 5);+const params = { sizeX: SIZE, sizeZ: SIZE, height: HEIGHT, rockSlope: 0.35, dirtHeight: 0.62, snowHeight: 0.88 };++function image(width: number, height: number, at: (i: number, j: number) => number): TerrainImage {+ const pixels = new Uint8Array(width * height * 4);+ for (let j = 0; j < height; j++) for (let i = 0; i < width; i++) {+ const v = Math.round(at(i, j) * 65535);+ pixels.set([v >> 8, v & 255, 0, 255], (j * width + i) * 4);+ }+ return { width, height, pixels };+}++function world(budget?: number) {+ const files = new Map<string, TerrainImage>();+ const doc: TerrainTilesDocument = { version: 1, tileSamples: T, tilesX: TILES, tilesZ: TILES, format: HeightmapFormat.RedGreen16, overview: 'o.png', tiles: [] };+ for (let tz = 0; tz < TILES; tz++) for (let tx = 0; tx < TILES; tx++) {+ const name = `t${tx}_${tz}.png`;+ files.set(name, image(T, T, (i, j) => ground((tx * (T - 1) + i) / (N - 1), (tz * (T - 1) + j) / (N - 1))));+ doc.tiles.push({ x: tx, z: tz, height: name });+ }+ const o = image(5, 5, (i, j) => ground(i / 4, j / 4));+ const overview: Heightfield = { width: 5, height: 5, data: Float32Array.from({ length: 25 }, (_, k) => (o.pixels[k * 4]! * 256 + o.pixels[k * 4 + 1]!) / 65535) };+ const reads: string[] = [];+ const read = async (path: string) => { reads.push(path); return files.get(path) ?? null; };+ return { source: new TiledSource(doc, params, overview, null, null, read, budget), reads };+}++const exact = (x: number, z: number): number => {+ const whole: Heightfield = { width: N, height: N, data: Float32Array.from({ length: N * N }, (_, k) => {+ const v = ground((k % N) / (N - 1), Math.floor(k / N) / (N - 1));+ return Math.round(v * 65535) / 65535;+ }) };+ return HEIGHT * sampleHeight(whole, x / SIZE + 0.5, z / SIZE + 0.5);+};++describe('ground kept as tiles', () => {+ it('reads nothing until a height is asked for, then only the tile under it', async () => {+ const { source, reads } = world();+ expect(reads).toEqual([]);+ expect(source.height(-300, -300)).toBeNull();+ await Promise.resolve(); await new Promise((r) => setTimeout(r, 0));+ expect(reads).toEqual(['t0_0.png']);+ expect(source.height(-300, -300)).toBeCloseTo(exact(-300, -300), 6);+ });++ it('answers a seam from either tile the same as the whole field does', async () => {+ const { source } = world();+ const seam = -SIZE / 2 + (T - 1) * SIZE / (N - 1);+ await source.region(seam - 20, 0, 5, 9);+ for (const x of [seam - 1e-3, seam, seam + 1e-3]) expect(source.height(x, 3)).toBeCloseTo(exact(x, 3), 4);+ });++ it('makes a page as coarse as the overview from it alone, and a finer one from the tiles it covers', async () => {+ const { source, reads } = world();+ const coarse = source.region(-320, -320, 160, 5);+ expect(coarse).not.toBeInstanceOf(Promise);+ expect(reads).toEqual([]);+ const fine = await source.region(-320, -320, 30, 9);+ expect(reads.sort()).toEqual(['t0_0.png', 't1_0.png', 't0_1.png', 't1_1.png'].sort());+ expect(fine.heights[0]).toBeCloseTo(exact(-320, -320), 4);+ expect(source.region(-320, -320, 30, 9)).not.toBeInstanceOf(Promise);+ });++ it('lets go of the least recently used tiles past its budget, and reads them again when asked', async () => {+ const one = T * T * 4;+ const { source, reads } = world(one * 2);+ for (const x of [-300, -140, 20]) await source.region(x, -300, 1, 2);+ expect(source.stats()).toMatchObject({ resident: 2, evictions: 1, bytes: one * 2 });+ reads.length = 0;+ await source.region(-300, -300, 1, 2);+ expect(reads).toEqual(['t0_0.png']);+ });++ it('refuses a document whose tiles fall outside its grid, or are listed twice', () => {+ const doc = { version: 1, tileSamples: 9, tilesX: 1, tilesZ: 1, overview: 'o.png', tiles: [{ x: 0, z: 0, height: 'a.png' }] };+ expect(parseTerrainTiles(doc).tiles).toHaveLength(1);+ expect(() => parseTerrainTiles({ ...doc, tiles: [{ x: 1, z: 0, height: 'a.png' }] })).toThrow(/outside/);+ expect(() => parseTerrainTiles({ ...doc, tiles: [doc.tiles[0], doc.tiles[0]] })).toThrow(/twice/);+ });+});diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjsindex 337733f70..bbd55435a 100644--- a/tools/releaseNotes.mjs+++ b/tools/releaseNotes.mjs@@ -4248,6 +4248,10 @@ export const NOTED = {{"note": "A 2D character can be rigged in the editor, with no other program."},"fix(text): a glyph's outline costs what its size does, and text too large for a bitmap glyph draws from a distance field":{"note": "Zooming in on outlined text no longer freezes the editor."},+ "feat(terrain): an area's ground can be kept as tiles, read where it is looked at under a memory budget, with an overview for the distance":+ {"note": "A terrain can be kept as tiles that are read where they are looked at."},+ "feat(terrain): a terrain splits into tiles from the sculpt panel, the editor waits for ground still being built, and opening a tiled terrain is measured near and far":+ {"note": "A terrain can be kept as tiles that are read where they are looked at."},"feat(world): a streamed world opens in the editor with only what never streams, and cells are loaded and unloaded in the edit view without touching the document":{"note": "A streamed world opens in the editor without its cells."},"fix(editor): what grows round the view follows the viewport in 2D and 3D, and a terrain stroke keeps only the tiles it touched":