@aethervtt/shard-terrain 0.0.1

package/dist/test-planet.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Test helpers (not a test): a planet app on a GPU (Dawn in Node) or headless, a camera placed in
+ * the planet's frame, and a loop that runs frames until the terrain stops generating.
+ */
+import type { Entity, World } from '@aethervtt/shard-core';
+import type { GpuContext } from '@aethervtt/shard-gpu';
+import { type NoiseGraph } from '@aethervtt/shard-noise';
+import { App, type Plugin } from '@aethervtt/shard-runtime';
+import type { PlanetRuntime } from './planet.js';
+export interface PlanetOptions {
+    radius: number;
+    heightScale?: number;
+    height?: NoiseGraph;
+    climate?: NoiseGraph;
+    seed?: number;
+    ocean?: boolean;
+    seaLevel?: number;
+    skirts?: boolean;
+    errorPixels?: number;
+    /** MSAA samples (default 1). */
+    msaa?: 1 | 4;
+    /** Planet.vertexPixels (default: the component's). */
+    vertexPixels?: number;
+    minSpacing?: number;
+    width?: number;
+    heightPx?: number;
+    /** The target's pixels per CSS pixel (a Retina display is 2). Default 1. */
+    pixelRatio?: number;
+    fovY?: number;
+    clearColor?: [number, number, number, number];
+    physics?: boolean;
+    extra?: Plugin[];
+    /** Chunk generations per frame (TerrainBudget.chunksPerFrame). */
+    chunksPerFrame?: number;
+}
+export interface PlanetApp {
+    app: App;
+    world: World;
+    planet: Entity;
+    camera: Entity;
+    /** The sun (a DirectionalLight), when there's a GPU. */
+    sun: Entity;
+    view: string;
+    runtime(): PlanetRuntime;
+}
+export declare function planetApp(gpu: GpuContext | undefined, o: PlanetOptions): Promise<PlanetApp>;
+/** Puts the camera at `eye` (planet frame, f64) looking at `target`, up roughly radial. */
+export declare function placeCamera(p: PlanetApp, eye: ArrayLike<number>, target: ArrayLike<number>): void;
+/** Runs frames (awaiting pipelines) until nothing is requested, queued, or compiling. */
+export declare function settleTerrain(p: PlanetApp, maxFrames?: number): Promise<number>;
+/** Renders one more frame and captures the camera's view. */
+export declare function capture(p: PlanetApp): Promise<import("@aethervtt/shard-render").CapturedImage>;
+/** Points the sun at a spot on the planet (planet frame direction) from `elevation` degrees up. */
+export declare function sunOver(p: PlanetApp, direction: ArrayLike<number>, elevation?: number): void;
+/**
+ * Pixels that show sky where the ray from the camera must hit the planet: anything inside the
+ * sphere of the lowest possible surface (radius − heightScale) is terrain whatever the LOD.
+ */
+export declare function holes(data: Uint8Array, W: number, H: number, FOV: number, eye: ArrayLike<number>, right: number[], up: number[], forward: number[], lowest: number): number;

package/dist/test-planet.js

