@aethervtt/shard-terrain 0.1.0 → 0.2.1

package/dist/heightfield/bake.js

@@ -0,0 +1,494 @@
+import { sha256Hex } from "@aethervtt/shard-assets";
+import { ShardError } from "@aethervtt/shard-core";
+import { loadNoiseKernel, NOISE_KERNEL_MODULE } from "@aethervtt/shard-noise";
+import {
+  BAKE_VERSION,
+  bakeBlock,
+  deflate,
+  encodePage,
+  PAGE,
+  pageBytes,
+  pageNormal,
+  parentPage,
+  readPage,
+  SIDE
+} from "./kernel.js";
+import { PACK, packOf, readIndex, writePack } from "./pack.js";
+import { mainNoise } from "./stack.js";
+const WORKER = new URL("./worker.js", import.meta.url).href;
+const MANIFEST = "manifest.json";
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+async function readManifest(store) {
+  const bytes = await store.read(MANIFEST);
+  if (!bytes) return void 0;
+  try {
+    const m = JSON.parse(decoder.decode(bytes));
+    return m.format === 1 ? m : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function gridOf(input) {
+  const l = input.layout;
+  return {
+    sizeX: l.sizeX,
+    sizeZ: l.sizeZ,
+    spacing: l.spacing,
+    paintSpacing: l.paintSpacing,
+    depth: l.depth,
+    block: l.block,
+    heightRange: input.source.heightRange
+  };
+}
+function rectBox(r, grow) {
+  const a = r.rotation * Math.PI / 180;
+  const hw = r.size[0] / 2;
+  const hd = r.size[1] / 2;
+  const ex = Math.abs(Math.cos(a)) * hw + Math.abs(Math.sin(a)) * hd + grow;
+  const ez = Math.abs(Math.sin(a)) * hw + Math.abs(Math.cos(a)) * hd + grow;
+  return [r.at[0] - ex, r.at[1] - ez, r.at[0] + ex, r.at[1] + ez];
+}
+const overlaps = (a, b) => a[0] <= b[2] && b[0] <= a[2] && a[1] <= b[3] && b[1] <= a[3];
+async function blockKeys(input, stack) {
+  const { source, layout } = input;
+  const base = JSON.stringify({
+    v: BAKE_VERSION,
+    grid: gridOf(input),
+    seed: source.seed,
+    layers: source.layers.map((l) => l.name)
+  });
+  const parts = [];
+  const digest = async (value, extra) => {
+    const text = JSON.stringify(value);
+    const bytes = encoder.encode(text);
+    if (!extra) return sha256Hex(bytes);
+    const f = Float64Array.from(extra);
+    const all = new Uint8Array(bytes.length + f.byteLength);
+    all.set(bytes);
+    all.set(new Uint8Array(f.buffer), bytes.length);
+    return sha256Hex(all);
+  };
+  for (let i = 0; i < source.height.length; i++) {
+    const l = source.height[i];
+    const s = stack.height[i];
+    if (l.kind === "noise") {
+      parts.push({
+        box: l.region ? rectBox(l.region, l.falloff) : void 0,
+        digest: await digest(["h", i, l, input.deps[l.noise.path]?.hash ?? ""], void 0)
+      });
+    } else if (l.kind === "image") {
+      parts.push({
+        box: rectBox(l, l.falloff),
+        digest: await digest(["h", i, l, input.deps[l.image.path]?.hash ?? ""], void 0)
+      });
+    } else {
+      const sp = s.spline;
+      parts.push({
+        box: [sp.minX, sp.minZ, sp.maxX, sp.maxZ],
+        digest: await digest(["h", i, l, source.splines[l.spline]], sp.pts)
+      });
+    }
+  }
+  for (let i = 0; i < source.paint.length; i++) {
+    const p = source.paint[i];
+    let box;
+    const clip = (b) => {
+      box = box ? [
+        Math.max(box[0], b[0]),
+        Math.max(box[1], b[1]),
+        Math.min(box[2], b[2]),
+        Math.min(box[3], b[3])
+      ] : b;
+    };
+    if (p.mask) clip(rectBox(p.mask, p.blend));
+    const sp = stack.paint[i].spline;
+    if (sp) clip([sp.minX, sp.minZ, sp.maxX, sp.maxZ]);
+    parts.push({
+      box,
+      digest: await digest(
+        [
+          "p",
+          i,
+          p,
+          p.noise ? input.deps[p.noise.ref.path]?.hash ?? "" : "",
+          p.mask ? input.deps[p.mask.ref.path]?.hash ?? "" : "",
+          p.spline ? source.splines[p.spline] : null
+        ],
+        sp?.pts
+      )
+    });
+  }
+  const margin = (2 ** Math.min(layout.blockLevels, layout.depth) + 1) * layout.spacing;
+  const size = layout.block * layout.leafSize;
+  const keys = [];
+  for (let bz = 0; bz < layout.blocksZ; bz++) {
+    for (let bx = 0; bx < layout.blocksX; bx++) {
+      const box = [
+        bx * size - margin,
+        bz * size - margin,
+        Math.min(layout.sizeX, (bx + 1) * size) + margin,
+        Math.min(layout.sizeZ, (bz + 1) * size) + margin
+      ];
+      const touching = parts.filter((p) => !p.box || overlaps(p.box, box)).map((p) => p.digest);
+      keys.push(await sha256Hex(encoder.encode(`${base}
+${touching.join("\n")}`)));
+    }
+  }
+  return keys;
+}
+class PageReader {
+  indexes = /* @__PURE__ */ new Map();
+  pages = /* @__PURE__ */ new Map();
+  store;
+  layout;
+  /** Pages this bake made, by "level/x/z". */
+  fresh;
+  /** Whether the stored packs match this grid (else they're ignored). */
+  usePacks;
+  constructor(store, layout, fresh, usePacks) {
+    this.store = store;
+    this.layout = layout;
+    this.fresh = fresh;
+    this.usePacks = usePacks;
+  }
+  index(path) {
+    let p = this.indexes.get(path);
+    if (!p) {
+      p = this.usePacks ? this.store.read(path).then((bytes) => bytes ? readIndex(path, bytes) : void 0) : Promise.resolve(void 0);
+      this.indexes.set(path, p);
+    }
+    return p;
+  }
+  /** Index entry and bytes of a stored page, or undefined. */
+  async stored(level, x, z) {
+    const depth = this.layout.depth - level;
+    const { path, slot } = packOf(depth, x, z);
+    const index = await this.index(path);
+    const e = index?.entries[slot];
+    if (!e || e.length === 0) return void 0;
+    const bytes = await this.store.read(path);
+    return { entry: e, data: bytes.subarray(e.offset, e.offset + e.length) };
+  }
+  /** A node's decoded page (fresh first), or null past the terrain's edge or where none is stored. */
+  page(level, x, z) {
+    const key = `${level}/${x}/${z}`;
+    let p = this.pages.get(key);
+    if (!p) {
+      p = (async () => {
+        const n = this.nodes(level);
+        if (x < 0 || z < 0 || x >= n[0] || z >= n[1]) return null;
+        const f = this.fresh.get(key);
+        const data = f ? f.data : (await this.stored(level, x, z))?.data;
+        return data ? readPage(data, level === 0, this.layout.cells) : null;
+      })();
+      this.pages.set(key, p);
+    }
+    return p;
+  }
+  /** Height range of a node (fresh first). */
+  async range(level, x, z) {
+    const f = this.fresh.get(`${level}/${x}/${z}`);
+    if (f) return [f.min, f.max];
+    const s = await this.stored(level, x, z);
+    return s ? [s.entry.min, s.entry.max] : void 0;
+  }
+  nodes(level) {
+    return [this.layout.leavesX >> level, this.layout.leavesZ >> level];
+  }
+}
+async function bakeTerrain(input, stack, store, options = {}) {
+  const t0 = performance.now();
+  const { layout } = input;
+  const D = layout.depth;
+  const lmax = Math.min(layout.blockLevels, D);
+  const previous = await readManifest(store);
+  const grid = gridOf(input);
+  const compatible = !options.force && previous !== void 0 && previous.bakeVersion === BAKE_VERSION && JSON.stringify(previous.grid) === JSON.stringify(grid);
+  const keys = await blockKeys(input, stack);
+  const blocks = {};
+  const stale = [];
+  for (let bz = 0; bz < layout.blocksZ; bz++) {
+    for (let bx = 0; bx < layout.blocksX; bx++) {
+      const id = `${bx},${bz}`;
+      const key = keys[bz * layout.blocksX + bx];
+      const old = compatible ? previous.blocks[id] : void 0;
+      if (old && old.key === key) blocks[id] = old;
+      else stale.push([bx, bz]);
+    }
+  }
+  const fresh = /* @__PURE__ */ new Map();
+  const reader = new PageReader(store, layout, fresh, compatible);
+  if (compatible) {
+    for (let bz = 0; bz < layout.blocksZ; bz++) {
+      for (let bx = 0; bx < layout.blocksX; bx++) {
+        const id = `${bx},${bz}`;
+        if (!blocks[id]) continue;
+        const { path } = packOf(D, bx * layout.block, bz * layout.block);
+        if (!await reader.index(path)) {
+          delete blocks[id];
+          stale.push([bx, bz]);
+        }
+      }
+    }
+  }
+  const kernel = await loadNoiseKernel();
+  const workers = options.workers && options.workers.size > 0 ? options.workers : void 0;
+  let done = 0;
+  let poolMs = 0;
+  const outOfRange = [];
+  const blockSize = layout.block * layout.leafSize;
+  await Promise.all(
+    stale.map(async ([bx, bz]) => {
+      const result = workers ? await workers.run(
+        WORKER,
+        "bakeBlock",
+        [NOISE_KERNEL_MODULE, kernel.module, stack, layout, bx, bz],
+        { kind: "terrain/bake-block" }
+      ) : bakeBlock(mainNoise(), stack, layout, bx, bz);
+      poolMs += result.ms;
+      const errors = new Array(D + 1).fill(0);
+      for (const p of result.pages) {
+        fresh.set(`${p.level}/${p.x}/${p.z}`, p);
+        if (p.level > 0) errors[p.level] = Math.max(errors[p.level], p.error);
+      }
+      result.above.forEach((e, i) => {
+        errors[lmax + 1 + i] = e;
+      });
+      blocks[`${bx},${bz}`] = {
+        key: keys[bz * layout.blocksX + bx],
+        errors,
+        range: result.range,
+        clipped: result.clipped,
+        lowest: result.lowest,
+        highest: result.highest,
+        ms: result.ms
+      };
+      if (result.clipped > 0) {
+        const rect = [
+          bx * blockSize,
+          bz * blockSize,
+          Math.min(layout.sizeX, (bx + 1) * blockSize),
+          Math.min(layout.sizeZ, (bz + 1) * blockSize)
+        ];
+        outOfRange.push({
+          rect,
+          samples: result.clipped,
+          lowest: result.lowest,
+          highest: result.highest
+        });
+        options.warn?.(
+          new ShardError(
+            "terrain/out-of-range",
+            `${result.clipped} heights in [${rect.join(", ")}] fall outside heightRange [${input.source.heightRange.join(", ")}] (from ${result.lowest.toFixed(1)} to ${result.highest.toFixed(1)} m) and were clipped`,
+            {
+              path: "/heightRange",
+              hint: "Widen heightRange to cover them (heights are 16-bit over it), or lower the layers that push past it."
+            }
+          )
+        );
+      }
+      options.onProgress?.(++done, stale.length);
+    })
+  );
+  let ancestors = 0;
+  const normals = /* @__PURE__ */ new WeakMap();
+  const v = new Float64Array(3);
+  const unpacked = (page) => {
+    let n = normals.get(page);
+    if (!n) {
+      n = new Float32Array(SIDE * SIDE * 3);
+      for (let k = 0; k < SIDE * SIDE; k++) {
+        pageNormal(page, k % SIDE, Math.floor(k / SIDE), v);
+        n[k * 3] = v[0];
+        n[k * 3 + 1] = v[1];
+        n[k * 3 + 2] = v[2];
+      }
+      normals.set(page, n);
+    }
+    return n;
+  };
+  for (let L = lmax + 1; L <= D; L++) {
+    const dirty = /* @__PURE__ */ new Set();
+    for (const [bx, bz] of stale)
+      dirty.add(`${bx * layout.block >> L},${bz * layout.block >> L}`);
+    for (const id of [...dirty].sort()) {
+      const [X, Z] = id.split(",").map(Number);
+      const ring = new Array(16).fill(null);
+      await Promise.all(
+        ring.map(async (_, k) => {
+          ring[k] = await reader.page(L - 1, 2 * X + k % 4 - 1, 2 * Z + Math.floor(k / 4) - 1);
+        })
+      );
+      const children = [ring[5], ring[6], ring[9], ring[10]];
+      const normalAt = (gi, gj, out) => {
+        let c = gi < 0 ? -1 : gi > 2 * PAGE ? 2 : gi === 2 * PAGE ? 1 : Math.floor(gi / PAGE);
+        let r = gj < 0 ? -1 : gj > 2 * PAGE ? 2 : gj === 2 * PAGE ? 1 : Math.floor(gj / PAGE);
+        let page = ring[(r + 1) * 4 + c + 1];
+        if (!page) {
+          gi = Math.min(2 * PAGE, Math.max(0, gi));
+          gj = Math.min(2 * PAGE, Math.max(0, gj));
+          c = gi === 2 * PAGE ? 1 : Math.floor(gi / PAGE);
+          r = gj === 2 * PAGE ? 1 : Math.floor(gj / PAGE);
+          page = ring[(r + 1) * 4 + c + 1];
+        }
+        if (!page) {
+          out[0] = 0;
+          out[1] = 1;
+          out[2] = 0;
+          return;
+        }
+        const n = unpacked(page);
+        const o = ((gj - r * PAGE) * SIDE + gi - c * PAGE) * 3;
+        out[0] = n[o];
+        out[1] = n[o + 1];
+        out[2] = n[o + 2];
+      };
+      const parent = parentPage(children, layout.cells, normalAt);
+      let min = 65535;
+      let max = 0;
+      for (let c = 0; c < 4; c++) {
+        const range = await reader.range(L - 1, 2 * X + (c & 1), 2 * Z + (c >> 1));
+        if (!range) continue;
+        min = Math.min(min, range[0]);
+        max = Math.max(max, range[1]);
+      }
+      let error = 0;
+      const span = 2 ** L / layout.block;
+      for (let bz = Z * span; bz < Math.min(layout.blocksZ, (Z + 1) * span); bz++)
+        for (let bx = X * span; bx < Math.min(layout.blocksX, (X + 1) * span); bx++)
+          error = Math.max(error, blocks[`${bx},${bz}`]?.errors[L] ?? 0);
+      fresh.set(`${L}/${X}/${Z}`, {
+        level: L,
+        x: X,
+        z: Z,
+        data: deflate(encodePage(parent, false, layout.cells)),
+        min,
+        max,
+        error
+      });
+      ancestors++;
+    }
+  }
+  const packs = /* @__PURE__ */ new Map();
+  for (const p of fresh.values()) {
+    const depth = D - p.level;
+    const { path } = packOf(depth, p.x, p.z);
+    packs.set(path, { depth, gx: Math.floor(p.x / PACK), gz: Math.floor(p.z / PACK) });
+  }
+  let bytes = 0;
+  for (const [path, { depth, gx, gz }] of [...packs].sort((a, b) => a[0] < b[0] ? -1 : 1)) {
+    const level = D - depth;
+    const pages = [];
+    for (let slot = 0; slot < PACK * PACK; slot++) {
+      const x = gx * PACK + slot % PACK;
+      const z = gz * PACK + Math.floor(slot / PACK);
+      const f = fresh.get(`${level}/${x}/${z}`);
+      if (f) pages.push(f);
+      else {
+        const s = await reader.stored(level, x, z);
+        pages.push(s ? { data: s.data, ...s.entry } : null);
+      }
+    }
+    const pack = writePack(depth, gx, gz, pages);
+    await store.write(path, pack);
+    bytes += pack.length;
+  }
+  const depthErrors = new Array(D + 1).fill(0);
+  for (const record of Object.values(blocks)) {
+    for (let L = 1; L <= D; L++)
+      depthErrors[D - L] = Math.max(depthErrors[D - L], record.errors[L] ?? 0);
+  }
+  const sorted = {};
+  for (let bz = 0; bz < layout.blocksZ; bz++) {
+    for (let bx = 0; bx < layout.blocksX; bx++) {
+      const record = blocks[`${bx},${bz}`];
+      if (record) sorted[`${bx},${bz}`] = record;
+    }
+  }
+  const manifest = {
+    format: 1,
+    bakeVersion: BAKE_VERSION,
+    grid,
+    blocks: sorted,
+    depthErrors,
+    sourceHash: input.hash
+  };
+  await store.write(MANIFEST, encoder.encode(`${JSON.stringify(manifest)}
+`));
+  return {
+    blocks: layout.blocksX * layout.blocksZ,
+    rebaked: stale.length,
+    dirtied: stale.map(([x, z]) => `${x},${z}`),
+    pages: fresh.size,
+    ancestors,
+    bytes,
+    ms: performance.now() - t0,
+    msPerBlock: stale.length > 0 ? poolMs / stale.length : 0,
+    outOfRange
+  };
+}
+async function terrainStats(input, store, manifest) {
+  const { layout } = input;
+  let pages = 0;
+  let rawBytes = 0;
+  if (manifest) {
+    for (let depth = 0; depth <= layout.depth; depth++) {
+      const level = layout.depth - depth;
+      const nx = layout.leavesX >> level;
+      const nz = layout.leavesZ >> level;
+      for (let gz = 0; gz < Math.ceil(nz / PACK); gz++) {
+        for (let gx = 0; gx < Math.ceil(nx / PACK); gx++) {
+          const path = `d${depth}/${gx}_${gz}.pack`;
+          const bytes = await store.read(path);
+          if (!bytes) continue;
+          for (const e of readIndex(path, bytes).entries) {
+            if (e.length === 0) continue;
+            pages++;
+            rawBytes += pageBytes(level === 0, layout.cells);
+          }
+        }
+      }
+    }
+  }
+  const samples = layout.sizeX / layout.spacing * (layout.sizeZ / layout.spacing);
+  const bytesOnDisk = await store.size();
+  const times = Object.values(manifest?.blocks ?? {}).map((b) => b.ms);
+  return {
+    baked: manifest !== void 0,
+    current: manifest?.sourceHash === input.hash,
+    size: [layout.sizeX, layout.sizeZ],
+    spacing: layout.spacing,
+    roots: layout.rootsX * layout.rootsZ,
+    depth: layout.depth,
+    blocks: layout.blocksX * layout.blocksZ,
+    pages,
+    rawBytes,
+    bytesOnDisk,
+    bytesPerSample: rawBytes / samples,
+    diskBytesPerSample: bytesOnDisk / samples,
+    msPerBlock: times.length > 0 ? times.reduce((a, b) => a + b, 0) / times.length : 0,
+    slowestBlockMs: times.length > 0 ? Math.max(...times) : 0
+  };
+}
+async function packHash(files) {
+  const paths = [...files.keys()].filter((p) => p !== MANIFEST).sort();
+  let size = 0;
+  for (const p of paths) size += p.length + files.get(p).length;
+  const all = new Uint8Array(size);
+  let o = 0;
+  for (const p of paths) {
+    all.set(encoder.encode(p), o);
+    o += p.length;
+    all.set(files.get(p), o);
+    o += files.get(p).length;
+  }
+  return sha256Hex(all);
+}
+export {
+  bakeTerrain,
+  blockKeys,
+  packHash,
+  readManifest,
+  terrainStats
+};

package/dist/heightfield/colliders.d.ts

@@ -0,0 +1,39 @@
+import { type Entity, type World } from '@aethervtt/shard-core';
+import type { HeightfieldRuntime } from './runtime.js';
+/** A heightfield collider tile: one leaf page as a fixed body. */
+export interface ColliderTile {
+    key: number;
+    x: number;
+    z: number;
+    /** The collider entity, or −1 while not wanted. */
+    entity: Entity;
+    /** The terrain version its heights are from. */
+    version: number;
+    used: number;
+    /** Heights (m), SIDE × SIDE, row by row along +Z: what Rapier gets. */
+    heights: number[];
+}
+/** A terrain's collider tiles, and when the wanted ones are due. */
+export declare class TileSet {
+    readonly tiles: Map<number, ColliderTile>;
+    /** Wanted keys → the frame each becomes a tile. */
+    readonly due: Map<number, number>;
+    /** Keys wanted this frame, sorted. */
+    wanted: number[];
+    /** Tiles made from a page that had arrived, and baked on the main thread at their due frame. */
+    fromPages: number;
+    bakedInline: number;
+}
+export declare function tilesOf(rt: HeightfieldRuntime): TileSet;
+/** Leaf tiles within reach of the runtime's anchors, as sorted keys. */
+export declare function wantedTiles(rt: HeightfieldRuntime): number[];
+/**
+ * Keeps a heightfield's collider tiles around its anchors (spec 0071): a leaf page within reach
+ * becomes a fixed body with a Rapier heightfield exactly COLLIDER_DELAY frames after it's wanted,
+ * from its page when the read has landed and baked here when it hasn't. Both are the same bytes
+ * (canonical samples), so the world never depends on IO timing. Unwanted tiles despawn but stay
+ * cached (least recently used out).
+ */
+export declare function updateHeightfieldColliders(world: World, rt: HeightfieldRuntime, frame: number, cacheSize: number): void;
+/** Drops every collider tile (terrain despawned). */
+export declare function clearHeightfieldColliders(world: World, rt: HeightfieldRuntime): void;

package/dist/heightfield/colliders.js

@@ -0,0 +1,152 @@
+import { ChildOf, Derived } from "@aethervtt/shard-core";
+import { NavSource } from "@aethervtt/shard-nav";
+import { Collider, RigidBody } from "@aethervtt/shard-physics";
+import { placeInGrid, propagateSubtree, Transform } from "@aethervtt/shard-transform";
+import { COLLIDER_DELAY } from "../colliders.js";
+import { TerrainChunk } from "./component.js";
+import { dequantize, LEAF_SIDE, SIDE } from "./kernel.js";
+import { keyX, keyZ, nodeKey } from "./pages.js";
+import { mainNoise } from "./stack.js";
+class TileSet {
+  tiles = /* @__PURE__ */ new Map();
+  /** Wanted keys → the frame each becomes a tile. */
+  due = /* @__PURE__ */ new Map();
+  /** Keys wanted this frame, sorted. */
+  wanted = [];
+  /** Tiles made from a page that had arrived, and baked on the main thread at their due frame. */
+  fromPages = 0;
+  bakedInline = 0;
+}
+function tilesOf(rt) {
+  let set = rt.parts.get("colliders");
+  if (!set) {
+    set = new TileSet();
+    rt.parts.set("colliders", set);
+  }
+  return set;
+}
+const wantedKeys = /* @__PURE__ */ new Set();
+function wantedTiles(rt) {
+  wantedKeys.clear();
+  const layout = rt.layout;
+  const size = layout.leafSize;
+  const D = layout.depth;
+  for (let i = 0; i < rt.anchors; i++) {
+    const ax = rt.anchorPos[i * 3];
+    const az = rt.anchorPos[i * 3 + 2];
+    const r = rt.anchorRadius[i];
+    const x0 = Math.max(0, Math.floor((ax - r) / size));
+    const x1 = Math.min(layout.leavesX - 1, Math.floor((ax + r) / size));
+    const z0 = Math.max(0, Math.floor((az - r) / size));
+    const z1 = Math.min(layout.leavesZ - 1, Math.floor((az + r) / size));
+    for (let z = z0; z <= z1; z++) {
+      for (let x = x0; x <= x1; x++) {
+        const dx = Math.max(x * size - ax, 0, ax - (x + 1) * size);
+        const dz = Math.max(z * size - az, 0, az - (z + 1) * size);
+        if (dx * dx + dz * dz <= r * r) wantedKeys.add(nodeKey(D, x, z));
+      }
+    }
+  }
+  return [...wantedKeys].sort((a, b) => a - b);
+}
+function updateHeightfieldColliders(world, rt, frame, cacheSize) {
+  const set = tilesOf(rt);
+  const pages = rt.pages;
+  if (!rt.ready || !pages) return;
+  const wanted = wantedTiles(rt);
+  set.wanted = wanted;
+  const D = rt.layout.depth;
+  for (const key of wanted) {
+    const tile = set.tiles.get(key);
+    if (tile && tile.version === rt.version) {
+      tile.used = frame;
+      if (tile.entity < 0) spawnTile(world, rt, tile);
+      continue;
+    }
+    let due = set.due.get(key);
+    if (due === void 0) {
+      due = frame + COLLIDER_DELAY;
+      set.due.set(key, due);
+      void pages.load(D, keyX(key), keyZ(key)).catch(() => {
+      });
+    }
+    if (frame < due) continue;
+    set.due.delete(key);
+    const cached = pages.get(key);
+    const page = cached ?? pages.leafNow(mainNoise(), rt.stack, keyX(key), keyZ(key));
+    if (cached) set.fromPages++;
+    else set.bakedInline++;
+    const heights = new Array(SIDE * SIDE);
+    for (let j = 0; j < SIDE; j++) {
+      for (let i = 0; i < SIDE; i++)
+        heights[j * SIDE + i] = dequantize(page.heights[(j + 1) * LEAF_SIDE + i + 1], rt.lo, rt.hi);
+    }
+    if (tile) despawnTile(world, tile);
+    const next = {
+      key,
+      x: keyX(key),
+      z: keyZ(key),
+      entity: -1,
+      version: rt.version,
+      used: frame,
+      heights
+    };
+    set.tiles.set(key, next);
+    spawnTile(world, rt, next);
+  }
+  const keep = new Set(wanted);
+  for (const key of set.due.keys()) if (!keep.has(key)) set.due.delete(key);
+  for (const tile of set.tiles.values())
+    if (!keep.has(tile.key) && tile.entity >= 0) despawnTile(world, tile);
+  if (set.tiles.size > cacheSize) {
+    const idle = [...set.tiles.values()].filter((t) => t.entity < 0).sort((a, b) => a.used - b.used || a.key - b.key);
+    for (let i = 0; i < idle.length && set.tiles.size > cacheSize; i++)
+      set.tiles.delete(idle[i].key);
+  }
+}
+const center = new Float64Array(3);
+function spawnTile(world, rt, tile) {
+  const size = rt.layout.leafSize;
+  const e = world.spawn(
+    [RigidBody, { kind: "fixed" }],
+    [
+      Collider,
+      {
+        shape: "heightfield",
+        halfExtents: [size / 2, 1, size / 2],
+        heightfield: { rows: SIDE, cols: SIDE, heights: tile.heights }
+      }
+    ],
+    [
+      TerrainChunk,
+      { terrain: rt.entity, key: `${rt.layout.depth}/${tile.x}/${tile.z}`, kind: "collider" }
+    ],
+    [ChildOf, { parent: rt.entity }],
+    NavSource,
+    Transform,
+    Derived
+  );
+  center[0] = (tile.x + 0.5) * size;
+  center[1] = 0;
+  center[2] = (tile.z + 0.5) * size;
+  placeInGrid(world, e, rt.entity, center);
+  propagateSubtree(world, e);
+  tile.entity = e;
+}
+function despawnTile(world, tile) {
+  if (world.isAlive(tile.entity)) world.despawn(tile.entity);
+  tile.entity = -1;
+}
+function clearHeightfieldColliders(world, rt) {
+  const set = tilesOf(rt);
+  for (const tile of set.tiles.values()) despawnTile(world, tile);
+  set.tiles.clear();
+  set.due.clear();
+}
+export {
+  TileSet,
+  clearHeightfieldColliders,
+  tilesOf,
+  updateHeightfieldColliders,
+  wantedTiles
+};

package/dist/heightfield/component.d.ts

@@ -0,0 +1,14 @@
+export declare const Terrain: import("@aethervtt/shard-core").ComponentDef<{
+    readonly source: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").AssetRef<"terrain/TerrainSource"> | null, "object">;
+    readonly errorPixels: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly vertexPixels: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly colliderRadius: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly skirts: import("@aethervtt/shard-core").FieldType<boolean, "u8">;
+    readonly residentDepth: import("@aethervtt/shard-core").FieldType<number, "i8">;
+    readonly scatter: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").AssetRef<"scatter/ScatterSet"> | null, "object">;
+}>;
+export declare const TerrainChunk: import("@aethervtt/shard-core").ComponentDef<{
+    readonly terrain: import("@aethervtt/shard-core").FieldType<number | null, "f64">;
+    readonly key: import("@aethervtt/shard-core").FieldType<string, "object">;
+    readonly kind: import("@aethervtt/shard-core").FieldType<"collider" | "render", "u8">;
+}>;