@aethervtt/shard-terrain 0.0.1

package/dist/material.js

@@ -0,0 +1,426 @@
+import { t } from "@aethervtt/shard-core";
+import { defineMaterial } from "@aethervtt/shard-render";
+const TEXTURE_PERIOD = 1024;
+const frame = {
+  center: t.vec4({
+    hidden: true,
+    description: "Set by the terrain every frame: the planet center (origin frame) and radius."
+  }),
+  rot0: t.vec4({
+    hidden: true,
+    description: "Set by the terrain: origin \u2192 planet rotation rows (xyz), planet-space texture origin (w)."
+  }),
+  rot1: t.vec4({ hidden: true }),
+  rot2: t.vec4({ hidden: true }),
+  camera: t.vec4({
+    hidden: true,
+    description: "Set by the terrain: the selecting camera (xyz) and pixels per radian / errorPixels (w)."
+  }),
+  tiles: t.vec4({
+    hidden: true,
+    description: "Set by the terrain: vertices per chunk edge, normal-tile edge (0: no tiles), tiles per layer row, layer size."
+  })
+};
+const PlanetMaterial = defineMaterial("terrain/PlanetSurface", {
+  shader: "terrain::planet",
+  arrays: ["albedoArray", "normalArray", "ormArray", "normalTiles"],
+  // Its surface is its own (no standard_input): room for the normal tiles in 16 textures a stage.
+  standardTextures: false,
+  fields: {
+    albedoArray: t.handle("Texture", { description: "The BiomeSet\u2019s albedo array." }),
+    normalArray: t.handle("Texture", { description: "The BiomeSet\u2019s normal map array." }),
+    ormArray: t.handle("Texture", {
+      description: "The BiomeSet\u2019s occlusion/roughness/metallic array."
+    }),
+    normalTiles: t.handle("Texture", {
+      hidden: true,
+      description: "Set by the terrain: every chunk\u2019s normals at twice its vertex density, one tile per slot."
+    }),
+    biomeTable: t.handle("Texture", {
+      hidden: true,
+      description: "Set by the terrain: biome ranges, tints, and layers as a small float texture."
+    }),
+    ...frame,
+    biomeParams: t.vec4({
+      hidden: true,
+      description: "Set by the terrain: biome count, latitude bias, snow line, texture period."
+    }),
+    debugParams: t.vec4({
+      hidden: true,
+      description: "Set by the terrain: debug mode (0 off, 1 dominant biome, 2 seams, 3 levels), far-texturing distance, has ORM, 0."
+    })
+  },
+  description: "Planet terrain: biome blending and triplanar texture-array layers, with geomorphing between LOD levels."
+});
+const OceanMaterial = defineMaterial("terrain/Ocean", {
+  shader: "terrain::ocean",
+  blend: "alpha",
+  fields: {
+    ...frame,
+    shallow: t.color({ default: [0.05, 0.35, 0.4, 1], description: "Color over shallow ground." }),
+    deep: t.color({ default: [5e-3, 0.03, 0.08, 1], description: "Color over deep water." }),
+    water: t.vec4({
+      default: [0.08, 0.25, 0.35, 0.04],
+      description: "x: color depth falloff (1/m), y: opacity falloff (1/m), z: minimum opacity, w: roughness."
+    })
+  },
+  description: "Planet ocean: a lit transparent surface with scrolling wave normals."
+});
+const MORPH = (u) => `
+/**
+ * How far toward its parent level a vertex has morphed: by distance within the parent's split
+ * band; overridden on ring edges by the instance's lock bits (render/InstanceData.y, two bits per
+ * edge: 1 this level, 2 the parent's), and on center lines where a partial draw (quadrant mask in
+ * InstanceData.x) meets a child's quadrant (this level, which the child's edge matches). Never less
+ * than the chunk's fade (the rest of InstanceData.x), 1 as it replaces its parent, easing to 0.
+ */
+/** The grid point (i, j) and normal tile of a vertex, from uv1.x (kernel.ts packGrid). */
+fn terrain_grid() -> vec3u {
+  let n = u32(${u}.tiles.x + 0.5);
+  let p = u32(vertex_uv1().x + 0.5);
+  let ij = p % (n * n);
+  return vec3u(ij % n, ij / n, p / (n * n));
+}
+
+/**
+ * A grid point's lock code (chunk.ts lockCode): its edge on the border ring (0 bottom, 1 right,
+ * 2 top, 3 left, each edge owning its first corner), the center lines (4-7), the center (8), else -1.
+ */
+fn terrain_lock(i: u32, j: u32) -> i32 {
+  let s = u32(${u}.tiles.x + 0.5) - 1u;
+  let h = s / 2u;
+  if (j == 0u && i < s) { return 0; }
+  if (i == s && j < s) { return 1; }
+  if (j == s && i > 0u) { return 2; }
+  if (i == 0u && j > 0u) { return 3; }
+  if (i == h && j == h) { return 8; }
+  if (i == h) { return select(5, 4, j < h); }
+  if (j == h) { return select(7, 6, i < h); }
+  return -1;
+}
+
+fn terrain_morph(position: vec3f) -> f32 {
+  let lock = vertex_uv1();
+  let grid = terrain_grid();
+  let data = vertex_instance_data();
+  let mask = u32(floor(data.x * 0.5 + 0.001));
+  let fade = clamp(data.x - f32(mask) * 2.0, 0.0, 1.0);
+  var t = 0.0;
+  let split = lock.y * ${u}.camera.w;
+  if (split > 0.0) {
+    let d = distance(vertex_world(position), ${u}.camera.xyz);
+    t = clamp((d - 0.5 * split) / (0.45 * split), 0.0, 1.0);
+  }
+  let code = terrain_lock(grid.x, grid.y);
+  if (code >= 0 && code < 4) {
+    // Edges never fade: the neighbor across may not be fading.
+    let bits = (u32(data.y + 0.5) >> (u32(code) * 2u)) & 3u;
+    if (bits == 1u) { return 0.0; } else if (bits == 2u) { return 1.0; }
+    return t;
+  } else if (code >= 4 && mask != 15u) {
+    // Quadrants on either side of this center-line half (all four at the center).
+    var a = 0u;
+    var b = 1u;
+    if (code == 5) { a = 2u; b = 3u; } else if (code == 6) { a = 0u; b = 2u; } else if (code == 7) { a = 1u; b = 3u; }
+    let differ = ((mask >> a) & 1u) != ((mask >> b) & 1u);
+    if (differ || (code == 8 && mask != 0u)) { return 0.0; }
+  }
+  return max(t, fade);
+}
+
+override fn vertex_position(position: vec3f, normal: vec3f, uv: vec2f) -> vec3f {
+  return position + vertex_tangent().xyz * terrain_morph(position);
+}
+
+/** To the surface stage: the grid point as uv across the chunk (xy), its normal tile (z), tiles on (w). */
+override fn vertex_extra(position: vec3f, normal: vec3f, uv: vec2f) -> vec4f {
+  let grid = terrain_grid();
+  let s = ${u}.tiles.x - 1.0;
+  return vec4f(f32(grid.x) / s, f32(grid.y) / s, f32(grid.z), select(0.0, 1.0, ${u}.tiles.y > 0.0));
+}
+`;
+const TERRAIN_SHADERS = {
+  "terrain::planet": `
+import shard::pbr::types::{ VertexOutput, PbrInput };
+import shard::view::view;
+import shard::mesh::{ vertex_uv1, vertex_tangent, vertex_world, vertex_instance_data };
+import material::planet_surface::{ PlanetSurface, PlanetSurface_albedoArray, PlanetSurface_albedoArray_sampler, PlanetSurface_normalArray, PlanetSurface_normalArray_sampler, PlanetSurface_ormArray, PlanetSurface_ormArray_sampler, PlanetSurface_biomeTable, PlanetSurface_normalTiles, PlanetSurface_normalTiles_sampler };
+${MORPH("PlanetSurface")}
+fn biome_window(x: f32, lo: f32, hi: f32, blend: f32) -> f32 {
+  if (!(lo < hi)) { return 1.0; }
+  let soft = max(1e-6, blend * (hi - lo));
+  return smoothstep(lo - soft, lo + soft, x) * (1.0 - smoothstep(hi - soft, hi + soft, x));
+}
+
+fn table(texel: i32, biome: u32) -> vec4f {
+  return textureLoad(PlanetSurface_biomeTable, vec2i(texel, i32(biome)), 0);
+}
+
+struct Layered {
+  albedo: vec3f,
+  normal: vec3f,
+  orm: vec3f,
+}
+
+/** Screen derivatives of the planet-space position (taken in uniform control flow). */
+struct Grads {
+  dx: vec3f,
+  dy: vec3f,
+}
+
+fn albedo_at(uv: vec2f, l: i32, gx: vec2f, gy: vec2f) -> vec3f {
+  return textureSampleGrad(PlanetSurface_albedoArray, PlanetSurface_albedoArray_sampler, uv, l, gx, gy).rgb;
+}
+
+fn orm_at(uv: vec2f, l: i32, gx: vec2f, gy: vec2f) -> vec3f {
+  return textureSampleGrad(PlanetSurface_ormArray, PlanetSurface_ormArray_sampler, uv, l, gx, gy).rgb;
+}
+
+fn normal_at(uv: vec2f, l: i32, gx: vec2f, gy: vec2f) -> vec3f {
+  return textureSampleGrad(PlanetSurface_normalArray, PlanetSurface_normalArray_sampler, uv, l, gx, gy).xyz * 2.0 - 1.0;
+}
+
+/** One array layer, triplanar in planet space (or top-down only, far away). */
+fn sample_layer(layer: f32, scale: f32, q: vec3f, g: Grads, n: vec3f, bw: vec3f, near: bool) -> Layered {
+  var out: Layered;
+  let l = i32(layer + 0.5);
+  if (!near) {
+    // One projection, along the dominant axis, at a coarser scale: no shimmer from orbit.
+    let s = 1.0 / (scale * 8.0);
+    var uv = q.xz * s;
+    var gx = g.dx.xz * s;
+    var gy = g.dy.xz * s;
+    if (bw.x >= bw.y && bw.x >= bw.z) {
+      uv = q.zy * s;
+      gx = g.dx.zy * s;
+      gy = g.dy.zy * s;
+    } else if (bw.z >= bw.y) {
+      uv = q.xy * s;
+      gx = g.dx.xy * s;
+      gy = g.dy.xy * s;
+    }
+    out.albedo = albedo_at(uv, l, gx, gy);
+    out.orm = orm_at(uv, l, gx, gy);
+    out.normal = n;
+    return out;
+  }
+  let s = 1.0 / scale;
+  let ux = q.zy * s;
+  let uy = q.xz * s;
+  let uz = q.xy * s;
+  let xx = g.dx.zy * s;
+  let xy = g.dy.zy * s;
+  let yx = g.dx.xz * s;
+  let yy = g.dy.xz * s;
+  let zx = g.dx.xy * s;
+  let zy = g.dy.xy * s;
+  out.albedo = albedo_at(ux, l, xx, xy) * bw.x + albedo_at(uy, l, yx, yy) * bw.y + albedo_at(uz, l, zx, zy) * bw.z;
+  out.orm = orm_at(ux, l, xx, xy) * bw.x + orm_at(uy, l, yx, yy) * bw.y + orm_at(uz, l, zx, zy) * bw.z;
+  // Whiteout-blended tangent normals (Golus), in planet space.
+  var tx = normal_at(ux, l, xx, xy);
+  var ty = normal_at(uy, l, yx, yy);
+  var tz = normal_at(uz, l, zx, zy);
+  tx = vec3f(tx.xy + n.zy, abs(tx.z) * n.x);
+  ty = vec3f(ty.xy + n.xz, abs(ty.z) * n.y);
+  tz = vec3f(tz.xy + n.xy, abs(tz.z) * n.z);
+  out.normal = normalize(tx.zyx * bw.x + ty.xzy * bw.y + tz.xyz * bw.z);
+  return out;
+}
+
+/**
+ * The surface normal from the chunk's normal tile (twice the vertex density, so relief finer than
+ * the geometry still shades), or the vertex normal without tiles.
+ */
+fn surface_normal(in: VertexOutput) -> vec3f {
+  if (in.extra.w < 0.5) { return normalize(in.world_normal); }
+  let t = PlanetSurface.tiles;
+  let per_row = u32(t.z + 0.5);
+  let tile = u32(round(in.extra.z));
+  let cell = tile % (per_row * per_row);
+  let layer = i32(tile / (per_row * per_row));
+  let corner = vec2f(f32(cell % per_row), f32(cell / per_row)) * t.y;
+  let texel = corner + 0.5 + clamp(in.extra.xy, vec2f(0.0), vec2f(1.0)) * (t.y - 1.0);
+  let c = textureSampleLevel(PlanetSurface_normalTiles, PlanetSurface_normalTiles_sampler, texel / t.w, layer, 0.0).xyz;
+  let np = normalize(c * 2.0 - 1.0);
+  // Planet space to world: the rotation rows transposed.
+  return normalize(PlanetSurface.rot0.xyz * np.x + PlanetSurface.rot1.xyz * np.y + PlanetSurface.rot2.xyz * np.z);
+}
+
+override fn pbr_input(in: VertexOutput) -> PbrInput {
+  // Everything below sets the surface; the standard texture slots aren't bound (standardTextures: false).
+  var p: PbrInput;
+  p.base_color = vec3f(1.0);
+  p.alpha = 1.0;
+  p.normal = normalize(in.world_normal);
+  p.metallic = 0.0;
+  p.roughness = 0.9;
+  p.emissive = vec3f(0.0);
+  p.occlusion = 1.0;
+  let up = normalize(in.world_position - PlanetSurface.center.xyz);
+  let n = surface_normal(in);
+  let slope = degrees(acos(clamp(dot(n, up), -1.0, 1.0)));
+  let latitude = dot(up, PlanetSurface.rot1.xyz);
+  let height = in.world_tangent.w;
+  let count = u32(PlanetSurface.biomeParams.x);
+  let snow = select(0.0, max(height, 0.0) / PlanetSurface.biomeParams.z, PlanetSurface.biomeParams.z > 0.0);
+  let temperature = in.uv.x - PlanetSurface.biomeParams.y * abs(latitude) - snow;
+  var best_w = vec4f(0.0);
+  var best_i = vec4u(0u);
+  var sum = 0.0;
+  for (var b = 0u; b < count; b++) {
+    let r0 = table(0, b);
+    let r1 = table(1, b);
+    let blend = table(3, b).x;
+    let w = biome_window(temperature, r0.x, r0.y, blend) * biome_window(in.uv.y, r0.z, r0.w, blend) *
+      biome_window(height, r1.x, r1.y, blend) * biome_window(slope, r1.z, r1.w, blend);
+    sum += w;
+    if (w > best_w.x) {
+      best_w = vec4f(w, best_w.xyz);
+      best_i = vec4u(b, best_i.xyz);
+    } else if (w > best_w.y) {
+      best_w = vec4f(best_w.x, w, best_w.yz);
+      best_i = vec4u(best_i.x, b, best_i.yz);
+    } else if (w > best_w.z) {
+      best_w = vec4f(best_w.xy, w, best_w.z);
+      best_i = vec4u(best_i.xy, b, best_i.z);
+    } else if (w > best_w.w) {
+      best_w.w = w;
+      best_i.w = b;
+    }
+  }
+  if (sum < 1e-6) {
+    best_w = vec4f(1.0, 0.0, 0.0, 0.0);
+    best_i = vec4u(0u);
+  }
+  best_w /= max(1e-6, best_w.x + best_w.y + best_w.z + best_w.w);
+  // Planet-space position (offset to stay small; repeats line up across the offset) and normal.
+  let q = vec3f(dot(PlanetSurface.rot0.xyz, in.world_position), dot(PlanetSurface.rot1.xyz, in.world_position), dot(PlanetSurface.rot2.xyz, in.world_position)) +
+    vec3f(PlanetSurface.rot0.w, PlanetSurface.rot1.w, PlanetSurface.rot2.w);
+  var grads: Grads;
+  grads.dx = dpdx(q);
+  grads.dy = dpdy(q);
+  let debug = u32(PlanetSurface.debugParams.x);
+  if (debug == 1u) {
+    p.base_color = table(2, best_i.x).rgb;
+    p.roughness = 1.0;
+    p.metallic = 0.0;
+    return p;
+  }
+  if (debug == 2u) {
+    p.base_color = vec3f(1.0);
+    p.emissive = vec3f(20000.0);
+    return p;
+  }
+  if (debug == 4u) {
+    p.base_color = n * 0.5 + 0.5;
+    p.emissive = p.base_color * 3000.0;
+    return p;
+  }
+  if (debug == 3u) {
+    // Levels of detail: a hue per depth (from the depth's morph error, which halves per level).
+    let level = floor(log2(max(in.uv1.y, 1e-6)) * 1.0);
+    let hue = fract(level * 0.37);
+    p.base_color = 0.5 + 0.5 * cos(6.2832 * (vec3f(hue) + vec3f(0.0, 0.33, 0.67)));
+    p.emissive = p.base_color * 3000.0;
+    return p;
+  }
+  let np = vec3f(dot(PlanetSurface.rot0.xyz, n), dot(PlanetSurface.rot1.xyz, n), dot(PlanetSurface.rot2.xyz, n));
+  var bw = pow(abs(np), vec3f(4.0));
+  bw /= max(1e-6, bw.x + bw.y + bw.z);
+  let near = distance(in.world_position, view.cameraPosition) < PlanetSurface.debugParams.y;
+  var albedo = vec3f(0.0);
+  var normal = vec3f(0.0);
+  var orm = vec3f(0.0);
+  for (var k = 0u; k < 4u; k++) {
+    let w = best_w[k];
+    if (w <= 0.001) { continue; }
+    let b = best_i[k];
+    let tint = table(2, b).rgb;
+    let info = table(3, b);
+    let layers = table(4, b);
+    let scales = table(5, b);
+    // Layers go from flat ground (first) to cliffs (last), blended by slope.
+    let last = max(1.0, info.y) - 1.0;
+    let f = clamp(slope / 50.0, 0.0, 1.0) * last;
+    let k0 = u32(floor(f));
+    let k1 = min(k0 + 1u, u32(last));
+    let s = smoothstep(0.0, 1.0, f - floor(f));
+    let a = sample_layer(layers[k0], scales[k0], q, grads, np, bw, near);
+    var c = a;
+    if (k1 != k0 && s > 0.01) {
+      let d = sample_layer(layers[k1], scales[k1], q, grads, np, bw, near);
+      c.albedo = mix(a.albedo, d.albedo, s);
+      c.orm = mix(a.orm, d.orm, s);
+      c.normal = normalize(mix(a.normal, d.normal, s));
+    }
+    albedo += c.albedo * tint * w;
+    normal += c.normal * w;
+    orm += c.orm * w;
+  }
+  let pn = normalize(normal);
+  p.base_color = albedo;
+  p.normal = normalize(PlanetSurface.rot0.xyz * pn.x + PlanetSurface.rot1.xyz * pn.y + PlanetSurface.rot2.xyz * pn.z);
+  if (PlanetSurface.debugParams.z > 0.5) {
+    p.occlusion = orm.r;
+    p.roughness = clamp(orm.g, 0.045, 1.0);
+    p.metallic = orm.b;
+  } else {
+    p.occlusion = 1.0;
+    p.roughness = 0.9;
+    p.metallic = 0.0;
+  }
+  return p;
+}
+`,
+  "terrain::ocean": `
+import shard::pbr::types::{ VertexOutput, PbrInput };
+import shard::pbr::standard::standard_input;
+import shard::globals::globals;
+import shard::mesh::{ vertex_uv1, vertex_tangent, vertex_world, vertex_instance_data };
+import material::ocean::Ocean;
+${MORPH("Ocean")}
+/** Slope (d/dx, d/dy) of a few scrolling sine waves at planet-space point xy. */
+fn waves(xy: vec2f, t: f32) -> vec2f {
+  var g = vec2f(0.0);
+  let dirs = array<vec2f, 4>(vec2f(1.0, 0.2), vec2f(-0.4, 1.0), vec2f(0.7, -0.7), vec2f(-1.0, -0.3));
+  let lengths = array<f32, 4>(9.0, 5.3, 3.1, 1.7);
+  for (var i = 0u; i < 4u; i++) {
+    let d = normalize(dirs[i]);
+    let k = 6.2831853 / lengths[i];
+    let speed = sqrt(9.81 / k);
+    let a = 0.04 * lengths[i] / 9.0;
+    g += d * (a * k * cos(k * dot(d, xy) - speed * k * t));
+  }
+  return g;
+}
+
+override fn pbr_input(in: VertexOutput) -> PbrInput {
+  var p = standard_input(in);
+  let depth = max(in.world_tangent.w, 0.0);
+  let up = normalize(in.world_position - Ocean.center.xyz);
+  // The point and a tangent frame in planet space, so the waves stay put as the planet turns.
+  let q = vec3f(dot(Ocean.rot0.xyz, in.world_position), dot(Ocean.rot1.xyz, in.world_position), dot(Ocean.rot2.xyz, in.world_position)) +
+    vec3f(Ocean.rot0.w, Ocean.rot1.w, Ocean.rot2.w);
+  let pu = vec3f(dot(Ocean.rot0.xyz, up), dot(Ocean.rot1.xyz, up), dot(Ocean.rot2.xyz, up));
+  let helper = select(vec3f(0.0, 1.0, 0.0), vec3f(1.0, 0.0, 0.0), abs(pu.y) > 0.9);
+  let tx = normalize(cross(helper, pu));
+  let ty = cross(pu, tx);
+  let g = waves(vec2f(dot(q, tx), dot(q, ty)), globals.time);
+  let pn = normalize(pu - tx * g.x - ty * g.y);
+  p.normal = normalize(Ocean.rot0.xyz * pn.x + Ocean.rot1.xyz * pn.y + Ocean.rot2.xyz * pn.z);
+  let shade = 1.0 - exp(-depth * Ocean.water.x);
+  p.base_color = mix(Ocean.shallow.rgb, Ocean.deep.rgb, shade);
+  p.alpha = clamp(1.0 - exp(-depth * Ocean.water.y), Ocean.water.z, 1.0);
+  p.roughness = Ocean.water.w;
+  p.metallic = 0.0;
+  p.occlusion = 1.0;
+  return p;
+}
+`
+};
+export {
+  OceanMaterial,
+  PlanetMaterial,
+  TERRAIN_SHADERS,
+  TEXTURE_PERIOD
+};

