Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

fix(terrain): a detail the pages cannot hold no longer cracks the ground - a tree that wanted more nodes than the atlas has pages was drawn in part by coarser pages standing in, which do not meet their finer neighbours' edges, and the pages were fought over every frame; the ground is now drawn at the share of its detail's range that fits, and says so once

yhhffe0ac3e661d
diff --git a/CHANGELOG.md b/CHANGELOG.md
index b6cebe4eb..b29e19144 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -35,6 +35,7 @@ published separately; it ships inside the editor.
### Fixed
+- **A detail the pages cannot hold no longer cracks the ground.** A terrain's heights are kept in an atlas of 900 pages, a page a node. A `detail` high enough to want more nodes than that (about 4 on 1.5 m cells: 1153 from inside a fjord) had part of its ground drawn by coarser pages standing in for the ones that had no room, which do not meet their finer neighbours' edges: slivers of sky showed through steep ground, and the pages were fought over frame after frame, so the ground never finished loading. The ground is now drawn at the share of its detail's range that fits the pages there are, and a warning says so once.
- **The sea past the rings lies at the sea's level.** The apron that carries an ocean from its mesh to the horizon took its inner edge's height from whatever water lay under it. With a river on high ground under that edge (a river along a cliff top, seen from across the island), a strip of sea eighty kilometres long rose to the river's height and stood on the horizon as a block with straight sides, moving as the camera did. The apron is now laid at the ocean's level.
- **A colour map and an occlusion map lie the way the heightmap does.** `Terrain.colorMap`, `Terrain.occlusionMap` and `Foliage.colorMap` were sampled with their rows turned over: a picture painted to match the heightmap, the splatmap or a density map came out mirrored north to south under them, flowers coloured for the far side of an island and gullies shaded where the ridges were. An image over an area now has its first row along the least z whoever reads it. A map that was drawn turned over to make up for this needs turning back.
- **The ground's lengths follow the project's units.** A `Terrain`'s size, height, cell, draw distance and collision distance were plain numbers, and so were its shaders' layer tiles, relief and wet line and a layer file's default tile: a new terrain in a default project was ten metres of ground on 2 cm cells with collision built 64 cm round a body. They are lengths now (`worldUnitFields`, `unit(length)`), written at 100 units a metre: a kilometre of ground on 2 m cells, collision 64 m round a body, a layer 24 m across, in a centimetre project and a metre one. What a scene, a material or a layer file states is untouched; a scene that left `collisionDistance` or `drawDistance` to the default gets the new one, so state the old (64, 4000) to keep it. Ground with `layers` is also no longer sent the four layer colours of the plain shader, which warned four times a load.
diff --git a/docs/astro/src/content/docs/graphics/terrain.mdx b/docs/astro/src/content/docs/graphics/terrain.mdx
index 7a0581842..78253d583 100644
--- a/docs/astro/src/content/docs/graphics/terrain.mdx
+++ b/docs/astro/src/content/docs/graphics/terrain.mdx
@@ -148,6 +148,11 @@ Pages are made as the tree asks for them, a few each frame within a time budget,
made, the node is drawn by its nearest ancestor that has one, so the ground is there at once and sharpens as the pages come in. When
the atlas is full, the page drawn least recently gives up its place.
+The pages are a budget, and the nodes drawn at once have to fit in it: a page that stands in for a finer one does not meet its finer
+neighbours' edges, and the ground cracks along them. So a `detail` that asks for more nodes than the atlas has pages for (about 4 on
+1.5 m cells from most places) is drawn at the share of its range that fits, 0.9 of it at a time, and a warning says so once with the
+detail the ground is being drawn at.
+
### Building over frames
Making pages and wearing an area by rain are spread over frames rather than done in one, so neither holds up a frame. While they run
diff --git a/docs/astro/src/content/docs/zh-cn/graphics/terrain.mdx b/docs/astro/src/content/docs/zh-cn/graphics/terrain.mdx
index 170e00f8c..542294f39 100644
--- a/docs/astro/src/content/docs/zh-cn/graphics/terrain.mdx
+++ b/docs/astro/src/content/docs/zh-cn/graphics/terrain.mdx
@@ -107,6 +107,8 @@ description: 一个 Terrain 组件,用高度图或噪声生成地面,可以是
页按四叉树的需要生成,每帧在时间预算内做几页,粗的、近的优先。节点的页做好之前,用它最近的、已有页的祖先节点代为绘制,所以地面立刻就在,随着页陆续做好而变清晰。图集满了时,最久没被绘制的页让出位置。
+页是一份预算,同时绘制的节点必须装得进去:替细页顶班的粗页和旁边细节点的边对不上,地面会沿着这些边裂开。所以当 `detail` 要的节点数超过图集装得下的页数时(1.5 m 的格子上大约是 4),地面按装得下的那部分范围来画,每次收 0.9,并提示一次,说明实际按多大的 detail 在画。
+
### 分帧构建
生成页和用雨水侵蚀区域都分摊到多帧里进行,而不是一次做完,所以都不会卡住某一帧。进行期间,它们和进度一起("Building the terrain"、"Eroding the terrain")列在编辑器的状态栏里,游戏也可以读取同一份列表来显示加载画面。
diff --git a/sdk/src/terrain/quadtree.ts b/sdk/src/terrain/quadtree.ts
index 1e80dbc1c..897dcf479 100644
--- a/sdk/src/terrain/quadtree.ts
+++ b/sdk/src/terrain/quadtree.ts
@@ -92,3 +92,28 @@ export function parentOf(n: TerrainNode, leafSize: number): TerrainNode {
export function nodeKey(level: number, ix: number, iz: number): string {
return `${level}:${ix}:${iz}`;
}
+
+/** How much a fit that is over its budget gives up at a time, and how far under the budget the next step up has to be before it is taken back. */
+const FIT_STEP = 0.9;
+const FIT_ROOM = 0.85;
+
+/**
+ * The share of its `range0` a tree (`tree(share)`) can keep and still draw the eye's ground in `most` nodes: a node is a page, and a tree
+ * that wants more pages than the atlas holds is drawn in part by coarser pages, which do not meet their finer neighbours' edges (cracks).
+ * `held` is the share the frame before settled on: given up a step at a time while the nodes are too many, taken back a step only with
+ * room to spare, so an eye moving along the edge of the budget does not change the ground every frame.
+ */
+export function fitRange(tree: (share: number) => QuadtreeParams, ex: number, ey: number, ez: number, most: number, held = 1): { share: number; nodes: TerrainNode[] } {
+ let share = Math.min(Math.max(held, 0.01), 1);
+ let nodes = selectNodes(tree(share), ex, ey, ez);
+ while (nodes.length > most && share > 0.01) {
+ share *= FIT_STEP;
+ nodes = selectNodes(tree(share), ex, ey, ez);
+ }
+ if (share < 1 && nodes.length <= most) {
+ const up = Math.min(share / FIT_STEP, 1);
+ const more = selectNodes(tree(up), ex, ey, ez);
+ if (more.length <= most * FIT_ROOM) return { share: up, nodes: more };
+ }
+ return { share, nodes };
+}
diff --git a/sdk/src/terrain/terrainPlugin.ts b/sdk/src/terrain/terrainPlugin.ts
index 0a5baf3a1..8ee35f4f0 100644
--- a/sdk/src/terrain/terrainPlugin.ts
+++ b/sdk/src/terrain/terrainPlugin.ts
@@ -43,7 +43,7 @@ import { paintWeights } from './paint';
export { paintWeights };
import { GroundEdit } from './groundEdit';
import { FieldSource, ModifiedSource, NoiseSource, type NoiseParams, type TerrainModifier, type TerrainSource } from './source';
-import { levelRange, nodeKey, parentOf, selectNodes, type QuadtreeParams, type TerrainNode } from './quadtree';
+import { fitRange, levelRange, nodeKey, parentOf, type QuadtreeParams, type TerrainNode } from './quadtree';
import { makePage, makePageJob, 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';
@@ -202,6 +202,8 @@ export const Terrain: ComponentDef<TerrainData> = /* @__PURE__ */ defineComponen
/** The side of the atlases the pages are kept in, in texels: 900 pages of 67 by 67. */
const ATLAS_SIZE = 2048;
+/** The share of the atlas the nodes drawn may fill: the rest is for the coarser pages that stand in while a finer one is made. */
+const PAGE_SHARE = 0.85;
/** 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. */
@@ -239,6 +241,9 @@ interface Built {
spare: Entity[];
/** Pages wanted and not made yet, by key. */
wanted: Map<string, TerrainNode>;
+ /** The share of its detail's range the ground is drawn at, so its nodes fit the pages there are (see fitRange). */
+ fit: number;
+ fitSaid?: boolean;
/** Pages asked of a provider that answers later, by key: the frame's budget is not spent waiting for them. */
asked: Set<string>;
/** The workers failed one of this terrain's pages: it makes its own. */
@@ -682,7 +687,7 @@ export class TerrainPlugin implements Plugin {
built = {
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,
+ nodes: new Map(), spare: [], wanted: new Map(), fit: 1, asked: new Set(), pending: false, failure: null, edits: 0,
paint2: 0, arrays: [], packed: '', packing: false, washed: false, shaded: false,
};
terrains.built_.set(entity, built);
@@ -966,10 +971,10 @@ export class TerrainPlugin implements Plugin {
}
/** The quadtree's cut for this terrain: leaf nodes a patch of the finest cells, ranges doubling, enough levels to cover it. */
- private treeOf(built: Built, source: TerrainSource): QuadtreeParams {
+ private treeOf(built: Built, source: TerrainSource, share = 1): QuadtreeParams {
const d = built.data;
const leafSize = PATCH_CELLS * Math.max(d.cellSize, 1e-3);
- const range0 = leafSize * 2.5 * Math.max(d.detail, 0.25);
+ const range0 = leafSize * 2.5 * Math.max(d.detail, 0.25) * share;
const reach = source.bounds ? Math.max(source.bounds[2] - source.bounds[0], source.bounds[3] - source.bounds[1]) : Math.max(d.drawDistance, leafSize);
let levels = 1;
while (levels < 16 && (source.bounds ? leafSize * 2 ** (levels - 1) < reach : levelRange({ range0 }, levels - 1) < reach)) levels++;
@@ -981,10 +986,17 @@ export class TerrainPlugin implements Plugin {
const source = built.source!;
const t = app.world.get(entity, Transform) as TransformData;
const eye = this.eye(app, t);
- const tree = this.treeOf(built, source);
const eyeAt = eye ?? [0, source.maxHeight, 0];
- const chosen = selectNodes(tree, eyeAt[0], eyeAt[1], eyeAt[2]);
const table = built.table;
+ // The pages are a budget (see fitRange): a `detail` that asks for more than the atlas holds is drawn at the share of it that fits.
+ const fitted = fitRange((share) => this.treeOf(built, source, share), eyeAt[0], eyeAt[1], eyeAt[2], Math.floor(table.capacity * PAGE_SHARE), built.fit);
+ if (fitted.share < 1 && !built.fitSaid) {
+ built.fitSaid = true;
+ log.warn('terrain', `detail ${built.data.detail} asks for more pages than the ${table.capacity} there are; the ground is drawn at ${(built.data.detail * fitted.share).toFixed(2)}`);
+ }
+ built.fit = fitted.share;
+ const tree = this.treeOf(built, source, fitted.share);
+ const chosen = fitted.nodes;
table.tick();
// Each node is drawn by its own page, or by its nearest ancestor that has one; a node under an ancestor drawn instead is not.
diff --git a/sdk/tests/terrain-quadtree.test.ts b/sdk/tests/terrain-quadtree.test.ts
index 4a60e9e04..f58313366 100644
--- a/sdk/tests/terrain-quadtree.test.ts
+++ b/sdk/tests/terrain-quadtree.test.ts
@@ -1,7 +1,7 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
import { describe, expect, it } from 'vitest';
-import { levelRange, parentOf, selectNodes, type QuadtreeParams, type TerrainNode } from '../src/terrain/quadtree';
+import { fitRange, levelRange, parentOf, selectNodes, type QuadtreeParams, type TerrainNode } from '../src/terrain/quadtree';
import { makePage, PageTable, PAGE_SIDE } from '../src/terrain/pages';
import { NoiseSource, noised } from '../src/terrain/source';
@@ -107,3 +107,32 @@ describe('the pages', () => {
expect(table.size).toBe(2);
});
});
+
+describe('a tree fitted to the pages there are', () => {
+ // Six kilometres of ground on 1.5 m cells at a detail of 4: what a fjord's cliffs cracked at, wanting 1153 pages of 900.
+ const island = (share: number): QuadtreeParams => ({ leafSize: 48, levels: 8, range0: 480 * share, bounds: [-3072, -3072, 3072, 3072], minHeight: 0, maxHeight: 528 });
+
+ it('keeps its whole range where the nodes fit', () => {
+ const fitted = fitRange(island, -300, 119, -640, 5000);
+ expect(fitted.share).toBe(1);
+ expect(fitted.nodes).toEqual(selectNodes(island(1), -300, 119, -640));
+ });
+
+ it('gives up range until the nodes fit, and no more than that', () => {
+ expect(selectNodes(island(1), -300, 119, -640).length).toBeGreaterThan(900);
+ const fitted = fitRange(island, -300, 119, -640, 765);
+ expect(fitted.nodes.length).toBeLessThanOrEqual(765);
+ expect(fitted.share).toBeLessThan(1);
+ expect(selectNodes(island(fitted.share / 0.9), -300, 119, -640).length).toBeGreaterThan(765);
+ expect(fitted.nodes).toEqual(selectNodes(island(fitted.share), -300, 119, -640));
+ });
+
+ it('holds what it settled on, and takes range back only with room to spare', () => {
+ const settled = fitRange(island, -300, 119, -640, 765).share;
+ expect(fitRange(island, -300, 119, -640, 765, settled).share).toBe(settled);
+ // A budget just over what the next step up wants is not room: one far over it is.
+ const next = selectNodes(island(settled / 0.9), -300, 119, -640).length;
+ expect(fitRange(island, -300, 119, -640, next + 1, settled).share).toBe(settled);
+ expect(fitRange(island, -300, 119, -640, next * 2, settled).share).toBeCloseTo(settled / 0.9, 9);
+ });
+});
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index c8eb95e27..c561f31ee 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -4574,4 +4574,6 @@ export const NOTED = {
{"note": "The sea past the rings lies at the sea's level."},
"feat(water): a waterfall - a Waterfall on an entity at a lip throws sheets of water level at a speed and lets gravity take them, each ending where it meets the ground or water that is not the water it left; it is the entity's own MeshRenderer, and with no material it takes the stock Waterfall shader, glass at the lip tearing into strands that ride down with the water":
{"note": "A waterfall."},
+ "fix(terrain): a detail the pages cannot hold no longer cracks the ground - a tree that wanted more nodes than the atlas has pages was drawn in part by coarser pages standing in, which do not meet their finer neighbours' edges, and the pages were fought over every frame; the ground is now drawn at the share of its detail's range that fits, and says so once":
+ {"note": "A detail the pages cannot hold no longer cracks the ground."},
};