@aethervtt/shard-terrain 0.1.0 → 0.2.0

package/dist/heightfield/heightmap.js

@@ -0,0 +1,160 @@
+import { AssetStore, defineAssetType, defineImporter } from "@aethervtt/shard-assets";
+import { defineResource, defineSchema, ShardError, t } from "@aethervtt/shard-core";
+import { inflate } from "./kernel.js";
+const Heightmaps = defineResource("terrain/Heightmaps", {
+  description: "Loaded heightmaps (16-bit PNG, .r16, .r32) by guid.",
+  init: () => new AssetStore("Heightmap")
+});
+const HeightmapAssetType = defineAssetType("Heightmap", {
+  store: Heightmaps,
+  load: (artifact) => {
+    const info = artifact.json;
+    const bytes = artifact.bytes ?? new Uint8Array(0);
+    const n = info.width * info.height;
+    const data = new Float32Array(n);
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    if (info.bits === 16) for (let i = 0; i < n; i++) data[i] = view.getUint16(i * 2, true) / 65535;
+    else for (let i = 0; i < n; i++) data[i] = view.getFloat32(i * 4, true);
+    return { width: info.width, height: info.height, data, version: 0 };
+  },
+  update: (existing, next) => {
+    const e = existing;
+    e.width = next.width;
+    e.height = next.height;
+    e.data = next.data;
+    e.version++;
+  }
+});
+const HeightmapSettings = defineSchema(
+  "terrain/HeightmapSettings",
+  {
+    width: t.u32({ description: "Raw files (.r16, .r32): samples per row." }),
+    height: t.u32({ description: "Raw files (.r16, .r32): rows." })
+  },
+  {
+    description: "A heightmap: a 16-bit grayscale PNG (dimensions from the file), or raw little-endian samples (.r16 unsigned 16-bit, .r32 float, 0\u20131) with width and height here."
+  }
+);
+function format(path, message) {
+  return new ShardError("terrain/heightmap-format", `${path}: ${message}`, {
+    path,
+    hint: 'Heightmaps are 16-bit grayscale PNGs, or .r16/.r32 raw files with "width" and "height" in their .meta settings. An 8-bit PNG is a texture, not a heightmap.'
+  });
+}
+function paeth(a, b, c) {
+  const p = a + b - c;
+  const pa = Math.abs(p - a);
+  const pb = Math.abs(p - b);
+  const pc = Math.abs(p - c);
+  return pa <= pb && pa <= pc ? a : pb <= pc ? b : c;
+}
+function decodeHeightPng(path, png) {
+  const view = new DataView(png.buffer, png.byteOffset, png.byteLength);
+  if (png.length < 8 || view.getUint32(0) !== 2303741511) throw format(path, "not a PNG file");
+  let offset = 8;
+  let width = 0;
+  let height = 0;
+  let depth = 0;
+  let colorType = -1;
+  let interlace = 0;
+  const idat = [];
+  while (offset + 8 <= png.length) {
+    const length = view.getUint32(offset);
+    const type = String.fromCharCode(...png.subarray(offset + 4, offset + 8));
+    const data = png.subarray(offset + 8, offset + 8 + length);
+    if (type === "IHDR") {
+      width = view.getUint32(offset + 8);
+      height = view.getUint32(offset + 12);
+      depth = data[8];
+      colorType = data[9];
+      interlace = data[12];
+    } else if (type === "IDAT") idat.push(data);
+    else if (type === "IEND") break;
+    offset += 12 + length;
+  }
+  if (colorType !== 0 || depth !== 16) {
+    throw format(
+      path,
+      `a ${depth}-bit ${colorType === 0 ? "grayscale" : "color"} PNG isn't 16-bit grayscale`
+    );
+  }
+  if (interlace !== 0)
+    throw format(path, "interlaced PNGs aren\u2019t read; save it without interlacing");
+  const joined = new Uint8Array(idat.reduce((n, p) => n + p.length, 0));
+  let o = 0;
+  for (const p of idat) {
+    joined.set(p, o);
+    o += p.length;
+  }
+  const rowBytes = width * 2;
+  const raw = inflate(joined.subarray(2), (rowBytes + 1) * height);
+  const samples = new Uint16Array(width * height);
+  const prev = new Uint8Array(rowBytes);
+  const row = new Uint8Array(rowBytes);
+  for (let y = 0; y < height; y++) {
+    const filter = raw[y * (rowBytes + 1)];
+    const src = y * (rowBytes + 1) + 1;
+    for (let x = 0; x < rowBytes; x++) {
+      const v = raw[src + x];
+      const a = x >= 2 ? row[x - 2] : 0;
+      const b = prev[x];
+      const c = x >= 2 ? prev[x - 2] : 0;
+      const r = filter === 0 ? v : filter === 1 ? v + a : filter === 2 ? v + b : filter === 3 ? v + (a + b >> 1) : filter === 4 ? v + paeth(a, b, c) : -1;
+      if (r < 0) throw format(path, `row ${y} has an invalid filter (${filter})`);
+      row[x] = r & 255;
+    }
+    for (let x = 0; x < width; x++) samples[y * width + x] = row[x * 2] << 8 | row[x * 2 + 1];
+    prev.set(row);
+  }
+  return { width, height, bits: 16, samples };
+}
+const HeightmapImporter = defineImporter({
+  name: "heightmap",
+  version: 1,
+  extensions: [".r16", ".r32", ".height.png"],
+  settings: HeightmapSettings,
+  async import(source, ctx) {
+    const path = source.path;
+    let info;
+    let bytes;
+    if (path.endsWith(".r16") || path.endsWith(".r32")) {
+      const bits = path.endsWith(".r16") ? 16 : 32;
+      const width = Number(ctx.settings.width ?? 0);
+      const height = Number(ctx.settings.height ?? 0);
+      if (!(width > 0 && height > 0))
+        throw format(path, "a raw heightmap needs width and height in its .meta settings");
+      const expected = width * height * (bits / 8);
+      if (source.bytes.length !== expected) {
+        throw format(
+          path,
+          `${source.bytes.length} bytes, but ${width} \xD7 ${height} ${bits}-bit samples are ${expected}`
+        );
+      }
+      info = { width, height, bits };
+      bytes = source.bytes.slice();
+    } else {
+      const png = decodeHeightPng(path, source.bytes);
+      info = { width: png.width, height: png.height, bits: 16 };
+      bytes = new Uint8Array(png.samples.length * 2);
+      const view = new DataView(bytes.buffer);
+      for (let i = 0; i < png.samples.length; i++) view.setUint16(i * 2, png.samples[i], true);
+    }
+    return {
+      assets: [
+        {
+          label: "",
+          type: "Heightmap",
+          bytes,
+          json: { ...info },
+          info: { width: info.width, height: info.height, bits: info.bits }
+        }
+      ]
+    };
+  }
+});
+export {
+  HeightmapAssetType,
+  HeightmapImporter,
+  Heightmaps,
+  decodeHeightPng
+};

