@aethervtt/shard-terrain 0.0.1

package/dist/cube.js

@@ -0,0 +1,87 @@
+import { directionToFace, faceToDirection } from "@aethervtt/shard-noise";
+const MAX_DEPTH = 24;
+const MAX_RADIUS = 5e7;
+const EDGE_BOTTOM = 0;
+const EDGE_RIGHT = 1;
+const EDGE_TOP = 2;
+const EDGE_LEFT = 3;
+function nodeExtent(depth) {
+  return 2 / 2 ** depth;
+}
+function nodeSpacing(radius, depth, resolution) {
+  return radius * Math.PI / 2 / 2 ** depth / (resolution - 1);
+}
+function maxDepthFor(radius, resolution, minSpacing) {
+  let d = 0;
+  while (d < MAX_DEPTH && nodeSpacing(radius, d, resolution) > minSpacing) d++;
+  return d;
+}
+function packKey(face, depth, x, y, out, offset = 0) {
+  out[offset] = (face << 29 | depth << 24 | x) >>> 0;
+  out[offset + 1] = y >>> 0;
+  return out;
+}
+function unpackKey(k0, k1) {
+  return { face: k0 >>> 29, depth: k0 >>> 24 & 31, x: k0 & 16777215, y: k1 >>> 0 };
+}
+function keyString(face, depth, x, y) {
+  return `${face}/${depth}/${x}/${y}`;
+}
+function parseKey(key) {
+  const parts = key.split("/").map(Number);
+  if (parts.length !== 4 || parts.some((p) => !Number.isInteger(p) || p < 0)) return void 0;
+  const [face, depth, x, y] = parts;
+  if (face > 5 || depth > MAX_DEPTH || x >= 2 ** depth || y >= 2 ** depth) return void 0;
+  return { face, depth, x, y };
+}
+const dir = new Float64Array(3);
+const uv = new Float64Array(2);
+function nodeAt(x, y, z, depth, out) {
+  const face = directionToFace(x, y, z, uv);
+  const n = 2 ** depth;
+  out[0] = face;
+  out[1] = Math.min(n - 1, Math.max(0, Math.floor((uv[0] + 1) / 2 * n)));
+  out[2] = Math.min(n - 1, Math.max(0, Math.floor((uv[1] + 1) / 2 * n)));
+  return out;
+}
+function neighborNode(face, depth, x, y, edge, out) {
+  const n = 2 ** depth;
+  let nx = x;
+  let ny = y;
+  if (edge === EDGE_BOTTOM) ny--;
+  else if (edge === EDGE_RIGHT) nx++;
+  else if (edge === EDGE_TOP) ny++;
+  else nx--;
+  if (nx >= 0 && ny >= 0 && nx < n && ny < n) {
+    out[0] = face;
+    out[1] = nx;
+    out[2] = ny;
+    return out;
+  }
+  const ext = 2 / n;
+  const u = -1 + (nx + 0.5) * ext;
+  const v = -1 + (ny + 0.5) * ext;
+  const pu = edge === EDGE_RIGHT || edge === EDGE_LEFT ? u + (edge === EDGE_RIGHT ? -0.25 : 0.25) * ext : u;
+  const pv = edge === EDGE_TOP || edge === EDGE_BOTTOM ? v + (edge === EDGE_TOP ? -0.25 : 0.25) * ext : v;
+  faceToDirection(face, pu, pv, dir);
+  return nodeAt(dir[0], dir[1], dir[2], depth, out);
+}
+export {
+  EDGE_BOTTOM,
+  EDGE_LEFT,
+  EDGE_RIGHT,
+  EDGE_TOP,
+  MAX_DEPTH,
+  MAX_RADIUS,
+  directionToFace,
+  faceToDirection,
+  keyString,
+  maxDepthFor,
+  neighborNode,
+  nodeAt,
+  nodeExtent,
+  nodeSpacing,
+  packKey,
+  parseKey,
+  unpackKey
+};

package/dist/frame.d.ts

