@aethervtt/shard-terrain 0.1.0 → 0.2.1

package/dist/heightfield/methods.js

@@ -0,0 +1,218 @@
+import { findComponent, ShardError } from "@aethervtt/shard-core";
+import { TerrainWorld } from "../heights.js";
+import { tilesOf } from "./colliders.js";
+import { finestPage, heightfieldSample, loadTerrainRegion, pageHeight } from "./queries.js";
+const round = (v, digits = 3) => {
+  const k = 10 ** digits;
+  return Math.round(v * k) / k;
+};
+function scenePath(world, entity) {
+  const member = findComponent("scene/SceneMember");
+  if (!member || !world.isAlive(entity)) return null;
+  const v = world.tryGet(entity, member);
+  return v?.path || null;
+}
+function resolveHeightfield(world, ref) {
+  const all = world.tryResource(TerrainWorld)?.heightfields;
+  if (!all || all.size === 0) {
+    throw new ShardError("terrain/no-terrain", "There is no terrain/Terrain in the world", {
+      hint: "Add terrain/Terrain (with a Grid and a *.terrain.json source) to an entity."
+    });
+  }
+  if (ref === void 0 || ref === null || ref === "") {
+    if (all.size > 1) {
+      throw new ShardError("terrain/which-terrain", `There are ${all.size} terrains; name one`, {
+        hint: "Pass terrain: an entity id or a scene path (terrain.describe lists them)."
+      });
+    }
+    return [...all.values()][0];
+  }
+  for (const rt of all.values()) {
+    if (rt.entity === ref) return rt;
+    const path = scenePath(world, rt.entity);
+    if (typeof ref === "string" && path && (path === ref || path.endsWith(`/${ref}`))) return rt;
+  }
+  throw new ShardError("terrain/not-a-terrain", `No terrain matches ${JSON.stringify(ref)}`, {
+    hint: "terrain.describe lists every terrain with its entity and scene path."
+  });
+}
+function usable(rt) {
+  if (rt.problem) throw rt.problem;
+  if (!rt.ready) {
+    throw new ShardError(
+      "terrain/not-ready",
+      `The terrain is waiting for ${rt.waiting ?? "its source"}`,
+      {
+        hint: "Its source and assets load asynchronously; step a frame and ask again."
+      }
+    );
+  }
+}
+function describeHeightfield(world, rt) {
+  const layout = rt.layout;
+  const r = rt.parts.get("render");
+  const byDepth = {};
+  let partial = 0;
+  for (let i = 0; i < rt.selection.renderedCount; i++) {
+    const n = rt.selection.rendered[i];
+    const d = rt.tree.depth[n];
+    byDepth[d] = (byDepth[d] ?? 0) + 1;
+    if (rt.tree.mask[n] !== 15) partial++;
+  }
+  const blocks = layout ? layout.blocksX * layout.blocksZ : 0;
+  const records = rt.manifest?.blocks ?? {};
+  const current = rt.bake === "current" ? Object.keys(records).length : 0;
+  const tiles = tilesOf(rt);
+  let resident = 0;
+  if (rt.pages && layout) {
+    for (const page of rt.pages.pages()) if (page.depth <= rt.residentDepth) resident++;
+  }
+  return {
+    entity: rt.entity,
+    path: scenePath(world, rt.entity),
+    source: rt.settings?.source?.path ?? rt.settings?.source?.guid ?? null,
+    ready: rt.ready,
+    streaming: rt.streaming,
+    waitingFor: rt.waiting,
+    problem: rt.problem ? rt.problem.toJSON() : null,
+    size: layout ? [layout.sizeX, layout.sizeZ] : null,
+    spacing: layout?.spacing ?? null,
+    heightRange: rt.asset ? rt.asset.source.heightRange : null,
+    roots: layout ? { x: layout.rootsX, z: layout.rootsZ, size: layout.rootSize } : null,
+    depths: layout ? layout.depth + 1 : 0,
+    version: rt.version,
+    bake: {
+      state: rt.bake,
+      blocks,
+      current,
+      stale: rt.bake === "current" ? blocks - current : blocks,
+      baking: rt.bake === "baking" ? blocks : 0,
+      lastBake: rt.lastBake ? {
+        rebaked: rt.lastBake.rebaked,
+        pages: rt.lastBake.pages,
+        ms: Math.round(rt.lastBake.ms),
+        msPerBlock: Math.round(rt.lastBake.msPerBlock),
+        outOfRange: rt.lastBake.outOfRange
+      } : null
+    },
+    detail: {
+      errorPixels: rt.settings?.errorPixels ?? null,
+      vertexPixels: rt.settings?.vertexPixels ?? null,
+      lodBias: round(rt.lodBias),
+      errors: Array.from(rt.errors, (e) => round(e))
+    },
+    selected: {
+      chunks: rt.selection.renderedCount,
+      byDepth,
+      partial,
+      requested: rt.selection.requestedCount,
+      waiting: rt.selection.waiting
+    },
+    pages: {
+      residentDepth: rt.residentDepth,
+      resident,
+      cached: rt.pages?.cached ?? 0,
+      readsInFlight: rt.pages?.pendingReads ?? 0,
+      reads: rt.pages?.stats.reads ?? 0,
+      bytesRead: rt.pages?.stats.bytesRead ?? 0,
+      bakedInline: rt.pages?.stats.bakedInline ?? 0
+    },
+    pool: r ? {
+      slots: r.capacity,
+      used: r.used,
+      uploaded: r.stats.uploaded,
+      uploadedLastFrame: r.stats.uploadedLastFrame,
+      waitingToUpload: r.arrived.length,
+      evicted: r.stats.evicted
+    } : null,
+    colliders: {
+      tiles: tiles.tiles.size,
+      active: [...tiles.tiles.values()].filter((t) => t.entity >= 0).length,
+      pending: tiles.due.size,
+      fromPages: tiles.fromPages,
+      bakedInline: tiles.bakedInline,
+      anchors: rt.anchors
+    }
+  };
+}
+async function sampleHeightfield(world, rt, points) {
+  usable(rt);
+  for (const [x, z] of points) {
+    await loadTerrainRegion(world, rt.entity, [x - 1, z - 1, x + 1, z + 1]);
+  }
+  return points.map(([x, z]) => {
+    const s = heightfieldSample(rt, x, z);
+    return {
+      x,
+      z,
+      height: round(s.height),
+      normal: s.normal.map((v) => round(v, 4)),
+      slope: round(s.slope, 2),
+      layers: s.layers,
+      share: round(s.share, 3),
+      depth: s.depth
+    };
+  });
+}
+function heightfieldMap(rt, width, mode) {
+  usable(rt);
+  const layout = rt.layout;
+  const height = Math.max(1, Math.round(width * layout.sizeZ / layout.sizeX));
+  const data = new Uint8Array(width * height * 4);
+  const lo = rt.lo;
+  const hi = rt.hi;
+  const tints = rt.asset.source.layers.map((l) => l.tint);
+  const dirtied = new Set(rt.dirtied);
+  const blockSize = layout.block * layout.leafSize;
+  for (let py = 0; py < height; py++) {
+    const z = (py + 0.5) / height * layout.sizeZ;
+    for (let px = 0; px < width; px++) {
+      const x = (px + 0.5) / width * layout.sizeX;
+      const o = (py * width + px) * 4;
+      let r = 0;
+      let g = 0;
+      let b = 0;
+      if (mode === "bake") {
+        const id = `${Math.floor(x / blockSize)},${Math.floor(z / blockSize)}`;
+        const current = rt.manifest?.blocks[id] !== void 0 && rt.bake === "current";
+        [r, g, b] = dirtied.has(id) ? [60, 200, 230] : current ? [70, 170, 80] : [220, 160, 40];
+        const fx = x / blockSize % 1;
+        const fz = z / blockSize % 1;
+        if (fx < 0.02 || fz < 0.02) [r, g, b] = [r * 0.5, g * 0.5, b * 0.5];
+      } else {
+        const page = finestPage(rt, x, z);
+        if (page) {
+          if (mode === "slope" || mode === "layers") {
+            const s = heightfieldSample(rt, x, z);
+            if (mode === "slope") r = g = b = Math.min(255, s.slope / 60 * 255);
+            else {
+              const names = rt.asset.source.layers.map((l) => l.name);
+              const ta = tints[names.indexOf(s.layers[0])] ?? [1, 0, 1];
+              const tb = tints[names.indexOf(s.layers[1])] ?? ta;
+              const t = s.share;
+              r = (ta[0] * (1 - t) + tb[0] * t) ** (1 / 2.2) * 255;
+              g = (ta[1] * (1 - t) + tb[1] * t) ** (1 / 2.2) * 255;
+              b = (ta[2] * (1 - t) + tb[2] * t) ** (1 / 2.2) * 255;
+            }
+          } else {
+            const k = Math.min(1, Math.max(0, (pageHeight(rt, page, x, z) - lo) / (hi - lo)));
+            r = 30 + 225 * k;
+            g = 50 + 205 * k;
+            b = 30 + 225 * k;
+          }
+        }
+      }
+      data[o] = r;
+      data[o + 1] = g;
+      data[o + 2] = b;
+      data[o + 3] = 255;
+    }
+  }
+  return { width, height, data };
+}
+export {
+  describeHeightfield,
+  heightfieldMap,
+  resolveHeightfield,
+  sampleHeightfield
+};

