@aethervtt/shard-terrain 0.0.1

package/dist/colliders.d.ts

@@ -0,0 +1,86 @@
+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 { 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. */
+export declare const COLLIDER_DELAY = 2;
+/** A cached collider chunk: its CPU mesh, the collider mesh, and its entity while wanted. */
+export interface ColliderChunk {
+    key: string;
+    face: number;
+    depth: number;
+    x: number;
+    y: number;
+    mesh: ChunkMesh;
+    /** Surface triangles (no skirts), sharing the mesh's positions. */
+    collider: Mesh;
+    colliderRef: {
+        guid: string | undefined;
+        path: string | undefined;
+        type: 'Mesh';
+    };
+    /** The collider entity, or −1 while not wanted. */
+    entity: Entity;
+    /** Planet version it was built for. */
+    version: number;
+    /** Frame it was last wanted. */
+    used: number;
+}
+interface ColliderJob {
+    key: string;
+    face: number;
+    depth: number;
+    x: number;
+    y: number;
+    /** Frame it becomes a chunk. */
+    due: number;
+    version: number;
+    pts: ChunkPoints | undefined;
+    values: Float32Array | undefined;
+    temps: Float32Array | undefined;
+    moist: Float32Array | undefined;
+    /** All pool results are in. */
+    ready: boolean;
+    cancelled: boolean;
+}
+/** A planet's collider chunks and the jobs making them. */
+export declare class ColliderSet {
+    readonly chunks: Map<string, ColliderChunk>;
+    readonly jobs: Map<string, ColliderJob>;
+    /** Keys wanted this frame, sorted. */
+    wanted: string[];
+    /** Chunks built on the main thread because the pool hadn't finished by the due frame. */
+    builtSync: number;
+    /** Chunks finished from pool results. */
+    builtPool: number;
+}
+export declare function collidersOf(planet: PlanetRuntime): ColliderSet;
+export interface AnchorQueries {
+    anchors: Query;
+    characters: Query;
+    bodies: Query;
+    agents: Query;
+}
+export declare function anchorQueries(world: World): AnchorQueries;
+/**
+ * Anchors near the planet this frame, in the planet frame: every TerrainAnchor (unless disabled),
+ * character, and awake dynamic body, with its reach.
+ */
+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[];
+/** How far skirts hang: past any morph mismatch between neighbors at this depth (true errors). */
+export declare function skirtDepth(planet: PlanetRuntime, depth: number): number;
+/**
+ * Keeps the planet's collider chunks around its anchors (spec 0043): a chunk is asked for when an
+ * anchor comes within reach and appears exactly COLLIDER_DELAY frames later, from pool results when
+ * they're in and built on the main thread when they aren't, so which frame it appears never depends
+ * on thread timing (the world hash is the same on every host). Unwanted chunks lose their entity
+ * but stay cached (least recently used first out).
+ */
+export declare function updateColliders(world: World, planet: PlanetRuntime, workers: Workers | undefined, frame: number, cacheSize: number): void;
+/** Drops every collider chunk (planet despawned). */
+export declare function clearColliders(world: World, planet: PlanetRuntime): void;
+export {};

package/dist/colliders.js

@@ -0,0 +1,356 @@
+import { ChildOf, Derived } from "@aethervtt/shard-core";
+import { Mesh } from "@aethervtt/shard-mesh";
+import { NavAgent, NavSource } from "@aethervtt/shard-nav";
+import { sampleNoiseAsync } from "@aethervtt/shard-noise";
+import { CharacterController, Collider, PhysicsParked, RigidBody } from "@aethervtt/shard-physics";
+import { Meshes } from "@aethervtt/shard-render";
+import {
+  GlobalTransform,
+  placeInGrid,
+  propagateSubtree,
+  Transform
+} from "@aethervtt/shard-transform";
+import { assembleChunk, buildChunk, chunkLayout } from "./chunk.js";
+import { Chunk, PlanetNav, TerrainAnchor } from "./components.js";
+import { faceToDirection, keyString, nodeAt, nodeExtent } from "./cube.js";
+import { createChunkPoints, prepareChunkPoints } from "./points.js";
+const COLLIDER_DELAY = 2;
+class ColliderSet {
+  chunks = /* @__PURE__ */ new Map();
+  jobs = /* @__PURE__ */ new Map();
+  /** Keys wanted this frame, sorted. */
+  wanted = [];
+  /** Chunks built on the main thread because the pool hadn't finished by the due frame. */
+  builtSync = 0;
+  /** Chunks finished from pool results. */
+  builtPool = 0;
+}
+function collidersOf(planet) {
+  let set = planet.parts.get("colliders");
+  if (!set) {
+    set = new ColliderSet();
+    planet.parts.set("colliders", set);
+  }
+  return set;
+}
+function anchorQueries(world) {
+  return {
+    anchors: world.query({ with: [TerrainAnchor, GlobalTransform] }),
+    characters: world.query({ with: [CharacterController, GlobalTransform] }),
+    bodies: world.query({ with: [RigidBody, GlobalTransform], without: [PhysicsParked] }),
+    agents: world.query({ with: [NavAgent, GlobalTransform] })
+  };
+}
+const seen = /* @__PURE__ */ new Set();
+const scratch = new Float64Array(3);
+function gatherAnchors(world, planet, q) {
+  const s = planet.settings;
+  seen.clear();
+  planet.anchors = 0;
+  planet.anchorEntity.length = 0;
+  const add = (entity, m, row, radius) => {
+    if (seen.has(entity)) return;
+    seen.add(entity);
+    planet.frame.pointToPlanet(m[row * 12 + 3], m[row * 12 + 7], m[row * 12 + 11], scratch);
+    const d = Math.sqrt(scratch[0] ** 2 + scratch[1] ** 2 + scratch[2] ** 2);
+    const top = s.radius * Math.max(s.shape[0], s.shape[1], s.shape[2]) + planet.highest;
+    if (d - top > radius) return;
+    const i = planet.anchors++;
+    if (planet.anchorPos.length < planet.anchors * 3) {
+      const pos = new Float64Array(planet.anchors * 6);
+      pos.set(planet.anchorPos);
+      planet.anchorPos = pos;
+      const r = new Float64Array(planet.anchors * 2);
+      r.set(planet.anchorRadius);
+      planet.anchorRadius = r;
+    }
+    planet.anchorPos[i * 3] = scratch[0];
+    planet.anchorPos[i * 3 + 1] = scratch[1];
+    planet.anchorPos[i * 3 + 2] = scratch[2];
+    planet.anchorRadius[i] = radius;
+    planet.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);
+    }
+  }
+  if (world.has(planet.entity, PlanetNav)) {
+    const reach = Math.max(s.colliderRadius, world.get(planet.entity, PlanetNav).radius);
+    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, reach);
+    }
+  }
+  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 node = new Float64Array(3);
+const dir = new Float64Array(3);
+const wantedKeys = /* @__PURE__ */ new Set();
+function wantedColliders(planet) {
+  wantedKeys.clear();
+  const s = planet.settings;
+  const depth = planet.colliderDepth;
+  const n = 2 ** depth;
+  const ext = nodeExtent(depth);
+  const size = planet.spacing(depth) * (s.resolution - 1);
+  for (let i = 0; i < planet.anchors; i++) {
+    const ax = planet.anchorPos[i * 3];
+    const ay = planet.anchorPos[i * 3 + 1];
+    const az = planet.anchorPos[i * 3 + 2];
+    const r = planet.anchorRadius[i];
+    const len = Math.sqrt(ax * ax + ay * ay + az * az);
+    if (len === 0) continue;
+    nodeAt(ax / len, ay / len, az / len, depth, node);
+    const face = node[0];
+    const cx = node[1];
+    const cy = node[2];
+    const k = Math.ceil(r / size) + 1;
+    for (let dj = -k; dj <= k; dj++) {
+      for (let di = -k; di <= k; di++) {
+        let f = face;
+        let x = cx + di;
+        let y = cy + dj;
+        if (x < 0 || y < 0 || x >= n || y >= n) {
+          faceToDirection(face, -1 + (x + 0.5) * ext, -1 + (y + 0.5) * ext, dir);
+          nodeAt(dir[0], dir[1], dir[2], depth, node);
+          f = node[0];
+          x = node[1];
+          y = node[2];
+        }
+        faceToDirection(f, -1 + (x + 0.5) * ext, -1 + (y + 0.5) * ext, dir);
+        const px = dir[0] * len * s.shape[0] - ax;
+        const py = dir[1] * len * s.shape[1] - ay;
+        const pz = dir[2] * len * s.shape[2] - az;
+        if (Math.sqrt(px * px + py * py + pz * pz) - size * 0.75 > r) continue;
+        wantedKeys.add(keyString(f, depth, x, y));
+      }
+    }
+  }
+  return [...wantedKeys].sort();
+}
+function specFor(planet, face, depth, x, y) {
+  const s = planet.settings;
+  return {
+    face,
+    depth,
+    x,
+    y,
+    radius: s.radius,
+    shape: s.shape,
+    heightScale: s.heightScale,
+    seed: s.seed,
+    resolution: s.resolution,
+    height: planet.height,
+    climate: planet.climate,
+    morphError: planet.errors[depth] ?? 0,
+    skirtDepth: skirtDepth(planet, depth)
+  };
+}
+function skirtDepth(planet, depth) {
+  return 2 * (planet.rawErrors[Math.max(0, depth - 1)] ?? 0) + planet.spacing(depth);
+}
+function updateColliders(world, planet, workers, frame, cacheSize) {
+  const set = collidersOf(planet);
+  if (!planet.ready) return;
+  const wanted = wantedColliders(planet);
+  set.wanted = wanted;
+  const keep = new Set(wanted);
+  for (const key of wanted) {
+    const chunk = set.chunks.get(key);
+    if (chunk && chunk.version === planet.version) {
+      chunk.used = frame;
+      if (chunk.entity < 0) spawnCollider(world, planet, chunk);
+      continue;
+    }
+    let job = set.jobs.get(key);
+    if (job && job.version !== planet.version) {
+      job.cancelled = true;
+      set.jobs.delete(key);
+      job = void 0;
+    }
+    if (!job) {
+      const [face, depth, x, y] = key.split("/").map(Number);
+      job = startJob(planet, workers, key, face, depth, x, y, frame + COLLIDER_DELAY);
+      set.jobs.set(key, job);
+    }
+    if (frame < job.due) continue;
+    set.jobs.delete(key);
+    const spec = specFor(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);
+      set.builtPool++;
+    } else {
+      job.cancelled = true;
+      mesh = buildChunk(spec);
+      set.builtSync++;
+    }
+    const next = makeChunk(world, key, job, mesh, planet.version, frame);
+    if (chunk) replaceChunk(world, chunk);
+    set.chunks.set(key, next);
+    spawnCollider(world, planet, next);
+  }
+  for (const [key, job] of set.jobs) {
+    if (!keep.has(key)) {
+      job.cancelled = true;
+      set.jobs.delete(key);
+    }
+  }
+  for (const chunk of set.chunks.values()) {
+    if (!keep.has(chunk.key) && chunk.entity >= 0) despawnCollider(world, chunk);
+  }
+  if (set.chunks.size > cacheSize) {
+    const idle = [...set.chunks.values()].filter((c) => c.entity < 0).sort((a, b) => a.used - b.used || (a.key < b.key ? -1 : 1));
+    for (let i = 0; i < idle.length && set.chunks.size > cacheSize; i++) {
+      dropChunk(world, idle[i]);
+      set.chunks.delete(idle[i].key);
+    }
+  }
+}
+function startJob(planet, workers, key, face, depth, x, y, due) {
+  const job = {
+    key,
+    face,
+    depth,
+    x,
+    y,
+    due,
+    version: planet.version,
+    pts: void 0,
+    values: void 0,
+    temps: void 0,
+    moist: void 0,
+    ready: false,
+    cancelled: false
+  };
+  if (!workers || workers.size === 0) return job;
+  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 parts = [];
+  const origin = new Float64Array(4);
+  for (let g = 0; g < pts.groups; g++) {
+    const a = pts.start[g];
+    const b = pts.start[g + 1];
+    const local = new Float32Array((b - a) * 3);
+    for (let i = a; i < b; i++) {
+      const k = pts.order[i];
+      local[(i - a) * 3] = pts.local[k * 3];
+      local[(i - a) * 3 + 1] = pts.local[k * 3 + 1];
+      local[(i - a) * 3 + 2] = pts.local[k * 3 + 2];
+    }
+    origin[0] = pts.origins[g * 4];
+    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);
+      parts.push(
+        sampleNoiseAsync(workers, graph, s.seed, local, out, {
+          origin: o,
+          ...node2 ? { node: node2 } : {}
+        }).then(() => scatter(target)(out))
+      );
+    };
+    run(planet.height, job.values);
+    run(planet.climate, job.temps, "temperature");
+    run(planet.climate, job.moist, "moisture");
+  }
+  Promise.all(parts).then(
+    () => {
+      if (!job.cancelled) job.ready = true;
+    },
+    () => {
+    }
+  );
+  return job;
+}
+function makeChunk(world, key, job, mesh, version, frame) {
+  const layout = chunkLayout(Math.round(Math.sqrt(mesh.heights.length)));
+  const collider = Mesh.create({ positions: mesh.data.positions, indices: layout.surfaceIndices });
+  const colliderRef = world.initResource(Meshes).add(collider, `terrain/collider/${key}`);
+  return {
+    key,
+    face: job.face,
+    depth: job.depth,
+    x: job.x,
+    y: job.y,
+    mesh,
+    collider,
+    colliderRef,
+    entity: -1,
+    version,
+    used: frame
+  };
+}
+function spawnCollider(world, planet, chunk) {
+  const e = world.spawn(
+    [RigidBody, { kind: "fixed" }],
+    [Collider, { shape: "trimesh", mesh: chunk.colliderRef }],
+    [Chunk, { planet: planet.entity, key: chunk.key, kind: "collider" }],
+    [ChildOf, { parent: planet.entity }],
+    Transform,
+    Derived
+  );
+  if (world.has(planet.entity, PlanetNav)) world.add(e, NavSource);
+  placeInGrid(world, e, planet.entity, chunk.mesh.center);
+  propagateSubtree(world, e);
+  chunk.entity = e;
+}
+function despawnCollider(world, chunk) {
+  if (world.isAlive(chunk.entity)) world.despawn(chunk.entity);
+  chunk.entity = -1;
+}
+function replaceChunk(world, chunk) {
+  despawnCollider(world, chunk);
+  dropChunk(world, chunk);
+}
+function dropChunk(world, chunk) {
+  if (chunk.colliderRef.guid) world.initResource(Meshes).delete(chunk.colliderRef.guid);
+}
+function clearColliders(world, planet) {
+  const set = collidersOf(planet);
+  for (const chunk of set.chunks.values()) replaceChunk(world, chunk);
+  for (const job of set.jobs.values()) job.cancelled = true;
+  set.chunks.clear();
+  set.jobs.clear();
+}
+export {
+  COLLIDER_DELAY,
+  ColliderSet,
+  anchorQueries,
+  clearColliders,
+  collidersOf,
+  gatherAnchors,
+  skirtDepth,
+  updateColliders,
+  wantedColliders
+};