@@ -0,0 +1,21 @@
+import { type Entity, type World } from '@aethervtt/shard-core';
+/**
+ * A planet's frame against the floating origin, in f64: planet coordinates are its grid's
+ * (`cell × cellSize + offset`), which is where chunks, anchors, and the camera are compared.
+ * Taken from the grid frames transform propagation solved this frame (spec 0040).
+ */
+export declare class PlanetFrame {
+    /** Planet frame → origin frame (affine, 12 f64). */
+    readonly toOrigin: Float64Array<ArrayBufferLike>;
+    /** Origin frame → planet frame. */
+    readonly toPlanet: Float64Array<ArrayBufferLike>;
+    update(world: World, planet: Entity): void;
+    /** An origin-frame point into the planet frame, at `out[o]`. */
+    pointToPlanet(x: number, y: number, z: number, out: Float64Array, o?: number): Float64Array;
+    /** An origin-frame direction into the planet frame (rotation only). */
+    vectorToPlanet(x: number, y: number, z: number, out: Float64Array, o?: number): Float64Array;
+    /** A planet-frame point into the origin frame. */
+    pointToOrigin(x: number, y: number, z: number, out: Float64Array | Float32Array, o?: number): Float32Array<ArrayBufferLike> | Float64Array<ArrayBufferLike>;
+    /** A planet-frame direction into the origin frame. */
+    vectorToOrigin(x: number, y: number, z: number, out: Float64Array | Float32Array, o?: number): Float32Array<ArrayBufferLike> | Float64Array<ArrayBufferLike>;
+}

package/dist/frame.js

@@ -0,0 +1,63 @@
+import { affine64 } from "@aethervtt/shard-core";
+import { GlobalTransform, GridFramesResource } from "@aethervtt/shard-transform";
+class PlanetFrame {
+  /** Planet frame → origin frame (affine, 12 f64). */
+  toOrigin = affine64.create();
+  /** Origin frame → planet frame. */
+  toPlanet = affine64.create();
+  update(world, planet) {
+    const frames = world.tryResource(GridFramesResource);
+    const slot = frames?.active ? frames.slotOf.get(planet) : void 0;
+    if (frames && slot !== void 0 && !Number.isNaN(frames.a[slot * 12])) {
+      const cs = frames.cellSize[slot];
+      affine64.translateAt(
+        this.toOrigin,
+        0,
+        frames.a,
+        slot * 12,
+        -frames.ref[slot * 3] * cs,
+        -frames.ref[slot * 3 + 1] * cs,
+        -frames.ref[slot * 3 + 2] * cs
+      );
+    } else if (world.has(planet, GlobalTransform)) {
+      const m = world.get(planet, GlobalTransform).matrix;
+      for (let i = 0; i < 12; i++) this.toOrigin[i] = m[i];
+    } else affine64.identity(this.toOrigin);
+    if (!affine64.invert(this.toPlanet, this.toOrigin)) affine64.identity(this.toPlanet);
+  }
+  /** An origin-frame point into the planet frame, at `out[o]`. */
+  pointToPlanet(x, y, z, out, o = 0) {
+    const m = this.toPlanet;
+    out[o] = m[0] * x + m[1] * y + m[2] * z + m[3];
+    out[o + 1] = m[4] * x + m[5] * y + m[6] * z + m[7];
+    out[o + 2] = m[8] * x + m[9] * y + m[10] * z + m[11];
+    return out;
+  }
+  /** An origin-frame direction into the planet frame (rotation only). */
+  vectorToPlanet(x, y, z, out, o = 0) {
+    const m = this.toPlanet;
+    out[o] = m[0] * x + m[1] * y + m[2] * z;
+    out[o + 1] = m[4] * x + m[5] * y + m[6] * z;
+    out[o + 2] = m[8] * x + m[9] * y + m[10] * z;
+    return out;
+  }
+  /** A planet-frame point into the origin frame. */
+  pointToOrigin(x, y, z, out, o = 0) {
+    const m = this.toOrigin;
+    out[o] = m[0] * x + m[1] * y + m[2] * z + m[3];
+    out[o + 1] = m[4] * x + m[5] * y + m[6] * z + m[7];
+    out[o + 2] = m[8] * x + m[9] * y + m[10] * z + m[11];
+    return out;
+  }
+  /** A planet-frame direction into the origin frame. */
+  vectorToOrigin(x, y, z, out, o = 0) {
+    const m = this.toOrigin;
+    out[o] = m[0] * x + m[1] * y + m[2] * z;
+    out[o + 1] = m[4] * x + m[5] * y + m[6] * z;
+    out[o + 2] = m[8] * x + m[9] * y + m[10] * z;
+    return out;
+  }
+}
+export {
+  PlanetFrame
+};

package/dist/heights.d.ts

