@aethervtt/shard-noise 0.0.1

package/dist/kernel.js

@@ -0,0 +1,263 @@
+// The noise kernel's JavaScript side: instances, memory layout, origin splits, and the point
+// generators for grids and cube-sphere patches. Plain JavaScript with no imports, because worker
+// threads load it directly (no bundler, no TypeScript loader). Types are in kernel.d.ts.
+
+/** Points per block: a register's length (matches `program::BLOCK`). */
+export const BLOCK = 256
+/** i32 words per origin record: cell xyzw, then fraction xyzw as f32 bits. */
+export const ORIGIN_WORDS = 8
+
+// Skew factors as the f32 values the kernel uses, so the f64 origin split and the f32 local part
+// apply the same matrix.
+const F2 = Math.fround((Math.sqrt(3) - 1) / 2)
+const F4 = Math.fround((Math.sqrt(5) - 1) / 4)
+const TWO_THIRDS = Math.fround(2 / 3)
+const I32_LIMIT = 2 ** 31
+
+const bits = new Float32Array(1)
+const bitsI = new Int32Array(bits.buffer)
+
+function kernelError(code, message, hint) {
+  return Object.assign(new Error(message), { code, hint })
+}
+
+/**
+ * Writes one origin record per term: the lattice position of `origin` (f64: a × origin + b, then the
+ * source's skew) split into an i32 cell and an f32 fraction.
+ */
+export function computeOrigins(terms, origin, out) {
+  const { a, b, skew } = terms
+  const ox = origin[0] ?? 0
+  const oy = origin[1] ?? 0
+  const oz = origin[2] ?? 0
+  const ow = origin[3] ?? 0
+  for (let j = 0; j < skew.length; j++) {
+    const j4 = j * 4
+    let x = a[j4] * ox + b[j4]
+    let y = a[j4 + 1] * oy + b[j4 + 1]
+    let z = a[j4 + 2] * oz + b[j4 + 2]
+    let w = a[j4 + 3] * ow + b[j4 + 3]
+    const k = skew[j]
+    if (k === 2) {
+      const s = (x + y) * F2
+      x += s
+      y += s
+    } else if (k === 3) {
+      const r = (x + y + z) * TWO_THIRDS
+      x = r - x
+      y = r - y
+      z = r - z
+    } else if (k === 4) {
+      const s = (x + y + z + w) * F4
+      x += s
+      y += s
+      z += s
+      w += s
+    }
+    const o = j * ORIGIN_WORDS
+    split(x, out, o)
+    split(y, out, o + 1)
+    split(z, out, o + 2)
+    split(w, out, o + 3)
+  }
+  return out
+}
+
+function split(v, out, i) {
+  const cell = Math.floor(v)
+  if (!(cell < I32_LIMIT && cell >= -I32_LIMIT)) {
+    throw kernelError(
+      'noise/frequency-too-high',
+      `A lattice coordinate reached ${v.toExponential(2)}, past what an i32 cell holds (2³¹)`,
+      'Lower the graph’s finest frequency, or sample closer to the origin.',
+    )
+  }
+  out[i] = cell | 0
+  bits[0] = v - cell
+  out[i + 4] = bitsI[0]
+}
+
+const states = new WeakMap()
+
+/** The instance for a compiled kernel module in this thread (made on first use). */
+export function instantiate(module, instance) {
+  let s = states.get(module)
+  if (!s) {
+    const inst = instance ?? new WebAssembly.Instance(module, {})
+    s = {
+      x: inst.exports,
+      memory: inst.exports.memory,
+      base: 0,
+      capacity: 0,
+      f32: null,
+      i32: null,
+      // The last output range as a view, reused while calls keep the same size.
+      outView: null,
+      outAt: -1,
+    }
+    states.set(module, s)
+  }
+  return s
+}
+
+const align = (n) => (n + 15) & ~15
+
+/**
+ * Runs `program` at `count` points (`stride` floats each, local to the origin the records were
+ * computed for) and writes the results into `out` from `outOffset`. Allocates nothing once the
+ * instance's memory is big enough.
+ */
+export function evalProgram(state, program, seed, origins, pts, stride, count, out, outOffset = 0) {
+  if (count === 0) return
+  const codeOff = 0
+  const constOff = codeOff + align(program.code.length * 4)
+  const originOff = constOff + align(program.consts.length * 4)
+  const ptsOff = originOff + align(origins.length * 4)
+  const outOff = ptsOff + align(count * stride * 4)
+  const regOff = outOff + align(count * 4)
+  const total = regOff + program.registers * BLOCK * 4
+  if (total > state.capacity) {
+    const base = state.x.reserve(total)
+    if (base === 0)
+      throw kernelError('noise/out-of-memory', `The noise kernel couldn't reserve ${total} bytes`)
+    state.base = base
+    state.capacity = total
+  }
+  if (state.f32 === null || state.f32.buffer !== state.memory.buffer) {
+    state.f32 = new Float32Array(state.memory.buffer)
+    state.i32 = new Int32Array(state.memory.buffer)
+    state.outView = null
+  }
+  const f32 = state.f32
+  const i32 = state.i32
+  const base = state.base
+  i32.set(program.code, (base + codeOff) >> 2)
+  f32.set(program.consts, (base + constOff) >> 2)
+  i32.set(origins, (base + originOff) >> 2)
+  const n = count * stride
+  const p = (base + ptsOff) >> 2
+  if (pts.length === n) f32.set(pts, p)
+  else for (let i = 0; i < n; i++) f32[p + i] = pts[i]
+  state.x.eval(
+    base + codeOff,
+    program.code.length / 12,
+    base + constOff,
+    base + originOff,
+    seed >>> 0,
+    base + ptsOff,
+    stride,
+    count,
+    base + outOff,
+    base + regOff,
+    program.result,
+  )
+  const o = (base + outOff) >> 2
+  if (state.outView === null || state.outAt !== o || state.outView.length !== count) {
+    state.outView = f32.subarray(o, o + count)
+    state.outAt = o
+  }
+  out.set(state.outView, outOffset)
+}
+
+// --- cube sphere -------------------------------------------------------------------------------
+
+/** Per face: normal, right, and up axes (right × up = normal). Faces are +X, −X, +Y, −Y, +Z, −Z. */
+const FACES = [
+  [1, 0, 0, 0, 0, -1, 0, 1, 0],
+  [-1, 0, 0, 0, 0, 1, 0, 1, 0],
+  [0, 1, 0, 1, 0, 0, 0, 0, -1],
+  [0, -1, 0, 1, 0, 0, 0, 0, 1],
+  [0, 0, 1, 1, 0, 0, 0, 1, 0],
+  [0, 0, -1, -1, 0, 0, 0, 1, 0],
+]
+
+const QUARTER_PI = Math.PI / 4
+
+/**
+ * The unit direction for face coordinates (u, v) in [-1, 1], with the tangent-adjusted mapping
+ * (each coordinate goes through tan(π/4 · u)), which keeps cells within 1.4× of each other in area.
+ */
+export function faceToDirection(face, u, v, out, offset = 0) {
+  const f = FACES[face]
+  const tu = Math.tan(QUARTER_PI * u)
+  const tv = Math.tan(QUARTER_PI * v)
+  const x = f[0] + tu * f[3] + tv * f[6]
+  const y = f[1] + tu * f[4] + tv * f[7]
+  const z = f[2] + tu * f[5] + tv * f[8]
+  const inv = 1 / Math.sqrt(x * x + y * y + z * z)
+  out[offset] = x * inv
+  out[offset + 1] = y * inv
+  out[offset + 2] = z * inv
+  return out
+}
+
+/** The face a direction lands on, with its face coordinates written to `out` as [u, v]. */
+export function directionToFace(x, y, z, out) {
+  const ax = Math.abs(x)
+  const ay = Math.abs(y)
+  const az = Math.abs(z)
+  const face =
+    ax >= ay && ax >= az ? (x >= 0 ? 0 : 1) : ay >= az ? (y >= 0 ? 2 : 3) : z >= 0 ? 4 : 5
+  const f = FACES[face]
+  const n = x * f[0] + y * f[1] + z * f[2]
+  out[0] = Math.atan((x * f[3] + y * f[4] + z * f[5]) / n) / QUARTER_PI
+  out[1] = Math.atan((x * f[6] + y * f[7] + z * f[8]) / n) / QUARTER_PI
+  return face
+}
+
+const dir = new Float64Array(3)
+
+/** The f64 center of a sphere patch: its middle direction × radius. */
+export function patchOrigin(p, out) {
+  const half = p.extent / 2
+  faceToDirection(p.face, p.x0 + half, p.y0 + half, dir)
+  out[0] = dir[0] * p.radius
+  out[1] = dir[1] * p.radius
+  out[2] = dir[2] * p.radius
+  out[3] = 0
+  return out
+}
+
+/**
+ * Local points (xyz, relative to `origin`) for rows [row0, row1) of a sphere patch: `resolution`
+ * vertices per side spanning [x0, x0 + extent] × [y0, y0 + extent] of the face.
+ */
+export function patchPoints(p, origin, row0, row1, out) {
+  const last = p.resolution - 1
+  let k = 0
+  for (let j = row0; j < row1; j++) {
+    const v = p.y0 + (p.extent * j) / last
+    for (let i = 0; i <= last; i++) {
+      faceToDirection(p.face, p.x0 + (p.extent * i) / last, v, dir)
+      out[k++] = dir[0] * p.radius - origin[0]
+      out[k++] = dir[1] * p.radius - origin[1]
+      out[k++] = dir[2] * p.radius - origin[2]
+    }
+  }
+  return out
+}
+
+/** The f64 center of a grid. */
+export function gridOrigin(g, out) {
+  out[0] = g.origin[0] + g.size[0] / 2
+  out[1] = g.origin[1] + g.size[1] / 2
+  out[2] = g.z ?? 0
+  out[3] = 0
+  return out
+}
+
+/** Local points for rows [row0, row1) of a grid on the z = `g.z` plane. */
+export function gridPoints(g, origin, row0, row1, out) {
+  const [nx, ny] = g.resolution
+  let k = 0
+  for (let j = row0; j < row1; j++) {
+    const y = g.origin[1] + (ny > 1 ? (g.size[1] * j) / (ny - 1) : 0)
+    for (let i = 0; i < nx; i++) {
+      const x = g.origin[0] + (nx > 1 ? (g.size[0] * i) / (nx - 1) : 0)
+      out[k++] = x - origin[0]
+      out[k++] = y - origin[1]
+      out[k++] = 0
+    }
+  }
+  return out
+}