package/dist/heightfield/kernel.d.ts

@@ -0,0 +1,277 @@
+// Types for kernel.js (plain JavaScript so worker threads can import it without a loader).
+
+export { deflate, inflate } from './deflate.js'
+
+export declare const PAGE: number
+export declare const SIDE: number
+export declare const LEAF_SIDE: number
+export declare const BLOCK: number
+export declare const LATTICE: number
+export declare const BLOCK_LEVELS: number
+export declare const BAKE_VERSION: number
+
+export declare const BLEND_ADD: 0
+export declare const BLEND_MAX: 1
+export declare const BLEND_MIN: 2
+export declare const BLEND_REPLACE: 3
+export declare const MODE_FLATTEN: 0
+export declare const MODE_RAISE: 1
+export declare const MODE_CARVE: 2
+export declare const LAYER_NOISE: 0
+export declare const LAYER_IMAGE: 1
+export declare const LAYER_SPLINE: 2
+
+/** The noise kernel a bake samples with: this thread's instance and its functions. */
+export interface NoiseAccess {
+  readonly state: unknown
+  computeOrigins(terms: unknown, origin: ArrayLike<number>, out: Int32Array): Int32Array
+  evalProgram(
+    state: unknown,
+    program: unknown,
+    seed: number,
+    origins: Int32Array,
+    pts: ArrayLike<number>,
+    stride: number,
+    count: number,
+    out: Float32Array,
+  ): void
+}
+
+/** A compiled noise program as the kernel reads it (`NoiseGraph.programFor`). */
+export interface StackProgram {
+  readonly terms: unknown
+  readonly zeroOrigins: Int32Array
+  readonly [key: string]: unknown
+}
+
+/** A heightmap: values 0–1, row by row, top row first. */
+export interface StackMap {
+  readonly width: number
+  readonly height: number
+  readonly data: Float32Array
+}
+
+/** A rotated rectangle: center, half width and depth, and its rotation's cosine and sine. */
+export interface StackRect {
+  readonly cx: number
+  readonly cz: number
+  readonly hw: number
+  readonly hd: number
+  readonly cos: number
+  readonly sin: number
+}
+
+/** A spline ready for distance queries (buildSpline). */
+export interface StackSpline {
+  readonly pts: Float64Array
+  readonly count: number
+  readonly width: number
+  readonly falloff: number
+  readonly reach: number
+  readonly cell: number
+  readonly x0: number
+  readonly z0: number
+  readonly cols: number
+  readonly rows: number
+  readonly start: Int32Array
+  readonly segs: Int32Array
+  readonly minX: number
+  readonly minZ: number
+  readonly maxX: number
+  readonly maxZ: number
+}
+
+export type StackHeightLayer =
+  | {
+      readonly kind: 0
+      readonly program: StackProgram
+      readonly scale: number
+      readonly offset: number
+      readonly blend: number
+      readonly rect: StackRect | null
+      readonly falloff: number
+    }
+  | {
+      readonly kind: 1
+      readonly map: StackMap
+      readonly rect: StackRect
+      readonly lo: number
+      readonly hi: number
+      readonly blend: number
+      readonly falloff: number
+    }
+  | {
+      readonly kind: 2
+      readonly spline: StackSpline
+      readonly mode: number
+      readonly offset: number
+      readonly falloff: number
+    }
+
+export interface StackPaint {
+  /** Material layer index. */
+  readonly layer: number
+  readonly height: readonly [number, number] | null
+  readonly slope: readonly [number, number] | null
+  readonly noise: { readonly program: StackProgram; readonly above: number } | null
+  readonly mask: { readonly map: StackMap; readonly rect: StackRect } | null
+  readonly spline: StackSpline | null
+  /** Edge softness: metres for height, masks and splines, degrees for slope. */
+  readonly blend: number
+}
+
+/** A terrain source compiled for the kernel (heightfield/stack.ts): structured-cloneable. */
+export interface Stack {
+  readonly spacing: number
+  readonly seed: number
+  readonly lo: number
+  readonly hi: number
+  readonly layerCount: number
+  readonly height: readonly StackHeightLayer[]
+  readonly paint: readonly StackPaint[]
+}
+
+/** What bakeBlock needs of the terrain's grid (heightfield/source.ts TerrainLayout). */
+export interface KernelLayout {
+  readonly depth: number
+  readonly spacing: number
+  readonly leavesX: number
+  readonly leavesZ: number
+  /** Leaf samples per paint sample. */
+  readonly paintStep: number
+  /** Paint cells per page side. */
+  readonly cells: number
+  /** Leaves per block side (BLOCK; smaller in tests), and log2 of it. */
+  readonly block: number
+  readonly blockLevels: number
+}
+
+/** A decoded page: u16 heights (LEAF_SIDE² for leaves, SIDE² for parents), normals, control. */
+export interface DecodedPage {
+  readonly heights: Uint16Array
+  /** Parents: x then z planes, SIDE² bytes each. Leaves: null (their heights make them). */
+  readonly normals: Uint8Array | null
+  /** (cells + 1)² texels of four bytes: heaviest layer, second, its share, hole bit. */
+  readonly control: Uint8Array
+}
+
+/** A baked page: its level above the leaves, node coordinates at that level, and deflated bytes. */
+export interface BakedPage {
+  level: number
+  x: number
+  z: number
+  data: Uint8Array
+  /** Quantized height range over the node (its whole subtree). */
+  min: number
+  max: number
+  /** Exact geometric error (m): the largest gap between its subtree's samples and its surface. */
+  error: number
+}
+
+export interface BlockResult {
+  pages: BakedPage[]
+  /** Errors of the levels above the block's own, over its samples (level BLOCK_LEVELS + 1 first). */
+  above: number[]
+  /** Quantized height range of the block. */
+  range: [number, number]
+  /** Samples clipped by heightRange. */
+  clipped: number
+  lowest: number
+  highest: number
+  ms: number
+}
+
+export declare function windowWeight(x: number, lo: number, hi: number, blend: number): number
+export declare function sampleMap(map: StackMap, u: number, v: number): number
+export declare function buildSpline(
+  pts: ArrayLike<number>,
+  width: number,
+  falloff: number,
+  reach: number,
+): StackSpline
+export declare function nearestOnSpline(
+  sp: StackSpline,
+  x: number,
+  z: number,
+  out: Float64Array,
+): number
+export declare function evalHeights(
+  noise: NoiseAccess,
+  stack: Stack,
+  gi0: number,
+  gj0: number,
+  step: number,
+  nx: number,
+  nz: number,
+  upTo: number,
+  out: Float64Array,
+): void
+export declare function evalHeightPoints(
+  noise: NoiseAccess,
+  stack: Stack,
+  xz: ArrayLike<number>,
+  count: number,
+  upTo: number,
+  out: Float64Array,
+): void
+export declare function evalControl(
+  noise: NoiseAccess,
+  stack: Stack,
+  gi0: number,
+  gj0: number,
+  k: number,
+  nx: number,
+  nz: number,
+  hq: Float64Array,
+  hx: number,
+  h0: number,
+  out: Uint8Array,
+): Uint8Array
+export declare function quantize(h: number, lo: number, hi: number): number
+export declare function dequantize(q: number, lo: number, hi: number): number
+export declare function normalByte(v: number): number
+export declare function byteNormal(b: number): number
+export declare function leafNormals(
+  heights: Uint16Array,
+  lo: number,
+  hi: number,
+  spacing: number,
+  out: Uint8Array,
+): Uint8Array
+export declare function pageBytes(leaf: boolean, cells: number): number
+export declare function encodePage(page: DecodedPage, leaf: boolean, cells: number): Uint8Array
+export declare function decodePage(raw: Uint8Array, leaf: boolean, cells: number): DecodedPage
+export declare function readPage(packed: Uint8Array, leaf: boolean, cells: number): DecodedPage
+export declare function pageTexels(
+  page: DecodedPage,
+  leaf: boolean,
+  lo: number,
+  hi: number,
+  spacing: number,
+  texels: Uint8Array,
+): Uint8Array
+export declare function bakeBlock(
+  noise: NoiseAccess,
+  stack: Stack,
+  layout: KernelLayout,
+  bx: number,
+  bz: number,
+): BlockResult
+export declare function bakeLeaf(
+  noise: NoiseAccess,
+  stack: Stack,
+  layout: KernelLayout,
+  x: number,
+  z: number,
+): { page: DecodedPage; min: number; max: number }
+export declare function parentPage(
+  children: readonly (DecodedPage | null)[],
+  cells: number,
+  normalAt: (i: number, j: number, out: Float64Array) => void,
+): DecodedPage
+export declare function pageNormal(
+  page: DecodedPage,
+  i: number,
+  j: number,
+  out: Float64Array,
+): Float64Array