@aethervtt/shard-noise 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Patrick Dias
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,3 @@
+# @aethervtt/shard-noise
+
+Part of [Shard](https://github.com/aethervtt/shard), a WebGPU-first 2D/3D game engine in TypeScript. See the repository for documentation.

package/dist/compile.d.ts

@@ -0,0 +1,61 @@
+import { type ParsedGraph } from './graph.js';
+import { type OriginTerms } from './kernel.js';
+/** i32 words per instruction: `[op, dst, a, b, c, d, e, f, k, n, seed, salt]`. */
+export declare const WIDTH = 12;
+/** Registers 0–3 hold the local position (x, y, z, w). */
+export declare const POSITION_REGS = 4;
+/** Opcodes, matching `crates/shard-noise/src/program.rs`. */
+export declare const OP: {
+    readonly CONST: 0;
+    readonly SOURCE: 1;
+    readonly ADD: 2;
+    readonly MUL: 3;
+    readonly MIN: 4;
+    readonly MAX: 5;
+    readonly LERP: 6;
+    readonly SELECT: 7;
+    readonly REMAP: 8;
+    readonly CLAMP: 9;
+    readonly CURVE: 10;
+    readonly TERRACE: 11;
+    readonly ABS: 12;
+    readonly POWER: 13;
+    readonly WARP: 14;
+    readonly SCALE_DISP: 15;
+};
+export declare const FRACTAL: {
+    readonly NONE: 0;
+    readonly FBM: 1;
+    readonly RIDGED: 2;
+    readonly BILLOW: 3;
+};
+/** Skew applied to a source's lattice coordinates: none, or the simplex skew for 2, 3, or 4 dims. */
+export declare const SKEW: {
+    readonly NONE: 0;
+    readonly SIMPLEX2: 2;
+    readonly SIMPLEX3: 3;
+    readonly SIMPLEX4: 4;
+};
+/**
+ * A compiled graph: instructions in topological order, their constants in one Float32Array, and one
+ * origin term per source octave (how that octave's lattice position depends on the sample origin).
+ */
+export interface NoiseProgram {
+    readonly code: Int32Array;
+    readonly consts: Float32Array;
+    /** Registers the program uses (each holds one block of points). */
+    readonly registers: number;
+    /** The register holding the result. */
+    readonly result: number;
+    readonly dimensions: 2 | 3 | 4;
+    readonly terms: OriginTerms;
+    /** Origin records for sampling at absolute positions (origin zero). */
+    readonly zeroOrigins: Int32Array;
+    /** Instructions: `code.length / WIDTH`. */
+    readonly instructions: number;
+}
+/**
+ * Compiles a parsed graph (or one of its nodes, for previews) into a program. Throws the first
+ * error with the rest in `details`.
+ */
+export declare function compileGraph(graph: ParsedGraph, output?: string): NoiseProgram;

package/dist/compile.js

@@ -0,0 +1,375 @@
+import { hashSeed, ShardError } from "@aethervtt/shard-core";
+import { pointer } from "./graph.js";
+import { computeOrigins } from "./kernel.js";
+import { CELL_DISTANCES, CELL_RETURNS, SOURCE_KINDS } from "./nodes.js";
+const WIDTH = 12;
+const POSITION_REGS = 4;
+const OP = {
+  CONST: 0,
+  SOURCE: 1,
+  ADD: 2,
+  MUL: 3,
+  MIN: 4,
+  MAX: 5,
+  LERP: 6,
+  SELECT: 7,
+  REMAP: 8,
+  CLAMP: 9,
+  CURVE: 10,
+  TERRACE: 11,
+  ABS: 12,
+  POWER: 13,
+  WARP: 14,
+  SCALE_DISP: 15
+};
+const FRACTAL = { NONE: 0, FBM: 1, RIDGED: 2, BILLOW: 3 };
+const SKEW = { NONE: 0, SIMPLEX2: 2, SIMPLEX3: 3, SIMPLEX4: 4 };
+const ctxKey = (s, t, disp, salt) => `${s.join(",")}|${t.join(",")}|${disp}|${salt}`;
+const ROOT = {
+  s: [1, 1, 1, 1],
+  t: [0, 0, 0, 0],
+  disp: -1,
+  salt: 0,
+  key: ctxKey([1, 1, 1, 1], [0, 0, 0, 0], -1, 0)
+};
+const fround = Math.fround;
+const I32_LIMIT = 2 ** 31;
+const SKEW_GROWTH = [1, 1, 1.52, 1, 1.62];
+class Compiler {
+  code = [];
+  consts = [];
+  a = [];
+  b = [];
+  skew = [];
+  errors = [];
+  registers = POSITION_REGS;
+  memo = /* @__PURE__ */ new Map();
+  constRegs = /* @__PURE__ */ new Map();
+  ids = /* @__PURE__ */ new WeakMap();
+  nextId = 0;
+  stack = [];
+  graph;
+  constructor(graph) {
+    this.graph = graph;
+  }
+  reg(count = 1) {
+    const r = this.registers;
+    this.registers += count;
+    return r;
+  }
+  konst(values) {
+    const k = this.consts.length;
+    for (const v of values) this.consts.push(fround(v));
+    return k;
+  }
+  emit(op, dst, ins = [], k = 0, n = 0, seed = 0, salt = 0) {
+    const w = [op, dst, -1, -1, -1, -1, -1, -1, k, n, seed | 0, salt | 0];
+    for (let i = 0; i < ins.length; i++) w[2 + i] = ins[i];
+    this.code.push(...w);
+  }
+  constant(value) {
+    const v = fround(value);
+    let r = this.constRegs.get(v);
+    if (r === void 0) {
+      r = this.reg();
+      this.emit(OP.CONST, r, [], this.konst([v]));
+      this.constRegs.set(v, r);
+    }
+    return r;
+  }
+  input(input, ctx) {
+    if (input.kind === "const") return this.constant(input.value);
+    if (input.kind === "ref") return this.named(input.name, ctx);
+    return this.node(input.node, ctx);
+  }
+  named(name, ctx) {
+    const key = `n:${name}@${ctx.key}`;
+    const hit = this.memo.get(key);
+    if (hit !== void 0) return hit;
+    const node = this.graph.nodes.get(name);
+    this.stack.push(name);
+    const r = this.build(node, ctx);
+    this.stack.pop();
+    this.memo.set(key, r);
+    return r;
+  }
+  node(node, ctx) {
+    let id = this.ids.get(node);
+    if (id === void 0) {
+      id = this.nextId++;
+      this.ids.set(node, id);
+    }
+    const key = `i:${id}@${ctx.key}`;
+    const hit = this.memo.get(key);
+    if (hit !== void 0) return hit;
+    const r = this.build(node, ctx);
+    this.memo.set(key, r);
+    return r;
+  }
+  build(node, ctx) {
+    const p = node.params;
+    const inp = (name) => this.input(p[name], ctx);
+    const num = (name) => p[name];
+    switch (node.type) {
+      case "value":
+      case "perlin":
+      case "simplex":
+      case "cellular":
+        return this.source(node, node.type, FRACTAL.NONE, ctx);
+      case "fbm":
+        return this.source(node, p.source, FRACTAL.FBM, ctx);
+      case "ridged":
+        return this.source(node, p.source, FRACTAL.RIDGED, ctx);
+      case "billow":
+        return this.source(node, p.source, FRACTAL.BILLOW, ctx);
+      case "add":
+      case "multiply":
+      case "min":
+      case "max": {
+        const op = { add: OP.ADD, multiply: OP.MUL, min: OP.MIN, max: OP.MAX }[node.type];
+        const inputs = p.inputs.map((i) => this.input(i, ctx));
+        let acc = inputs[0];
+        for (let i = 1; i < inputs.length; i++) {
+          const dst = this.reg();
+          this.emit(op, dst, [acc, inputs[i]]);
+          acc = dst;
+        }
+        return acc;
+      }
+      case "lerp": {
+        const [a, b, t] = [inp("a"), inp("b"), inp("t")];
+        const dst = this.reg();
+        this.emit(OP.LERP, dst, [a, b, t]);
+        return dst;
+      }
+      case "select": {
+        const [a, b, c] = [inp("a"), inp("b"), inp("control")];
+        const th = num("threshold");
+        const fo = num("falloff");
+        const dst = this.reg();
+        this.emit(
+          OP.SELECT,
+          dst,
+          [a, b, c],
+          this.konst([th, fo, th - fo, fo > 0 ? 1 / (2 * fo) : 0])
+        );
+        return dst;
+      }
+      case "remap": {
+        const a = inp("input");
+        const [f0, f1] = p.from;
+        const [t0, t1] = p.to;
+        const scale = f1 === f0 ? 0 : (t1 - t0) / (f1 - f0);
+        const dst = this.reg();
+        this.emit(
+          OP.REMAP,
+          dst,
+          [a],
+          this.konst([f0, t0, scale, Math.min(t0, t1), Math.max(t0, t1)]),
+          p.clamp ? 1 : 0
+        );
+        return dst;
+      }
+      case "clamp": {
+        const a = inp("input");
+        const dst = this.reg();
+        this.emit(OP.CLAMP, dst, [a], this.konst([num("min"), num("max")]));
+        return dst;
+      }
+      case "curve": {
+        const a = inp("input");
+        const pts = p.points;
+        const values = [];
+        for (let i = 0; i + 1 < pts.length; i++) {
+          const [x0, y0] = pts[i];
+          const [x1, y1] = pts[i + 1];
+          const fx0 = fround(x0);
+          const fy0 = fround(y0);
+          values.push(fx0, fy0, 1 / (fround(x1) - fx0), fround(y1) - fy0);
+        }
+        const dst = this.reg();
+        this.emit(OP.CURVE, dst, [a], this.konst(values), pts.length);
+        return dst;
+      }
+      case "terrace": {
+        const a = inp("input");
+        const [lo, hi] = p.range;
+        const steps = num("steps");
+        const span = hi - lo || 1;
+        const dst = this.reg();
+        this.emit(
+          OP.TERRACE,
+          dst,
+          [a],
+          this.konst([lo, steps / span, 1 / Math.max(1 - num("sharpness"), 1e-4), span / steps])
+        );
+        return dst;
+      }
+      case "abs": {
+        const a = inp("input");
+        const dst = this.reg();
+        this.emit(OP.ABS, dst, [a]);
+        return dst;
+      }
+      case "power": {
+        const a = inp("input");
+        const dst = this.reg();
+        this.emit(OP.POWER, dst, [a], this.konst([num("exponent")]));
+        return dst;
+      }
+      case "constant":
+        return this.constant(num("value"));
+      case "warp": {
+        const by = p.by;
+        const channels = [];
+        for (let axis = 0; axis < this.graph.dimensions; axis++) {
+          const salt = axis === 0 ? ctx.salt : hashSeed(ctx.salt, axis + 1) || 1;
+          channels.push(
+            this.input(by, axis === 0 ? ctx : this.withCtx(ctx, ctx.s, ctx.t, ctx.disp, salt))
+          );
+        }
+        while (channels.length < 4) channels.push(-1);
+        const disp = this.reg(4);
+        this.emit(OP.WARP, disp, [ctx.disp, ...channels], this.konst([num("amount")]));
+        return this.input(p.input, this.withCtx(ctx, ctx.s, ctx.t, disp, ctx.salt));
+      }
+      case "scale": {
+        const by = p.by;
+        const s = ctx.s.map((v, i) => v * by[i]);
+        const t = ctx.t.map((v, i) => v * by[i]);
+        let disp = ctx.disp;
+        if (disp >= 0) {
+          const dst = this.reg(4);
+          this.emit(OP.SCALE_DISP, dst, [disp], this.konst(by));
+          disp = dst;
+        }
+        return this.input(p.input, this.withCtx(ctx, s, t, disp, ctx.salt));
+      }
+      case "translate": {
+        const by = p.by;
+        const t = ctx.t.map((v, i) => v + by[i]);
+        return this.input(p.input, this.withCtx(ctx, ctx.s, t, ctx.disp, ctx.salt));
+      }
+    }
+    throw new ShardError("noise/unknown-type", `No compiler for node type "${node.type}"`, {
+      path: node.path
+    });
+  }
+  withCtx(_ctx, s, t, disp, salt) {
+    return { s, t, disp, salt, key: ctxKey(s, t, disp, salt) };
+  }
+  source(node, kind, fractal, ctx) {
+    const p = node.params;
+    const dims = p.dims;
+    const octaves = fractal === FRACTAL.NONE ? 1 : p.octaves;
+    const freq = p.frequency;
+    const lacunarity = fractal === FRACTAL.NONE ? 1 : p.lacunarity;
+    const gain = fractal === FRACTAL.NONE ? 1 : p.gain;
+    const kindIndex = SOURCE_KINDS.indexOf(kind);
+    const skew = kind === "simplex" ? dims : SKEW.NONE;
+    const metric = CELL_DISTANCES.indexOf(p.distance ?? "euclidean");
+    const ret = CELL_RETURNS.indexOf(p.return ?? "f1");
+    let ampSum = 0;
+    const amps = [];
+    for (let o = 0; o < octaves; o++) {
+      const amp = fround(gain ** o);
+      amps.push(amp);
+      ampSum += amp;
+    }
+    const values = [p.jitter ?? 1, 1 / ampSum];
+    const originBase = this.skew.length;
+    for (let o = 0; o < octaves; o++) {
+      const f = freq * lacunarity ** o;
+      for (let axis = 0; axis < 4; axis++) {
+        const a = axis < dims ? fround(f * ctx.s[axis]) : 0;
+        values.push(a);
+        this.a.push(a);
+        this.b.push(axis < dims ? f * ctx.t[axis] : 0);
+      }
+      values.push(f, amps[o]);
+      this.skew.push(skew);
+      this.checkRange(node, dims, skew, originBase + o);
+    }
+    const dst = this.reg();
+    this.emit(
+      OP.SOURCE,
+      dst,
+      [ctx.disp, originBase, kindIndex, dims, fractal, metric | ret << 4],
+      this.konst(values),
+      octaves,
+      p.seed >>> 0,
+      ctx.salt
+    );
+    return dst;
+  }
+  /** With an extent, every lattice coordinate must fit an i32 at that distance. */
+  checkRange(node, dims, skew, term) {
+    const extent = this.graph.extent;
+    if (extent === void 0) return;
+    let worst = 0;
+    for (let axis = 0; axis < dims; axis++) {
+      worst = Math.max(
+        worst,
+        Math.abs(this.a[term * 4 + axis]) * extent + Math.abs(this.b[term * 4 + axis])
+      );
+    }
+    worst *= SKEW_GROWTH[skew];
+    if (worst >= I32_LIMIT) {
+      const where = this.stack.length > 0 ? `/nodes/${pointer(this.stack[this.stack.length - 1])}` : node.path;
+      this.errors.push(
+        new ShardError(
+          "noise/frequency-too-high",
+          `A frequency in "${node.type}" reaches lattice cell ${worst.toExponential(2)} at extent ${extent}, past what an i32 cell holds (2\xB3\xB9)`,
+          {
+            path: node.path.startsWith("/nodes/") ? node.path : where,
+            hint: "Lower the frequency or octaves: features that fine are invisible anywhere they apply at this extent."
+          }
+        )
+      );
+    }
+  }
+}
+function compileGraph(graph, output = graph.output) {
+  if (!graph.nodes.has(output)) {
+    throw new ShardError("noise/unknown-node", `"${output}" isn't a node in this graph`, {
+      path: "/output",
+      hint: `Nodes: ${[...graph.nodes.keys()].join(", ")}.`
+    });
+  }
+  const c = new Compiler(graph);
+  const result = c.named(output, ROOT);
+  if (c.errors.length > 0) {
+    const first = c.errors[0];
+    throw new ShardError(first.code, first.message, {
+      path: first.path,
+      hint: first.hint,
+      details: c.errors
+    });
+  }
+  const terms = {
+    a: new Float64Array(c.a),
+    b: new Float64Array(c.b),
+    skew: new Uint8Array(c.skew)
+  };
+  const zeroOrigins = new Int32Array(terms.skew.length * 8);
+  computeOrigins(terms, ZERO, zeroOrigins);
+  return {
+    code: new Int32Array(c.code),
+    consts: new Float32Array(c.consts),
+    registers: c.registers,
+    result,
+    dimensions: graph.dimensions,
+    terms,
+    zeroOrigins,
+    instructions: c.code.length / WIDTH
+  };
+}
+const ZERO = new Float64Array(4);
+export {
+  FRACTAL,
+  OP,
+  POSITION_REGS,
+  SKEW,
+  WIDTH,
+  compileGraph
+};

package/dist/gpu.d.ts

@@ -0,0 +1,11 @@
+import type { ShaderLibrary } from '@aethervtt/shard-shader';
+import type { NoiseGraph } from './noise-graph.js';
+/** Module path of the shared sources and helpers. */
+export declare const NOISE_LIBRARY_PATH = "shard::noise";
+/** Registers `shard::noise` once. */
+export declare function registerNoiseLibrary(library: ShaderLibrary): void;
+/**
+ * Registers a graph's module (`graph.module`, exporting `noise_<name>` and `noise_<name>_at`).
+ * Registering a changed graph relinks every shader that imports it; an unchanged one is a no-op.
+ */
+export declare function registerNoiseGraph(library: ShaderLibrary, graph: NoiseGraph, origin?: string): void;

package/dist/gpu.js

@@ -0,0 +1,15 @@
+import { NOISE_LIBRARY } from "./wgsl.js";
+const NOISE_LIBRARY_PATH = "shard::noise";
+function registerNoiseLibrary(library) {
+  if (!library.has(NOISE_LIBRARY_PATH))
+    library.register(NOISE_LIBRARY_PATH, NOISE_LIBRARY, "@aethervtt/shard-noise");
+}
+function registerNoiseGraph(library, graph, origin) {
+  registerNoiseLibrary(library);
+  library.register(graph.module, graph.wgsl, origin ?? graph.module);
+}
+export {
+  NOISE_LIBRARY_PATH,
+  registerNoiseGraph,
+  registerNoiseLibrary
+};

package/dist/graph.d.ts

@@ -0,0 +1,44 @@
+import { ShardError } from '@aethervtt/shard-core';
+import { type NodeDef } from './nodes.js';
+/** Where a node input comes from: another named node, an inline node, or a number. */
+export type GraphInput = {
+    readonly kind: 'ref';
+    readonly name: string;
+    readonly path: string;
+} | {
+    readonly kind: 'node';
+    readonly node: GraphNode;
+} | {
+    readonly kind: 'const';
+    readonly value: number;
+};
+export type ParamValue = number | boolean | string | readonly number[] | readonly (readonly [number, number])[] | GraphInput | readonly GraphInput[];
+/** A node with its parameters filled in from the table's defaults. */
+export interface GraphNode {
+    readonly type: string;
+    readonly def: NodeDef;
+    readonly params: Readonly<Record<string, ParamValue>>;
+    /** JSON pointer to the node's body (`/nodes/mask/remap`). */
+    readonly path: string;
+}
+export interface ParsedGraph {
+    readonly output: string;
+    /** 3 unless the file says 2 or 4. A 4D graph reads w; 4D sources need one. */
+    readonly dimensions: 2 | 3 | 4;
+    /** Largest distance from the origin the graph is sampled at (a planet's radius), if set. */
+    readonly extent: number | undefined;
+    readonly description: string | undefined;
+    readonly nodes: ReadonlyMap<string, GraphNode>;
+}
+/** Escapes a JSON pointer segment. */
+export declare function pointer(segment: string): string;
+/**
+ * Parses and validates a `*.noise.json` graph. Returns every error found (each with a JSON
+ * pointer), and the graph when there are none.
+ */
+export declare function parseGraph(json: unknown): {
+    graph?: ParsedGraph;
+    errors: ShardError[];
+};
+/** Calls `f` on every node input, inline nodes included. */
+export declare function forEachInput(node: GraphNode, f: (input: GraphInput) => void): void;