@aethervtt/shard-terrain 0.1.0 → 0.2.0

package/dist/heightfield/pages.js

@@ -0,0 +1,244 @@
+import {
+  bakeLeaf,
+  LEAF_SIDE,
+  leafNormals,
+  pageTexels,
+  readPage,
+  SIDE
+} from "./kernel.js";
+import {
+  PACK_INDEX_BYTES,
+  packOf,
+  readIndex
+} from "./pack.js";
+const WORKER = new URL("./worker.js", import.meta.url).href;
+function nodeKey(depth, x, z) {
+  return depth * 2 ** 40 + z * 2 ** 20 + x;
+}
+function keyDepth(key) {
+  return Math.floor(key / 2 ** 40);
+}
+function keyX(key) {
+  return key % 2 ** 20;
+}
+function keyZ(key) {
+  return Math.floor(key / 2 ** 20) % 2 ** 20;
+}
+class PageStore {
+  store;
+  layout;
+  lo;
+  hi;
+  workers;
+  /** Extra milliseconds before every read resolves (tests: a slow disk). */
+  delayMs = 0;
+  /** Pages kept decoded on the CPU, besides pinned ones. */
+  capacity = 512;
+  indexes = /* @__PURE__ */ new Map();
+  pendingIndexes = /* @__PURE__ */ new Map();
+  inflight = /* @__PURE__ */ new Map();
+  /** Decoded pages by key, in use order (Map insertion order: oldest first). */
+  cache = /* @__PURE__ */ new Map();
+  pinned = /* @__PURE__ */ new Set();
+  stats = { reads: 0, bytesRead: 0, inflated: 0, bakedInline: 0 };
+  constructor(store, layout, lo, hi, workers) {
+    this.store = store;
+    this.layout = layout;
+    this.lo = lo;
+    this.hi = hi;
+    this.workers = workers;
+  }
+  /** Nodes per side at a depth. */
+  nodesAt(depth) {
+    const level = this.layout.depth - depth;
+    return [this.layout.leavesX >> level, this.layout.leavesZ >> level];
+  }
+  /** A node's index entry, if its pack's index is loaded. */
+  entry(depth, x, z) {
+    const { path, slot } = packOf(depth, x, z);
+    const index = this.indexes.get(path);
+    const e = index?.entries[slot];
+    return e && e.length > 0 ? e : void 0;
+  }
+  /** Loads the index of the pack holding a node. */
+  index(depth, x, z) {
+    const { path } = packOf(depth, x, z);
+    const have = this.indexes.get(path);
+    if (have !== void 0) return Promise.resolve(have);
+    let p = this.pendingIndexes.get(path);
+    if (!p) {
+      p = this.store.readRange(path, 0, PACK_INDEX_BYTES).then(
+        (bytes) => {
+          const index = bytes.length >= PACK_INDEX_BYTES ? readIndex(path, bytes) : null;
+          this.indexes.set(path, index);
+          this.pendingIndexes.delete(path);
+          return index;
+        },
+        () => {
+          this.indexes.set(path, null);
+          this.pendingIndexes.delete(path);
+          return null;
+        }
+      );
+      this.pendingIndexes.set(path, p);
+    }
+    return p;
+  }
+  /** Whether a node's pack index is loaded (or known missing). */
+  hasIndex(depth, x, z) {
+    return this.indexes.has(packOf(depth, x, z).path);
+  }
+  /** A decoded page in the CPU cache (marked used), or undefined. */
+  get(key) {
+    const p = this.cache.get(key);
+    if (p && !this.pinned.has(key)) {
+      this.cache.delete(key);
+      this.cache.set(key, p);
+    }
+    return p;
+  }
+  /** Whether a read for this page is under way. */
+  loading(key) {
+    return this.inflight.has(key);
+  }
+  /** Keeps a page decoded for the store's life (coarse levels). */
+  pin(key) {
+    this.pinned.add(key);
+  }
+  /**
+   * Reads, inflates and decodes a page (once, however many ask), into the CPU cache. Undefined
+   * past the terrain's edge or when the pack doesn't have it.
+   */
+  load(depth, x, z) {
+    const key = nodeKey(depth, x, z);
+    const cached = this.cache.get(key);
+    if (cached) return Promise.resolve(cached);
+    let p = this.inflight.get(key);
+    if (p) return p;
+    p = this.read(depth, x, z, key).finally(() => this.inflight.delete(key));
+    this.inflight.set(key, p);
+    return p;
+  }
+  async read(depth, x, z, key) {
+    const [nx, nz] = this.nodesAt(depth);
+    if (x < 0 || z < 0 || x >= nx || z >= nz) return void 0;
+    await this.index(depth, x, z);
+    const e = this.entry(depth, x, z);
+    if (!e) return void 0;
+    const { path } = packOf(depth, x, z);
+    const packed = await this.store.readRange(path, e.offset, e.length);
+    this.stats.reads++;
+    this.stats.bytesRead += packed.length;
+    if (this.delayMs > 0) await new Promise((r) => setTimeout(r, this.delayMs));
+    const leaf = depth === this.layout.depth;
+    const decoded = this.workers && this.workers.size > 0 ? await this.workers.run(
+      WORKER,
+      "loadPage",
+      [packed, leaf, this.layout.cells, this.lo, this.hi, this.layout.spacing],
+      {
+        kind: "terrain/inflate"
+      }
+    ) : decodeInline(packed, leaf, this.layout.cells, this.lo, this.hi, this.layout.spacing);
+    this.stats.inflated++;
+    const page = {
+      key,
+      depth,
+      x,
+      z,
+      leaf,
+      heights: decoded.heights,
+      normals: decoded.normals,
+      control: decoded.control,
+      texels: decoded.texels,
+      min: e.min,
+      max: e.max,
+      error: e.error
+    };
+    this.put(page);
+    return page;
+  }
+  /** Adds a page to the CPU cache, dropping the least recently used unpinned ones over capacity. */
+  put(page) {
+    this.cache.delete(page.key);
+    this.cache.set(page.key, page);
+    let over = this.cache.size - this.pinned.size - this.capacity;
+    if (over <= 0) return;
+    for (const key of this.cache.keys()) {
+      if (over <= 0) break;
+      if (this.pinned.has(key)) continue;
+      this.cache.delete(key);
+      over--;
+    }
+  }
+  /**
+   * A leaf page now: from the cache, else baked on this thread from the stack (exactly the pack's
+   * bytes, spec 0071). Colliders use it on the frame a tile is due, so when a read lands never
+   * changes the world.
+   */
+  leafNow(noise, stack, x, z) {
+    const depth = this.layout.depth;
+    const key = nodeKey(depth, x, z);
+    const cached = this.get(key);
+    if (cached) return cached;
+    const baked = bakeLeaf(noise, stack, this.layout, x, z);
+    this.stats.bakedInline++;
+    const page = {
+      key,
+      depth,
+      x,
+      z,
+      leaf: true,
+      heights: baked.page.heights,
+      normals: leafNormals(
+        baked.page.heights,
+        this.lo,
+        this.hi,
+        this.layout.spacing,
+        new Uint8Array(SIDE * SIDE * 2)
+      ),
+      control: baked.page.control,
+      texels: void 0,
+      min: baked.min,
+      max: baked.max,
+      error: 0
+    };
+    this.put(page);
+    return page;
+  }
+  /** Every decoded page (pinned and cached). */
+  pages() {
+    return this.cache.values();
+  }
+  get cached() {
+    return this.cache.size;
+  }
+  get pendingReads() {
+    return this.inflight.size;
+  }
+  /** Forgets every index and page (after a rebake). Reads under way finish into the new cache. */
+  clear() {
+    this.indexes.clear();
+    this.cache.clear();
+    this.pinned.clear();
+  }
+}
+function decodeInline(packed, leaf, cells, lo, hi, spacing) {
+  const page = readPage(packed, leaf, cells);
+  const normals = page.normals ?? leafNormals(page.heights, lo, hi, spacing, new Uint8Array(SIDE * SIDE * 2));
+  const texels = pageTexels(
+    { heights: page.heights, normals, control: page.control },
+    leaf,
+    lo,
+    hi,
+    spacing,
+    new Uint8Array(LEAF_SIDE * LEAF_SIDE * 4)
+  );
+  return { heights: page.heights, normals, control: page.control, texels };
+}
+export {
+  PageStore,
+  keyDepth,
+  keyX,
+  keyZ,
+  nodeKey
+};