package/dist/loader.d.ts

@@ -0,0 +1,25 @@
+import { type KernelState } from './kernel.js';
+export interface NoiseKernel {
+    /** The compiled module; workers instantiate it from this (modules are cheap to post). */
+    readonly module: WebAssembly.Module;
+    /** This thread's instance. */
+    readonly state: KernelState;
+    /** Whether this is the simd128 build. */
+    readonly simd: boolean;
+}
+/** Whether this host runs WebAssembly SIMD (every current browser and Node does). */
+export declare function simdSupported(): boolean;
+/**
+ * Loads the WASM noise kernel once per thread: the SIMD build where the host supports it (or when
+ * `simd` says so), the scalar build otherwise. The two give bitwise-equal results.
+ */
+export declare function loadNoiseKernel(options?: {
+    simd?: boolean;
+}): Promise<NoiseKernel>;
+/**
+ * Makes a compiled kernel module (`noiseKernel().module`, posted from another thread) this thread's
+ * kernel, so a worker samples without fetching the .wasm. Later `loadNoiseKernel()` calls return it.
+ */
+export declare function useNoiseKernel(module: WebAssembly.Module, simd?: boolean): NoiseKernel;
+/** The kernel sync sampling uses. Throws `noise/kernel-not-loaded` before `loadNoiseKernel`. */
+export declare function noiseKernel(): NoiseKernel;

