@aethervtt/shard-terrain 0.0.1

package/dist/nav.d.ts

@@ -0,0 +1,14 @@
+import { type Entity, type Query, type World } from '@aethervtt/shard-core';
+import type { PlanetRuntime } from './planet.js';
+/** NavAgents near a planet (positions in its frame), for the navmesh's frame. */
+export declare function planetAgents(rt: PlanetRuntime, query: Query, out: Float64Array[]): number;
+/**
+ * Keeps a planet's navmesh (spec 0043): a NavMesh in a tangent frame (up is radial) at the ground
+ * under its NavAgents, baked from the collider chunks around them (which get NavSource), within
+ * PlanetNav.radius. The frame moves (and the navmesh rebakes) once the agents' center drifts
+ * half the radius away, so its tiles stay put while agents walk and while the origin moves.
+ */
+export declare function updatePlanetNav(world: World, rt: PlanetRuntime, query: Query): void;
+export declare function clearPlanetNav(world: World, rt: PlanetRuntime): void;
+/** The planet's NavMesh entity, if it has one. */
+export declare function planetNavMesh(rt: PlanetRuntime): Entity | undefined;

package/dist/nav.js

@@ -0,0 +1,114 @@
+import { ChildOf, Derived, quat } from "@aethervtt/shard-core";
+import { NavMesh, NavSource } from "@aethervtt/shard-nav";
+import {
+  GlobalTransform,
+  placeInGrid,
+  propagateSubtree,
+  Transform
+} from "@aethervtt/shard-transform";
+import { collidersOf } from "./colliders.js";
+import { PlanetNav } from "./components.js";
+import { heightAt } from "./heights.js";
+function stateOf(rt) {
+  return rt.parts.get("nav");
+}
+const p = new Float64Array(3);
+const sum = new Float64Array(3);
+function planetAgents(rt, query, out) {
+  let n = 0;
+  const s = rt.settings;
+  const reach = s.radius * Math.max(s.shape[0], s.shape[1], s.shape[2]) + rt.highest + 1e3;
+  for (const table of query.tables) {
+    const m = table.column(GlobalTransform, "matrix");
+    for (let row = 0; row < table.count; row++) {
+      rt.frame.pointToPlanet(m[row * 12 + 3], m[row * 12 + 7], m[row * 12 + 11], p);
+      if (Math.hypot(p[0], p[1], p[2]) > reach) continue;
+      if (!out[n]) out[n] = new Float64Array(3);
+      out[n].set(p);
+      n++;
+    }
+  }
+  return n;
+}
+const agents = [];
+function updatePlanetNav(world, rt, query) {
+  const state = stateOf(rt);
+  if (!world.has(rt.entity, PlanetNav)) {
+    if (state) clearPlanetNav(world, rt);
+    return;
+  }
+  const v = world.get(rt.entity, PlanetNav);
+  for (const chunk of collidersOf(rt).chunks.values()) {
+    if (chunk.entity >= 0 && !world.has(chunk.entity, NavSource)) world.add(chunk.entity, NavSource);
+  }
+  const n = planetAgents(rt, query, agents);
+  if (n === 0) return;
+  sum.fill(0);
+  for (let i = 0; i < n; i++) {
+    sum[0] = sum[0] + agents[i][0];
+    sum[1] = sum[1] + agents[i][1];
+    sum[2] = sum[2] + agents[i][2];
+  }
+  const key = JSON.stringify([v.agentRadius, v.agentHeight, v.maxSlope, v.radius]);
+  const cx = sum[0] / n;
+  const cy = sum[1] / n;
+  const cz = sum[2] / n;
+  if (state) {
+    const d = Math.hypot(cx - state.anchor[0], cy - state.anchor[1], cz - state.anchor[2]);
+    if (d < v.radius * 0.5 && state.key === key && world.isAlive(state.frame)) return;
+  }
+  const l = Math.hypot(cx, cy, cz) || 1;
+  const ux = cx / l;
+  const uy = cy / l;
+  const uz = cz / l;
+  const r = rt.settings.radius + heightAt(rt, ux, uy, uz);
+  const anchor = new Float64Array([ux * r, uy * r, uz * r]);
+  const side = Math.abs(uy) < 0.9 ? [0, 1, 0] : [1, 0, 0];
+  const forward = [
+    uy * side[2] - uz * side[1],
+    uz * side[0] - ux * side[2],
+    ux * side[1] - uy * side[0]
+  ];
+  const rotation = quat.lookRotation([0, 0, 0, 1], forward, [ux, uy, uz]);
+  let frame = state?.frame;
+  if (frame === void 0 || !world.isAlive(frame)) {
+    frame = world.spawn([ChildOf, { parent: rt.entity }], Transform, Derived);
+  }
+  placeInGrid(world, frame, rt.entity, anchor);
+  world.set(frame, Transform, { ...world.get(frame, Transform), rotation });
+  propagateSubtree(world, frame);
+  const settings = {
+    agentRadius: v.agentRadius,
+    agentHeight: v.agentHeight,
+    maxSlope: v.maxSlope,
+    maxClimb: Math.max(0.3, v.agentHeight * 0.3),
+    // Coarser voxels than a level's: the area is hundreds of metres across.
+    cellSize: Math.max(0.3, v.agentRadius / 1.5),
+    cellHeight: 0.15,
+    tileSize: 64,
+    boundsMin: [-v.radius, -v.radius, -v.radius],
+    boundsMax: [v.radius, v.radius, v.radius],
+    frame
+  };
+  let navmesh = state?.navmesh;
+  if (navmesh === void 0 || !world.isAlive(navmesh))
+    navmesh = world.spawn([NavMesh, settings], Derived);
+  else world.set(navmesh, NavMesh, settings);
+  rt.parts.set("nav", { frame, navmesh, anchor, key });
+}
+function clearPlanetNav(world, rt) {
+  const state = stateOf(rt);
+  if (!state) return;
+  if (world.isAlive(state.navmesh)) world.despawn(state.navmesh);
+  if (world.isAlive(state.frame)) world.despawn(state.frame);
+  rt.parts.delete("nav");
+}
+function planetNavMesh(rt) {
+  return stateOf(rt)?.navmesh;
+}
+export {
+  clearPlanetNav,
+  planetAgents,
+  planetNavMesh,
+  updatePlanetNav
+};

