@aethervtt/shard-terrain 0.1.0 → 0.2.0

package/dist/heightfield/system.js

@@ -0,0 +1,165 @@
+import { defineSystem } from "@aethervtt/shard-core";
+import { RigidBody } from "@aethervtt/shard-physics";
+import {
+  addRenderFeatures,
+  GpuAssetsResource,
+  Graph,
+  RenderPhase,
+  Shaders
+} from "@aethervtt/shard-render";
+import { GlobalTransform } from "@aethervtt/shard-transform";
+import { anchorQueries } from "../colliders.js";
+import { TerrainAnchor, TerrainBudget } from "../components.js";
+import { TerrainWorld } from "../heights.js";
+import { updateHeightfieldColliders } from "./colliders.js";
+import { Terrain } from "./component.js";
+import { HEIGHTFIELD_SHADERS } from "./material.js";
+import { enqueueResident } from "./render.js";
+import { HeightfieldRuntime } from "./runtime.js";
+const seen = /* @__PURE__ */ new Set();
+const p = new Float64Array(3);
+function gatherHeightfieldAnchors(_world, rt, q) {
+  const s = rt.settings;
+  const layout = rt.layout;
+  seen.clear();
+  rt.anchors = 0;
+  rt.anchorEntity.length = 0;
+  const top = rt.hi;
+  const add = (entity, m, row, radius) => {
+    if (seen.has(entity)) return;
+    seen.add(entity);
+    rt.frame.pointToPlanet(m[row * 12 + 3], m[row * 12 + 7], m[row * 12 + 11], p);
+    if (p[0] < -radius || p[2] < -radius || p[0] > layout.sizeX + radius || p[2] > layout.sizeZ + radius)
+      return;
+    if (p[1] - top > radius) return;
+    const i = rt.anchors++;
+    if (rt.anchorPos.length < rt.anchors * 3) {
+      const pos = new Float64Array(rt.anchors * 6);
+      pos.set(rt.anchorPos);
+      rt.anchorPos = pos;
+      const r = new Float64Array(rt.anchors * 2);
+      r.set(rt.anchorRadius);
+      rt.anchorRadius = r;
+    }
+    rt.anchorPos[i * 3] = p[0];
+    rt.anchorPos[i * 3 + 1] = p[1];
+    rt.anchorPos[i * 3 + 2] = p[2];
+    rt.anchorRadius[i] = radius;
+    rt.anchorEntity.push(entity);
+  };
+  for (const table of q.anchors.tables) {
+    const enabled = table.column(TerrainAnchor, "enabled");
+    const radius = table.column(TerrainAnchor, "radius");
+    const m = table.column(GlobalTransform, "matrix");
+    for (let row = 0; row < table.count; row++) {
+      const entity = table.entities[row];
+      if (!enabled[row]) {
+        seen.add(entity);
+        continue;
+      }
+      add(entity, m, row, radius[row] > 0 ? radius[row] : s.colliderRadius);
+    }
+  }
+  for (const table of q.agents.tables) {
+    const m = table.column(GlobalTransform, "matrix");
+    for (let row = 0; row < table.count; row++) add(table.entities[row], m, row, s.colliderRadius);
+  }
+  for (const table of q.characters.tables) {
+    const m = table.column(GlobalTransform, "matrix");
+    for (let row = 0; row < table.count; row++) add(table.entities[row], m, row, s.colliderRadius);
+  }
+  for (const table of q.bodies.tables) {
+    const kind = table.column(RigidBody, "kind");
+    const m = table.column(GlobalTransform, "matrix");
+    for (let row = 0; row < table.count; row++) {
+      if (kind[row] !== 0) continue;
+      add(table.entities[row], m, row, s.colliderRadius);
+    }
+  }
+}
+const heightfieldUpdates = [];
+const updateHeightfields = defineSystem({
+  name: "terrain/heightfields",
+  description: "Resolves each Terrain\u2019s source, bakes its packs when missing or stale (on first use), loads its coarse levels, and keeps heightfield collider tiles (fixed bodies) around characters, dynamic bodies, NavAgents and TerrainAnchors.",
+  setup: (world) => ({
+    terrains: world.query({ with: [Terrain] }),
+    anchors: anchorQueries(world)
+  }),
+  run: (s, world) => {
+    const state = world.resource(TerrainWorld);
+    const frame = state.frame;
+    for (const table of s.terrains.tables) {
+      for (let row = 0; row < table.count; row++) {
+        const entity = table.entities[row];
+        if (!state.heightfields.has(entity))
+          state.heightfields.set(entity, new HeightfieldRuntime(entity));
+      }
+    }
+    const env = { fs: state.fs, workers: state.workers };
+    const colliderCache = world.resource(TerrainBudget).colliderCache;
+    for (const rt of state.heightfields.values()) {
+      if (!world.isAlive(rt.entity)) continue;
+      rt.refresh(world, env);
+      rt.frame.update(world, rt.entity);
+      if (!rt.ready) continue;
+      gatherHeightfieldAnchors(world, rt, s.anchors);
+      updateHeightfieldColliders(world, rt, frame, colliderCache);
+      for (const update of heightfieldUpdates) update(world, rt, frame);
+      const r = rt.parts.get("render");
+      if (r && rt.streaming && r.residentVersion !== rt.version) {
+        r.residentVersion = rt.version;
+        enqueueResident(rt, r);
+      }
+    }
+  }
+});
+const ownBytes = /* @__PURE__ */ new Map();
+function writeUniforms(world, gpu) {
+  const state = world.tryResource(TerrainWorld);
+  const assets = world.tryResource(GpuAssetsResource);
+  if (!state || !assets) return;
+  for (const rt of state.heightfields.values()) {
+    const r = rt.parts.get("render");
+    if (!r) continue;
+    const material = r.material;
+    const gm = assets.materials.get(material);
+    const layout = material.type.layout;
+    if (!gm?.ownBuffer || !layout || gm.version !== material.version) continue;
+    let view = ownBytes.get(layout.size);
+    if (!view) {
+      view = new DataView(new ArrayBuffer(layout.size));
+      ownBytes.set(layout.size, view);
+    }
+    layout.write(view, 0, material.value);
+    gpu.device.queue.writeBuffer(gm.ownBuffer, 0, view.buffer, 0, layout.size);
+  }
+}
+function registerHeightfield(app) {
+  const graph = app.world.tryResource(Graph);
+  if (!graph) return;
+  for (const [path, source] of Object.entries(HEIGHTFIELD_SHADERS))
+    app.world.resource(Shaders).register(path, source, "@aethervtt/shard-terrain");
+  addRenderFeatures(app.world, {
+    name: "terrain/heightfield",
+    description: "Heightfield terrain: one grid mesh drawn per streamed page, heights fetched in the vertex stage.",
+    nodes: ["terrain/heightfield"],
+    baseline: {
+      strategy: "The same shader: vertex texture fetch of the RGBA8 page pool and the chunk table (WebGL2 texelFetch), pages uploaded with writeTexture. No compute: leaf normals come from the inflate worker."
+    },
+    components: [Terrain]
+  });
+  graph.addNode("terrain/heightfield", {
+    kind: "raw",
+    phase: RenderPhase.Setup,
+    sideEffects: true,
+    run(ctx) {
+      writeUniforms(ctx.world, ctx.gpu);
+    }
+  });
+}
+export {
+  gatherHeightfieldAnchors,
+  heightfieldUpdates,
+  registerHeightfield,
+  updateHeightfields
+};