package/dist/heightfield/project.d.ts

@@ -0,0 +1,40 @@
+import type { AssetServer } from '@aethervtt/shard-assets';
+import { ShardError, type World } from '@aethervtt/shard-core';
+import type { PlatformFileSystem, Workers } from '@aethervtt/shard-platform';
+import { type BakeReport } from './bake.js';
+import type { Stack } from './kernel.js';
+import { type PackStore } from './pack.js';
+import { TerrainSourceAsset } from './source-asset.js';
+/** Where a terrain source's packs live, under the project: `.shard/cache/terrain/<guid>`. */
+export declare function terrainCacheDir(guid: string): string;
+/**
+ * The bake kernel's stack for a loaded source, from the noise graphs and heightmaps loaded in the
+ * world's stores. Throws `terrain/not-ready` while one isn't loaded.
+ */
+export declare function stackFor(world: World, asset: TerrainSourceAsset): Stack;
+/** Whether a terrain's packs match its source (a bake would rebake nothing it can't see). */
+export declare function bakeIsCurrent(store: PackStore, asset: TerrainSourceAsset): Promise<boolean>;
+/** What baking needs of a host: its file service and, where it has one, its worker pool. */
+export interface BakeHost {
+    readonly fs: PlatformFileSystem;
+    readonly workers?: Workers | undefined;
+}
+export interface ProjectBake {
+    path: string;
+    guid: string;
+    report: BakeReport;
+}
+/**
+ * Bakes a project's terrain sources into `.shard/cache/terrain/` (`shard import`, `shard terrain
+ * bake`): each one's assets loaded through the server, then an incremental bake (all of it with
+ * `force`). `only` limits it to sources whose path ends with it. Sources already current are
+ * skipped unless forced.
+ */
+export declare function bakeProjectTerrains(server: AssetServer, world: World, fs: PlatformFileSystem, options?: {
+    force?: boolean;
+    only?: string;
+    workers?: Workers;
+    warn?: (problem: ShardError, path: string) => void;
+    /** Bake even when the packs already match the source. */
+    always?: boolean;
+}): Promise<ProjectBake[]>;