@@ -0,0 +1,51 @@
+import { type Entity, type World } from '@aethervtt/shard-core';
+import type { Workers } from '@aethervtt/shard-platform';
+import type { PlanetRuntime } from './planet.js';
+/** Every planet's runtime state, and the frame counter terrain systems stamp with. */
+export declare class TerrainState {
+    readonly planets: Map<number, PlanetRuntime>;
+    frame: number;
+    workers: Workers | undefined;
+    /** Set when a graph or biome asset (re)loaded: planets re-resolve their assets. */
+    dirty: boolean;
+}
+export declare const Terrain: import("@aethervtt/shard-core").ResourceDef<TerrainState>;
+/** The runtime for a planet entity, ready to sample, or a `terrain/not-ready` error. */
+export declare function planetRuntime(world: World, planet: Entity): PlanetRuntime;
+/** Height-graph metres above radius at a unit direction in the planet's frame. Sync, CPU. */
+export declare function heightAt(rt: PlanetRuntime, x: number, y: number, z: number): number;
+/**
+ * The surface height (metres above the planet's radius) in `direction` (the planet's frame, any
+ * length), from the canonical CPU noise (0041) the colliders use. Headless-safe and sync; allocates
+ * nothing. Between vertices the collider surface is flat triangles, so it can differ from this by
+ * the terrain's roughness below the vertex spacing.
+ */
+export declare function planetHeightAt(world: World, planet: Entity, direction: ArrayLike<number>): number;
+export interface PlanetSurface {
+    /** Metres above radius. */
+    height: number;
+    /** Below sea level (planets with an ocean). */
+    underwater: boolean;
+    /** Metres of water above the ground (0 on land). */
+    depth: number;
+}
+/** Height, and whether and how deep it's under water, in `direction`. */
+export declare function planetSurfaceAt(world: World, planet: Entity, direction: ArrayLike<number>, out?: PlanetSurface): PlanetSurface;
+export interface TerrainSample extends PlanetSurface {
+    /** Degrees from flat. */
+    slope: number;
+    /** Climate at the point, before latitude and altitude. */
+    temperature: number;
+    moisture: number;
+    /** Sine of the latitude. */
+    latitude: number;
+    /** Biome weights (summing to 1), by index in the BiomeSet. */
+    biomes: number[];
+    /** The heaviest biome's index. */
+    biome: number;
+}
+/**
+ * Everything the surface is at a direction: height, water, slope (from two nearby heights), climate,
+ * and biome weights, as the terrain shader computes them.
+ */
+export declare function terrainSample(rt: PlanetRuntime, direction: ArrayLike<number>): TerrainSample;

package/dist/heights.js