package/dist/heightfield/pack.d.ts

@@ -0,0 +1,59 @@
+import type { PlatformFileSystem } from '@aethervtt/shard-platform';
+/** Nodes per pack side. */
+export declare const PACK = 16;
+export declare const PACK_PAGES: number;
+/** Bytes before the first page: header and index. */
+export declare const PACK_INDEX_BYTES: number;
+/** A page's index entry. Absent pages (past the terrain's edge) have length 0. */
+export interface PackEntry {
+    offset: number;
+    length: number;
+    /** Quantized height range over the node's subtree. */
+    min: number;
+    max: number;
+    /** Geometric error (m). */
+    error: number;
+}
+export interface PackIndex {
+    depth: number;
+    gx: number;
+    gz: number;
+    entries: PackEntry[];
+}
+/** Where a node's page lives: its pack file and slot in it. */
+export declare function packOf(depth: number, x: number, z: number): {
+    path: string;
+    slot: number;
+};
+export declare function readIndex(path: string, bytes: Uint8Array): PackIndex;
+/** A pack file from its pages (null where absent), in slot order. */
+export declare function writePack(depth: number, gx: number, gz: number, pages: readonly ({
+    data: Uint8Array;
+    min: number;
+    max: number;
+    error: number;
+} | null)[]): Uint8Array;
+/**
+ * Where a terrain's packs and manifest live: the project's `.shard/cache/terrain/<id>/` through
+ * the platform's file service, or memory (tests, read-only hosts baking on first use).
+ */
+export interface PackStore {
+    readonly writable: boolean;
+    /** A whole file, or undefined if it doesn't exist. */
+    read(path: string): Promise<Uint8Array | undefined>;
+    /** `length` bytes at `offset` (one ranged read where the host has them). */
+    readRange(path: string, offset: number, length: number): Promise<Uint8Array>;
+    write(path: string, bytes: Uint8Array): Promise<void>;
+    /** Bytes of every file, for stats. */
+    size(): Promise<number>;
+}
+/** Packs in memory. */
+export declare function memoryPackStore(): PackStore & {
+    files: Map<string, Uint8Array>;
+};
+/**
+ * Packs under `dir` on a platform file service: ranged reads through `readRange` (a whole read
+ * and a slice on hosts without one), writes to a temporary file moved into place, so a running
+ * game reading the old pack never sees half a new one.
+ */
+export declare function fsPackStore(fs: PlatformFileSystem, dir: string): PackStore;

