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): a tiled terrain's heights export to one image and import from one, over every tile or only the loaded ones
yhh4d879aabe423
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 28bac31fc..e38669fbb 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -16,6 +16,7 @@ published separately; it ships inside the editor.### Added+- **A tiled terrain exports and imports its heightmap, over every tile or only the loaded ones.** The terrain sculpt panel exports the heights as one image the size of the whole area, and imports one (16-bit grey, or the red and green the export writes) over the tiles, as do the **Terrain: Export Heightmap** and **Terrain: Import Selected Heightmap** commands. **Loaded tiles** reads no tile that is not in memory: an export takes the rest from the overview, and an import writes only the tiles in memory and the overview; **All tiles** reads and writes every one. An import is refused while the terrain has changes not saved.- **Tiled terrain can be sculpted and painted, and a save writes only what changed.** A brush on tiled ground runs on the samples copied out of the tiles under it and writes them back to every tile that holds them, so a seam stays one height and the result is the same as on one heightfield, sample for sample. Only tiles in memory are edited: a dab over one not read yet is skipped and the tile is read. A changed tile is kept in memory past the budget until it is saved, the overview follows each stroke so distant ground shows it, and undo covers the tiles and the overview. **Save Ground** writes the changed tiles and the overview only: six dabs on a 4097 by 4097 terrain wrote 2 of its 64 tiles.- **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. 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.diff --git a/desktop b/desktopindex b0330ff26..5b53eec38 160000--- a/desktop+++ b/desktop@@ -1 +1 @@-Subproject commit b0330ff26a1dc75118d373284e547b2662ef64cb+Subproject commit 5b53eec3841a7a14e1bbc93d19ccc44d8d7d7912diff --git a/docs/astro/src/content/docs/graphics/terrain.mdx b/docs/astro/src/content/docs/graphics/terrain.mdxindex 892402ba0..b19f2cb82 100644--- a/docs/astro/src/content/docs/graphics/terrain.mdx+++ b/docs/astro/src/content/docs/graphics/terrain.mdx@@ -342,6 +342,9 @@ A heightmap is read whole: an 8193 by 8193 field is about 256 MiB. Point `tiles`- **Split into Tiles** in the terrain sculpt panel converts a terrain.- Tiled ground is sculpted and painted like any other, on the tiles in memory: a dab over a tile not read yet is skipped and the tileis read. A changed tile stays in memory until it is saved, and a save writes the changed tiles and the overview only.+- The sculpt panel exports the heights as one image the size of the area, and imports one over the tiles. With **Loaded tiles** no+ tile that is not in memory is read: an export takes the rest from the overview, and an import writes the tiles in memory and the+ overview only; **All tiles** reads and writes every one. An import is refused while there are changes not saved.- 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.diff --git a/docs/astro/src/content/docs/zh-cn/graphics/terrain.mdx b/docs/astro/src/content/docs/zh-cn/graphics/terrain.mdxindex 6653776fa..35eeacfdb 100644--- a/docs/astro/src/content/docs/zh-cn/graphics/terrain.mdx+++ b/docs/astro/src/content/docs/zh-cn/graphics/terrain.mdx@@ -263,6 +263,7 @@ registerPlanetProvider({- 视点或运动物体附近才读精细分块;超过 256 MiB 时先放掉最久没用的块。还没读到的地方高度暂时未知,碰撞和查询会等它读到后再算。- 在地形雕刻面板里点 **拆分为分块**,就能把现有地形转换过去。- 分块地形照样能雕刻和绘制,但只改已加载的分块:笔刷底下有块还没读到,这一笔就跳过并去读它。改过的块在保存前不会被放掉,保存只写改过的块和总览图。+- 雕刻面板可以导出整块地面的高度图,也能把一张高度图导入到分块上。选 **已加载分块** 时不会读任何还没加载的块:导出时没加载的部分从总览图补,导入时只写已加载的块和总览图;选 **全部分块** 则每块都读、都写。有未保存的改动时不能导入。- 分块图只经 `.esterrain` 引用,不会像 `heightmap` 那样在打开场景时作为贴图预载、上传。编辑器里实测(4096 单位见方):8193×8193 的地面按分块打开时占 36 MiB,贴近地面时占 45 MiB。diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.jsonindex 9b88191a2..b7ee47ec4 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": 2991,+ "experimental": 2992,"deprecated": 3},- "total": 3284,+ "total": 3285,"subsystems": [{"id": "mobile-controls",diff --git a/sdk/etc/terrain.api.md b/sdk/etc/terrain.api.mdindex 434c32c49..c7f49cc70 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 · 114 experimental · 0 deprecated+Symbols: 0 public · 0 beta · 115 experimental · 0 deprecated## Brush — interface @experimental```@@ -664,7 +664,9 @@ apply: (patch: TiledGroundPatch, side: "before" | "after") => voidarea: { sizeX: number; sizeZ: number; }begin: () => voidend: () => TiledGroundPatch | null+exportImage: (mode: "all" | "loaded") => Promise<{ width: number; height: number; pixels: Uint8Array; } | null>heightAt: (x: number, z: number) => number | null+importImage: (field: Heightfield, mode: "all" | "loaded") => TiledGroundImage[]maxHeight: numberminHeight: numberorigin: { x: number; z: number; }@@ -855,6 +857,11 @@ PlanetPlugin(p: ProceduralParams): Heightfield```+## readTerrainImage — function @experimental+```+(app: App, path: string): Promise<{ width: number; height: number; pixels: Uint8Array; wide?: Uint16Array; } | null>+```+## registerPlanetProvider — function @experimental```(provider: PlanetProvider): voiddiff --git a/sdk/src/terrain/index.ts b/sdk/src/terrain/index.tsindex b4571bd6c..3fade74d1 100644--- a/sdk/src/terrain/index.ts+++ b/sdk/src/terrain/index.ts@@ -33,4 +33,5 @@ export {} from './sphere';export { GroundEdit, type GroundPatch } from './groundEdit';export { TiledGroundEdit, type TiledGroundPatch, type TiledGroundImage } from './tiledGroundEdit';+export { imagePixelsAt as readTerrainImage } from './layerArrays';export { SculptMode, brushWeight, encodeHeightmap, paintSplat, sculptField, unionDirty, type Brush, type Dirty, type PaintDab, type SculptDab } from './sculpt';diff --git a/sdk/src/terrain/tiledGroundEdit.ts b/sdk/src/terrain/tiledGroundEdit.tsindex de629e0ae..dc3ad6a4f 100644--- a/sdk/src/terrain/tiledGroundEdit.ts+++ b/sdk/src/terrain/tiledGroundEdit.ts@@ -163,6 +163,62 @@ export class TiledGroundEdit {return { images, document: named ? doc : null };}+ /**+ * The whole area as one heightmap image, the size {@link importImage} takes: from every tile (`all`, each read in turn), or from+ * the tiles in memory (`loaded`), the rest from the overview. Null when `loaded` finds no tile in memory.+ */+ async exportImage(mode: 'all' | 'loaded'): Promise<{ width: number; height: number; pixels: Uint8Array } | null> {+ const s = this.source, n = s.doc.tileSamples - 1, t = n + 1;+ const chosen = s.doc.tiles.filter((e) => mode === 'all' || s.tileAt(e.x, e.z));+ if (chosen.length === 0) return null;+ const x0 = 0, z0 = 0;+ const field: Heightfield = { width: s.samplesX, height: s.samplesZ, data: new Float32Array(s.samplesX * s.samplesZ) };+ const ov = s.overview;+ for (let j = 0; j < field.height; j++) for (let i = 0; i < field.width; i++) {+ const u = (x0 + i) / (s.samplesX - 1) * (ov.width - 1), v = (z0 + j) / (s.samplesZ - 1) * (ov.height - 1);+ field.data[j * field.width + i] = bilinear(ov.data, ov.width, u, v);+ }+ for (const e of chosen) {+ const tile = s.tileAt(e.x, e.z) ?? (mode === 'all' ? await s.readTile(e.x, e.z) : null);+ if (!tile) continue;+ for (let j = 0; j < t; j++) {+ const row = (e.z * n + j - z0) * field.width + (e.x * n - x0);+ field.data.set(tile.field.data.subarray(j * t, j * t + t), row);+ }+ }+ return { width: field.width, height: field.height, pixels: encodeHeightmap(field) };+ }++ /**+ * A heightmap laid over the ground: on every tile (`all`) or the tiles in memory (`loaded`). `field` covers the whole area and is+ * resampled to it if its size differs. The tiles in memory take it at once; what comes back is every image to write (the tiles'+ * and the overview's). Refused while there are changes not saved, which it would overwrite.+ */+ importImage(field: Heightfield, mode: 'all' | 'loaded'): TiledGroundImage[] {+ const s = this.source, n = s.doc.tileSamples - 1, t = n + 1;+ if (s.dirtyTiles().length > 0 || s.overviewDirty) throw new Error('save or undo the changes to this terrain before importing over it');+ const at = (gi: number, gj: number): number => bilinear(field.data, field.width,+ gi / (s.samplesX - 1) * (field.width - 1), gj / (s.samplesZ - 1) * (field.height - 1));+ const chosen = s.doc.tiles.filter((e) => mode === 'all' || s.tileAt(e.x, e.z));+ const images: TiledGroundImage[] = [];+ for (const e of chosen) {+ const heights: Heightfield = { width: t, height: t, data: new Float32Array(t * t) };+ for (let j = 0; j < t; j++) for (let i = 0; i < t; i++) heights.data[j * t + i] = at(e.x * n + i, e.z * n + j);+ const tile = s.tileAt(e.x, e.z);+ if (tile) tile.field.data.set(heights.data);+ images.push({ path: e.height, width: t, height: t, pixels: encodeHeightmap(heights) });+ }+ const ov = s.overview;+ for (let oj = 0; oj < ov.height; oj++) for (let oi = 0; oi < ov.width; oi++) {+ const gi = oi / (ov.width - 1) * (s.samplesX - 1), gj = oj / (ov.height - 1) * (s.samplesZ - 1);+ const tx = Math.min(Math.floor(gi / n), s.doc.tilesX - 1), tz = Math.min(Math.floor(gj / n), s.doc.tilesZ - 1);+ if (chosen.some((e) => e.x === tx && e.z === tz)) ov.data[oj * ov.width + oi] = at(gi, gj);+ }+ images.push({ path: s.doc.overview, width: ov.width, height: ov.height, pixels: encodeHeightmap(ov) });+ this.host.remake(this.world([-this.sizeX / 2, -this.sizeZ / 2, this.sizeX / 2, this.sizeZ / 2]));+ return images;+ }+/** After the images of {@link saveImages} are written: the tiles may leave memory again. */saved(): void {this.source.markSaved();diff --git a/sdk/tests/terrain-tiled-sculpt.test.ts b/sdk/tests/terrain-tiled-sculpt.test.tsindex f24b1d0c3..e84571e0b 100644--- a/sdk/tests/terrain-tiled-sculpt.test.ts+++ b/sdk/tests/terrain-tiled-sculpt.test.ts@@ -142,3 +142,55 @@ describe('brushes on ground kept as tiles', () => {expect(out.document?.overviewSplat).toBe('o_splat.png');});});++describe('a heightmap in and out of ground kept as tiles', () => {+ const heightsOf = (img: { width: number; height: number; pixels: Uint8Array }): Float32Array =>+ Float32Array.from({ length: img.width * img.height }, (_, k) => (img.pixels[k * 4]! * 256 + img.pixels[k * 4 + 1]!) / 65535);++ it('exports every tile as the whole field', async () => {+ const t = tiled();+ const out = (await t.edit.exportImage('all'))!;+ expect([out.width, out.height]).toEqual([N, N]);+ const got = heightsOf(out);+ for (let k = 0; k < N * N; k++) expect(got[k]).toBeCloseTo(ground(k % N, Math.floor(k / N)), 4);+ });++ it('exports what is loaded at the whole size, the rest from the overview, reading nothing', async () => {+ const t = tiled();+ await t.source.readTile(1, 0);+ await t.source.readTile(2, 1);+ t.reads.length = 0;+ const out = (await t.edit.exportImage('loaded'))!;+ expect(t.reads).toEqual([]);+ expect([out.width, out.height]).toEqual([N, N]);+ const got = heightsOf(out);+ expect(got[3 * N + T - 1 + 3]).toBeCloseTo(ground(T - 1 + 3, 3), 4);+ const off = -SIZE / 2 + 3 * SIZE / (N - 1);+ const fromOverview = (t.source.region(off, off, 1e9, 1) as { heights: Float32Array }).heights[0]! / HEIGHT;+ expect(got[3 * N + 3]).toBeCloseTo(fromOverview, 4);+ expect(await tiled().edit.exportImage('loaded')).toBeNull();+ });++ it('imports onto every tile, or only those in memory, and the overview follows', async () => {+ const flat: Heightfield = { width: 5, height: 5, data: new Float32Array(25).fill(0.25) };+ const all = tiled();+ await all.source.readTile(0, 0);+ const written = all.edit.importImage(flat, 'all').map((i) => i.path);+ expect(written.length).toBe(TILES * TILES + 1);+ expect(all.source.height(-230, -230)).toBeCloseTo(25, 4);+ expect(all.source.overview.data.every((v) => Math.abs(v - 0.25) < 1e-6)).toBe(true);++ const some = tiled();+ await some.source.readTile(0, 0);+ expect(some.edit.importImage(flat, 'loaded').map((i) => i.path)).toEqual(['t0_0.png', 'o.png']);+ expect(some.source.overview.data[0]).toBeCloseTo(0.25, 6);+ expect(some.source.overview.data[80]).not.toBeCloseTo(0.25, 3);+ });++ it('refuses to import over changes not saved', async () => {+ const t = tiled();+ await loadAll(t.source);+ t.edit.sculpt(SculptMode.Raise, 0, 0, 30, 0.5, 10);+ expect(() => t.edit.importImage({ width: 2, height: 2, data: new Float32Array(4) }, 'all')).toThrow(/save or undo/);+ });+});diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjsindex e2b690b2e..3e04e0064 100644--- a/tools/releaseNotes.mjs+++ b/tools/releaseNotes.mjs@@ -4248,6 +4248,8 @@ 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): a tiled terrain's heights export to one image and import from one, over every tile or only the loaded ones":+ {"note": "A tiled terrain exports and imports its heightmap, over every tile or only the loaded ones."},"fix(editor): a tiled terrain's .esterrain is a known asset, and the cell load and split buttons carry their state and tip through Button's own props":{"note": "Tiled terrain can be sculpted and painted, and a save writes only what changed."},"feat(terrain): tiled ground is sculpted and painted on the tiles in memory, a changed tile stays until it is saved, and a save writes only what changed":