package/dist/loader.js

@@ -0,0 +1,108 @@
+import { ShardError } from "@aethervtt/shard-core";
+import { instantiate } from "./kernel.js";
+const SIMD_PROBE = new Uint8Array([
+  0,
+  97,
+  115,
+  109,
+  1,
+  0,
+  0,
+  0,
+  1,
+  5,
+  1,
+  96,
+  0,
+  1,
+  123,
+  3,
+  2,
+  1,
+  0,
+  10,
+  10,
+  1,
+  8,
+  0,
+  65,
+  0,
+  253,
+  15,
+  253,
+  98,
+  11
+]);
+function simdSupported() {
+  return WebAssembly.validate(SIMD_PROBE);
+}
+const loaded = /* @__PURE__ */ new Map();
+let current;
+async function readWasm(file) {
+  const url = new URL(`../wasm/${file}`, import.meta.url);
+  if (url.protocol === "file:") {
+    const { readFile } = await import("node:fs/promises");
+    const data = await readFile(url);
+    return new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+  }
+  const res = await fetch(url);
+  if (!res.ok) {
+    throw new ShardError(
+      "noise/kernel-load-failed",
+      `Couldn't fetch the noise kernel (${res.status})`,
+      {
+        path: url.href,
+        hint: "The .wasm files live in packages/noise/wasm; the dev server must serve them."
+      }
+    );
+  }
+  return res;
+}
+function loadNoiseKernel(options = {}) {
+  if (options.simd === void 0 && current && installed) return Promise.resolve(current);
+  const simd = options.simd ?? simdSupported();
+  let p = loaded.get(simd);
+  if (!p) {
+    p = (async () => {
+      const source = await readWasm(simd ? "shard_noise_simd.wasm" : "shard_noise.wasm");
+      let module;
+      try {
+        module = source instanceof Uint8Array ? await WebAssembly.compile(source) : await WebAssembly.compileStreaming(source);
+      } catch (cause) {
+        throw new ShardError("noise/kernel-load-failed", "The noise kernel didn't compile", {
+          cause,
+          hint: "Rebuild it with `pnpm build:wasm`."
+        });
+      }
+      const instance = await WebAssembly.instantiate(module, {});
+      const kernel = { module, state: instantiate(module, instance), simd };
+      if (options.simd === void 0 || !current) current = kernel;
+      return kernel;
+    })();
+    loaded.set(simd, p);
+  }
+  return p;
+}
+let installed = false;
+function useNoiseKernel(module, simd = true) {
+  if (current?.module === module) return current;
+  const kernel = { module, state: instantiate(module), simd };
+  loaded.set(simd, Promise.resolve(kernel));
+  current = kernel;
+  installed = true;
+  return kernel;
+}
+function noiseKernel() {
+  if (!current) {
+    throw new ShardError("noise/kernel-not-loaded", "The noise kernel is not loaded yet", {
+      hint: "await loadNoiseKernel() (or load a NoiseGraph asset, which does) before sampling synchronously."
+    });
+  }
+  return current;
+}
+export {
+  loadNoiseKernel,
+  noiseKernel,
+  simdSupported,
+  useNoiseKernel
+};

