@aethervtt/shard-terrain 0.1.0 → 0.2.1

package/dist/plugin.d.ts

@@ -1,10 +1,16 @@
 import { type World } from '@aethervtt/shard-core';
-import type { Workers } from '@aethervtt/shard-platform';
+import type { PlatformFileSystem, Workers } from '@aethervtt/shard-platform';
 import { type Plugin } from '@aethervtt/shard-runtime';
+import type { HeightfieldRuntime } from './heightfield/runtime.js';
 import { PlanetRuntime } from './planet.js';
 export interface TerrainPluginOptions {
-    /** Where collider chunks sample (default: inline on the main thread). */
-    workers?: Workers;
+    /** Where collider chunks sample and heightfield blocks bake (default: inline on the main thread). */
+    workers?: Workers | undefined;
+    /**
+     * Where heightfield packs are read from and baked into (`.shard/cache/terrain`). Without one,
+     * heightfields bake in memory on first use.
+     */
+    fs?: PlatformFileSystem | undefined;
 }
 /**
  * Keeps a runtime per Planet (spec 0043): resolves its graphs and biomes, measures per-depth
@@ -21,3 +27,4 @@ export declare function terrainPlugin(options?: TerrainPluginOptions): Plugin;
 export declare const terrainExtensions: ((app: Parameters<Plugin['build']>[0]) => void)[];
 export declare const terrainReadyHooks: ((app: Parameters<Plugin['build']>[0]) => Promise<void> | void)[];
 export declare const terrainCleanups: ((world: World, rt: PlanetRuntime) => void)[];
+export declare const heightfieldCleanups: ((world: World, rt: HeightfieldRuntime) => void)[];

package/dist/plugin.js

@@ -1,5 +1,5 @@
 import { AssetServerResource, assetServer } from "@aethervtt/shard-assets";
-import { defineSystem, onRemove, PostUpdate } from "@aethervtt/shard-core";
+import { defineSystem, First, onRemove, PostUpdate } from "@aethervtt/shard-core";
 import { computeVisibility } from "@aethervtt/shard-render";
 import { definePlugin } from "@aethervtt/shard-runtime";
 import { TransformSystems } from "@aethervtt/shard-transform";
@@ -7,8 +7,20 @@ import * as biomesModule from "./biomes.js";
 import { anchorQueries, clearColliders, gatherAnchors, updateColliders } from "./colliders.js";
 import * as componentsModule from "./components.js";
 import { Planet, TerrainBudget } from "./components.js";
+import { clearHeightfieldColliders } from "./heightfield/colliders.js";
+import * as heightfieldComponentModule from "./heightfield/component.js";
+import { Terrain } from "./heightfield/component.js";
+import * as heightmapModule from "./heightfield/heightmap.js";
+import * as heightfieldMaterialModule from "./heightfield/material.js";
+import {
+  cleanupHeightfieldRender,
+  selectHeightfields,
+  uploadHeightfieldPages
+} from "./heightfield/render.js";
+import * as sourceModule from "./heightfield/source-asset.js";
+import { registerHeightfield, updateHeightfields } from "./heightfield/system.js";
 import * as heightsModule from "./heights.js";
-import { Terrain } from "./heights.js";
+import { TerrainWorld } from "./heights.js";
 import * as materialModule from "./material.js";
 import { terrainMethods } from "./methods.js";
 import { clearPlanetNav, updatePlanetNav } from "./nav.js";
@@ -21,7 +33,7 @@ function watchAssets(world) {
   watching.add(world);
   assetServer(world).onEvent((event) => {
     if (event.kind === "loaded" || event.kind === "modified" || event.kind === "failed")
-      world.resource(Terrain).dirty = true;
+      world.resource(TerrainWorld).dirty = true;
   });
 }
 const updatePlanets = defineSystem({
@@ -32,7 +44,7 @@ const updatePlanets = defineSystem({
     anchors: anchorQueries(world)
   }),
   run: (s, world) => {
-    const state = world.resource(Terrain);
+    const state = world.resource(TerrainWorld);
     watchAssets(world);
     state.frame++;
     const frame = state.frame;
@@ -59,29 +71,55 @@ const updatePlanets = defineSystem({
 function terrainPlugin(options = {}) {
   return definePlugin({
     name: "terrain",
-    provides: [biomesModule, componentsModule, heightsModule, materialModule, overlaysModule],
+    provides: [
+      biomesModule,
+      componentsModule,
+      heightsModule,
+      heightfieldComponentModule,
+      heightfieldMaterialModule,
+      heightmapModule,
+      materialModule,
+      overlaysModule,
+      sourceModule
+    ],
     dependencies: ["core/transform"],
     build(app) {
       const world = app.world;
-      const state = world.initResource(Terrain);
+      const state = world.initResource(TerrainWorld);
       state.workers = options.workers;
+      state.fs = options.fs;
       world.initResource(TerrainBudget);
       world.observe(onRemove(Planet), ({ entity, world: world2 }) => {
-        const rt = world2.resource(Terrain).planets.get(entity);
+        const rt = world2.resource(TerrainWorld).planets.get(entity);
         if (!rt) return;
         clearColliders(world2, rt);
         clearPlanetNav(world2, rt);
         cleanupRender(world2, rt);
         for (const cleanup of terrainCleanups) cleanup(world2, rt);
-        world2.resource(Terrain).planets.delete(entity);
+        world2.resource(TerrainWorld).planets.delete(entity);
+      });
+      world.observe(onRemove(Terrain), ({ entity, world: world2 }) => {
+        const rt = world2.resource(TerrainWorld).heightfields.get(entity);
+        if (!rt) return;
+        for (const cleanup of heightfieldCleanups) cleanup(world2, rt);
+        clearHeightfieldColliders(world2, rt);
+        cleanupHeightfieldRender(world2, rt);
+        world2.resource(TerrainWorld).heightfields.delete(entity);
       });
       app.addSystems(PostUpdate, updatePlanets.after(TransformSystems));
+      app.addSystems(PostUpdate, updateHeightfields.after(updatePlanets));
       app.addMethod(...terrainMethods);
       app.addSystems(PostUpdate, selectChunks.after(updatePlanets).before(computeVisibility));
+      app.addSystems(
+        PostUpdate,
+        selectHeightfields.after(updateHeightfields).before(computeVisibility)
+      );
+      app.addSystems(First, uploadHeightfieldPages);
       for (const extend of terrainExtensions) extend(app);
     },
     async ready(app) {
       registerNode(app);
+      registerHeightfield(app);
       for (const hook of terrainReadyHooks) await hook(app);
     }
   });
@@ -89,7 +127,9 @@ function terrainPlugin(options = {}) {
 const terrainExtensions = [];
 const terrainReadyHooks = [];
 const terrainCleanups = [];
+const heightfieldCleanups = [];
 export {
+  heightfieldCleanups,
   terrainCleanups,
   terrainExtensions,
   terrainPlugin,

package/dist/quadtree.d.ts

@@ -1,17 +1,53 @@
-/** The node's mesh exists (GPU dispatched, or a CPU mesh assigned): it can render. */
+/** The node's mesh exists (GPU dispatched, a CPU mesh assigned, a page resident): it can render. */
 export declare const NODE_READY = 1;