package/dist/components.d.ts

@@ -0,0 +1,49 @@
+export declare const Planet: import("@aethervtt/shard-core").ComponentDef<{
+    readonly radius: import("@aethervtt/shard-core").FieldType<number, "f64">;
+    readonly shape: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Vec3, "f32">;
+    readonly height: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").AssetRef<"NoiseGraph"> | null, "object">;
+    readonly heightScale: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly seed: import("@aethervtt/shard-core").FieldType<number, "u32">;
+    readonly ocean: import("@aethervtt/shard-core").FieldType<boolean, "u8">;
+    readonly seaLevel: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly climate: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").AssetRef<"NoiseGraph"> | null, "object">;
+    readonly biomes: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").AssetRef<"terrain/BiomeSet"> | null, "object">;
+    readonly resolution: import("@aethervtt/shard-core").FieldType<number, "u16">;
+    readonly minSpacing: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly errorPixels: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    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">;
+}>;
+export declare const TerrainAnchor: import("@aethervtt/shard-core").ComponentDef<{
+    readonly enabled: import("@aethervtt/shard-core").FieldType<boolean, "u8">;
+    readonly radius: import("@aethervtt/shard-core").FieldType<number, "f32">;
+}>;
+export declare const PlanetNav: import("@aethervtt/shard-core").ComponentDef<{
+    readonly agentRadius: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly agentHeight: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly maxSlope: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly radius: import("@aethervtt/shard-core").FieldType<number, "f32">;
+}>;
+export declare const Chunk: import("@aethervtt/shard-core").ComponentDef<{
+    readonly planet: import("@aethervtt/shard-core").FieldType<number | null, "f64">;
+    readonly key: import("@aethervtt/shard-core").FieldType<string, "object">;
+    readonly kind: import("@aethervtt/shard-core").FieldType<"collider" | "ocean" | "render", "u8">;
+}>;
+export interface TerrainBudgetValue {
+    /** Chunks generated per frame, at most. */
+    chunksPerFrame: number;
+    /**
+     * Terrain triangles on screen per planet, at most (0: no limit). Past it the planet's detail
+     * coarsens a little each frame (a bias on errorPixels) until it fits, and refines back when
+     * there's room: frame time holds at any resolution and on any GPU.
+     */
+    triangles: number;
+    /** GPU milliseconds per frame for generation (timestamp queries where available). */
+    msPerFrame: number;
+    /** Render chunk slots per planet (meshes kept, evicted least recently used). */
+    pool: number;
+    /** Collider chunks cached per planet. */
+    colliderCache: number;
+}
+export declare const TerrainBudget: import("@aethervtt/shard-core").ResourceDef<TerrainBudgetValue>;