package/dist/heightfield/project.js

@@ -0,0 +1,55 @@
+import { ShardError } from "@aethervtt/shard-core";
+import { NoiseGraphs } from "@aethervtt/shard-noise";
+import { bakeTerrain, readManifest } from "./bake.js";
+import { Heightmaps } from "./heightmap.js";
+import { fsPackStore } from "./pack.js";
+import { TerrainSourceAsset } from "./source-asset.js";
+import { compileStack } from "./stack.js";
+function terrainCacheDir(guid) {
+  return `.shard/cache/terrain/${guid.replace(/[^a-zA-Z0-9._-]/g, "-")}`;
+}
+function stackFor(world, asset) {
+  const need = (path, item) => {
+    if (item === void 0) {
+      throw new ShardError("terrain/not-ready", `The terrain is waiting for ${path}`, {
+        path,
+        hint: "Its assets load asynchronously; step a frame (or await the loads) first."
+      });
+    }
+    return item;
+  };
+  const guid = (path) => ({ guid: asset.deps[path]?.guid });
+  return compileStack(asset.source, {
+    noise: (path) => need(path, world.tryResource(NoiseGraphs)?.get(guid(path))),
+    heightmap: (path) => need(path, world.tryResource(Heightmaps)?.get(guid(path)))
+  });
+}
+async function bakeIsCurrent(store, asset) {
+  const manifest = await readManifest(store);
+  return manifest?.sourceHash === asset.hash;
+}
+async function bakeProjectTerrains(server, world, fs, options = {}) {
+  const out = [];
+  for (const entry of server.all("terrain/TerrainSource")) {
+    if (options.only && !entry.path.endsWith(options.only)) continue;
+    await server.load(entry.guid);
+    const asset = server.item(entry.guid);
+    if (!(asset instanceof TerrainSourceAsset)) continue;
+    const store = fsPackStore(fs, terrainCacheDir(entry.guid));
+    if (!options.force && !options.always && await bakeIsCurrent(store, asset)) continue;
+    const stack = stackFor(world, asset);
+    const report = await bakeTerrain(asset, stack, store, {
+      force: options.force === true,
+      ...options.workers ? { workers: options.workers } : {},
+      warn: (problem) => options.warn?.(problem, entry.path)
+    });
+    out.push({ path: entry.path, guid: entry.guid, report });
+  }
+  return out;
+}
+export {
+  bakeIsCurrent,
+  bakeProjectTerrains,
+  stackFor,
+  terrainCacheDir
+};