package/dist/methods.d.ts

@@ -0,0 +1,12 @@
+import { type World } from '@aethervtt/shard-core';
+import type { AppMethod } from '@aethervtt/shard-runtime';
+import type { PlanetRuntime } from './planet.js';
+/** A planet from an entity id or scene path; the only planet when omitted. */
+export declare function resolvePlanet(world: World, ref: unknown): PlanetRuntime;
+/** Pixels of an equirectangular map: height (sea blue by depth, land dark to light) or biomes. */
+export declare function terrainMap(rt: PlanetRuntime, width: number, mode: 'height' | 'biomes'): {
+    width: number;
+    height: number;
+    data: Uint8Array<ArrayBuffer>;
+};
+export declare const terrainMethods: AppMethod[];

package/dist/methods.js

@@ -0,0 +1,259 @@
+import {
+  defineSchema,
+  findComponent,
+  ShardError,
+  t
+} from "@aethervtt/shard-core";
+import { encodePng, toBase64 } from "@aethervtt/shard-protocol";
+import { collidersOf } from "./colliders.js";
+import { Terrain, terrainSample } from "./heights.js";
+function scenePath(world, entity) {
+  const member = findComponent("scene/SceneMember");
+  if (!member || !world.isAlive(entity)) return null;
+  const v = world.tryGet(entity, member);
+  return v?.path || null;
+}
+function resolvePlanet(world, ref) {
+  const planets = world.tryResource(Terrain)?.planets;
+  if (!planets || planets.size === 0) {
+    throw new ShardError("terrain/no-planet", "There is no terrain/Planet in the world", {
+      hint: "Add terrain/Planet (with a Grid) to an entity, and the terrain plugin to the app."
+    });
+  }
+  if (ref === void 0 || ref === null || ref === "") {
+    if (planets.size > 1) {
+      throw new ShardError("terrain/which-planet", `There are ${planets.size} planets; name one`, {
+        hint: "Pass planet: an entity id or a scene path (terrain.describe lists them)."
+      });
+    }
+    return [...planets.values()][0];
+  }
+  for (const rt of planets.values()) {
+    if (rt.entity === ref) return rt;
+    const path = scenePath(world, rt.entity);
+    if (typeof ref === "string" && path && (path === ref || path.endsWith(`/${ref}`))) return rt;
+  }
+  throw new ShardError("terrain/not-a-planet", `No planet matches ${JSON.stringify(ref)}`, {
+    hint: "terrain.describe lists every planet with its entity and scene path."
+  });
+}
+function usable(rt) {
+  if (rt.problem) throw rt.problem;
+  if (!rt.ready) {
+    throw new ShardError(
+      "terrain/not-ready",
+      `The planet is waiting for ${rt.waiting ?? "its settings"}`,
+      {
+        hint: "Its graphs and biomes load asynchronously; step a frame and ask again."
+      }
+    );
+  }
+}
+const round = (v, digits = 3) => {
+  const k = 10 ** digits;
+  return Math.round(v * k) / k;
+};
+function latlon(lat, lon) {
+  const a = lat * Math.PI / 180;
+  const b = lon * Math.PI / 180;
+  return [Math.cos(a) * Math.sin(b), Math.sin(a), Math.cos(a) * Math.cos(b)];
+}
+function describePlanet(world, rt) {
+  const s = rt.settings;
+  const byDepth = [];
+  const t2 = rt.tree;
+  let partial = 0;
+  for (let i = 0; i < rt.selection.renderedCount; i++) {
+    const n = rt.selection.rendered[i];
+    byDepth[t2.depth[n]] = (byDepth[t2.depth[n]] ?? 0) + 1;
+    if (t2.mask[n] !== 15) partial++;
+  }
+  const pr = rt.parts.get("render");
+  const colliders = collidersOf(rt);
+  let underCamera = null;
+  if (pr?.hasCamera && rt.ready) {
+    const p = pr.view.position;
+    underCamera = terrainSample(rt, [p[0], p[1], p[2]]);
+  }
+  return {
+    entity: rt.entity,
+    path: scenePath(world, rt.entity),
+    ready: rt.ready,
+    waitingFor: rt.waiting,
+    problem: rt.problem ? rt.problem.toJSON() : null,
+    radius: s?.radius ?? null,
+    heightScale: s?.heightScale ?? null,
+    ocean: s ? s.ocean ? { seaLevel: s.seaLevel } : null : null,
+    maxDepth: rt.maxDepth,
+    colliderDepth: rt.colliderDepth,
+    spacing: {
+      finest: round(rt.spacing(rt.maxDepth)),
+      colliders: round(rt.spacing(rt.colliderDepth))
+    },
+    version: rt.version,
+    biomes: rt.table.count,
+    detail: {
+      vertexPixels: s?.vertexPixels ?? null,
+      // Over TerrainBudget.triangles the LOD bias rises above 1 (coarser), and falls back after.
+      lodBias: round(rt.lodBias),
+      triangles: rt.selection.renderedCount * 2 * ((s?.resolution ?? 33) - 1) ** 2
+    },
+    selected: {
+      chunks: rt.selection.renderedCount,
+      byDepth: Object.fromEntries(byDepth.flatMap((c, d) => c ? [[d, c]] : [])),
+      partial,
+      ocean: rt.oceanSelection.renderedCount,
+      requested: rt.selection.requestedCount + rt.oceanSelection.requestedCount,
+      waiting: rt.selection.waiting,
+      walks: rt.selection.passes
+    },
+    pool: pr ? {
+      slots: pr.slots.length,
+      shown: pr.slots.filter((x) => x.shown).length,
+      inFlight: pr.jobs.length,
+      generated: pr.stats.generated,
+      fromColliders: pr.stats.fromColliders,
+      evicted: pr.stats.evicted,
+      readbacks: pr.stats.readbacks,
+      jobsLastFrame: pr.stats.lastFrameJobs
+    } : null,
+    colliders: {
+      chunks: colliders.chunks.size,
+      active: [...colliders.chunks.values()].filter((c) => c.entity >= 0).length,
+      pending: colliders.jobs.size,
+      builtOnPool: colliders.builtPool,
+      builtOnMainThread: colliders.builtSync,
+      anchors: rt.anchors
+    },
+    underCamera: underCamera ? {
+      height: round(underCamera.height),
+      underwater: underCamera.underwater,
+      biome: underCamera.biome,
+      slope: round(underCamera.slope, 1)
+    } : null,
+    treeNodes: rt.tree.live
+  };
+}
+function terrainMap(rt, width, mode) {
+  usable(rt);
+  const height = Math.max(1, Math.round(width / 2));
+  const data = new Uint8Array(width * height * 4);
+  const s = rt.settings;
+  const top = Math.max(1, rt.highest - Math.max(s.seaLevel, rt.lowest));
+  const low = Math.max(1, (s.ocean ? s.seaLevel : 0) - rt.lowest);
+  for (let y = 0; y < height; y++) {
+    const lat = 90 - (y + 0.5) / height * 180;
+    for (let x = 0; x < width; x++) {
+      const lon = (x + 0.5) / width * 360 - 180;
+      const sample = terrainSample(rt, latlon(lat, lon));
+      const o = (y * width + x) * 4;
+      let r;
+      let g;
+      let b;
+      if (sample.underwater) {
+        const d = Math.min(1, sample.depth / low);
+        r = 20 * (1 - d);
+        g = 90 * (1 - d) + 20;
+        b = 200 - 110 * d;
+      } else if (mode === "height") {
+        const k = Math.min(
+          1,
+          Math.max(0, (sample.height - (s.ocean ? s.seaLevel : rt.lowest)) / top)
+        );
+        r = 40 + 215 * k;
+        g = 80 + 175 * k;
+        b = 40 + 215 * k;
+      } else {
+        const tint = rt.table.tints.subarray(sample.biome * 4, sample.biome * 4 + 4);
+        const shade = 0.75 + 0.25 * Math.cos(sample.slope * Math.PI / 180);
+        r = Math.min(255, tint[0] ** (1 / 2.2) * 255 * shade);
+        g = Math.min(255, tint[1] ** (1 / 2.2) * 255 * shade);
+        b = Math.min(255, tint[2] ** (1 / 2.2) * 255 * shade);
+      }
+      data[o] = r;
+      data[o + 1] = g;
+      data[o + 2] = b;
+      data[o + 3] = 255;
+    }
+  }
+  return { width, height, data };
+}
+const planetField = t.json({
+  description: "The planet: entity id or scene path (default: the only planet)."
+});
+const terrainMethods = [
+  {
+    name: "terrain.describe",
+    description: "Planet terrain as data: per planet, the chunks selected by depth (and partial ones waiting for children), requests and chunks in flight, pool usage, generation counts, collider chunks and anchors, the vertex spacing at the finest and collider depths, and the height, biome, and slope under the camera. Problems (a bad radius, a climate graph without temperature/moisture) and what it waits for are here too.",
+    params: defineSchema("terrain/DescribeParams", { planet: planetField }),
+    handler: ({ world }, p) => {
+      const planets = world.tryResource(Terrain)?.planets;
+      if (!planets) return { planets: [] };
+      if (p.planet !== void 0 && p.planet !== null && p.planet !== "")
+        return { planets: [describePlanet(world, resolvePlanet(world, p.planet))] };
+      return { planets: [...planets.values()].map((rt) => describePlanet(world, rt)) };
+    }
+  },
+  {
+    name: "terrain.sample",
+    description: "The surface at points on a planet, from the CPU noise the colliders use (headless-safe): height (m above radius), underwater and water depth, slope (degrees), climate, and biome weights with the dominant biome. Points are directions from the planet center in its frame ([x, y, z], any length) or [lat, lon] in degrees (lat from the +Y axis\u2019s equator, lon around it).",
+    params: defineSchema("terrain/SampleParams", {
+      planet: planetField,
+      directions: t.json({ description: "Directions: [[x, y, z], \u2026] (at most 4096)." }),
+      latlon: t.json({ description: "Latitudes and longitudes in degrees: [[lat, lon], \u2026]." })
+    }),
+    handler: ({ world }, p) => {
+      const rt = resolvePlanet(world, p.planet);
+      usable(rt);
+      const dirs = [];
+      if (Array.isArray(p.directions)) for (const d of p.directions) dirs.push(d);
+      if (Array.isArray(p.latlon))
+        for (const [a, b] of p.latlon) dirs.push(latlon(a, b));
+      if (dirs.length === 0 || dirs.length > 4096) {
+        throw new ShardError(
+          "terrain/bad-points",
+          "Pass 1 to 4096 points in directions or latlon",
+          {
+            hint: 'e.g. { "latlon": [[0, 0], [45, 90]] }, or { "directions": [[0, 1, 0]] } for the north pole.'
+          }
+        );
+      }
+      return {
+        samples: dirs.map((d) => {
+          const s = terrainSample(rt, d);
+          return {
+            height: round(s.height),
+            underwater: s.underwater,
+            depth: round(s.depth),
+            slope: round(s.slope, 2),
+            temperature: round(s.temperature),
+            moisture: round(s.moisture),
+            latitude: round(s.latitude),
+            biome: s.biome,
+            biomes: s.biomes.map((w) => round(w))
+          };
+        })
+      };
+    }
+  },
+  {
+    name: "terrain.map",
+    description: 'An equirectangular PNG of a planet (width \xD7 width/2; latitude +90 at the top, longitude \u2212180 to 180 left to right): mode "biomes" colors land by its dominant biome\u2019s tint (shaded by slope), mode "height" dark lowlands to white peaks; water is blue, darker when deeper. One image answers "are there continents, oceans, and polar caps".',
+    params: defineSchema("terrain/MapParams", {
+      planet: planetField,
+      size: t.u32({ default: 256, min: 16, max: 1024, description: "Width in pixels." }),
+      mode: t.enum(["biomes", "height"])
+    }),
+    handler: async ({ world }, p) => {
+      const rt = resolvePlanet(world, p.planet);
+      const image = terrainMap(rt, p.size, p.mode);
+      const png = await encodePng(image.data, image.width, image.height);
+      return { width: image.width, height: image.height, data: toBase64(png) };
+    }
+  }
+];
+export {
+  resolvePlanet,
+  terrainMap,
+  terrainMethods
+};