@@ -0,0 +1,137 @@
+import { defineResource, ShardError } from "@aethervtt/shard-core";
+import { biomeWeights, dominantBiome, MAX_BIOMES } from "./biomes.js";
+import { samplePoint } from "./points.js";
+class TerrainState {
+  planets = /* @__PURE__ */ new Map();
+  frame = 0;
+  workers;
+  /** Set when a graph or biome asset (re)loaded: planets re-resolve their assets. */
+  dirty = true;
+}
+const Terrain = defineResource("terrain/Terrain", {
+  description: "Per-planet terrain state: quadtrees, collider chunks, and resolved assets.",
+  init: () => new TerrainState()
+});
+function planetRuntime(world, planet) {
+  const rt = world.tryResource(Terrain)?.planets.get(planet);
+  if (!rt) {
+    throw new ShardError("terrain/not-a-planet", `Entity ${planet} has no terrain/Planet`, {
+      hint: "Add terrain/Planet (and a Grid) to the planet entity, and the terrain plugin to the app."
+    });
+  }
+  if (rt.problem) throw rt.problem;
+  if (!rt.ready) {
+    throw new ShardError(
+      "terrain/not-ready",
+      `Planet ${planet} is waiting for ${rt.waiting ?? "its settings"}`,
+      {
+        hint: "Its graphs and biomes load asynchronously; step a frame (or await the asset loads) first."
+      }
+    );
+  }
+  return rt;
+}
+const one = new Float32Array(1);
+function heightAt(rt, x, y, z) {
+  const s = rt.settings;
+  if (!rt.height) return 0;
+  return samplePoint(rt.height, s.seed, x, y, z, s.radius, one) * s.heightScale;
+}
+function unit(direction, out) {
+  const x = direction[0];
+  const y = direction[1];
+  const z = direction[2];
+  const len = Math.sqrt(x * x + y * y + z * z);
+  if (!(len > 0)) {
+    throw new ShardError("terrain/bad-direction", "The direction is zero or not a number", {
+      hint: "Pass a direction from the planet\u2019s center in its frame, e.g. the position of a point on it."
+    });
+  }
+  out[0] = x / len;
+  out[1] = y / len;
+  out[2] = z / len;
+  return out;
+}
+const d = new Float64Array(3);
+function planetHeightAt(world, planet, direction) {
+  const rt = planetRuntime(world, planet);
+  unit(direction, d);
+  return heightAt(rt, d[0], d[1], d[2]);
+}
+function planetSurfaceAt(world, planet, direction, out = { height: 0, underwater: false, depth: 0 }) {
+  const rt = planetRuntime(world, planet);
+  unit(direction, d);
+  const h = heightAt(rt, d[0], d[1], d[2]);
+  const s = rt.settings;
+  out.height = h;
+  out.underwater = s.ocean && h < s.seaLevel;
+  out.depth = out.underwater ? s.seaLevel - h : 0;
+  return out;
+}
+const weights = new Float32Array(MAX_BIOMES);
+const t1 = new Float64Array(3);
+const t2 = new Float64Array(3);
+function terrainSample(rt, direction) {
+  const s = rt.settings;
+  unit(direction, d);
+  const [x, y, z] = [d[0], d[1], d[2]];
+  const h = heightAt(rt, x, y, z);
+  const step = Math.max(rt.spacing(rt.colliderDepth), 0.25) / s.radius;
+  const ax = Math.abs(y) < 0.9 ? 0 : 1;
+  const ay = Math.abs(y) < 0.9 ? 1 : 0;
+  let e1x = ay * z;
+  let e1y = -ax * z;
+  let e1z = ax * y - ay * x;
+  const l1 = Math.hypot(e1x, e1y, e1z);
+  e1x /= l1;
+  e1y /= l1;
+  e1z /= l1;
+  const e2x = y * e1z - z * e1y;
+  const e2y = z * e1x - x * e1z;
+  const e2z = x * e1y - y * e1x;
+  unit([x + e1x * step, y + e1y * step, z + e1z * step], t1);
+  unit([x + e2x * step, y + e2y * step, z + e2z * step], t2);
+  const h1 = heightAt(rt, t1[0], t1[1], t1[2]);
+  const h2 = heightAt(rt, t2[0], t2[1], t2[2]);
+  const r0 = s.radius + h;
+  const p0 = [x * r0, y * r0, z * r0];
+  const r1 = s.radius + h1;
+  const r2 = s.radius + h2;
+  const a = [t1[0] * r1 - p0[0], t1[1] * r1 - p0[1], t1[2] * r1 - p0[2]];
+  const b = [t2[0] * r2 - p0[0], t2[1] * r2 - p0[1], t2[2] * r2 - p0[2]];
+  const nx = a[1] * b[2] - a[2] * b[1];
+  const ny = a[2] * b[0] - a[0] * b[2];
+  const nz = a[0] * b[1] - a[1] * b[0];
+  const nl = Math.hypot(nx, ny, nz);
+  const cos = Math.abs(nx * x + ny * y + nz * z) / nl;
+  const slope = Math.acos(Math.min(1, cos)) * 180 / Math.PI;
+  let temperature = 0;
+  let moisture = 0;
+  if (rt.climate) {
+    temperature = samplePoint(rt.climate, s.seed, x, y, z, s.radius, one, "temperature");
+    moisture = samplePoint(rt.climate, s.seed, x, y, z, s.radius, one, "moisture");
+  }
+  const table = rt.table;
+  biomeWeights(table, { temperature, moisture, height: h, slope, latitude: y }, weights);
+  const underwater = s.ocean && h < s.seaLevel;
+  return {
+    height: h,
+    underwater,
+    depth: underwater ? s.seaLevel - h : 0,
+    slope,
+    temperature,
+    moisture,
+    latitude: y,
+    biomes: Array.from(weights.subarray(0, table.count)),
+    biome: dominantBiome(weights, table.count)
+  };
+}
+export {
+  Terrain,
+  TerrainState,
+  heightAt,
+  planetHeightAt,
+  planetRuntime,
+  planetSurfaceAt,
+  terrainSample
+};

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+export { Biome, type BiomeInputs, BiomeSet, type BiomeSetValue, type BiomeTable, type BiomeValue, BLENDED_BIOMES, biomeTable, biomeWeights, biomeWindow, dominantBiome, effectiveTemperature, MAX_BIOMES, MAX_LAYERS, } from './biomes.js';
+export { assembleChunk, buildChunk, type ChunkLayout, type ChunkMesh, type ChunkSpec, checkResolution, chunkCenter, chunkLayout, } from './chunk.js';
+export { COLLIDER_DELAY, type ColliderChunk, ColliderSet, collidersOf, skirtDepth, } from './colliders.js';
+export { Chunk, Planet, PlanetNav, TerrainAnchor, TerrainBudget, type TerrainBudgetValue, } from './components.js';
+export { directionToFace, EDGE_BOTTOM, EDGE_LEFT, EDGE_RIGHT, EDGE_TOP, faceToDirection, keyString, MAX_DEPTH, MAX_RADIUS, maxDepthFor, type NodeAddress, neighborNode, nodeAt, nodeExtent, nodeSpacing, packKey, parseKey, unpackKey, } from './cube.js';
+export { PlanetFrame } from './frame.js';
+export { heightAt, type PlanetSurface, planetHeightAt, planetRuntime, planetSurfaceAt, Terrain, type TerrainSample, TerrainState, terrainSample, } from './heights.js';
+export { GEN_CLIMATE, GEN_HEIGHT, GEN_OCEAN, GEN_ROOT, type KernelGraph, kernelGraph, PARAMS_BYTES, POINT_FLOATS, sampleKernel, VERTEX_KERNEL, } from './kernel.js';
+export { measureErrors } from './lod.js';
+export { OceanMaterial, PlanetMaterial, TERRAIN_SHADERS, TEXTURE_PERIOD } from './material.js';
+export { resolvePlanet, terrainMap, terrainMethods } from './methods.js';
+export { clearPlanetNav, planetAgents, planetNavMesh, updatePlanetNav } from './nav.js';
+export { terrainBiomesOverlay, terrainCollidersOverlay, terrainLodOverlay } from './overlays.js';
+export { COLLIDER_SPACING, PlanetRuntime, type PlanetSettings } from './planet.js';
+export { type TerrainPluginOptions, terrainPlugin, updatePlanets } from './plugin.js';
+export { type ChunkPoints, createChunkPoints, gridDirection, prepareChunkPoints, SNAP, sampleChunkPoints, samplePoint, } from './points.js';
+export { createSelection, NODE_BOUNDS, NODE_READY, NodeTree, type Selection, type SelectionParams, type SelectionView, selectNodes, } from './quadtree.js';
+export { PlanetRender, renderOf, selectChunks, TerrainDebug } from './render.js';
+export { createView, omniView, perspectiveView } from './view.js';