package/dist/heightfield/queries.d.ts

@@ -0,0 +1,48 @@
+import { type Entity, type World } from '@aethervtt/shard-core';
+import { type LoadedPage } from './pages.js';
+import type { HeightfieldRuntime } from './runtime.js';
+/** What `terrainHeightAt` found. */
+export interface TerrainHeight {
+    /** Metres, in the terrain's frame (its corner at 0). */
+    height: number;
+    /** The depth of the page it came from (the leaf depth is exact). */
+    depth: number;
+    /** Whether that's the leaf depth: the collider's own surface. */
+    exact: boolean;
+}
+/** The heightfield runtime of a Terrain entity, ready for queries, or a `terrain/*` error. */
+export declare function heightfieldRuntime(world: World, terrain: Entity): HeightfieldRuntime;
+/** The finest page held on the CPU that covers (x, z), deepest first. */
+export declare function finestPage(rt: HeightfieldRuntime, x: number, z: number): LoadedPage | undefined;
+/**
+ * The page's surface at (x, z): its cell's triangle split along (i+1, j)–(i, j+1), as the mesh and
+ * Rapier's heightfield are.
+ */
+export declare function pageHeight(rt: HeightfieldRuntime, page: LoadedPage, x: number, z: number): number;
+/**
+ * The ground's height at terrain point (x, z) (spec 0071): sync, from the finest page held on the
+ * CPU there (the coarse levels always are), with the depth it used. `loadTerrainRegion` first makes
+ * it exact (the leaf depth, the colliders' surface) away from anchors. Throws
+ * `terrain/out-of-bounds` off the terrain.
+ */
+export declare function terrainHeightAt(world: World, terrain: Entity, x: number, z: number, out?: TerrainHeight): TerrainHeight;
+/**
+ * Loads and pins the leaf pages over `rect` ([x0, z0, x1, z1] metres in the terrain's frame), so
+ * `terrainHeightAt` there is exact: gameplay that needs the colliders' heights away from anchors
+ * (spawn points, say). Resolves with the pages pinned.
+ */
+export declare function loadTerrainRegion(world: World, terrain: Entity, rect: readonly [number, number, number, number]): Promise<number>;
+/** Everything about the ground at a point: what `terrain.sample` reports. */
+export interface HeightfieldSample {
+    height: number;
+    /** Unit normal in the terrain's frame. */
+    normal: [number, number, number];
+    /** Degrees from flat. */
+    slope: number;
+    /** The two heaviest material layers (names) and the second's share of their weight. */
+    layers: [string, string];
+    share: number;
+    depth: number;
+}
+/** The ground at (x, z) from the finest page held (leaf pages after `loadTerrainRegion`). */
+export declare function heightfieldSample(rt: HeightfieldRuntime, x: number, z: number): HeightfieldSample;

package/dist/heightfield/queries.js