-/** Heights are known exactly (CPU mesh, or the GPU readback arrived). */
+/** Heights are known exactly (CPU mesh, the GPU readback arrived, or a baked page's range). */
 export declare const NODE_BOUNDS = 2;
 /**
- * One cube-sphere quadtree per planet surface (terrain or ocean), stored as flat typed arrays
- * indexed by node, so the per-frame walk allocates nothing. The six roots are nodes 0–5; children
- * are made on first split as a block of four consecutive nodes, and freed as a block when their
- * subtree hasn't been needed for a while.
+ * What a quadtree needs from the surface it covers (spec 0071): how many roots there are, each
+ * node's geometry (its bounding sphere and box at its height range), whether it's out of view or
+ * behind the horizon, and its neighbor across an edge. The cube-sphere (`CubeSphere`, six roots)
+ * and the heightfield's root grid (`RootGrid`) are the two surfaces; selection, 2:1 balance and
+ * edge locks are the same code for both.
  */
-export declare class NodeTree {
+export interface QuadSurface {
+    /** Root nodes, 0 to roots − 1. */
+    readonly roots: number;
+    /** The tree grew to `capacity` nodes: per-node data the surface keeps grows with it. */
+    grow(capacity: number): void;
+    /**
+     * Sets up a new node's geometry; the tree has filled its root, depth, x, y and a height range
+     * (its parent's, or the tree's). A surface that knows the node's range (or that it's ready) may
+     * set it here, with its flags.
+     */
+    initNode(tree: QuadTree, n: number): void;
+    /** The node's bounding sphere at its height range, into `tree.sphere`. */
+    updateSphere(tree: QuadTree, n: number): void;
+    /** Axis-aligned bounds of the node relative to `center` (its chunk's reference point). */
+    bounds(tree: QuadTree, n: number, center: ArrayLike<number>, out: {
+        [i: number]: number;
+    }): void;
+    /** Whether the node is outside the view's frustum or below the horizon. */
+    culled(tree: QuadTree, n: number, view: SelectionView, params: SelectionParams): boolean;
+    /**
+     * The same-depth node across `edge` (EDGE_BOTTOM … EDGE_LEFT), written into `out` as
+     * [root, x, y]. False where the surface ends (a heightfield's border).
+     */
+    neighbor(root: number, depth: number, x: number, y: number, edge: number, out: {
+        [i: number]: number;
+    }): boolean;
+}
+/**
+ * A quadtree over a surface (spec 0043, shared with 0071), stored as flat typed arrays indexed by
+ * node, so the per-frame walk allocates nothing. The roots are nodes 0 to `surface.roots − 1`;
+ * children are made on first split as a block of four consecutive nodes, and freed as a block when
+ * their subtree hasn't been needed for a while.
+ */
+export declare class QuadTree {
+    readonly surface: QuadSurface;
     capacity: number;
     count: number;
-    face: Uint8Array<ArrayBuffer>;
+    /** The root each node is under (a cube face on a planet, a grid cell on a heightfield). */
+    root: Uint8Array<ArrayBuffer>;
     depth: Uint8Array<ArrayBuffer>;
     x: Uint32Array<ArrayBuffer>;
     y: Uint32Array<ArrayBuffer>;
@@ -19,13 +55,11 @@ export declare class NodeTree {
     /** First of four children (in order (2x, 2y), (2x+1, 2y), (2x, 2y+1), (2x+1, 2y+1)), or −1. */
     child: Int32Array<ArrayBuffer>;
     flags: Uint8Array<ArrayBuffer>;
-    /** Bounding sphere in the planet frame (f64): center xyz, radius. */
+    /** Bounding sphere in the surface's frame (f64): center xyz, radius. */
     sphere: Float64Array<ArrayBuffer>;
-    /** Height range (m above radius): exact once NODE_BOUNDS, else inherited or the planet's. */
+    /** Height range (m): exact once NODE_BOUNDS, else inherited or the surface's. */
     minH: Float32Array<ArrayBuffer>;
     maxH: Float32Array<ArrayBuffer>;
-    /** Horizon test directions (unit, 9 per node). */
-    dirs: Float64Array<ArrayBuffer>;
     /** Stamps: last walk (frame), rendered and culled (walk stamp), forced split, last needed (frame). */
     visited: Uint32Array<ArrayBuffer>;
     rendered: Uint32Array<ArrayBuffer>;
@@ -41,7 +75,7 @@ export declare class NodeTree {
      * Prefetched and out-of-view nodes are only `used`; a full pool evicts them first.
      */
     neededAt: Uint32Array<ArrayBuffer>;
-    /** Render slot holding its mesh, or −1. */
+    /** Render slot holding its mesh (or its page), or −1. */
     slot: Int32Array<ArrayBuffer>;
     /** Projected error (px) and distance when last requested: generation priority. */
     priority: Float32Array<ArrayBuffer>;
@@ -50,26 +84,17 @@ export declare class NodeTree {
     locks: Int8Array<ArrayBuffer>;
     /** Quadrants drawn when rendered (15: all; fewer while a split waits for some children). */
     mask: Uint8Array<ArrayBuffer>;
-    /** The planet version the node's mesh was made for: older is stale (it renders until replaced). */
+    /** The content version the node's mesh was made for: older is stale (it renders until replaced). */
     gen: Uint32Array<ArrayBuffer>;
-    /**
-     * 1 / cos(half the widest angle between neighboring test points, diagonals included): lifting
-     * the points by it puts the surface between them inside their hull (horizon test, bulge).
-     */
-    lift: Float64Array<ArrayBuffer>;
     /** Starts of freed child blocks. */
     private blocks;
-    radius: number;
-    readonly shape: Float64Array<ArrayBuffer>;
     /** Height range for nodes whose heights aren't known yet. */
     lowest: number;
     highest: number;
-    constructor(capacity?: number);
+    constructor(surface: QuadSurface, capacity?: number);
     private grow;
-    /** Clears every node and makes the six roots (after a planet's shape or graphs change). */
-    reset(radius: number, shape: ArrayLike<number>, lowest: number, highest: number): void;
-    /** Root of a face (nodes 0–5). */
-    root(face: number): number;
+    /** Clears every node and makes the roots (after the surface's shape or contents change). */
+    resetRoots(lowest: number, highest: number): void;
     private init;
     /** Children of `n`, made if needed. Returns the first (the others follow it). */
     split(n: number): number;
@@ -79,23 +104,20 @@ export declare class NodeTree {
     get live(): number;
     /** Sets a node's exact height range and recomputes its bounds. */
     setHeights(n: number, minH: number, maxH: number): void;
-    /** Bounding sphere of the node's 9 test points at its lowest and highest heights, plus bulge. */
+    /** Recomputes the node's bounding sphere from its height range. */
     updateSphere(n: number): void;
-    /**
-     * Axis-aligned bounds of the node relative to `center` (its chunk's reference point), from its
-     * test points at its lowest and highest heights plus the bulge between them.
-     */
+    /** Axis-aligned bounds of the node relative to `center` (its chunk's reference point). */
     bounds(n: number, center: ArrayLike<number>, out: {
         [i: number]: number;
     }): void;
-    /** The node at (face, depth, x, y) if the tree has it, else the deepest existing ancestor. */
-    find(face: number, depth: number, x: number, y: number): number;
+    /** The node at (root, depth, x, y) if the tree has it, else the deepest existing ancestor. */
+    find(root: number, depth: number, x: number, y: number): number;
     /** Frees subtrees nobody has needed since frame `before`. */
     prune(before: number, release: (node: number) => void): void;
     /** Returns whether `n` and its whole subtree are idle. */
     private pruneNode;
 }
-/** What selection sees of the camera, in the planet frame (f64). */
+/** What selection sees of the camera, in the surface's frame (f64). */
 export interface SelectionView {
     /** Camera position. */
     position: Float64Array;
@@ -119,7 +141,7 @@ export interface SelectionParams {
     occluder: number;
     /** Depth colliders use: forced near anchors, and the deepest rendered there. */
     colliderDepth: number;
-    /** Anchor positions in the planet frame (xyz) and their radii; `anchors` of them. */
+    /** Anchor positions in the surface's frame (xyz) and their radii; `anchors` of them. */
     anchorPos: Float64Array;
     anchorRadius: Float64Array;
     anchors: number;
@@ -141,13 +163,13 @@ export interface Selection {
 }
 export declare function createSelection(): Selection;
 /**
- * Picks the nodes to render this frame (spec 0043): walks the six trees, culls nodes behind the
- * horizon or outside the frustum, splits a node when its children's geometric error projects past
+ * Picks the nodes to render this frame (spec 0043): walks the trees from every root, culls nodes
+ * behind the horizon or outside the frustum, splits a node when its children's geometric error projects past
  * `errorPixels` (or an anchor needs collider depth nearby, where nothing goes deeper), and renders
  * a split node's children only once all of the visible ones are ready, so a split never shows a
  * hole. Then enforces 2:1 balance between neighbors (marking coarse nodes to split and walking
  * again) and sets each rendered node's edge locks. Allocates nothing once its arrays are big enough.
  */
-export declare function selectNodes(tree: NodeTree, view: SelectionView, params: SelectionParams, frame: number, out: Selection): void;
+export declare function selectNodes(tree: QuadTree, view: SelectionView, params: SelectionParams, frame: number, out: Selection): void;
 /** Whether any anchor is within its radius of the node's bounds. */
-export declare function nearAnchor(tree: NodeTree, n: number, params: SelectionParams): boolean;
+export declare function nearAnchor(tree: QuadTree, n: number, params: SelectionParams): boolean;