package/dist/index.js

@@ -0,0 +1,193 @@
+import {
+  Biome,
+  BiomeSet,
+  BLENDED_BIOMES,
+  biomeTable,
+  biomeWeights,
+  biomeWindow,
+  dominantBiome,
+  effectiveTemperature,
+  MAX_BIOMES,
+  MAX_LAYERS
+} from "./biomes.js";
+import {
+  assembleChunk,
+  buildChunk,
+  checkResolution,
+  chunkCenter,
+  chunkLayout
+} from "./chunk.js";
+import {
+  COLLIDER_DELAY,
+  ColliderSet,
+  collidersOf,
+  skirtDepth
+} from "./colliders.js";
+import {
+  Chunk,
+  Planet,
+  PlanetNav,
+  TerrainAnchor,
+  TerrainBudget
+} from "./components.js";
+import {
+  directionToFace,
+  EDGE_BOTTOM,
+  EDGE_LEFT,
+  EDGE_RIGHT,
+  EDGE_TOP,
+  faceToDirection,
+  keyString,
+  MAX_DEPTH,
+  MAX_RADIUS,
+  maxDepthFor,
+  neighborNode,
+  nodeAt,
+  nodeExtent,
+  nodeSpacing,
+  packKey,
+  parseKey,
+  unpackKey
+} from "./cube.js";
+import { PlanetFrame } from "./frame.js";
+import {
+  heightAt,
+  planetHeightAt,
+  planetRuntime,
+  planetSurfaceAt,
+  Terrain,
+  TerrainState,
+  terrainSample
+} from "./heights.js";
+import {
+  GEN_CLIMATE,
+  GEN_HEIGHT,
+  GEN_OCEAN,
+  GEN_ROOT,
+  kernelGraph,
+  PARAMS_BYTES,
+  POINT_FLOATS,
+  sampleKernel,
+  VERTEX_KERNEL
+} from "./kernel.js";
+import { measureErrors } from "./lod.js";
+import { OceanMaterial, PlanetMaterial, TERRAIN_SHADERS, TEXTURE_PERIOD } from "./material.js";
+import { resolvePlanet, terrainMap, terrainMethods } from "./methods.js";
+import { clearPlanetNav, planetAgents, planetNavMesh, updatePlanetNav } from "./nav.js";
+import { terrainBiomesOverlay, terrainCollidersOverlay, terrainLodOverlay } from "./overlays.js";
+import { COLLIDER_SPACING, PlanetRuntime } from "./planet.js";
+import { terrainPlugin, updatePlanets } from "./plugin.js";
+import {
+  createChunkPoints,
+  gridDirection,
+  prepareChunkPoints,
+  SNAP,
+  sampleChunkPoints,
+  samplePoint
+} from "./points.js";
+import {
+  createSelection,
+  NODE_BOUNDS,
+  NODE_READY,
+  NodeTree,
+  selectNodes
+} from "./quadtree.js";
+import { PlanetRender, renderOf, selectChunks, TerrainDebug } from "./render.js";
+import { createView, omniView, perspectiveView } from "./view.js";
+export {
+  BLENDED_BIOMES,
+  Biome,
+  BiomeSet,
+  COLLIDER_DELAY,
+  COLLIDER_SPACING,
+  Chunk,
+  ColliderSet,
+  EDGE_BOTTOM,
+  EDGE_LEFT,
+  EDGE_RIGHT,
+  EDGE_TOP,
+  GEN_CLIMATE,
+  GEN_HEIGHT,
+  GEN_OCEAN,
+  GEN_ROOT,
+  MAX_BIOMES,
+  MAX_DEPTH,
+  MAX_LAYERS,
+  MAX_RADIUS,
+  NODE_BOUNDS,
+  NODE_READY,
+  NodeTree,
+  OceanMaterial,
+  PARAMS_BYTES,
+  POINT_FLOATS,
+  Planet,
+  PlanetFrame,
+  PlanetMaterial,
+  PlanetNav,
+  PlanetRender,
+  PlanetRuntime,
+  SNAP,
+  TERRAIN_SHADERS,
+  TEXTURE_PERIOD,
+  Terrain,
+  TerrainAnchor,
+  TerrainBudget,
+  TerrainDebug,
+  TerrainState,
+  VERTEX_KERNEL,
+  assembleChunk,
+  biomeTable,
+  biomeWeights,
+  biomeWindow,
+  buildChunk,
+  checkResolution,
+  chunkCenter,
+  chunkLayout,
+  clearPlanetNav,
+  collidersOf,
+  createChunkPoints,
+  createSelection,
+  createView,
+  directionToFace,
+  dominantBiome,
+  effectiveTemperature,
+  faceToDirection,
+  gridDirection,
+  heightAt,
+  kernelGraph,
+  keyString,
+  maxDepthFor,
+  measureErrors,
+  neighborNode,
+  nodeAt,
+  nodeExtent,
+  nodeSpacing,
+  omniView,
+  packKey,
+  parseKey,
+  perspectiveView,
+  planetAgents,
+  planetHeightAt,
+  planetNavMesh,
+  planetRuntime,
+  planetSurfaceAt,
+  prepareChunkPoints,
+  renderOf,
+  resolvePlanet,
+  sampleChunkPoints,
+  sampleKernel,
+  samplePoint,
+  selectChunks,
+  selectNodes,
+  skirtDepth,
+  terrainBiomesOverlay,
+  terrainCollidersOverlay,
+  terrainLodOverlay,
+  terrainMap,
+  terrainMethods,
+  terrainPlugin,
+  terrainSample,
+  unpackKey,
+  updatePlanetNav,
+  updatePlanets
+};