package/dist/methods.d.ts

@@ -0,0 +1,9 @@
+import { type World } from '@aethervtt/shard-core';
+import type { AppMethod } from '@aethervtt/shard-runtime';
+import { NoiseGraph } from './noise-graph.js';
+/** The most points `noise.sample` returns in one call. */
+export declare const MAX_SAMPLE_POINTS = 4096;
+/** A graph from an asset path or guid (loaded if needed), or inline graph JSON to try before saving. */
+export declare function resolveGraph(world: World, graph: unknown): Promise<NoiseGraph>;
+export declare const noiseMethods: AppMethod[];
+export declare const noiseGraphPreview: import("@aethervtt/shard-assets").AssetPreview;

package/dist/methods.js

@@ -0,0 +1,119 @@
+import { assetServer, defineAssetPreview } from "@aethervtt/shard-assets";
+import { defineSchema, ShardError, t } from "@aethervtt/shard-core";
+import { loadNoiseKernel } from "./loader.js";
+import { NoiseGraph, NoiseGraphs } from "./noise-graph.js";
+import { sampleNoise, sampleOffset } from "./sample.js";
+import { noiseStats, previewNoise } from "./stats.js";
+const MAX_SAMPLE_POINTS = 4096;
+async function resolveGraph(world, graph) {
+  await loadNoiseKernel();
+  if (graph && typeof graph === "object") return NoiseGraph.fromJson(graph);
+  if (typeof graph !== "string") {
+    throw new ShardError("noise/invalid-graph", '"graph" is an asset path, a guid, or graph JSON', {
+      hint: 'Pass "noise/planet.noise.json", or { "output": \u2026, "nodes": { \u2026 } } to try a graph unsaved.'
+    });
+  }
+  const server = assetServer(world);
+  const ref = server.resolve(graph);
+  if (ref?.type !== "NoiseGraph") {
+    throw new ShardError("noise/not-a-graph", `"${graph}" isn't a noise graph asset`, {
+      hint: "asset.list shows NoiseGraph assets (*.noise.json)."
+    });
+  }
+  await server.load(ref.path ?? graph);
+  const loaded = world.resource(NoiseGraphs).get(ref);
+  if (!loaded)
+    throw new ShardError("noise/not-loaded", `"${graph}" didn't load`, {
+      hint: "asset.status shows why."
+    });
+  return loaded;
+}
+const graphField = t.json({
+  required: true,
+  description: "A NoiseGraph asset path or guid, or inline graph JSON (tried without saving)."
+});
+const noiseMethods = [
+  {
+    name: "noise.sample",
+    description: `Values of a noise graph at up to ${MAX_SAMPLE_POINTS} points ([x, y, z], or [x, y, z, w] for 4D graphs). With origin, points are offsets from it (precise at any distance). node samples an intermediate node.`,
+    params: defineSchema("noise/SampleParams", {
+      graph: graphField,
+      seed: t.u32({ default: 0 }),
+      points: t.json({ required: true, description: "Points: [[x, y, z], \u2026]." }),
+      origin: t.json({ description: "f64 origin [x, y, z] the points are relative to." }),
+      node: t.string({ description: "Sample this node instead of the output." })
+    }),
+    handler: async ({ world }, p) => {
+      const graph = await resolveGraph(world, p.graph);
+      const points = p.points;
+      if (!Array.isArray(points) || points.length > MAX_SAMPLE_POINTS) {
+        throw new ShardError(
+          "noise/too-many-points",
+          `points is an array of at most ${MAX_SAMPLE_POINTS} points`,
+          {
+            hint: "Split the points over several calls, or use noise.stats for a summary of a whole domain."
+          }
+        );
+      }
+      const stride = graph.program.dimensions === 4 ? 4 : 3;
+      const flat = new Float32Array(points.length * stride);
+      points.forEach((pt, i) => {
+        for (let k = 0; k < stride; k++) flat[i * stride + k] = pt[k] ?? 0;
+      });
+      const out = new Float32Array(points.length);
+      const node = p.node || void 0;
+      if (Array.isArray(p.origin))
+        sampleOffset(graph, p.seed, p.origin, flat, out, node);
+      else sampleNoise(graph, p.seed, flat, out, node);
+      return { values: Array.from(out, (v) => Math.round(v * 1e6) / 1e6) };
+    }
+  },
+  {
+    name: "noise.stats",
+    description: 'Samples a noise graph over a plane or a sphere and summarizes it: min, max, mean, stdDev, a 16-bin histogram, and the fraction below each threshold (sphere samples weighted by area, so "below 0" is the share of the surface). Check coverage numerically, e.g. how much of a planet is under sea level.',
+    params: defineSchema("noise/StatsParams", {
+      graph: graphField,
+      seed: t.u32({ default: 0 }),
+      domain: t.enum(["plane", "sphere"], { default: "plane" }),
+      size: t.f64({ description: "Plane side (default: 2 \xD7 extent, or 4)." }),
+      radius: t.f64({ description: "Sphere radius (default: extent, or 1)." }),
+      resolution: t.u32({ description: "Samples per side (per face for spheres).", max: 1024 }),
+      node: t.string({ description: "Summarize this node instead of the output." }),
+      thresholds: t.json({ description: "Values to report the fraction below, e.g. [0]." })
+    }),
+    handler: async ({ world }, p) => {
+      const graph = await resolveGraph(world, p.graph);
+      const domain = {
+        kind: p.domain,
+        // Absent numbers arrive as 0: only positive sizes count.
+        ...typeof p.size === "number" && p.size > 0 ? { size: p.size } : {},
+        ...typeof p.radius === "number" && p.radius > 0 ? { radius: p.radius } : {},
+        ...typeof p.resolution === "number" && p.resolution > 0 ? { resolution: p.resolution } : {}
+      };
+      return noiseStats(graph, p.seed, domain, {
+        node: p.node || void 0,
+        thresholds: Array.isArray(p.thresholds) ? p.thresholds : []
+      });
+    }
+  }
+];
+const noiseGraphPreview = defineAssetPreview(
+  "NoiseGraph",
+  async (world, path, width, height, options) => {
+    const graph = await resolveGraph(world, path);
+    const o = options ?? {};
+    return previewNoise(graph, width, height, {
+      ...o.domain === "sphere" ? { domain: "sphere" } : {},
+      ...typeof o.seed === "number" ? { seed: o.seed } : {},
+      ...typeof o.size === "number" ? { size: Math.max(16, Math.min(2048, o.size)) } : {},
+      ...typeof o.node === "string" ? { node: o.node } : {},
+      ...typeof o.span === "number" ? { span: o.span } : {}
+    });
+  }
+);
+export {
+  MAX_SAMPLE_POINTS,
+  noiseGraphPreview,
+  noiseMethods,
+  resolveGraph
+};