@@ -0,0 +1,150 @@
+import { ShardError } from "@aethervtt/shard-core";
+import { TerrainWorld } from "../heights.js";
+import { dequantize, LEAF_SIDE, PAGE, SIDE } from "./kernel.js";
+import { nodeKey } from "./pages.js";
+function heightfieldRuntime(world, terrain) {
+  const rt = world.tryResource(TerrainWorld)?.heightfields.get(terrain);
+  if (!rt) {
+    throw new ShardError("terrain/not-a-terrain", `Entity ${terrain} has no terrain/Terrain`, {
+      hint: "Add terrain/Terrain (with a Grid) to the entity, and the terrain plugin to the app."
+    });
+  }
+  if (rt.problem) throw rt.problem;
+  if (!rt.ready || !rt.pages) {
+    throw new ShardError(
+      "terrain/not-ready",
+      `Terrain ${terrain} is waiting for ${rt.waiting ?? "its source"}`,
+      {
+        hint: "Its source and assets load asynchronously; step a frame (or await them) first."
+      }
+    );
+  }
+  return rt;
+}
+function finestPage(rt, x, z) {
+  const layout = rt.layout;
+  if (x < 0 || z < 0 || x > layout.sizeX || z > layout.sizeZ) return void 0;
+  for (let depth = layout.depth; depth >= 0; depth--) {
+    const size = rt.nodeSize(depth);
+    const [nx, nz] = rt.pages.nodesAt(depth);
+    const px = Math.min(nx - 1, Math.floor(x / size));
+    const pz = Math.min(nz - 1, Math.floor(z / size));
+    const page = rt.pages.get(nodeKey(depth, px, pz));
+    if (page) return page;
+  }
+  return void 0;
+}
+function sample(rt, page, i, j) {
+  const side = page.leaf ? LEAF_SIDE : SIDE;
+  const o = page.leaf ? 1 : 0;
+  return dequantize(page.heights[(j + o) * side + i + o], rt.lo, rt.hi);
+}
+function pageHeight(rt, page, x, z) {
+  const size = rt.nodeSize(page.depth);
+  const fx = (x - page.x * size) / size * PAGE;
+  const fz = (z - page.z * size) / size * PAGE;
+  const i = Math.min(PAGE - 1, Math.max(0, Math.floor(fx)));
+  const j = Math.min(PAGE - 1, Math.max(0, Math.floor(fz)));
+  const u = Math.min(1, Math.max(0, fx - i));
+  const v = Math.min(1, Math.max(0, fz - j));
+  const h00 = sample(rt, page, i, j);
+  const h10 = sample(rt, page, i + 1, j);
+  const h01 = sample(rt, page, i, j + 1);
+  const h11 = sample(rt, page, i + 1, j + 1);
+  return u + v <= 1 ? h00 + u * (h10 - h00) + v * (h01 - h00) : h11 + (1 - u) * (h01 - h11) + (1 - v) * (h10 - h11);
+}
+function terrainHeightAt(world, terrain, x, z, out = { height: 0, depth: 0, exact: false }) {
+  const rt = heightfieldRuntime(world, terrain);
+  const page = finestPage(rt, x, z);
+  if (!page) {
+    const l = rt.layout;
+    if (x < 0 || z < 0 || x > l.sizeX || z > l.sizeZ) {
+      throw new ShardError(
+        "terrain/out-of-bounds",
+        `(${x}, ${z}) is off the terrain (0\u2013${l.sizeX} \xD7 0\u2013${l.sizeZ} m)`,
+        {
+          hint: "Points are metres from the terrain\u2019s corner in its frame."
+        }
+      );
+    }
+    throw new ShardError("terrain/not-ready", "The terrain\u2019s coarse levels are still loading", {
+      hint: "Step a few frames, or await loadTerrainRegion first."
+    });
+  }
+  out.height = pageHeight(rt, page, x, z);
+  out.depth = page.depth;
+  out.exact = page.depth === rt.layout.depth;
+  return out;
+}
+async function loadTerrainRegion(world, terrain, rect) {
+  const rt = heightfieldRuntime(world, terrain);
+  const layout = rt.layout;
+  const size = layout.leafSize;
+  const D = layout.depth;
+  const x0 = Math.max(0, Math.floor(rect[0] / size));
+  const z0 = Math.max(0, Math.floor(rect[1] / size));
+  const x1 = Math.min(layout.leavesX - 1, Math.floor(rect[2] / size));
+  const z1 = Math.min(layout.leavesZ - 1, Math.floor(rect[3] / size));
+  const loads = [];
+  for (let z = z0; z <= z1; z++) {
+    for (let x = x0; x <= x1; x++) {
+      rt.pages.pin(nodeKey(D, x, z));
+      loads.push(rt.pages.load(D, x, z));
+    }
+  }
+  await Promise.all(loads);
+  return loads.length;
+}
+function heightfieldSample(rt, x, z) {
+  const page = finestPage(rt, x, z);
+  if (!page) {
+    throw new ShardError("terrain/out-of-bounds", `(${x}, ${z}) is off the terrain`, {
+      hint: "Points are metres from the terrain\u2019s corner in its frame."
+    });
+  }
+  const size = rt.nodeSize(page.depth);
+  const fx = (x - page.x * size) / size * PAGE;
+  const fz = (z - page.z * size) / size * PAGE;
+  const i = Math.min(PAGE, Math.max(0, Math.round(fx)));
+  const j = Math.min(PAGE, Math.max(0, Math.round(fz)));
+  const spacing = size / PAGE;
+  const ci = Math.min(PAGE - 1, Math.max(0, Math.floor(fx)));
+  const cj = Math.min(PAGE - 1, Math.max(0, Math.floor(fz)));
+  const u = fx - ci;
+  const v = fz - cj;
+  let dx;
+  let dz;
+  if (u + v <= 1) {
+    dx = (sample(rt, page, ci + 1, cj) - sample(rt, page, ci, cj)) / spacing;
+    dz = (sample(rt, page, ci, cj + 1) - sample(rt, page, ci, cj)) / spacing;
+  } else {
+    dx = (sample(rt, page, ci + 1, cj + 1) - sample(rt, page, ci, cj + 1)) / spacing;
+    dz = (sample(rt, page, ci + 1, cj + 1) - sample(rt, page, ci + 1, cj)) / spacing;
+  }
+  const l = Math.sqrt(dx * dx + 1 + dz * dz);
+  const normal = [-dx / l, 1 / l, -dz / l];
+  const cells = rt.layout.cells;
+  const k = PAGE / cells;
+  const ci2 = Math.min(cells, Math.max(0, Math.round(i / k)));
+  const cj2 = Math.min(cells, Math.max(0, Math.round(j / k)));
+  const o = (cj2 * (cells + 1) + ci2) * 4;
+  const names = rt.asset.source.layers.map((layer) => layer.name);
+  const a = page.control[o];
+  const b = page.control[o + 1];
+  return {
+    height: pageHeight(rt, page, x, z),
+    normal,
+    slope: Math.acos(Math.min(1, normal[1])) * 180 / Math.PI,
+    layers: [names[a] ?? "", names[b] ?? ""],
+    share: page.control[o + 2] / 255,
+    depth: page.depth
+  };
+}
+export {
+  finestPage,
+  heightfieldRuntime,
+  heightfieldSample,
+  loadTerrainRegion,
+  pageHeight,
+  terrainHeightAt
+};