package/dist/overlays.d.ts

@@ -0,0 +1,6 @@
+/** Chunk shading by depth: what `terrain-lod` turns on (the material's debug mode 3). */
+export declare const terrainLodOverlay: import("@aethervtt/shard-render").OverlayDef;
+/** Chunk shading by dominant biome: what `terrain-biomes` turns on (debug mode 1). */
+export declare const terrainBiomesOverlay: import("@aethervtt/shard-render").OverlayDef;
+/** Collider chunks (their borders, on the surface) and the anchors that keep them. */
+export declare const terrainCollidersOverlay: import("@aethervtt/shard-render").OverlayDef;

package/dist/overlays.js

@@ -0,0 +1,67 @@
+import { defineOverlay } from "@aethervtt/shard-render";
+import { chunkLayout } from "./chunk.js";
+import { collidersOf } from "./colliders.js";
+import { Terrain } from "./heights.js";
+const terrainLodOverlay = defineOverlay({
+  name: "terrain-lod",
+  description: "Planet terrain shaded by LOD depth (a hue per level, darker toward edges locked to a coarser neighbor), to see where chunks split.",
+  draw: () => {
+  }
+});
+const terrainBiomesOverlay = defineOverlay({
+  name: "terrain-biomes",
+  description: "Planet terrain shaded flat by its dominant biome\u2019s tint, without textures.",
+  draw: () => {
+  }
+});
+const COLLIDER = [0.2, 1, 0.4, 1];
+const PENDING = [1, 0.8, 0.2, 1];
+const ANCHOR = [0.3, 0.7, 1, 1];
+const a = new Float64Array(3);
+const b = new Float64Array(3);
+const terrainCollidersOverlay = defineOverlay({
+  name: "terrain-colliders",
+  description: "Planet collider chunks: each one\u2019s border on the surface (green; yellow while cached but not in use), and a circle per anchor showing the radius it keeps colliders within.",
+  draw: (world, g) => {
+    const state = world.tryResource(Terrain);
+    if (!state) return;
+    for (const rt of state.planets.values()) {
+      if (!rt.ready) continue;
+      const layout = chunkLayout(rt.settings.resolution);
+      const rp = layout.ringPoints;
+      for (const chunk of collidersOf(rt).chunks.values()) {
+        const m = chunk.mesh;
+        const p = m.data.positions;
+        const color = chunk.entity >= 0 ? COLLIDER : PENDING;
+        for (let r = 0; r < layout.ring; r++) {
+          const s = (r + 1) % layout.ring;
+          const va = layout.index[rp[r * 2] + rp[r * 2 + 1] * layout.resolution];
+          const vb = layout.index[rp[s * 2] + rp[s * 2 + 1] * layout.resolution];
+          rt.frame.pointToOrigin(
+            p[va * 3] + m.center[0],
+            p[va * 3 + 1] + m.center[1],
+            p[va * 3 + 2] + m.center[2],
+            a
+          );
+          rt.frame.pointToOrigin(
+            p[vb * 3] + m.center[0],
+            p[vb * 3 + 1] + m.center[1],
+            p[vb * 3 + 2] + m.center[2],
+            b
+          );
+          g.line(a, b, color);
+        }
+      }
+      for (let i = 0; i < rt.anchors; i++) {
+        const o = i * 3;
+        rt.frame.pointToOrigin(rt.anchorPos[o], rt.anchorPos[o + 1], rt.anchorPos[o + 2], a);
+        g.sphere(a, rt.anchorRadius[i], ANCHOR);
+      }
+    }
+  }
+});
+export {
+  terrainBiomesOverlay,
+  terrainCollidersOverlay,
+  terrainLodOverlay
+};