package/dist/heightfield/pack.js

@@ -0,0 +1,127 @@
+import { ShardError } from "@aethervtt/shard-core";
+const PACK = 16;
+const PACK_PAGES = PACK * PACK;
+const MAGIC = 827348051;
+const HEADER = 16;
+const ENTRY = 20;
+const PACK_INDEX_BYTES = HEADER + ENTRY * PACK_PAGES;
+function packOf(depth, x, z) {
+  const gx = Math.floor(x / PACK);
+  const gz = Math.floor(z / PACK);
+  return { path: `d${depth}/${gx}_${gz}.pack`, slot: (z - gz * PACK) * PACK + (x - gx * PACK) };
+}
+function corrupt(path, why) {
+  return new ShardError("terrain/corrupt-pack", `${path}: ${why}`, {
+    path,
+    hint: "The pack is damaged or from another bake: `shard terrain bake --force` rewrites it."
+  });
+}
+function readIndex(path, bytes) {
+  if (bytes.length < PACK_INDEX_BYTES) throw corrupt(path, "too short for an index");
+  const v = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  if (v.getUint32(0, true) !== MAGIC) throw corrupt(path, "not a terrain pack");
+  const entries = [];
+  for (let i = 0; i < PACK_PAGES; i++) {
+    const o = HEADER + i * ENTRY;
+    entries.push({
+      offset: v.getUint32(o, true),
+      length: v.getUint32(o + 4, true),
+      min: v.getUint16(o + 8, true),
+      max: v.getUint16(o + 10, true),
+      error: v.getFloat32(o + 12, true)
+    });
+  }
+  return { depth: v.getUint8(6), gx: v.getUint16(8, true), gz: v.getUint16(10, true), entries };
+}
+function writePack(depth, gx, gz, pages) {
+  let size = PACK_INDEX_BYTES;
+  for (const p of pages) if (p) size += p.data.length;
+  const out = new Uint8Array(size);
+  const v = new DataView(out.buffer);
+  v.setUint32(0, MAGIC, true);
+  v.setUint16(4, 1, true);
+  v.setUint8(6, depth);
+  v.setUint16(8, gx, true);
+  v.setUint16(10, gz, true);
+  v.setUint16(12, PACK_PAGES, true);
+  let offset = PACK_INDEX_BYTES;
+  for (let i = 0; i < PACK_PAGES; i++) {
+    const p = pages[i];
+    if (!p) continue;
+    const o = HEADER + i * ENTRY;
+    v.setUint32(o, offset, true);
+    v.setUint32(o + 4, p.data.length, true);
+    v.setUint16(o + 8, p.min, true);
+    v.setUint16(o + 10, p.max, true);
+    v.setFloat32(o + 12, p.error, true);
+    out.set(p.data, offset);
+    offset += p.data.length;
+  }
+  return out;
+}
+function memoryPackStore() {
+  const files = /* @__PURE__ */ new Map();
+  return {
+    files,
+    writable: true,
+    read: async (path) => files.get(path),
+    readRange: async (path, offset, length) => {
+      const f = files.get(path);
+      if (!f) {
+        throw new ShardError("terrain/missing-pack", `No pack ${path}`, {
+          path,
+          hint: "The terrain isn\u2019t baked (or was baked for another grid): `shard terrain bake`."
+        });
+      }
+      return f.subarray(offset, offset + length);
+    },
+    write: async (path, bytes) => void files.set(path, bytes),
+    size: async () => {
+      let n = 0;
+      for (const f of files.values()) n += f.length;
+      return n;
+    }
+  };
+}
+function fsPackStore(fs, dir) {
+  const full = (p) => `${dir}/${p}`;
+  return {
+    writable: fs.writable,
+    read: async (path) => await fs.exists(full(path)) ? fs.readBytes(full(path)) : void 0,
+    readRange: async (path, offset, length) => {
+      if (fs.readRange) return fs.readRange(full(path), offset, length);
+      const all = await fs.readBytes(full(path));
+      return all.subarray(offset, offset + length);
+    },
+    write: async (path, bytes) => {
+      if (fs.move) {
+        const temp = `${full(path)}.tmp`;
+        await fs.writeBytes(temp, bytes);
+        await fs.move(temp, full(path));
+      } else await fs.writeBytes(full(path), bytes);
+    },
+    size: async () => {
+      if (!fs.list || !fs.stat) return 0;
+      let n = 0;
+      const walk = async (d) => {
+        for (const e of await fs.list(d)) {
+          const p = `${d}/${e.name}`;
+          if (e.kind === "dir") await walk(p);
+          else n += (await fs.stat(p))?.size ?? 0;
+        }
+      };
+      await walk(dir);
+      return n;
+    }
+  };
+}
+export {
+  PACK,
+  PACK_INDEX_BYTES,
+  PACK_PAGES,
+  fsPackStore,
+  memoryPackStore,
+  packOf,
+  readIndex,
+  writePack
+};