package/dist/heightfield/render.d.ts

@@ -0,0 +1,108 @@
+import { type AssetRef, type Entity, type World } from '@aethervtt/shard-core';
+import { MaterialAsset } from '@aethervtt/shard-render';
+import { Texture } from '@aethervtt/shard-texture';
+import { type LoadedPage } from './pages.js';
+import type { HeightfieldRuntime } from './runtime.js';
+/** Atlas side of the page pool (texels): within WebGL2's floor of 2048. */
+export declare const ATLAS = 2048;
+/** Pages per atlas row, and per layer. */
+export declare const PER_ROW: number;
+export declare const PER_LAYER: number;
+/** Debug shading and test hooks for heightfields. */
+export declare const HeightfieldDebug: {
+    /** 0 off, 1 layers, 2 seams, 3 levels, 4 normals, 5 pages. */
+    mode: number;
+};
+/** The chunk drawing one pool slot. */
+interface ChunkEntity {
+    entity: Entity;
+    /** The node it's placed for (nodeKey), or −1. */
+    key: number;
+    /** Index set drawn: quadrant mask + 16 × stitched edges. */
+    variant: number;
+    shown: boolean;
+    fade: number;
+    used: number;
+}
+/**
+ * Render-side state of one heightfield (spec 0071): the GPU page pool (two texture arrays: page
+ * texels and control texels, `TerrainBudget.pages` slots, least recently used out, coarse levels
+ * pinned), the chunk table, reads in flight and pages waiting to upload, and one chunk entity per
+ * slot drawing the shared grid mesh with its index set.
+ */
+export declare class HeightfieldRender {
+    readonly material: MaterialAsset;
+    readonly materialRef: AssetRef<'Material'>;
+    capacity: number;
+    layers: number;
+    pages: Texture | undefined;
+    pagesRef: AssetRef | undefined;
+    /** The pool's GPU textures this frame (looked up in First). */
+    gpuPages: GPUTexture | undefined;
+    gpuControl: GPUTexture | undefined;
+    control: Texture | undefined;
+    controlRef: AssetRef | undefined;
+    chunksTexture: Texture | undefined;
+    chunksRef: AssetRef | undefined;
+    layerRef: AssetRef | undefined;
+    layerHash: string;
+    /** Per slot: node key (−1 free), frame last drawn, pinned. */
+    slotKey: Float64Array<ArrayBuffer>;
+    slotUsed: Uint32Array<ArrayBuffer>;
+    slotPinned: Uint8Array<ArrayBuffer>;
+    readonly keySlot: Map<number, number>;
+    /** Chunk table bytes (RGBA8 per slot: lock bits, quadrant mask, fade, depth). */
+    table: Uint8Array<ArrayBuffer>;
+    tableDirty: boolean;
+    chunks: (ChunkEntity | undefined)[];
+    /** Pages read and waiting to upload, in arrival order. */
+    arrived: LoadedPage[];
+    /** Keys read or waiting, so a node is asked for once. */
+    readonly pending: Set<number>;
+    readonly meshes: Map<number, AssetRef<"Mesh">>;
+    readonly view: import("..").SelectionView;
+    /** The selecting camera in the origin frame (xyz), pixels per radian / errorPixels (w). */
+    readonly camera: Float32Array<ArrayBuffer>;
+    hasCamera: boolean;
+    /** The walk stamp last frame (what was on screen then). */
+    lastStamp: number;
+    /** The terrain version the pool's pages are from. */
+    version: number;
+    /** The grid the pool's pages are for. */
+    layout: object | undefined;
+    /** The terrain version whose coarse levels went to the pool. */
+    residentVersion: number;
+    stats: {
+        uploaded: number;
+        evicted: number;
+        uploadedLastFrame: number;
+        requested: number;
+        skippedFull: number;
+    };
+    constructor(world: World);
+    /** The pool slot holding a node's page, or −1. */
+    slotOf(key: number): number;
+    get used(): number;
+}
+export declare function heightfieldRenderOf(world: World, rt: HeightfieldRuntime): HeightfieldRender;
+/**
+ * Uploads pages that arrived into the pool (spec 0071), in `First`: pinned coarse levels first and
+ * all at once, then in arrival order (reads start highest projected error first), at most
+ * `TerrainBudget.pagesPerFrame` a frame. A node becomes drawable the frame its page lands. Writes
+ * go through the GPU queue, so 0055's upload accounting counts them.
+ */
+export declare const uploadHeightfieldPages: import("@aethervtt/shard-core").SystemDef<undefined>;
+/**
+ * Chooses each heightfield's nodes for the selecting camera (spec 0071, 0043's selection on the
+ * root grid), reads the pages they need (highest projected error first), and shows exactly the
+ * selected chunks. Pages arrive asynchronously and upload in `First`; a split waits for its
+ * children's pages, drawing its own quadrants meanwhile.
+ */
+export declare const selectHeightfields: import("@aethervtt/shard-core").SystemDef<{
+    cameras: import("@aethervtt/shard-core").Query;
+}>;
+/** The coarse levels, pinned in the CPU cache, go to the pool once streaming starts. */
+export declare function enqueueResident(rt: HeightfieldRuntime, r: HeightfieldRender): void;
+/** Despawns a heightfield's chunk entities and frees its textures, meshes and material. */
+export declare function cleanupHeightfieldRender(world: World, rt: HeightfieldRuntime): void;
+export {};