package/dist/heightfield/testing.d.ts

@@ -0,0 +1,317 @@
+/**
+ * Test helpers (not a test) for heightfield terrain (spec 0071): an app with a terrain baked in
+ * memory from a source object, a camera placed in the terrain's frame, a loop that runs frames until
+ * streaming settles, and hole detection against the sky color.
+ */
+import { type Entity, type World } from '@aethervtt/shard-core';
+import type { GpuContext } from '@aethervtt/shard-gpu';
+import { NoiseGraph } from '@aethervtt/shard-noise';
+import type { PlatformFileSystem, Workers } from '@aethervtt/shard-platform';
+import { App, type Plugin } from '@aethervtt/shard-runtime';
+import type { HeightfieldRender } from './render.js';
+import type { HeightfieldRuntime } from './runtime.js';
+import { TerrainSourceAsset } from './source-asset.js';
+export interface HeightfieldOptions {
+    /** A `*.terrain.json` object; asset paths name entries of `noise` and `heightmaps`. */
+    source: unknown;
+    noise?: Record<string, NoiseGraph>;
+    heightmaps?: Record<string, {
+        width: number;
+        height: number;
+        data: Float32Array;
+    }>;
+    /** Blocks per side override (tests: small blocks). */
+    block?: number;
+    workers?: Workers;
+    width?: number;
+    heightPx?: number;
+    fovY?: number;
+    clearColor?: [number, number, number, number];
+    physics?: boolean;
+    skirts?: boolean;
+    errorPixels?: number;
+    vertexPixels?: number;
+    extra?: Plugin[];
+    pages?: number;
+    pagesPerFrame?: number;
+    /** Where the terrain's corner sits in the world (its Transform). */
+    at?: [number, number, number];
+    /** Bake into (and read packs from) this file service's `.shard/cache/terrain`; memory without. */
+    fs?: PlatformFileSystem;
+    /** The source asset's guid (its cache directory), default `mem:…`. */
+    name?: string;
+}
+export interface HeightfieldApp {
+    app: App;
+    world: World;
+    terrain: Entity;
+    camera: Entity;
+    sun: Entity;
+    view: string;
+    runtime(): HeightfieldRuntime;
+    render(): HeightfieldRender | undefined;
+}
+/** A terrain source asset made in memory, its assets in the world's stores. */
+export declare function sourceAsset(world: World, o: HeightfieldOptions): TerrainSourceAsset;
+export declare function heightfieldApp(gpu: GpuContext | undefined, o: HeightfieldOptions): Promise<HeightfieldApp>;
+/** Puts the camera at `eye` (terrain frame) looking at `target`, up +Y. */
+export declare function lookAt(p: HeightfieldApp, eye: ArrayLike<number>, target: ArrayLike<number>): void;
+/** Waits until the terrain is streaming (its bake done and coarse levels loaded). */
+export declare function untilStreaming(p: HeightfieldApp, maxMs?: number): Promise<void>;
+/** Runs frames (awaiting pipelines and reads) until nothing is requested, read or uploading. */
+export declare function settleHeightfield(p: HeightfieldApp, maxFrames?: number): Promise<number>;
+/** Renders one more frame and captures the camera's view. */
+export declare function capture(p: HeightfieldApp): Promise<import("@aethervtt/shard-render").CapturedImage>;
+/**
+ * Sky-colored pixels (the magenta clear color) whose ray from the camera reaches the plane of the
+ * lowest possible ground (`lowest`) inside the terrain's rectangle (less `margin`): the ground is
+ * above that plane everywhere, so the ray must have hit it.
+ */
+export declare function holes(data: Uint8Array, W: number, H: number, fov: number, eye: ArrayLike<number>, right: number[], up: number[], forward: number[], lowest: number, rect: [number, number, number, number]): number;
+/** 0071's 2 km test terrain at 0.5 m: hills, a valley image, and a road flattened through them. */
+export declare function valleySource(size?: number, spacing?: number): {
+    source: {
+        size: number[];
+        spacing: number;
+        heightRange: number[];
+        seed: number;
+        splines: {
+            road: {
+                points: (string | number)[][];
+                width: number;
+                falloff: number;
+            };
+        };
+        height: ({
+            noise: {
+                path: string;
+            };
+            scale: number;
+            image?: undefined;
+            at?: undefined;
+            size?: undefined;
+            rotation?: undefined;
+            range?: undefined;
+            blend?: undefined;
+            falloff?: undefined;
+            spline?: undefined;
+            mode?: undefined;
+        } | {
+            noise?: undefined;
+            scale?: undefined;
+            image: {
+                path: string;
+            };
+            at: number[];
+            size: number[];
+            rotation: number;
+            range: number[];
+            blend: string;
+            falloff: number;
+            spline?: undefined;
+            mode?: undefined;
+        } | {
+            noise?: undefined;
+            scale?: undefined;
+            image?: undefined;
+            at?: undefined;
+            size?: undefined;
+            rotation?: undefined;
+            range?: undefined;
+            blend?: undefined;
+            falloff?: undefined;
+            spline: string;
+            mode: string;
+        })[];
+        layers: ({
+            name: string;
+            triplanar?: undefined;
+        } | {
+            name: string;
+            triplanar: boolean;
+        })[];
+        paint: ({
+            blend?: undefined;
+            spline?: undefined;
+            layer: string;
+            slope?: undefined;
+        } | {
+            spline?: undefined;
+            layer: string;
+            slope: number[];
+            blend: number;
+        } | {
+            slope?: undefined;
+            layer: string;
+            spline: string;
+            blend: number;
+        })[];
+    };
+    heightmaps: {
+        valley: {
+            width: number;
+            height: number;
+            data: Float32Array<ArrayBuffer>;
+        };
+    };
+};
+/** The hills graph of the valley terrain (the playground's #heightfield page uses it too). */
+export declare const VALLEY_HILLS: {
+    output: string;
+    nodes: {
+        base: {
+            fbm: {
+                source: string;
+                octaves: number;
+                frequency: number;
+                seed: number;
+            };
+        };
+        ridges: {
+            ridged: {
+                source: string;
+                octaves: number;
+                frequency: number;
+                seed: number;
+            };
+        };
+        h: {
+            add: (string | {
+                multiply: (string | number)[];
+            })[];
+        };
+    };
+};
+/** What was drawn in one frame: rendered nodes (by key) and the morph camera. */
+export interface DrawnFrame {
+    nodes: Map<number, {
+        depth: number;
+        x: number;
+        z: number;
+        locks: number[];
+        mask: number;
+        fade: number;
+        anchored: boolean;
+    }>;
+    /** Camera position in the terrain's frame. */
+    camera: number[];
+    /** pixelsPerRadian / (errorPixels × lodBias): a depth's split distance per metre of error. */
+    splitScale: number;
+    errors: Float32Array;
+}
+export declare function snapshotDrawn(p: HeightfieldApp): DrawnFrame;
+/**
+ * The drawn ground's height at terrain point (x, z) in a frame, as the vertex stage puts it: the
+ * rendered node there, its page's heights morphed toward the parent level (odd vertices to their
+ * even neighbors' average, odd-odd along the anti-diagonal) by distance, edge locks, quadrants and
+ * fade, then the anti-diagonal triangle under the point. Undefined where nothing drawn covers it
+ * or its page isn't in the CPU cache. `edge` skips points within a cell of a stitched edge (its
+ * triangles are zipped, not quads).
+ */
+export declare function drawnHeightAt(rt: HeightfieldRuntime, f: DrawnFrame, x: number, z: number, skipStitched?: boolean): number | undefined;
+export interface HeightfieldWalk {
+    /** FNV-1a over the characters' final terrain-frame positions (f64 bytes) and the tile count. */
+    checksum: string;
+    walked: number[];
+    /** The lowest the feet got under the collider surface (m, negative is below). */
+    lowest: number;
+    tiles: number;
+    ms: number;
+}
+/**
+ * Drops `characters` capsules at deterministic points on the valley terrain and walks each for
+ * `seconds` headless (no GPU, colliders only). Node (packages/terrain tests) and Chrome (the
+ * playground's #heightfield page) must print the same checksum: the bake, the collider tiles and
+ * physics are deterministic.
+ */
+export declare function heightfieldWalk(characters?: number, seconds?: number, workers?: Workers): Promise<HeightfieldWalk>;
+/**
+ * 0071's 16 km terrain at 1 m (benches only: about 600 MB of packs): the valley terrain's layers
+ * spread over 16 km, with a 12 km road.
+ */
+export declare function openWorldSource(): {
+    heightmaps: {
+        valley: {
+            width: number;
+            height: number;
+            data: Float32Array<ArrayBuffer>;
+        };
+    };
+    source: {
+        size: number[];
+        spacing: number;
+        seed: number;
+        splines: {
+            road: {
+                points: (string | number)[][];
+                width: number;
+                falloff: number;
+            };
+        };
+        height: ({
+            noise: {
+                path: string;
+            };
+            scale: number;
+            image?: undefined;
+            at?: undefined;
+            size?: undefined;
+            rotation?: undefined;
+            range?: undefined;
+            blend?: undefined;
+            falloff?: undefined;
+            spline?: undefined;
+            mode?: undefined;
+        } | {
+            noise?: undefined;
+            scale?: undefined;
+            image: {
+                path: string;
+            };
+            at: number[];
+            size: number[];
+            rotation: number;
+            range: number[];
+            blend: string;
+            falloff: number;
+            spline?: undefined;
+            mode?: undefined;
+        } | {
+            noise?: undefined;
+            scale?: undefined;
+            image?: undefined;
+            at?: undefined;
+            size?: undefined;
+            rotation?: undefined;
+            range?: undefined;
+            blend?: undefined;
+            falloff?: undefined;
+            spline: string;
+            mode: string;
+        })[];
+        layers: ({
+            name: string;
+            triplanar?: undefined;
+        } | {
+            name: string;
+            triplanar: boolean;
+        })[];
+        paint: ({
+            blend?: undefined;
+            spline?: undefined;
+            layer: string;
+            slope?: undefined;
+        } | {
+            spline?: undefined;
+            layer: string;
+            slope: number[];
+            blend: number;
+        } | {
+            slope?: undefined;
+            layer: string;
+            spline: string;
+            blend: number;
+        })[];
+        heightRange: number[];
+    };
+};