@@ -0,0 +1,189 @@
+import { quat } from "@aethervtt/shard-core";
+import { NoiseGraphs } from "@aethervtt/shard-noise";
+import { GravitySource, PhysicsConfig, physics3dPlugin } from "@aethervtt/shard-physics";
+import {
+  Camera3d,
+  captureView,
+  DirectionalLight,
+  Exposure,
+  forwardPlugin,
+  Gpu,
+  OffscreenTarget,
+  RenderTargets,
+  renderPlugin,
+  Shaders,
+  Tonemapping
+} from "@aethervtt/shard-render";
+import { App } from "@aethervtt/shard-runtime";
+import {
+  FloatingOrigin,
+  Grid,
+  placeInGrid,
+  Transform,
+  TransformPlugin
+} from "@aethervtt/shard-transform";
+import { Planet, TerrainBudget } from "./components.js";
+import { Terrain } from "./heights.js";
+import { terrainPlugin } from "./plugin.js";
+async function planetApp(gpu, o) {
+  const app = new App().addPlugin(TransformPlugin);
+  if (gpu)
+    app.addPlugin(renderPlugin({ gpu, windowView: false }), forwardPlugin({ msaa: o.msaa ?? 1 }));
+  if (o.physics) app.addPlugin(physics3dPlugin);
+  app.addPlugin(terrainPlugin(), ...o.extra ?? []);
+  await app.init();
+  const world = app.world;
+  if (o.physics) world.resource(PhysicsConfig).gravity = [0, 0, 0];
+  if (o.chunksPerFrame !== void 0)
+    world.resource(TerrainBudget).chunksPerFrame = o.chunksPerFrame;
+  const graphs = world.initResource(NoiseGraphs);
+  const planet = world.spawn(
+    [Grid, { cellSize: 2e3 }],
+    [
+      Planet,
+      {
+        radius: o.radius,
+        heightScale: o.heightScale ?? 0,
+        height: o.height ? graphs.add(o.height, "height") : null,
+        climate: o.climate ? graphs.add(o.climate, "climate") : null,
+        seed: o.seed ?? 1,
+        ocean: o.ocean ?? false,
+        seaLevel: o.seaLevel ?? 0,
+        skirts: o.skirts ?? true,
+        errorPixels: o.errorPixels ?? 2,
+        ...o.vertexPixels !== void 0 ? { vertexPixels: o.vertexPixels } : {},
+        minSpacing: o.minSpacing ?? 0.4
+      }
+    ],
+    [GravitySource, { strength: 9.81, radius: o.radius }],
+    Transform
+  );
+  let view = "";
+  let camera = -1;
+  let sun = -1;
+  if (gpu) {
+    const target = new OffscreenTarget(gpu, {
+      label: "terrain-test",
+      width: o.width ?? 96,
+      height: o.heightPx ?? 64,
+      pixelRatio: o.pixelRatio ?? 1
+    });
+    const targetRef = world.resource(RenderTargets).add(target, "terrain-test");
+    camera = world.spawn(
+      [
+        Camera3d,
+        {
+          target: targetRef,
+          fovY: o.fovY ?? 60,
+          near: 0.05,
+          clearColor: o.clearColor ?? [1, 0, 1, 1]
+        }
+      ],
+      [Exposure, { ev100: 14 }],
+      [Tonemapping, { curve: "none", dither: false }],
+      Transform,
+      FloatingOrigin
+    );
+    view = `camera:${camera}`;
+    sun = world.spawn(
+      [DirectionalLight, { illuminance: 5e4, shadows: false }],
+      [
+        Transform,
+        {
+          rotation: quat.fromEuler([0, 0, 0, 1], -0.8, 0.4, 0)
+        }
+      ]
+    );
+  }
+  app.update(1 / 60);
+  return {
+    app,
+    world,
+    planet,
+    camera,
+    sun,
+    view,
+    runtime: () => world.resource(Terrain).planets.get(planet)
+  };
+}
+function placeCamera(p, eye, target) {
+  const f = [target[0] - eye[0], target[1] - eye[1], target[2] - eye[2]];
+  const l = Math.hypot(eye[0], eye[1], eye[2]) || 1;
+  const upv = [eye[0] / l, eye[1] / l, eye[2] / l];
+  const rotation = quat.lookRotation([0, 0, 0, 1], f, upv);
+  placeInGrid(p.world, p.camera, p.planet, eye);
+  p.world.set(p.camera, Transform, { rotation });
+}
+async function settleTerrain(p, maxFrames = 400) {
+  const gpu = p.world.tryResource(Gpu);
+  let quiet = 0;
+  for (let f = 0; f < maxFrames; f++) {
+    p.app.update(1 / 60);
+    const rt = p.runtime();
+    const pr = rt?.parts.get("render");
+    if (gpu) {
+      await p.world.resource(Shaders).whenIdle();
+      await gpu.pipelines.whenIdle();
+      await new Promise((r) => setTimeout(r, 0));
+      for (let k = 0; pr && pr.stats.readbacks < pr.stats.generated && k < 500; k++) {
+        await new Promise((r) => setTimeout(r, 1));
+      }
+    }
+    const busy = !rt?.ready || rt.selection.requestedCount > 0 || rt.oceanSelection.requestedCount > 0 || (pr?.jobs.length ?? 0) > 0 || // Bounds from generation readbacks still on the way would change culling.
+    (pr ? pr.stats.readbacks < pr.stats.generated : false) || (gpu ? gpu.pipelines.pending > 0 : false);
+    quiet = busy ? 0 : quiet + 1;
+    if (quiet >= 3) return f;
+  }
+  return maxFrames;
+}
+async function capture(p) {
+  const shot = captureView(p.world, p.view);
+  p.app.update(1 / 60);
+  return shot;
+}
+function sunOver(p, direction, elevation = 35) {
+  const l = Math.hypot(direction[0], direction[1], direction[2]);
+  const up = [direction[0] / l, direction[1] / l, direction[2] / l];
+  const side = Math.abs(up[1]) < 0.9 ? [0, 1, 0] : [1, 0, 0];
+  const h = [
+    side[1] * up[2] - side[2] * up[1],
+    side[2] * up[0] - side[0] * up[2],
+    side[0] * up[1] - side[1] * up[0]
+  ];
+  const hl = Math.hypot(h[0], h[1], h[2]);
+  const e = elevation * Math.PI / 180;
+  const travel = [0, 1, 2].map((k) => h[k] / hl * Math.cos(e) - up[k] * Math.sin(e));
+  const rotation = quat.lookRotation([0, 0, 0, 1], travel, up);
+  p.world.set(p.sun, Transform, { rotation });
+}
+function holes(data, W, H, FOV, eye, right, up, forward, lowest) {
+  let count = 0;
+  const ty = Math.tan(FOV / 2 * Math.PI / 180);
+  const tx = ty * (W / H);
+  for (let py = 0; py < H; py++) {
+    for (let px = 0; px < W; px++) {
+      const a = (px + 0.5) / W * 2 - 1;
+      const b = 1 - (py + 0.5) / H * 2;
+      const d = [0, 1, 2].map((k) => forward[k] + right[k] * a * tx + up[k] * b * ty);
+      const dl = Math.hypot(d[0], d[1], d[2]);
+      const dx = d[0] / dl;
+      const dy = d[1] / dl;
+      const dz = d[2] / dl;
+      const bq = eye[0] * dx + eye[1] * dy + eye[2] * dz;
+      const c = eye[0] ** 2 + eye[1] ** 2 + eye[2] ** 2 - lowest * lowest;
+      const disc = bq * bq - c;
+      if (disc <= lowest * lowest * 0.02 || -bq - Math.sqrt(disc) < 0) continue;
+      const o = (py * W + px) * 4;
+      if (data[o] > 200 && data[o + 1] < 60 && data[o + 2] > 200) count++;
+    }
+  }
+  return count;
+}
+export {
+  capture,
+  holes,
+  placeCamera,
+  planetApp,
+  settleTerrain,
+  sunOver
+};