package/dist/kernel.d.ts

@@ -0,0 +1,47 @@
+import { type NoiseGraph, type NoiseProgram } from '@aethervtt/shard-noise';
+import type { ShaderLibrary } from '@aethervtt/shard-shader';
+/** A graph (or one node of it) as the kernel imports it: a WGSL module and its program. */
+export interface KernelGraph {
+    module: string;
+    name: string;
+    wgsl: string;
+    program: NoiseProgram;
+    hash: string;
+}
+/** The graph's own output, or one node of it (the climate graph's temperature and moisture). */
+export declare function kernelGraph(graph: NoiseGraph, node?: string): KernelGraph;
+/** Floats per point in the uploaded point buffer: local xyz, q xyz, dir xyz, group (u32 bits). */
+export declare const POINT_FLOATS = 10;
+/** Bytes of the kernel's uniform. */
+export declare const PARAMS_BYTES = 64;
+/** Flags in GenParams.flags. */
+export declare const GEN_HEIGHT = 1;
+export declare const GEN_CLIMATE = 2;
+export declare const GEN_ROOT = 4;
+export declare const GEN_OCEAN = 8;
+/** The sampling pass: each point's height and climate from its lattice origin. */
+export declare function sampleKernel(height: KernelGraph | undefined, temperature: KernelGraph | undefined, moisture: KernelGraph | undefined): string;
+/**
+ * The vertex pass, one invocation per surface vertex: position (the point's offset from the chunk
+ * center plus its direction times its height), central-difference normal from the bordered grid,
+ * climate, morph delta to the parent level, and the skirt copy of ring vertices. Heights, water
+ * depth, and morph error go into the stats for the readback. Same layout and math as `buildChunk`.
+ * uv1 is (grid point i + j·n + n²·tile, morph error): the vertex stage derives lock codes from the
+ * grid point, the surface stage finds its normal tile (`packGrid`).
+ */
+export declare const VERTEX_KERNEL = "\nstruct GenParams {\n  count: u32,\n  side: u32,\n  n: u32,\n  surface: u32,\n  ring: u32,\n  seed: u32,\n  flags: u32,\n  /** The chunk's slot: its normal tile, packed into uv1.x (see packGrid). */\n  tile: u32,\n  /** Ellipsoid axis ratios (xyz), metres per height unit (w). */\n  shape: vec4f,\n  /** x: surface offset (m, the ocean's sea level), y: morph error, z: skirt depth. */\n  misc: vec4f,\n}\n\n@group(0) @binding(0) var<uniform> params: GenParams;\n@group(0) @binding(1) var<storage, read> pts: array<f32>;\n\n@group(0) @binding(2) var<storage, read> values: array<f32>;\n@group(0) @binding(3) var<storage, read_write> positions: array<f32>;\n@group(0) @binding(4) var<storage, read_write> normals: array<f32>;\n@group(0) @binding(5) var<storage, read_write> uvs: array<f32>;\n@group(0) @binding(6) var<storage, read_write> uvs1: array<f32>;\n@group(0) @binding(7) var<storage, read_write> tangents: array<f32>;\n/** Min height, max height (mm), largest morph delta (mm). */\n@group(0) @binding(8) var<storage, read_write> stats: array<atomic<i32>, 4>;\n\n/** Vertex index of grid point (i, j): the border ring first (counter-clockwise), then rows. */\nfn vertex_index(i: u32, j: u32, n: u32) -> u32 {\n  let s = n - 1u;\n  if (j == 0u) { return i; }\n  if (i == s) { return s + j; }\n  if (j == s) { return 2u * s + (s - i); }\n  if (i == 0u) { return 3u * s + (s - j); }\n  return 4u * s + (j - 1u) * (n - 2u) + (i - 1u);\n}\n\nfn terrain_height(k: u32) -> f32 {\n  return values[k * 3u] * params.shape.w;\n}\n\nfn surface_height(k: u32) -> f32 {\n  if ((params.flags & 8u) != 0u) { return params.misc.x; }\n  return terrain_height(k) + params.misc.x;\n}\n\nfn point_position(k: u32) -> vec3f {\n  let p = k * 10u;\n  let q = vec3f(pts[p + 3u], pts[p + 4u], pts[p + 5u]);\n  let d = vec3f(pts[p + 6u], pts[p + 7u], pts[p + 8u]);\n  return q + params.shape.xyz * d * surface_height(k);\n}\n\nfn write_vertex(v: u32, p: vec3f, n: vec3f, climate: vec2f, lock: vec2f, t: vec4f) {\n  positions[v * 3u] = p.x;\n  positions[v * 3u + 1u] = p.y;\n  positions[v * 3u + 2u] = p.z;\n  normals[v * 3u] = n.x;\n  normals[v * 3u + 1u] = n.y;\n  normals[v * 3u + 2u] = n.z;\n  uvs[v * 2u] = climate.x;\n  uvs[v * 2u + 1u] = climate.y;\n  uvs1[v * 2u] = lock.x;\n  uvs1[v * 2u + 1u] = lock.y;\n  tangents[v * 4u] = t.x;\n  tangents[v * 4u + 1u] = t.y;\n  tangents[v * 4u + 2u] = t.z;\n  tangents[v * 4u + 3u] = t.w;\n}\n\n@compute @workgroup_size(64)\nfn main(@builtin(global_invocation_id) id: vec3u) {\n  let v = id.x;\n  if (v >= params.surface) { return; }\n  let n = params.n;\n  let b = params.side;\n  let i = v % n;\n  let j = v / n;\n  let k = (i + 1u) + (j + 1u) * b;\n  let p = point_position(k);\n  let normal = normalize(cross(point_position(k + 1u) - point_position(k - 1u), point_position(k + b) - point_position(k - b)));\n  var delta = vec3f(0.0);\n  let oi = (i & 1u) == 1u;\n  let oj = (j & 1u) == 1u;\n  if ((oi || oj) && (params.flags & 4u) == 0u) {\n    let ka = select(k, k - 1u, oi) - select(0u, b, oj);\n    let kb = select(k, k + 1u, oi) + select(0u, b, oj);\n    delta = (point_position(ka) + point_position(kb)) * 0.5 - p;\n    atomicMax(&stats[2], i32(ceil(length(delta) * 1000.0)));\n  }\n  let h = terrain_height(k);\n  let surface = surface_height(k);\n  var w = h;\n  if ((params.flags & 8u) != 0u) { w = params.misc.x - h; }\n  let climate = vec2f(values[k * 3u + 1u], values[k * 3u + 2u]);\n  let vi = vertex_index(i, j, n);\n  let lock = vec2f(f32(i + j * n + n * n * params.tile), params.misc.y);\n  let tangent = vec4f(delta, w);\n  write_vertex(vi, p, normal, climate, lock, tangent);\n  if (vi < params.ring) {\n    let q = k * 10u;\n    let down = normalize(params.shape.xyz * vec3f(pts[q + 6u], pts[q + 7u], pts[q + 8u]));\n    write_vertex(params.surface + vi, p - down * params.misc.z, normal, climate, lock, tangent);\n  }\n  atomicMin(&stats[0], i32(floor(surface * 1000.0)));\n  atomicMax(&stats[1], i32(ceil(surface * 1000.0)));\n}\n";
+/**
+ * The normal-tile pass (spec 0044 follow-up to 0043): over a chunk's grid at twice the vertex
+ * density (sampled like any chunk grid, bordered), one planet-space normal per texel into the
+ * chunk's tile of the planet's tile array. The same central differences as the vertex pass, so a
+ * tile texel on a vertex has that vertex's normal (to 8 bits).
+ */
+export declare const NORMAL_KERNEL = "\nstruct GenParams {\n  count: u32,\n  side: u32,\n  n: u32,\n  surface: u32,\n  ring: u32,\n  seed: u32,\n  flags: u32,\n  /** The chunk's slot: its normal tile, packed into uv1.x (see packGrid). */\n  tile: u32,\n  /** Ellipsoid axis ratios (xyz), metres per height unit (w). */\n  shape: vec4f,\n  /** x: surface offset (m, the ocean's sea level), y: morph error, z: skirt depth. */\n  misc: vec4f,\n}\n\n@group(0) @binding(0) var<uniform> params: GenParams;\n@group(0) @binding(1) var<storage, read> pts: array<f32>;\n\n@group(0) @binding(2) var<storage, read> values: array<f32>;\n@group(0) @binding(3) var tile_out: texture_storage_2d<rgba8unorm, write>;\n\nfn point_position(k: u32) -> vec3f {\n  let p = k * 10u;\n  let q = vec3f(pts[p + 3u], pts[p + 4u], pts[p + 5u]);\n  let d = vec3f(pts[p + 6u], pts[p + 7u], pts[p + 8u]);\n  return q + params.shape.xyz * d * (values[k * 3u] * params.shape.w);\n}\n\n@compute @workgroup_size(64)\nfn main(@builtin(global_invocation_id) id: vec3u) {\n  let t = params.n;\n  if (id.x >= t * t) { return; }\n  let b = params.side;\n  let i = id.x % t;\n  let j = id.x / t;\n  let k = (i + 1u) + (j + 1u) * b;\n  let normal = normalize(cross(point_position(k + 1u) - point_position(k - 1u), point_position(k + b) - point_position(k - b)));\n  // The tile's corner in its layer: surface (texel x) and ring (texel y) carry it.\n  textureStore(tile_out, vec2u(params.surface + i, params.ring + j), vec4f(normal * 0.5 + 0.5, 1.0));\n}\n";
+/** uv1.x of grid point (i, j) in a chunk of resolution n drawn from normal tile `tile`. */
+export declare function packGrid(i: number, j: number, n: number, tile: number): number;
+/** Registers a kernel's graph modules and its two roots; returns the root module paths. */
+export declare function registerKernel(library: ShaderLibrary, key: string, height: KernelGraph | undefined, temperature: KernelGraph | undefined, moisture: KernelGraph | undefined): {
+    sample: string;
+    vertices: string;
+    normals: string;
+};