package/dist/components.js

@@ -0,0 +1,137 @@
+import { defineComponent, defineResource, t } from "@aethervtt/shard-core";
+import { Visibility } from "@aethervtt/shard-render";
+import { Grid, Transform } from "@aethervtt/shard-transform";
+const Planet = defineComponent(
+  "terrain/Planet",
+  {
+    radius: t.f64({
+      default: 4e3,
+      min: 1,
+      unit: "m",
+      description: "Surface radius before heights, 1 km to 50 000 km (Earth is 6 371 000)."
+    }),
+    shape: t.vec3({
+      default: [1, 1, 1],
+      min: 0.01,
+      description: "Ellipsoid axis ratios: [1, 1, 1] is a sphere, [1, 0.7, 1.2] a lumpy moon."
+    }),
+    height: t.handle("NoiseGraph", {
+      description: "Height graph (*.noise.json), output in [\u22121, 1], sampled on the sphere of `radius`. None: a smooth sphere."
+    }),
+    heightScale: t.f32({
+      default: 600,
+      min: 0,
+      unit: "m",
+      description: "Metres per unit of the height graph."
+    }),
+    seed: t.u32({ description: "Mixed into every graph: the same graphs make a new planet." }),
+    ocean: t.bool({ default: true, description: "A sea surface at seaLevel." }),
+    seaLevel: t.f32({ unit: "m", description: "Sea surface height above radius." }),
+    climate: t.handle("NoiseGraph", {
+      description: "Climate graph with nodes named `temperature` and `moisture` (each in [\u22121, 1]). None: both 0."
+    }),
+    biomes: t.handle("terrain/BiomeSet", {
+      description: "Biomes (*.biomes.json): what the surface looks like where."
+    }),
+    resolution: t.u16({
+      default: 33,
+      min: 5,
+      max: 129,
+      description: "Vertices per chunk edge, 2^n + 1."
+    }),
+    minSpacing: t.f32({
+      default: 0.4,
+      min: 0.01,
+      unit: "m",
+      description: "Finest vertex spacing: sets the deepest quadtree level."
+    }),
+    errorPixels: t.f32({
+      default: 2,
+      min: 0.1,
+      description: "A chunk splits when its geometric error covers more pixels than this."
+    }),
+    vertexPixels: t.f32({
+      default: 4,
+      min: 0,
+      description: "Finest on-screen vertex spacing: however rough the terrain, chunks stop splitting once their vertices are this many pixels apart (smaller triangles cost GPU time and show nothing; normal tiles keep the finer relief in the shading). Vertices then morph a few px per frame in fast descents instead of under one. 0: no limit."
+    }),
+    colliderRadius: t.f32({
+      default: 96,
+      min: 0,
+      unit: "m",
+      description: "Collider chunks (and full-detail rendering) within this distance of every TerrainAnchor, character, and dynamic body."
+    }),
+    skirts: t.bool({
+      default: true,
+      description: "Walls under chunk edges that hide cracks while neighbors change level."
+    })
+  },
+  {
+    description: "A planet you can see from orbit and walk on: a cube-sphere quadtree of chunks generated from noise graphs, with biomes, an ocean, colliders near bodies, and navmesh tiles near agents. Needs a Grid (its chunks are grid children); hiding it hides its chunks.",
+    requires: [Grid, Transform, Visibility]
+  }
+);
+const TerrainAnchor = defineComponent(
+  "terrain/TerrainAnchor",
+  {
+    enabled: t.bool({
+      default: true,
+      description: "False: this body gets no terrain colliders (a ship in orbit, a projectile)."
+    }),
+    radius: t.f32({
+      min: 0,
+      unit: "m",
+      description: "Collider chunks within this distance (0: the planet\u2019s colliderRadius)."
+    })
+  },
+  {
+    description: "Terrain colliders around this entity. Characters and dynamic bodies are anchors without it; add it with enabled: false to opt one out."
+  }
+);
+const PlanetNav = defineComponent(
+  "terrain/PlanetNav",
+  {
+    agentRadius: t.f32({ default: 0.4, min: 0, unit: "m" }),
+    agentHeight: t.f32({ default: 1.8, min: 0.01, unit: "m" }),
+    maxSlope: t.f32({ default: 45, min: 0, max: 89.9, unit: "deg" }),
+    radius: t.f32({
+      default: 150,
+      min: 1,
+      unit: "m",
+      description: "Navmesh around every NavAgent on the planet, this far out."
+    })
+  },
+  {
+    description: "Navigation on a planet: a NavMesh baked from collider chunks near NavAgents, in a tangent frame (up is radial) that follows them.",
+    requires: [Planet]
+  }
+);
+const Chunk = defineComponent(
+  "terrain/Chunk",
+  {
+    planet: t.entity({ readonly: true }),
+    key: t.string({ readonly: true, description: "face/depth/x/y" }),
+    kind: t.enum(["render", "ocean", "collider"], { readonly: true })
+  },
+  {
+    description: "A terrain chunk the planet spawned. Rebuilt from the planet; never saved.",
+    serialize: false
+  }
+);
+const TerrainBudget = defineResource("terrain/Budget", {
+  description: "How much terrain work a frame may do: chunk generations, GPU milliseconds, and how many chunks stay cached.",
+  init: () => ({
+    chunksPerFrame: 8,
+    triangles: 2e6,
+    msPerFrame: 1.5,
+    pool: 2048,
+    colliderCache: 256
+  })
+});
+export {
+  Chunk,
+  Planet,
+  PlanetNav,
+  TerrainAnchor,
+  TerrainBudget
+};