package/dist/testing.d.ts

@@ -0,0 +1,42 @@
+/** The Earth-sized planet the walk checksum runs on. */
+export declare const WALK_PLANET: {
+    output: string;
+    nodes: {
+        continents: {
+            fbm: {
+                source: string;
+                octaves: number;
+                frequency: number;
+                seed: number;
+            };
+        };
+        hills: {
+            fbm: {
+                source: string;
+                octaves: number;
+                frequency: number;
+                seed: number;
+            };
+        };
+        h: {
+            add: (string | {
+                multiply: (string | number)[];
+            })[];
+        };
+    };
+};
+export interface WalkResult {
+    /** FNV-1a over the characters' final planet-frame positions (f64 bytes) and the collider count. */
+    checksum: string;
+    /** Metres each character walked. */
+    walked: number[];
+    colliders: number;
+    ms: number;
+}
+/**
+ * Drops `characters` capsules at deterministic points on an Earth-radius planet and walks each
+ * for `seconds` headless (no GPU). Node (packages/terrain tests) and Chrome (the playground's
+ * #terrain page) must print the same checksum: the noise kernel, collider meshes, and physics are
+ * all deterministic.
+ */
+export declare function walkChecksum(characters?: number, seconds?: number): Promise<WalkResult>;

package/dist/testing.js

