@aethervtt/shard-terrain 0.0.1 → 0.2.0

package/dist/biomes.d.ts

@@ -15,6 +15,7 @@ export declare const Biome: import("@aethervtt/shard-assets").DataType<{
     readonly slope: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Vec2, "f32">;
     readonly blend: import("@aethervtt/shard-core").FieldType<number, "f32">;
     readonly tint: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Color, "f32">;
+    readonly scatter: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").AssetRef<"scatter/ScatterSet"> | null, "object">;
 }, "terrain/Biome">;
 export declare const BiomeSet: import("@aethervtt/shard-assets").DataType<{
     readonly biomes: import("@aethervtt/shard-core").FieldType<(import("@aethervtt/shard-core").AssetRef<"terrain/Biome"> | null)[], "object">;

package/dist/biomes.js

@@ -38,6 +38,9 @@ const Biome = defineDataType(
     tint: t.color({
       default: [1, 1, 1, 1],
       description: "Multiplies the albedo (the whole color when the set has no textures)."
+    }),
+    scatter: t.handle("scatter/ScatterSet", {
+      description: "Props and foliage where this biome is the heaviest (*.scatter.json; needs the scatter plugin)."
     })
   },
   {

package/dist/chunk.d.ts

@@ -1,50 +1,6 @@
 import type { MeshData } from '@aethervtt/shard-mesh';
 import type { NoiseGraph } from '@aethervtt/shard-noise';
 import { type ChunkPoints } from './points.js';
-/**
- * How a chunk's vertices are laid out, per resolution `n` (vertices per edge, 2^k + 1). The border
- * ring comes first (so edge locks rewrite one contiguous block), then the interior row by row, then
- * one skirt vertex under each ring vertex. Every chunk of a resolution shares one index buffer.
- */
-export interface ChunkLayout {
-    resolution: number;
-    /** Ring vertices: 4 (n − 1), counter-clockwise from (0, 0) seen from outside. */
-    ring: number;
-    /** Surface vertices: n². */
-    surface: number;
-    /** Surface plus skirt: n² + 4 (n − 1). */
-    vertexCount: number;
-    /** Vertex index of grid point (i, j), at `i + j * n`. */
-    index: Uint16Array;
-    /** Grid point of each ring vertex: i, j pairs. */
-    ringPoints: Uint16Array;
-    /** Triangles: the surface, then the skirts (`chunkIndices` with every quadrant, no stitching). */
-    indices: Uint16Array;
-    /** Triangles without skirts (the surface only): colliders, and planets with skirts off. */
-    surfaceIndices: Uint16Array;
-}
-/**
- * A chunk's triangles (cached per combination, so chunks share the array and its GPU index buffer).
- * `mask` picks quadrants (bit q: quadrant q, in child order (x, y), (x+1, y), (x, y+1),
- * (x+1, y+1)): a split waiting for children draws its own quadrants where they're missing and the
- * children elsewhere. `stitch` bit e marks edge e (0 bottom, 1 right, 2 top, 3 left) as meeting a
- * coarser neighbor: that edge's triangles use only its even vertices, the neighbor's, so there's no
- * T-junction (a vertex on the neighbor's edge only up to rounding shows pixel-sized holes).
- *
- * Quads fill the interior; each edge's strip (between the border and the first inner row) is
- * zipped per half, so no triangle crosses a quadrant boundary. Skirts follow the drawn border.
- */
-export declare function chunkIndices(n: number, mask: number, stitch: number, skirts: boolean): Uint16Array;
-/** Throws `terrain/bad-resolution` unless `n` is 2^k + 1 (5 to 129). */
-export declare function checkResolution(n: number): void;
-export declare function chunkLayout(n: number): ChunkLayout;
-/**
- * A vertex's lock code (uv1.x): its edge for ring vertices (0 bottom, 1 right, 2 top, 3 left, where
- * the instance's lock bits apply), the quadrant boundary for vertices on the center lines (4 and 5
- * the vertical line's lower and upper half, 6 and 7 the horizontal line's left and right half, 8
- * the center; locked to this level where a partial draw meets a child), else −1.
- */
-export declare function lockCode(i: number, j: number, n: number, vi: number, ring: number): number;
 /** What a chunk is made from: its node, the planet's numbers, and its graphs. */
 export interface ChunkSpec {
     face: number;

package/dist/chunk.js

@@ -1,131 +1,10 @@
-import { ShardError } from "@aethervtt/shard-core";
 import { faceToDirection, nodeExtent } from "./cube.js";
+import { chunkLayout } from "./grid-mesh.js";
 import {
   createChunkPoints,
   prepareChunkPoints,
   sampleChunkPoints
 } from "./points.js";
-const layouts = /* @__PURE__ */ new Map();
-const sets = /* @__PURE__ */ new Map();
-function chunkIndices(n, mask, stitch, skirts) {
-  const key = `${n}:${mask}:${stitch}:${skirts}`;
-  let out = sets.get(key);
-  if (out) return out;
-  const layout = chunkLayout(n);
-  const index = layout.index;
-  const side = n - 1;
-  const h = side / 2;
-  const parts = [];
-  const quadrant = (i, j) => (i >= h ? 1 : 0) + (j >= h ? 2 : 0);
-  for (let j = 1; j < side - 1; j++) {
-    for (let i = 1; i < side - 1; i++) {
-      if (!(mask & 1 << quadrant(i, j))) continue;
-      const a = index[i + j * n];
-      const b = index[i + 1 + j * n];
-      const c = index[i + 1 + (j + 1) * n];
-      const d = index[i + (j + 1) * n];
-      parts.push(a, b, c, a, c, d);
-    }
-  }
-  const at = (e, s, depth) => {
-    const i = e === 0 ? s : e === 1 ? side - depth : e === 2 ? side - s : depth;
-    const j = e === 0 ? depth : e === 1 ? s : e === 2 ? side - depth : side - s;
-    return index[i + j * n];
-  };
-  const skirt = [];
-  const outer = [];
-  const inner = [];
-  for (let e = 0; e < 4; e++) {
-    const step = stitch & 1 << e ? 2 : 1;
-    for (let half = 0; half < 2; half++) {
-      const s0 = half * h;
-      const s1 = s0 + h;
-      const m = s0 + h / 2;
-      const q = e === 0 ? quadrant(m, 0) : e === 1 ? quadrant(side, m) : e === 2 ? quadrant(side - m, side) : quadrant(0, side - m);
-      if (!(mask & 1 << q)) continue;
-      outer.length = 0;
-      inner.length = 0;
-      for (let s = s0; s <= s1; s += step) outer.push(s);
-      for (let s = Math.max(1, s0); s <= Math.min(side - 1, s1); s++) inner.push(s);
-      let a = 0;
-      let b = 0;
-      while (a < outer.length - 1 || b < inner.length - 1) {
-        const advanceOuter = b === inner.length - 1 || a < outer.length - 1 && outer[a + 1] <= inner[b + 1];
-        if (advanceOuter) {
-          parts.push(at(e, outer[a], 0), at(e, outer[a + 1], 0), at(e, inner[b], 1));
-          a++;
-        } else {
-          parts.push(at(e, outer[a], 0), at(e, inner[b + 1], 1), at(e, inner[b], 1));
-          b++;
-        }
-      }
-      if (!skirts) continue;
-      for (let k = 0; k + 1 < outer.length; k++) {
-        const va = at(e, outer[k], 0);
-        const vb = at(e, outer[k + 1], 0);
-        const sa = layout.surface + va;
-        const sb = layout.surface + vb;
-        skirt.push(va, sa, vb, vb, sa, sb, va, vb, sa, vb, sb, sa);
-      }
-    }
-  }
-  for (const v of skirt) parts.push(v);
-  out = Uint16Array.from(parts);
-  sets.set(key, out);
-  return out;
-}
-function checkResolution(n) {
-  const k = Math.log2(n - 1);
-  if (!Number.isInteger(k) || k < 2 || k > 7) {
-    throw new ShardError("terrain/bad-resolution", `Planet resolution ${n} isn't 2^n + 1`, {
-      hint: "Use 17, 33 (the default), 65, or 129 vertices per chunk edge."
-    });
-  }
-}
-function chunkLayout(n) {
-  let layout = layouts.get(n);
-  if (layout) return layout;
-  checkResolution(n);
-  const ring = 4 * (n - 1);
-  const surface = n * n;
-  const index = new Uint16Array(surface);
-  const ringPoints = new Uint16Array(ring * 2);
-  let r = 0;
-  const put = (i, j) => {
-    index[i + j * n] = r;
-    ringPoints[r * 2] = i;
-    ringPoints[r * 2 + 1] = j;
-    r++;
-  };
-  for (let i = 0; i < n - 1; i++) put(i, 0);
-  for (let j = 0; j < n - 1; j++) put(n - 1, j);
-  for (let i = n - 1; i > 0; i--) put(i, n - 1);
-  for (let j = n - 1; j > 0; j--) put(0, j);
-  let v = ring;
-  for (let j = 1; j < n - 1; j++) for (let i = 1; i < n - 1; i++) index[i + j * n] = v++;
-  layout = {
-    resolution: n,
-    ring,
-    surface,
-    vertexCount: surface + ring,
-    index,
-    ringPoints,
-    indices: new Uint16Array(0),
-    surfaceIndices: new Uint16Array(0)
-  };
-  layouts.set(n, layout);
-  layout.indices = chunkIndices(n, 15, 0, true);
-  layout.surfaceIndices = chunkIndices(n, 15, 0, false);
-  return layout;
-}
-function lockCode(i, j, n, vi, ring) {
-  if (vi < ring) return Math.floor(vi / (n - 1));
-  const h = (n - 1) / 2;
-  if (i === h && j === h) return 8;
-  if (i === h) return j < h ? 4 : 5;
-  if (j === h) return i < h ? 6 : 7;
-  return -1;
-}
 let values = new Float32Array(0);
 let temps = new Float32Array(0);
 let moist = new Float32Array(0);
@@ -296,9 +175,5 @@ function assembleChunk(spec, pts, values2, temps2, moist2) {
 export {
   assembleChunk,
   buildChunk,
-  checkResolution,
-  chunkCenter,
-  chunkIndices,
-  chunkLayout,
-  lockCode
+  chunkCenter
 };

package/dist/colliders.d.ts

@@ -1,7 +1,7 @@
 import { type Entity, type Query, type World } from '@aethervtt/shard-core';
 import { Mesh } from '@aethervtt/shard-mesh';
 import type { Workers } from '@aethervtt/shard-platform';
-import { type ChunkMesh } from './chunk.js';
+import { type ChunkMesh, type ChunkSpec } from './chunk.js';
 import type { PlanetRuntime } from './planet.js';
 import { type ChunkPoints } from './points.js';
 /** Frames between asking for a collider chunk and it appearing. Always this many, pool or not. */
@@ -71,6 +71,7 @@ export declare function anchorQueries(world: World): AnchorQueries;
 export declare function gatherAnchors(world: World, planet: PlanetRuntime, q: AnchorQueries): void;
 /** The collider nodes within reach of the planet's anchors, as sorted keys. */
 export declare function wantedColliders(planet: PlanetRuntime): string[];
+export declare function chunkSpec(planet: PlanetRuntime, face: number, depth: number, x: number, y: number): ChunkSpec;
 /** How far skirts hang: past any morph mismatch between neighbors at this depth (true errors). */
 export declare function skirtDepth(planet: PlanetRuntime, depth: number): number;
 /**
@@ -81,6 +82,20 @@ export declare function skirtDepth(planet: PlanetRuntime, depth: number): number
  * but stay cached (least recently used first out).
  */
 export declare function updateColliders(world: World, planet: PlanetRuntime, workers: Workers | undefined, frame: number, cacheSize: number): void;
+/** A chunk's sample points with their graphs sampled on the pool (`done` resolves when all are in). */
+export interface ChunkSampling {
+    pts: ChunkPoints;
+    values: Float32Array;
+    temps: Float32Array;
+    moist: Float32Array;
+    done: Promise<void>;
+}
+/**
+ * Samples a chunk's height and climate on the worker pool: `assembleChunk(chunkSpec(…), pts, values,
+ * temps, moist)` then gives the same mesh `buildChunk` does inline. Colliders and scatter's foliage
+ * patches (0045) use it.
+ */
+export declare function sampleChunkAsync(planet: PlanetRuntime, workers: Workers, face: number, depth: number, x: number, y: number): ChunkSampling;
 /** Drops every collider chunk (planet despawned). */
 export declare function clearColliders(world: World, planet: PlanetRuntime): void;
 export {};

package/dist/colliders.js

@@ -10,9 +10,10 @@ import {
   propagateSubtree,
   Transform
 } from "@aethervtt/shard-transform";
-import { assembleChunk, buildChunk, chunkLayout } from "./chunk.js";
+import { assembleChunk, buildChunk } from "./chunk.js";
 import { Chunk, PlanetNav, TerrainAnchor } from "./components.js";
 import { faceToDirection, keyString, nodeAt, nodeExtent } from "./cube.js";
+import { chunkLayout } from "./grid-mesh.js";
 import { createChunkPoints, prepareChunkPoints } from "./points.js";
 const COLLIDER_DELAY = 2;
 class ColliderSet {
@@ -148,7 +149,7 @@ function wantedColliders(planet) {
   }
   return [...wantedKeys].sort();
 }
-function specFor(planet, face, depth, x, y) {
+function chunkSpec(planet, face, depth, x, y) {
   const s = planet.settings;
   return {
     face,
@@ -195,7 +196,7 @@ function updateColliders(world, planet, workers, frame, cacheSize) {
     }
     if (frame < job.due) continue;
     set.jobs.delete(key);
-    const spec = specFor(planet, job.face, job.depth, job.x, job.y);
+    const spec = chunkSpec(planet, job.face, job.depth, job.x, job.y);
     let mesh;
     if (job.ready && job.pts && job.values && job.temps && job.moist) {
       mesh = assembleChunk(spec, job.pts, job.values, job.temps, job.moist);
@@ -244,13 +245,31 @@ function startJob(planet, workers, key, face, depth, x, y, due) {
     cancelled: false
   };
   if (!workers || workers.size === 0) return job;
+  const sampling = sampleChunkAsync(planet, workers, face, depth, x, y);
+  job.pts = sampling.pts;
+  job.values = sampling.values;
+  job.temps = sampling.temps;
+  job.moist = sampling.moist;
+  sampling.done.then(
+    () => {
+      if (!job.cancelled) job.ready = true;
+    },
+    () => {
+    }
+  );
+  return job;
+}
+function sampleChunkAsync(planet, workers, face, depth, x, y) {
   const s = planet.settings;
   const pts = prepareChunkPoints(face, depth, x, y, s.resolution, s.radius, createChunkPoints());
-  job.pts = pts;
   const count = pts.count;
-  job.values = new Float32Array(count);
-  job.temps = new Float32Array(count);
-  job.moist = new Float32Array(count);
+  const out = {
+    pts,
+    values: new Float32Array(count),
+    temps: new Float32Array(count),
+    moist: new Float32Array(count),
+    done: Promise.resolve()
+  };
   const parts = [];
   const origin = new Float64Array(4);
   for (let g = 0; g < pts.groups; g++) {
@@ -267,31 +286,25 @@ function startJob(planet, workers, key, face, depth, x, y, due) {
     origin[1] = pts.origins[g * 4 + 1];
     origin[2] = pts.origins[g * 4 + 2];
     const o = Float64Array.from(origin);
-    const scatter = (target) => (values) => {
-      for (let i = a; i < b; i++) target[pts.order[i]] = values[i - a];
-    };
     const run = (graph, target, node2) => {
       if (!graph) return;
-      const out = new Float32Array(b - a);
+      const values = new Float32Array(b - a);
       parts.push(
-        sampleNoiseAsync(workers, graph, s.seed, local, out, {
+        sampleNoiseAsync(workers, graph, s.seed, local, values, {
           origin: o,
           ...node2 ? { node: node2 } : {}
-        }).then(() => scatter(target)(out))
+        }).then(() => {
+          for (let i = a; i < b; i++) target[pts.order[i]] = values[i - a];
+        })
       );
     };
-    run(planet.height, job.values);
-    run(planet.climate, job.temps, "temperature");
-    run(planet.climate, job.moist, "moisture");
+    run(planet.height, out.values);
+    run(planet.climate, out.temps, "temperature");
+    run(planet.climate, out.moist, "moisture");
   }
-  Promise.all(parts).then(
-    () => {
-      if (!job.cancelled) job.ready = true;
-    },
-    () => {
-    }
-  );
-  return job;
+  out.done = Promise.all(parts).then(() => {
+  });
+  return out;
 }
 function makeChunk(world, key, job, mesh, version, frame) {
   const layout = chunkLayout(Math.round(Math.sqrt(mesh.heights.length)));
@@ -347,9 +360,11 @@ export {
   COLLIDER_DELAY,
   ColliderSet,
   anchorQueries,
+  chunkSpec,
   clearColliders,
   collidersOf,
   gatherAnchors,
+  sampleChunkAsync,
   skirtDepth,
   updateColliders,
   wantedColliders

package/dist/components.d.ts

@@ -14,6 +14,7 @@ export declare const Planet: import("@aethervtt/shard-core").ComponentDef<{
     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 scatter: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").AssetRef<"scatter/ScatterSet"> | null, "object">;
 }>;
 export declare const TerrainAnchor: import("@aethervtt/shard-core").ComponentDef<{
     readonly enabled: import("@aethervtt/shard-core").FieldType<boolean, "u8">;
@@ -45,5 +46,9 @@ export interface TerrainBudgetValue {
     pool: number;
     /** Collider chunks cached per planet. */
     colliderCache: number;
+    /** Heightfields (0071): GPU page pool slots per terrain (about 22 KB each). */
+    pages: number;
+    /** Heightfields: pages uploaded to the pool per frame, at most. */
+    pagesPerFrame: number;
 }
 export declare const TerrainBudget: import("@aethervtt/shard-core").ResourceDef<TerrainBudgetValue>;

package/dist/components.js

@@ -64,6 +64,9 @@ const Planet = defineComponent(
     skirts: t.bool({
       default: true,
       description: "Walls under chunk edges that hide cracks while neighbors change level."
+    }),
+    scatter: t.handle("scatter/ScatterSet", {
+      description: "Props and foliage everywhere on the planet (*.scatter.json; needs the scatter plugin). Each biome can add its own (Biome.scatter)."
     })
   },
   {
@@ -119,13 +122,15 @@ const Chunk = defineComponent(
   }
 );
 const TerrainBudget = defineResource("terrain/Budget", {
-  description: "How much terrain work a frame may do: chunk generations, GPU milliseconds, and how many chunks stay cached.",
+  description: "How much terrain work a frame may do: chunk generations, GPU milliseconds, page uploads, and how many chunks and pages stay cached.",
   init: () => ({
     chunksPerFrame: 8,
     triangles: 2e6,
     msPerFrame: 1.5,
     pool: 2048,
-    colliderCache: 256
+    colliderCache: 256,
+    pages: 1024,
+    pagesPerFrame: 16
   })
 });
 export {

package/dist/cube-sphere.d.ts

@@ -0,0 +1,50 @@
+import { type QuadSurface, QuadTree, type SelectionParams, type SelectionView } from './quadtree.js';
+/**
+ * The cube-sphere as a quadtree surface (spec 0043): six roots, one per cube face, projected onto
+ * an ellipsoid of `radius` and `shape`. Each node keeps 9 test directions (corners, edge middles,
+ * center) for its bounds and the horizon test, and how far to lift them over the surface's bulge.
+ */
+export declare class CubeSphere implements QuadSurface {
+    readonly roots = 6;
+    radius: number;
+    readonly shape: Float64Array<ArrayBuffer>;
+    /** Horizon test directions (unit, 9 per node). */
+    dirs: Float64Array<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>;
+    grow(capacity: number): void;
+    initNode(tree: QuadTree, n: number): void;
+    /** Bounding sphere of the node's 9 test points at its lowest and highest heights, plus bulge. */
+    updateSphere(tree: QuadTree, n: number): void;
+    /**
+     * Axis-aligned bounds of the node relative to `center`, from its test points at its lowest and
+     * highest heights plus the bulge between them.
+     */
+    bounds(tree: QuadTree, n: number, center: ArrayLike<number>, out: {
+        [i: number]: number;
+    }): void;
+    culled(tree: QuadTree, n: number, view: SelectionView, params: SelectionParams): boolean;
+    /** Across a cube edge the neighbor is on another face: there always is one. */
+    neighbor(root: number, depth: number, x: number, y: number, edge: number, out: {
+        [i: number]: number;
+    }): boolean;
+}
+/**
+ * A planet surface's quadtree (terrain or ocean): a `QuadTree` on a `CubeSphere`. The six roots
+ * are nodes 0–5, one per face.
+ */
+export declare class NodeTree extends QuadTree {
+    readonly cube: CubeSphere;
+    constructor(capacity?: number);
+    /** Each node's cube face (its root). */
+    get face(): Uint8Array;
+    get radius(): number;
+    get shape(): Float64Array;
+    /** 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). */
+    rootOf(face: number): number;
+}