package/dist/planet.d.ts

@@ -0,0 +1,106 @@
+import { type AssetRef, type Entity, ShardError, type World } from '@aethervtt/shard-core';
+import { type NoiseGraph } from '@aethervtt/shard-noise';
+import { type BiomeSetValue, type BiomeTable, type BiomeValue } from './biomes.js';
+import { PlanetFrame } from './frame.js';
+import { NodeTree } from './quadtree.js';
+/** Collider chunks are the first depth whose vertices are at most this far apart (m). */
+export declare const COLLIDER_SPACING = 1;
+/** A planet's settings as numbers, read from its component when it changes. */
+export interface PlanetSettings {
+    radius: number;
+    shape: Float64Array;
+    heightScale: number;
+    seed: number;
+    ocean: boolean;
+    seaLevel: number;
+    resolution: number;
+    minSpacing: number;
+    errorPixels: number;
+    vertexPixels: number;
+    colliderRadius: number;
+    skirts: boolean;
+    height: AssetRef | null;
+    climate: AssetRef | null;
+    biomes: AssetRef | null;
+}
+/**
+ * Everything the terrain keeps per Planet entity: resolved graphs and biomes, per-depth errors, the
+ * terrain and ocean quadtrees, the planet's frame, and the collider and render state (added by
+ * those modules). `version` bumps whenever what a chunk contains changes (a graph edit, a new seed),
+ * which makes every generated chunk stale; stale chunks keep rendering until their replacement is
+ * ready, so an edit never shows a hole.
+ */
+export declare class PlanetRuntime {
+    readonly entity: Entity;
+    settings: PlanetSettings | undefined;
+    /** Component change tick last read. */
+    tick: number;
+    /** Bumps when chunk contents change. */
+    version: number;
+    /** What the quadtree's shape depends on (radius, shape, resolution, depth). */
+    private structureKey;
+    private contentKey;
+    height: NoiseGraph | undefined;
+    climate: NoiseGraph | undefined;
+    set: BiomeSetValue | undefined;
+    biomes: (BiomeValue | undefined)[];
+    table: BiomeTable;
+    /** Bumps when the biome table changes. */
+    biomeVersion: number;
+    private biomeKey;
+    /**
+     * Geometric error per depth (terrain), and for the flat ocean surface, as selection and morphing
+     * use them: measured, then capped by vertex spacing (`vertexPixels`).
+     */
+    errors: Float32Array;
+    oceanErrors: Float32Array;
+    /**
+     * Multiplies errorPixels for selection and morphing: above 1 while the planet is over
+     * TerrainBudget.triangles (adjusted about 1% a frame, so morphs stay smooth).
+     */
+    lodBias: number;
+    /** The measured errors, uncapped: how far skirts must hang. */
+    rawErrors: Float32Array;
+    rawOceanErrors: Float32Array;
+    maxDepth: number;
+    colliderDepth: number;
+    readonly tree: NodeTree;
+    readonly ocean: NodeTree;
+    readonly frame: PlanetFrame;
+    readonly selection: import("./quadtree.js").Selection;
+    readonly oceanSelection: import("./quadtree.js").Selection;
+    /** Why the planet can't generate, if it can't (bad settings). */
+    problem: ShardError | null;
+    /** What it's waiting for (a graph or biome loading), if anything. */
+    waiting: string | null;
+    /** Anchors this frame, in the planet frame. */
+    anchorPos: Float64Array<ArrayBuffer>;
+    anchorRadius: Float64Array<ArrayBuffer>;
+    anchorEntity: Entity[];
+    anchors: number;
+    /** Module state (colliders, render, nav) keyed by module. */
+    readonly parts: Map<string, unknown>;
+    constructor(entity: Entity);
+    /** Whether the planet has what it needs to generate chunks. */
+    get ready(): boolean;
+    /** Lowest the surface gets (m above radius): the horizon occluder and default bounds. */
+    get lowest(): number;
+    get highest(): number;
+    /**
+     * Brings the runtime up to date with the component and the assets it names. Cheap when nothing
+     * changed: compares a change tick and graph versions.
+     */
+    refresh(world: World, dirty: boolean): void;
+    private heightVersion;
+    private climateVersion;
+    private report;
+    /**
+     * Caps each depth's error at the spacing that projects to `vertexPixels` wherever it projects to
+     * `errorPixels`: a node then splits only while its children's vertices stay that far apart on
+     * screen. Rough terrain otherwise keeps splitting into sub-pixel triangles. Selection and
+     * morphing read the same capped table, so morph bands still end where splits happen.
+     */
+    private capErrors;
+    /** Vertex spacing at a depth (m). */
+    spacing(depth: number): number;
+}