@@ -0,0 +1,96 @@
+import { hash32 } from "@aethervtt/shard-core";
+import { loadNoiseKernel, NoiseGraph, NoiseGraphs } from "@aethervtt/shard-noise";
+import {
+  CharacterController,
+  CharacterIntent,
+  CharacterState,
+  GravitySource,
+  PhysicsConfig,
+  physics3dPlugin
+} from "@aethervtt/shard-physics";
+import { App } from "@aethervtt/shard-runtime";
+import {
+  FloatingOrigin,
+  Grid,
+  placeInGrid,
+  Transform,
+  TransformPlugin,
+  worldPosition64
+} from "@aethervtt/shard-transform";
+import { collidersOf } from "./colliders.js";
+import { Planet } from "./components.js";
+import { planetHeightAt, Terrain } from "./heights.js";
+import { terrainPlugin } from "./plugin.js";
+const WALK_PLANET = {
+  output: "h",
+  nodes: {
+    continents: { fbm: { source: "simplex", octaves: 5, frequency: 2e-6, seed: 1 } },
+    hills: { fbm: { source: "simplex", octaves: 6, frequency: 2e-3, seed: 2 } },
+    h: { add: ["continents", { multiply: ["hills", 0.05] }] }
+  }
+};
+async function walkChecksum(characters = 4, seconds = 3) {
+  const t0 = performance.now();
+  await loadNoiseKernel();
+  const graph = NoiseGraph.fromJson(WALK_PLANET);
+  const app = new App().addPlugin(TransformPlugin, physics3dPlugin, terrainPlugin());
+  await app.init();
+  const w = app.world;
+  const R = 6371e3;
+  w.resource(PhysicsConfig).gravity = [0, 0, 0];
+  const height = w.initResource(NoiseGraphs).add(graph, "walk");
+  const planet = w.spawn(
+    [Grid, { cellSize: 2e3 }],
+    [Planet, { radius: R, height, heightScale: 400, seed: 11, ocean: false }],
+    [GravitySource, { strength: 9.81, radius: R }],
+    Transform
+  );
+  app.update(1 / 60);
+  const walked = [];
+  const bytes = new Uint8Array(characters * 24 + 4);
+  const f64 = new Float64Array(bytes.buffer, 0, characters * 3);
+  const p0 = new Float64Array(3);
+  const p = new Float64Array(3);
+  for (let k = 0; k < characters; k++) {
+    const u = hash32(77, k) / 2 ** 32 * 2 - 1;
+    const a = hash32(76, k) / 2 ** 32 * Math.PI * 2;
+    const s = Math.sqrt(1 - u * u);
+    const dir = [s * Math.cos(a), u, s * Math.sin(a)];
+    const h = planetHeightAt(w, planet, dir);
+    const c = w.spawn(
+      [CharacterController, { up: "gravity", radius: 0.35, height: 1.8 }],
+      [CharacterIntent, {}],
+      [CharacterState, {}],
+      Transform,
+      FloatingOrigin
+    );
+    placeInGrid(
+      w,
+      c,
+      planet,
+      dir.map((v) => v * (R + h + 1.2))
+    );
+    for (let f = 0; f < 30; f++) app.update(1 / 60);
+    worldPosition64(w, c, p0, planet);
+    w.set(c, CharacterIntent, { move: [0, 0, -5] });
+    for (let f = 0; f < seconds * 60; f++) app.update(1 / 60);
+    worldPosition64(w, c, p, planet);
+    walked.push(Math.hypot(p[0] - p0[0], p[1] - p0[1], p[2] - p0[2]));
+    f64.set(p, k * 3);
+    w.despawn(c);
+  }
+  const colliders = collidersOf(w.resource(Terrain).planets.get(planet)).chunks.size;
+  new DataView(bytes.buffer).setUint32(characters * 24, colliders, true);
+  let hash = 2166136261;
+  for (let i = 0; i < bytes.length; i++) hash = Math.imul(hash ^ bytes[i], 16777619);
+  return {
+    checksum: (hash >>> 0).toString(16).padStart(8, "0"),
+    walked,
+    colliders,
+    ms: performance.now() - t0
+  };
+}
+export {
+  WALK_PLANET,
+  walkChecksum
+};

package/dist/view.d.ts