package/dist/nodes.d.ts

@@ -0,0 +1,74 @@
+/**
+ * The node table. Every node type is one entry here; the validator, the JSON Schema, the agent
+ * docs, the compiler, and the WGSL generator all read it. Adding a node is an entry plus its
+ * instruction in the Rust kernel (`crates/shard-noise`) and in `wgsl.ts`.
+ */
+export type ParamDef = {
+    readonly type: 'number';
+    readonly default?: number;
+    readonly min?: number;
+    readonly max?: number;
+    readonly positive?: boolean;
+    readonly description: string;
+} | {
+    readonly type: 'integer';
+    readonly default?: number;
+    readonly min?: number;
+    readonly max?: number;
+    readonly description: string;
+} | {
+    readonly type: 'boolean';
+    readonly default?: boolean;
+    readonly description: string;
+} | {
+    readonly type: 'enum';
+    readonly values: readonly (string | number)[];
+    readonly default?: string | number;
+    readonly description: string;
+}
+/** A node name, an inline node, or a number. */
+ | {
+    readonly type: 'input';
+    readonly description: string;
+}
+/** `[a, b]` */
+ | {
+    readonly type: 'pair';
+    readonly default?: readonly [number, number];
+    readonly description: string;
+}
+/** A number (all axes) or `[x, y, z]` / `[x, y, z, w]`. */
+ | {
+    readonly type: 'vec';
+    readonly default?: number;
+    readonly description: string;
+}
+/** `[[x, y], …]`, x increasing. */
+ | {
+    readonly type: 'points';
+    readonly description: string;
+};
+export type NodeCategory = 'source' | 'fractal' | 'combine' | 'shape' | 'domain' | 'constant';
+export interface NodeDef {
+    readonly name: string;
+    readonly category: NodeCategory;
+    readonly description: string;
+    /** The output range, for docs. */
+    readonly range: string;
+    /**
+     * `params`: an object of parameters. `list`: an array of two or more inputs. `unary`: one input,
+     * written bare or as `{ "input": … }`. `value`: a number.
+     */
+    readonly form: 'params' | 'list' | 'unary' | 'value';
+    readonly params: Readonly<Record<string, ParamDef>>;
+    /** A typical use, shown in the schema and the docs. */
+    readonly example: unknown;
+}
+export declare const SOURCE_KINDS: readonly ['value', 'perlin', 'simplex', 'cellular'];
+export type SourceKind = (typeof SOURCE_KINDS)[number];
+export declare const CELL_DISTANCES: readonly ['euclidean', 'manhattan', 'chebyshev'];
+export declare const CELL_RETURNS: readonly ['f1', 'f2', 'f2-f1', 'cell'];
+/** Largest octave count a fractal may have (`noise/too-many-octaves`). */
+export declare const MAX_OCTAVES = 16;
+export declare const NODE_DEFS: readonly NodeDef[];
+export declare function nodeDef(name: string): NodeDef | undefined;