package/dist/cube.d.ts

@@ -0,0 +1,51 @@
+import { directionToFace, faceToDirection } from '@aethervtt/shard-noise';
+export { directionToFace, faceToDirection };
+/** Deepest quadtree level: node keys hold 24 bits per axis. */
+export declare const MAX_DEPTH = 24;
+/** Largest planet radius (m): 0.4 m spacing at depth 24 reaches about this far. */
+export declare const MAX_RADIUS = 50000000;
+/** Edges of a node, counter-clockwise seen from outside: bottom (−v), right (+u), top (+v), left (−u). */
+export declare const EDGE_BOTTOM = 0;
+export declare const EDGE_RIGHT = 1;
+export declare const EDGE_TOP = 2;
+export declare const EDGE_LEFT = 3;
+/** Face-coordinate side of a node at `depth`: a face spans [-1, 1], so 2 / 2^depth. */
+export declare function nodeExtent(depth: number): number;
+/** Metres between vertices at `depth` (along a face's middle): a face edge is a quarter circle. */
+export declare function nodeSpacing(radius: number, depth: number, resolution: number): number;
+/** The first depth whose vertex spacing is at most `minSpacing`, capped at `MAX_DEPTH`. */
+export declare function maxDepthFor(radius: number, resolution: number, minSpacing: number): number;
+/**
+ * Packs a node as two u32s: `face << 29 | depth << 24 | x` and `y` (3 + 5 + 24 + 24 bits). Stable
+ * across runs and machines, so caches and saves can key by it.
+ */
+export declare function packKey(face: number, depth: number, x: number, y: number, out: Uint32Array, offset?: number): Uint32Array;
+export interface NodeAddress {
+    face: number;
+    depth: number;
+    x: number;
+    y: number;
+}
+export declare function unpackKey(k0: number, k1: number): NodeAddress;
+/** A node as text, `face/depth/x/y` (cache keys, describe output). */
+export declare function keyString(face: number, depth: number, x: number, y: number): string;
+export declare function parseKey(key: string): NodeAddress | undefined;
+/**
+ * The node at `depth` containing a unit direction: its face and cell, written into `out` as
+ * [face, x, y].
+ */
+export declare function nodeAt(x: number, y: number, z: number, depth: number, out: {
+    [i: number]: number;
+}): {
+    [i: number]: number;
+};
+/**
+ * The same-depth neighbor across one edge, written into `out` as [face, x, y]. Across a cube edge
+ * it's on another face, found through the direction just past the edge's middle (the grids of two
+ * faces meet edge to edge at every depth).
+ */
+export declare function neighborNode(face: number, depth: number, x: number, y: number, edge: number, out: {
+    [i: number]: number;
+}): {
+    [i: number]: number;
+};