package/dist/planet.js

@@ -0,0 +1,313 @@
+import { assetServer } from "@aethervtt/shard-assets";
+import { ShardError } from "@aethervtt/shard-core";
+import { NoiseGraphs } from "@aethervtt/shard-noise";
+import { LogResource } from "@aethervtt/shard-runtime";
+import {
+  Biome,
+  BiomeSet,
+  biomeTable
+} from "./biomes.js";
+import { checkResolution } from "./chunk.js";
+import { Planet } from "./components.js";
+import { MAX_RADIUS, maxDepthFor, nodeSpacing } from "./cube.js";
+import { PlanetFrame } from "./frame.js";
+import { measureErrors } from "./lod.js";
+import { createSelection, NODE_BOUNDS, NodeTree } from "./quadtree.js";
+const COLLIDER_SPACING = 1;
+class PlanetRuntime {
+  entity;
+  settings;
+  /** Component change tick last read. */
+  tick = -1;
+  /** Bumps when chunk contents change. */
+  version = 0;
+  /** What the quadtree's shape depends on (radius, shape, resolution, depth). */
+  structureKey = "";
+  contentKey = "";
+  height;
+  climate;
+  set;
+  biomes = [];
+  table = biomeTable(void 0, []);
+  /** Bumps when the biome table changes. */
+  biomeVersion = 0;
+  biomeKey = "";
+  /**
+   * Geometric error per depth (terrain), and for the flat ocean surface, as selection and morphing
+   * use them: measured, then capped by vertex spacing (`vertexPixels`).
+   */
+  errors = new Float32Array(2);
+  oceanErrors = new Float32Array(2);
+  /**
+   * Multiplies errorPixels for selection and morphing: above 1 while the planet is over
+   * TerrainBudget.triangles (adjusted about 1% a frame, so morphs stay smooth).
+   */
+  lodBias = 1;
+  /** The measured errors, uncapped: how far skirts must hang. */
+  rawErrors = new Float32Array(2);
+  rawOceanErrors = new Float32Array(2);
+  maxDepth = 0;
+  colliderDepth = 0;
+  tree = new NodeTree();
+  ocean = new NodeTree(256);
+  frame = new PlanetFrame();
+  selection = createSelection();
+  oceanSelection = createSelection();
+  /** Why the planet can't generate, if it can't (bad settings). */
+  problem = null;
+  /** What it's waiting for (a graph or biome loading), if anything. */
+  waiting = null;
+  /** Anchors this frame, in the planet frame. */
+  anchorPos = new Float64Array(0);
+  anchorRadius = new Float64Array(0);
+  anchorEntity = [];
+  anchors = 0;
+  /** Module state (colliders, render, nav) keyed by module. */
+  parts = /* @__PURE__ */ new Map();
+  constructor(entity) {
+    this.entity = entity;
+  }
+  /** Whether the planet has what it needs to generate chunks. */
+  get ready() {
+    return this.problem === null && this.waiting === null && this.settings !== void 0;
+  }
+  /** Lowest the surface gets (m above radius): the horizon occluder and default bounds. */
+  get lowest() {
+    const s = this.settings;
+    if (!s) return 0;
+    return this.height ? -s.heightScale : 0;
+  }
+  get highest() {
+    const s = this.settings;
+    if (!s) return 0;
+    return this.height ? s.heightScale : 0;
+  }
+  /**
+   * Brings the runtime up to date with the component and the assets it names. Cheap when nothing
+   * changed: compares a change tick and graph versions.
+   */
+  refresh(world, dirty) {
+    const table = world.entityTable(this.entity);
+    const tick = table.changedTicks(Planet)[world.entityRow(this.entity)];
+    if (tick !== this.tick || !this.settings) {
+      this.tick = tick;
+      this.settings = readSettings(world.get(this.entity, Planet));
+      dirty = true;
+    }
+    const s = this.settings;
+    if (!dirty && this.waiting === null) {
+      const h = this.height;
+      const c = this.climate;
+      if ((!h || h.version === this.heightVersion) && (!c || c.version === this.climateVersion))
+        return;
+    }
+    this.problem = null;
+    this.waiting = null;
+    try {
+      validate(s);
+    } catch (err) {
+      this.report(world, err);
+      return;
+    }
+    const height = resolve(world, s.height, (w) => w.initResource(NoiseGraphs));
+    const climate = resolve(world, s.climate, (w) => w.initResource(NoiseGraphs));
+    if (height === null || climate === null) {
+      this.waiting = height === null ? `height graph ${refName(s.height)}` : `climate graph ${refName(s.climate)}`;
+      return;
+    }
+    if (climate && (!climate.graph.nodes.has("temperature") || !climate.graph.nodes.has("moisture"))) {
+      this.report(
+        world,
+        new ShardError(
+          "terrain/climate-outputs",
+          `Climate graph ${refName(s.climate)} needs nodes named "temperature" and "moisture"`,
+          {
+            path: refName(s.climate),
+            hint: 'Name the two climate layers "temperature" and "moisture"; each should stay in [\u22121, 1].'
+          }
+        )
+      );
+      return;
+    }
+    const set = resolve(world, s.biomes, (w) => w.initResource(BiomeSet.store));
+    if (set === null) {
+      this.waiting = `biome set ${refName(s.biomes)}`;
+      return;
+    }
+    const biomes = [];
+    for (const ref of set?.biomes ?? []) {
+      const b = resolve(world, ref, (w) => w.initResource(Biome.store));
+      if (b === null) {
+        this.waiting = `biome ${refName(ref)}`;
+        return;
+      }
+      biomes.push(b);
+    }
+    try {
+      const biomeKey = JSON.stringify([set ?? null, biomes]);
+      if (biomeKey !== this.biomeKey) {
+        this.table = biomeTable(set, biomes);
+        this.biomeKey = biomeKey;
+        this.biomeVersion++;
+      }
+    } catch (err) {
+      this.report(world, err);
+      return;
+    }
+    this.set = set;
+    this.biomes = biomes;
+    this.height = height;
+    this.climate = climate;
+    this.heightVersion = height?.version ?? -1;
+    this.climateVersion = climate?.version ?? -1;
+    const maxDepth = maxDepthFor(s.radius, s.resolution, s.minSpacing);
+    const structureKey = JSON.stringify([s.radius, [...s.shape], s.resolution, maxDepth]);
+    const contentKey = JSON.stringify([
+      structureKey,
+      height?.hash ?? null,
+      climate?.hash ?? null,
+      s.heightScale,
+      s.seed,
+      s.ocean,
+      s.seaLevel
+    ]);
+    if (contentKey === this.contentKey) {
+      this.capErrors();
+      return;
+    }
+    this.maxDepth = maxDepth;
+    this.colliderDepth = Math.min(
+      maxDepth,
+      maxDepthFor(s.radius, s.resolution, Math.max(COLLIDER_SPACING, s.minSpacing))
+    );
+    this.rawErrors = measureErrors({
+      radius: s.radius,
+      shape: s.shape,
+      heightScale: s.heightScale,
+      seed: s.seed,
+      resolution: s.resolution,
+      maxDepth,
+      height
+    });
+    this.rawOceanErrors = measureErrors({
+      radius: s.radius,
+      shape: s.shape,
+      heightScale: 0,
+      seed: s.seed,
+      resolution: s.resolution,
+      maxDepth,
+      height: void 0,
+      heightOffset: s.seaLevel
+    });
+    this.capErrors(false);
+    if (structureKey !== this.structureKey) {
+      this.tree.reset(s.radius, s.shape, this.lowest, this.highest);
+      this.ocean.reset(s.radius, s.shape, s.seaLevel, s.seaLevel);
+      this.structureKey = structureKey;
+    } else {
+      this.tree.lowest = this.lowest;
+      this.tree.highest = this.highest;
+      this.ocean.lowest = s.seaLevel;
+      this.ocean.highest = s.seaLevel;
+      widen(this.tree);
+      widen(this.ocean);
+    }
+    this.contentKey = contentKey;
+    this.version++;
+  }
+  heightVersion = -1;
+  climateVersion = -1;
+  report(world, err) {
+    this.problem = err;
+    world.tryResource(LogResource)?.error(err);
+  }
+  /**
+   * Caps each depth's error at the spacing that projects to `vertexPixels` wherever it projects to
+   * `errorPixels`: a node then splits only while its children's vertices stay that far apart on
+   * screen. Rough terrain otherwise keeps splitting into sub-pixel triangles. Selection and
+   * morphing read the same capped table, so morph bands still end where splits happen.
+   */
+  capErrors(bump = true) {
+    const s = this.settings;
+    if (!s) return;
+    const k = s.vertexPixels > 0 ? s.errorPixels / s.vertexPixels : Number.POSITIVE_INFINITY;
+    const cap = (raw, out) => {
+      const o = out.length === raw.length ? out : new Float32Array(raw.length);
+      for (let d = 0; d < raw.length; d++) o[d] = Math.min(raw[d], k * this.spacing(d));
+      for (let d = raw.length - 2; d >= 0; d--) o[d] = Math.max(o[d], o[d + 1]);
+      return o;
+    };
+    const before = this.errors;
+    const same = (a, b) => a.length === b.length && a.every((v, i) => v === b[i]);
+    const errors = cap(this.rawErrors, new Float32Array(this.rawErrors.length));
+    const ocean = cap(this.rawOceanErrors, new Float32Array(this.rawOceanErrors.length));
+    if (same(errors, before) && same(ocean, this.oceanErrors)) return;
+    this.errors = errors;
+    this.oceanErrors = ocean;
+    if (bump) this.version++;
+  }
+  /** Vertex spacing at a depth (m). */
+  spacing(depth) {
+    return nodeSpacing(this.settings?.radius ?? 1, depth, this.settings?.resolution ?? 33);
+  }
+}
+function widen(tree) {
+  for (let n = 0; n < tree.count; n++) {
+    tree.flags[n] &= ~NODE_BOUNDS;
+    tree.minH[n] = tree.lowest;
+    tree.maxH[n] = tree.highest;
+    tree.updateSphere(n);
+  }
+}
+function readSettings(v) {
+  return {
+    radius: v.radius,
+    shape: Float64Array.from(v.shape),
+    heightScale: v.heightScale,
+    seed: v.seed >>> 0,
+    ocean: v.ocean,
+    seaLevel: v.seaLevel,
+    resolution: v.resolution,
+    minSpacing: v.minSpacing,
+    errorPixels: v.errorPixels,
+    vertexPixels: v.vertexPixels,
+    colliderRadius: v.colliderRadius,
+    skirts: v.skirts,
+    height: v.height,
+    climate: v.climate,
+    biomes: v.biomes
+  };
+}
+function validate(s) {
+  if (s.radius > MAX_RADIUS) {
+    throw new ShardError(
+      "terrain/radius-too-large",
+      `Planet radius ${s.radius} m is over ${MAX_RADIUS} m (50 000 km)`,
+      {
+        hint: "Rocky planets go up to about 16 000 km; gas giants have no surface (spec 0046 renders them)."
+      }
+    );
+  }
+  checkResolution(s.resolution);
+}
+function refName(ref) {
+  return ref?.path ?? ref?.guid ?? "(none)";
+}
+function resolve(world, ref, store) {
+  if (!ref || ref.guid === void 0 && ref.path === void 0) return void 0;
+  const value = ref.guid !== void 0 ? store(world).get(ref) : void 0;
+  if (value !== void 0) return value;
+  const server = assetServer(world);
+  const entry = server.entry(ref);
+  if (entry) {
+    if (entry.state !== "failed") void server.request(entry.guid).catch(() => {
+    });
+    const loaded = store(world).get({ guid: entry.guid });
+    if (loaded !== void 0) return loaded;
+  }
+  return null;
+}
+export {
+  COLLIDER_SPACING,
+  PlanetRuntime
+};

package/dist/plugin.d.ts

@@ -0,0 +1,23 @@
+import { type World } from '@aethervtt/shard-core';
+import type { Workers } from '@aethervtt/shard-platform';
+import { type Plugin } from '@aethervtt/shard-runtime';
+import { PlanetRuntime } from './planet.js';
+export interface TerrainPluginOptions {
+    /** Where collider chunks sample (default: inline on the main thread). */
+    workers?: Workers;
+}
+/**
+ * Keeps a runtime per Planet (spec 0043): resolves its graphs and biomes, measures per-depth
+ * errors, tracks its frame against the floating origin, gathers anchors, and builds the collider
+ * chunks around them. Runs with or without a GPU; the render side adds chunk selection on top.
+ */
+export declare const updatePlanets: import("@aethervtt/shard-core").SystemDef<{
+    planets: import("@aethervtt/shard-core").Query;
+    anchors: import("./colliders.js").AnchorQueries;
+}>;
+/** Everything the terrain needs without a GPU: runtimes, colliders, heights. */
+export declare function terrainPlugin(options?: TerrainPluginOptions): Plugin;
+/** Other packages hook into the plugin here (render, overlays, and nav are built in). */
+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)[];