package/dist/heightfield/pages.d.ts

@@ -0,0 +1,91 @@
+import type { Workers } from '@aethervtt/shard-platform';
+import { type NoiseAccess, type Stack } from './kernel.js';
+import { type PackEntry, type PackIndex, type PackStore } from './pack.js';
+import type { TerrainLayout } from './source.js';
+/** A node's number: depth, then z, then x (exact in an f64 up to 2^20 nodes a side). */
+export declare function nodeKey(depth: number, x: number, z: number): number;
+export declare function keyDepth(key: number): number;
+export declare function keyX(key: number): number;
+export declare function keyZ(key: number): number;
+/** A page as streaming and queries use it. */
+export interface LoadedPage {
+    key: number;
+    depth: number;
+    x: number;
+    z: number;
+    leaf: boolean;
+    /** u16 heights: LEAF_SIDE² with a border for leaves, SIDE² for parents. */
+    heights: Uint16Array;
+    /** Normals, x then z planes (SIDE² each). */
+    normals: Uint8Array;
+    control: Uint8Array;
+    /** RGBA8 texels for the GPU pool (LEAF_SIDE²), until uploaded. */
+    texels: Uint8Array | undefined;
+    /** Quantized height range of the node's subtree, and its geometric error. */
+    min: number;
+    max: number;
+    error: number;
+}
+/**
+ * A terrain's pages at runtime (spec 0071): pack indexes, reads through the store's ranged reads,
+ * inflate on the worker pool, and a CPU cache of decoded pages (least recently used out, coarse
+ * levels pinned). Colliders, height queries and the GPU pool all read through it.
+ */
+export declare class PageStore {
+    store: PackStore;
+    readonly layout: TerrainLayout;
+    readonly lo: number;
+    readonly hi: number;
+    workers: Workers | undefined;
+    /** Extra milliseconds before every read resolves (tests: a slow disk). */
+    delayMs: number;
+    /** Pages kept decoded on the CPU, besides pinned ones. */
+    capacity: number;
+    private readonly indexes;
+    private readonly pendingIndexes;
+    private readonly inflight;
+    /** Decoded pages by key, in use order (Map insertion order: oldest first). */
+    private readonly cache;
+    private readonly pinned;
+    stats: {
+        reads: number;
+        bytesRead: number;
+        inflated: number;
+        bakedInline: number;
+    };
+    constructor(store: PackStore, layout: TerrainLayout, lo: number, hi: number, workers?: Workers);
+    /** Nodes per side at a depth. */
+    nodesAt(depth: number): [number, number];
+    /** A node's index entry, if its pack's index is loaded. */
+    entry(depth: number, x: number, z: number): PackEntry | undefined;
+    /** Loads the index of the pack holding a node. */
+    index(depth: number, x: number, z: number): Promise<PackIndex | null>;
+    /** Whether a node's pack index is loaded (or known missing). */
+    hasIndex(depth: number, x: number, z: number): boolean;
+    /** A decoded page in the CPU cache (marked used), or undefined. */
+    get(key: number): LoadedPage | undefined;
+    /** Whether a read for this page is under way. */
+    loading(key: number): boolean;
+    /** Keeps a page decoded for the store's life (coarse levels). */
+    pin(key: number): void;
+    /**
+     * 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: number, x: number, z: number): Promise<LoadedPage | undefined>;
+    private read;
+    /** Adds a page to the CPU cache, dropping the least recently used unpinned ones over capacity. */
+    put(page: LoadedPage): void;
+    /**
+     * 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: NoiseAccess, stack: Stack, x: number, z: number): LoadedPage;
+    /** Every decoded page (pinned and cached). */
+    pages(): IterableIterator<LoadedPage>;
+    get cached(): number;
+    get pendingReads(): number;
+    /** Forgets every index and page (after a rebake). Reads under way finish into the new cache. */
+    clear(): void;
+}