@@ -0,0 +1,12 @@
+import type { SelectionView } from './quadtree.js';
+/** A selection view with room for four side planes. */
+export declare function createView(): SelectionView;
+/**
+ * Fills a selection view for a perspective camera at `position` (planet frame, f64) with unit axes
+ * `right`, `up`, and `forward` (the direction it looks): the four side planes through the camera
+ * (near and far are left out; the horizon culls far terrain), and pixels per radian for a viewport
+ * `height` pixels tall.
+ */
+export declare function perspectiveView(out: SelectionView, position: ArrayLike<number>, right: ArrayLike<number>, up: ArrayLike<number>, forward: ArrayLike<number>, fovY: number, aspect: number, height: number): SelectionView;
+/** A view that sees in every direction (no side planes): selection culls by the horizon only. */
+export declare function omniView(out: SelectionView, position: ArrayLike<number>, pixelsPerRadian: number): SelectionView;

package/dist/view.js

@@ -0,0 +1,61 @@
+function createView() {
+  return {
+    position: new Float64Array(3),
+    frustum: new Float64Array(16),
+    wide: new Float64Array(16),
+    planes: 0,
+    pixelsPerRadian: 1e3
+  };
+}
+function perspectiveView(out, position, right, up, forward, fovY, aspect, height) {
+  out.position[0] = position[0];
+  out.position[1] = position[1];
+  out.position[2] = position[2];
+  const hy = fovY / 2;
+  const hx = Math.atan(Math.tan(hy) * aspect);
+  const cx = Math.cos(hx);
+  const sx = Math.sin(hx);
+  const cy = Math.cos(hy);
+  const sy = Math.sin(hy);
+  const f = out.frustum;
+  plane(f, 0, right, forward, cx, sx, position);
+  plane(f, 1, right, forward, -cx, sx, position);
+  plane(f, 2, up, forward, cy, sy, position);
+  plane(f, 3, up, forward, -cy, sy, position);
+  const wx = Math.min(1.45, hx * 1.5);
+  const wy = Math.min(1.45, hy * 1.5);
+  const w = out.wide;
+  plane(w, 0, right, forward, Math.cos(wx), Math.sin(wx), position);
+  plane(w, 1, right, forward, -Math.cos(wx), Math.sin(wx), position);
+  plane(w, 2, up, forward, Math.cos(wy), Math.sin(wy), position);
+  plane(w, 3, up, forward, -Math.cos(wy), Math.sin(wy), position);
+  out.planes = 4;
+  out.pixelsPerRadian = height / (2 * Math.tan(hy));
+  return out;
+}
+function plane(f, i, side, forward, a, b, p) {
+  let nx = side[0] * a + forward[0] * b;
+  let ny = side[1] * a + forward[1] * b;
+  let nz = side[2] * a + forward[2] * b;
+  const len = Math.sqrt(nx * nx + ny * ny + nz * nz);
+  nx /= len;
+  ny /= len;
+  nz /= len;
+  f[i * 4] = nx;
+  f[i * 4 + 1] = ny;
+  f[i * 4 + 2] = nz;
+  f[i * 4 + 3] = -(nx * p[0] + ny * p[1] + nz * p[2]);
+}
+function omniView(out, position, pixelsPerRadian) {
+  out.position[0] = position[0];
+  out.position[1] = position[1];
+  out.position[2] = position[2];
+  out.planes = 0;
+  out.pixelsPerRadian = pixelsPerRadian;
+  return out;
+}
+export {
+  createView,
+  omniView,
+  perspectiveView
+};

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@aethervtt/shard-terrain",
+  "version": "0.0.1",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "default": "./dist/testing.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "dependencies": {
+    "@aethervtt/shard-assets": "0.0.1",
+    "@aethervtt/shard-core": "0.0.1",
+    "@aethervtt/shard-gpu": "0.0.1",
+    "@aethervtt/shard-mesh": "0.0.1",
+    "@aethervtt/shard-nav": "0.0.1",
+    "@aethervtt/shard-noise": "0.0.1",
+    "@aethervtt/shard-physics": "0.0.1",
+    "@aethervtt/shard-platform": "0.0.1",
+    "@aethervtt/shard-protocol": "0.0.1",
+    "@aethervtt/shard-render": "0.0.1",
+    "@aethervtt/shard-runtime": "0.0.1",
+    "@aethervtt/shard-shader": "0.0.1",
+    "@aethervtt/shard-texture": "0.0.1",
+    "@aethervtt/shard-transform": "0.0.1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aethervtt/shard.git",
+    "directory": "packages/terrain"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "shard": {
+    "buildSha": "d6c5c6aef4675575c878b02cf2c8f738b4190229"
+  }
+}