@aethervtt/shard-noise 0.0.1

package/dist/nodes.js

@@ -0,0 +1,366 @@
+const SOURCE_KINDS = ["value", "perlin", "simplex", "cellular"];
+const CELL_DISTANCES = ["euclidean", "manhattan", "chebyshev"];
+const CELL_RETURNS = ["f1", "f2", "f2-f1", "cell"];
+const MAX_OCTAVES = 16;
+const seed = {
+  type: "integer",
+  default: 0,
+  min: 0,
+  max: 4294967295,
+  description: "Layer seed, mixed with the seed the graph is sampled with. Changing it changes only this layer."
+};
+const frequency = {
+  type: "number",
+  default: 1,
+  positive: true,
+  description: "Features per unit of distance. 1 means one lattice cell per unit."
+};
+const dims = (values) => ({
+  type: "enum",
+  values,
+  default: 3,
+  description: `Dimensions sampled: ${values.join(", ")}. 2 reads x and y only; 4 needs a 4D graph.`
+});
+const cellular = {
+  distance: {
+    type: "enum",
+    values: CELL_DISTANCES,
+    default: "euclidean",
+    description: "Distance metric to feature points."
+  },
+  return: {
+    type: "enum",
+    values: CELL_RETURNS,
+    default: "f1",
+    description: "f1: distance to the nearest point. f2: to the second nearest. f2-f1: cell edges (0 on a border). cell: a random value per cell in [-1, 1]."
+  },
+  jitter: {
+    type: "number",
+    default: 1,
+    min: 0,
+    max: 1,
+    description: "How far feature points move from cell centers: 0 is a regular grid."
+  }
+};
+const input = (description) => ({ type: "input", description });
+const fractal = (name, description, range, example) => ({
+  name,
+  category: "fractal",
+  description,
+  range,
+  form: "params",
+  params: {
+    source: {
+      type: "enum",
+      values: SOURCE_KINDS,
+      default: "simplex",
+      description: "The source summed per octave."
+    },
+    octaves: {
+      type: "integer",
+      default: 4,
+      min: 1,
+      max: MAX_OCTAVES,
+      description: `Layers summed, 1 to ${MAX_OCTAVES}. Each adds detail at lacunarity \xD7 the previous frequency.`
+    },
+    frequency: { ...frequency, description: "Frequency of the first octave." },
+    lacunarity: {
+      type: "number",
+      default: 2,
+      positive: true,
+      description: "Frequency multiplier per octave (usually 2)."
+    },
+    gain: {
+      type: "number",
+      default: 0.5,
+      positive: true,
+      description: "Amplitude multiplier per octave (0.5 halves each; higher is rougher)."
+    },
+    seed,
+    dims: dims([2, 3, 4]),
+    ...cellular
+  },
+  example
+});
+const shape = (def) => ({
+  category: "shape",
+  form: "params",
+  ...def
+});
+const NODE_DEFS = [
+  {
+    name: "value",
+    category: "source",
+    description: "Value noise: random values on a lattice, smoothly interpolated. Blocky, cheap.",
+    range: "[-1, 1], mean 0",
+    form: "params",
+    params: { seed, frequency, dims: dims([2, 3]) },
+    example: { value: { frequency: 4, seed: 1 } }
+  },
+  {
+    name: "perlin",
+    category: "source",
+    description: "Perlin gradient noise: smooth, with a slight grid alignment.",
+    range: "[-1, 1], mean 0",
+    form: "params",
+    params: { seed, frequency, dims: dims([2, 3]) },
+    example: { perlin: { frequency: 2, seed: 1 } }
+  },
+  {
+    name: "simplex",
+    category: "source",
+    description: "Simplex noise: smooth and isotropic, the usual choice. 3D uses the OpenSimplex2 lattice; 2D and 4D the classic simplex lattice.",
+    range: "[-1, 1], mean 0",
+    form: "params",
+    params: { seed, frequency, dims: dims([2, 3, 4]) },
+    example: { simplex: { frequency: 1, seed: 1 } }
+  },
+  {
+    name: "cellular",
+    category: "source",
+    description: "Cellular (Worley) noise: distances to jittered feature points, one per cell. Cracks, cells, pebbles.",
+    range: "euclidean f1 [0, 1.25] (mean \u2248 0.43 in 2D, 0.52 in 3D); f2 [0, 1.5] (mean \u2248 0.70); f2-f1 [0, 1.25] (mean \u2248 0.2 in 3D); manhattan distances reach 2 and chebyshev 1; cell [-1, 1], mean 0",
+    form: "params",
+    params: { seed, frequency, dims: dims([2, 3]), ...cellular },
+    example: { cellular: { frequency: 3, return: "f2-f1" } }
+  },
+  fractal(
+    "fbm",
+    "Fractal Brownian motion: octaves of a source summed with falling amplitude. Continents, hills, clouds.",
+    "[-1, 1] (normalized by the sum of amplitudes), mean 0",
+    { fbm: { source: "simplex", octaves: 5, frequency: 0.8, gain: 0.5, seed: 1 } }
+  ),
+  fractal(
+    "ridged",
+    "Ridged multifractal: (1 \u2212 |n|)\xB2 per octave, so zero crossings become sharp ridges. Mountains.",
+    "[-1, 1], ridges near 1",
+    { ridged: { source: "simplex", octaves: 6, frequency: 3.2, seed: 2 } }
+  ),
+  fractal(
+    "billow",
+    "Billow: 2|n| \u2212 1 per octave, so valleys become creases. Puffy clouds, rolling hills.",
+    "[-1, 1]",
+    { billow: { source: "simplex", octaves: 4, frequency: 2, seed: 3 } }
+  ),
+  {
+    name: "add",
+    category: "combine",
+    description: "Sum of two or more inputs.",
+    range: "sum of the input ranges",
+    form: "list",
+    params: {},
+    example: { add: ["continents", { multiply: ["mountains", "mask"] }] }
+  },
+  {
+    name: "multiply",
+    category: "combine",
+    description: "Product of two or more inputs. Multiply by a 0\u20131 mask to fade a layer in and out.",
+    range: "product of the input ranges",
+    form: "list",
+    params: {},
+    example: { multiply: ["mountains", "mask"] }
+  },
+  {
+    name: "min",
+    category: "combine",
+    description: "Smallest of two or more inputs.",
+    range: "within the input ranges",
+    form: "list",
+    params: {},
+    example: { min: ["a", "b"] }
+  },
+  {
+    name: "max",
+    category: "combine",
+    description: "Largest of two or more inputs.",
+    range: "within the input ranges",
+    form: "list",
+    params: {},
+    example: { max: ["a", 0] }
+  },
+  {
+    name: "lerp",
+    category: "combine",
+    description: "a + t \xD7 (b \u2212 a): blends a toward b by t (0 gives a, 1 gives b).",
+    range: "between a and b for t in [0, 1]",
+    form: "params",
+    params: { a: input("Value at t = 0."), b: input("Value at t = 1."), t: input("Blend factor.") },
+    example: { lerp: { a: "plains", b: "mountains", t: "mask" } }
+  },
+  {
+    name: "select",
+    category: "combine",
+    description: "a where control is below threshold, b above it, blended smoothly over \xB1falloff (0 is a hard edge).",
+    range: "between a and b",
+    form: "params",
+    params: {
+      a: input("Value below the threshold."),
+      b: input("Value above the threshold."),
+      control: input("What decides between a and b."),
+      threshold: { type: "number", default: 0, description: "Where control switches from a to b." },
+      falloff: {
+        type: "number",
+        default: 0,
+        min: 0,
+        description: "Half-width of the smooth blend around the threshold."
+      }
+    },
+    example: {
+      select: { a: "ocean", b: "land", control: "continents", threshold: 0.1, falloff: 0.05 }
+    }
+  },
+  shape({
+    name: "remap",
+    description: "Linearly maps [from\u2080, from\u2081] to [to\u2080, to\u2081], optionally clamped. Builds masks.",
+    range: "to (when clamped)",
+    params: {
+      input: input("The value to map."),
+      from: { type: "pair", default: [-1, 1], description: "Input range." },
+      to: { type: "pair", default: [0, 1], description: "Output range." },
+      clamp: {
+        type: "boolean",
+        default: false,
+        description: "Clamp the result to the output range."
+      }
+    },
+    example: { remap: { input: "continents", from: [0.1, 0.4], to: [0, 1], clamp: true } }
+  }),
+  shape({
+    name: "clamp",
+    description: "Limits the input to [min, max].",
+    range: "[min, max]",
+    params: {
+      input: input("The value to clamp."),
+      min: { type: "number", default: -1, description: "Lower bound." },
+      max: { type: "number", default: 1, description: "Upper bound." }
+    },
+    example: { clamp: { input: "height", min: 0, max: 1 } }
+  }),
+  shape({
+    name: "curve",
+    description: "Piecewise-linear curve through control points, flat beyond the first and last. Reshapes a height profile.",
+    range: "the points\u2019 y range",
+    params: {
+      input: input("The value to reshape."),
+      points: {
+        type: "points",
+        description: "Control points [[x, y], \u2026], x increasing, at least two."
+      }
+    },
+    example: {
+      curve: {
+        input: "height",
+        points: [
+          [-1, -1],
+          [0, -0.2],
+          [0.5, 0.3],
+          [1, 1]
+        ]
+      }
+    }
+  }),
+  shape({
+    name: "terrace",
+    description: "Quantizes the input into steps with sloped risers. Mesas, rice terraces, strata.",
+    range: "range",
+    params: {
+      input: input("The value to terrace."),
+      steps: {
+        type: "integer",
+        default: 4,
+        min: 1,
+        max: 256,
+        description: "Steps across the range."
+      },
+      range: { type: "pair", default: [-1, 1], description: "The input range the steps span." },
+      sharpness: {
+        type: "number",
+        default: 0.5,
+        min: 0,
+        max: 1,
+        description: "0 leaves the input linear; 1 makes vertical risers."
+      }
+    },
+    example: { terrace: { input: "hills", steps: 6, sharpness: 0.7 } }
+  }),
+  shape({
+    name: "abs",
+    description: "Absolute value.",
+    range: "[0, max |input|]",
+    form: "unary",
+    params: { input: input("The value.") },
+    example: { abs: "ridges" }
+  }),
+  shape({
+    name: "power",
+    description: "sign(x) \xD7 |x|^exponent. Exponents above 1 flatten low values and sharpen peaks.",
+    range: "same sign as the input",
+    params: {
+      input: input("The base."),
+      exponent: { type: "number", default: 2, description: "The exponent." }
+    },
+    example: { power: { input: "mask", exponent: 3 } }
+  }),
+  {
+    name: "constant",
+    category: "constant",
+    description: "A fixed value. A bare number anywhere an input goes means the same.",
+    range: "the value",
+    form: "value",
+    params: {},
+    example: { constant: 0.5 }
+  },
+  {
+    name: "warp",
+    category: "domain",
+    description: "Domain warp: samples input at a position displaced by `by` (read three times with independent seeds, one per axis) \xD7 amount. Makes layers swirl and flow.",
+    range: "the input\u2019s",
+    form: "params",
+    params: {
+      input: input("What is sampled at the displaced position."),
+      by: input("The displacement source (usually a low-frequency fbm)."),
+      amount: {
+        type: "number",
+        default: 0.1,
+        description: "Displacement in domain units at |by| = 1."
+      }
+    },
+    example: { warp: { input: "mountains", by: "continents", amount: 0.15 } }
+  },
+  {
+    name: "scale",
+    category: "domain",
+    description: "The input sees the position multiplied by `by`: 2 doubles every frequency below it. A vector scales axes separately.",
+    range: "the input\u2019s",
+    form: "params",
+    params: {
+      input: input("What sees the scaled position."),
+      by: { type: "vec", default: 1, description: "Scale: a number, or [x, y, z] (and w in 4D)." }
+    },
+    example: { scale: { input: "hills", by: [1, 0.25, 1] } }
+  },
+  {
+    name: "translate",
+    category: "domain",
+    description: "The input sees the position moved by `by`. Offsets two otherwise identical layers.",
+    range: "the input\u2019s",
+    form: "params",
+    params: {
+      input: input("What sees the moved position."),
+      by: { type: "vec", default: 0, description: "Offset: a number, or [x, y, z] (and w in 4D)." }
+    },
+    example: { translate: { input: "hills", by: [100, 0, 0] } }
+  }
+];
+const byName = new Map(NODE_DEFS.map((d) => [d.name, d]));
+function nodeDef(name) {
+  return byName.get(name);
+}
+export {
+  CELL_DISTANCES,
+  CELL_RETURNS,
+  MAX_OCTAVES,
+  NODE_DEFS,
+  SOURCE_KINDS,
+  nodeDef
+};

package/dist/noise-graph.d.ts

@@ -0,0 +1,80 @@
+import { AssetStore } from '@aethervtt/shard-assets';
+import { type JsonValue } from '@aethervtt/shard-core';
+import { type NoiseProgram } from './compile.js';
+import { type ParsedGraph } from './graph.js';
+/** A program as JSON: what the importer writes and loading copies back into typed arrays. */
+export interface ProgramJson {
+    code: number[];
+    consts: number[];
+    registers: number;
+    result: number;
+    dimensions: 2 | 3 | 4;
+    terms: {
+        a: number[];
+        b: number[];
+        skew: number[];
+    };
+}
+/** The `noise` importer's artifact: the source graph, its program, the WGSL, and a hash. */
+export interface NoiseGraphArtifact {
+    format: 1;
+    name: string;
+    module: string;
+    source: JsonValue;
+    program: ProgramJson;
+    wgsl: string;
+    hash: string;
+}
+/** The WGSL function name (`noise_<name>`) and module path (`noise::…`) for an asset path. */
+export declare function noiseNames(path: string): {
+    name: string;
+    module: string;
+};
+/**
+ * A noise graph ready to sample: the validated graph, its compiled program (what the CPU kernel
+ * runs), and its WGSL module (what shaders import). One JSON source gives both the same function.
+ */
+export declare class NoiseGraph {
+    /** Bumps on hot reload. */
+    version: number;
+    private nodePrograms;
+    /** The graph file's JSON (without `$schema`). */
+    source: JsonValue;
+    graph: ParsedGraph;
+    /** What the CPU kernel runs. */
+    program: NoiseProgram;
+    /** Function suffix: the WGSL exports `noise_<name>` and `noise_<name>_at`. */
+    name: string;
+    /** WGSL module path, e.g. `noise::assets::noise::planet`. */
+    module: string;
+    wgsl: string;
+    /** Hash of the program: equal hashes sample equal values. */
+    hash: string;
+    constructor(source: JsonValue, graph: ParsedGraph, program: NoiseProgram, name: string, module: string, wgsl: string, hash: string);
+    /** The WGSL function for positions near the origin. */
+    get fn(): string;
+    /** Parses, validates, and compiles a graph. Throws its first error, with the rest in `details`. */
+    static fromJson(json: unknown, options?: {
+        name?: string;
+        module?: string;
+    }): NoiseGraph;
+    /** `fromJson` once the kernel is loaded, so the graph can be sampled synchronously. */
+    static create(json: unknown, options?: {
+        name?: string;
+        module?: string;
+    }): Promise<NoiseGraph>;
+    static fromArtifact(artifact: NoiseGraphArtifact): NoiseGraph;
+    toArtifact(): NoiseGraphArtifact;
+    /** The program with `node` as its output (the graph's own output by default), for previews. */
+    programFor(node?: string): NoiseProgram;
+    /** Hot reload: takes `next`'s graph, program, and WGSL, and bumps `version`. */
+    copyFrom(next: NoiseGraph): void;
+}
+export declare class NoiseGraphStore extends AssetStore<NoiseGraph, 'NoiseGraph'> {
+    constructor();
+}
+export declare const NoiseGraphs: import("@aethervtt/shard-core").ResourceDef<NoiseGraphStore>;
+export declare const NoiseGraphAssetType: import("@aethervtt/shard-assets").AssetTypeDef<NoiseGraph>;
+/** `*.noise.json`: a noise graph, validated with pointers into the file and compiled. */
+export declare const NoiseGraphImporter: import("@aethervtt/shard-assets").ImporterDef;
+export declare const noiseGraphSchema: () => unknown;

package/dist/noise-graph.js

@@ -0,0 +1,258 @@
+import {
+  AssetStore,
+  defineAssetSchema,
+  defineAssetType,
+  defineImporter
+} from "@aethervtt/shard-assets";
+import { defineResource, defineSchema, ShardError } from "@aethervtt/shard-core";
+import { compileGraph } from "./compile.js";
+import { parseGraph } from "./graph.js";
+import { computeOrigins } from "./kernel.js";
+import { loadNoiseKernel } from "./loader.js";
+import { noiseJsonSchema } from "./schema.js";
+import { generateWgsl } from "./wgsl.js";
+function noiseNames(path) {
+  const clean = (s) => {
+    const t = s.toLowerCase().replace(/[^a-z0-9_]/g, "_");
+    return /^[a-z_]/.test(t) ? t : `_${t}`;
+  };
+  const segments = path.replace(/\.noise\.json$/, "").split("/").filter(Boolean).map(clean);
+  const name = segments[segments.length - 1] ?? "graph";
+  return { name, module: `noise::${segments.join("::") || "graph"}` };
+}
+function throwFirst(errors) {
+  const first = errors[0];
+  throw new ShardError(
+    first.code,
+    `${first.message}${errors.length > 1 ? ` (+${errors.length - 1} more)` : ""}`,
+    { path: first.path, hint: first.hint, details: errors }
+  );
+}
+function fnv(h, bytes) {
+  for (let i = 0; i < bytes.length; i++) h = Math.imul(h ^ bytes[i], 16777619);
+  return h >>> 0;
+}
+function programHash(p) {
+  const parts = [
+    new Uint8Array(p.code.buffer, p.code.byteOffset, p.code.byteLength),
+    new Uint8Array(p.consts.buffer, p.consts.byteOffset, p.consts.byteLength),
+    new Uint8Array(p.terms.a.buffer, p.terms.a.byteOffset, p.terms.a.byteLength),
+    new Uint8Array(p.terms.b.buffer, p.terms.b.byteOffset, p.terms.b.byteLength),
+    p.terms.skew,
+    new Uint8Array([
+      p.registers & 255,
+      p.registers >> 8,
+      p.result & 255,
+      p.result >> 8,
+      p.dimensions
+    ])
+  ];
+  let a = 2166136261;
+  let b = 2538058380;
+  for (const part of parts) {
+    a = fnv(a, part);
+    b = fnv(b ^ 1540483477, part);
+  }
+  return a.toString(16).padStart(8, "0") + b.toString(16).padStart(8, "0");
+}
+function programFromJson(p) {
+  const terms = {
+    a: new Float64Array(p.terms.a),
+    b: new Float64Array(p.terms.b),
+    skew: new Uint8Array(p.terms.skew)
+  };
+  const zeroOrigins = new Int32Array(terms.skew.length * 8);
+  computeOrigins(terms, [0, 0, 0, 0], zeroOrigins);
+  const code = new Int32Array(p.code);
+  return {
+    code,
+    consts: new Float32Array(p.consts),
+    registers: p.registers,
+    result: p.result,
+    dimensions: p.dimensions,
+    terms,
+    zeroOrigins,
+    instructions: code.length / 12
+  };
+}
+function programToJson(p) {
+  return {
+    code: [...p.code],
+    consts: [...p.consts],
+    registers: p.registers,
+    result: p.result,
+    dimensions: p.dimensions,
+    terms: { a: [...p.terms.a], b: [...p.terms.b], skew: [...p.terms.skew] }
+  };
+}
+class NoiseGraph {
+  /** Bumps on hot reload. */
+  version = 0;
+  nodePrograms = /* @__PURE__ */ new Map();
+  /** The graph file's JSON (without `$schema`). */
+  source;
+  graph;
+  /** What the CPU kernel runs. */
+  program;
+  /** Function suffix: the WGSL exports `noise_<name>` and `noise_<name>_at`. */
+  name;
+  /** WGSL module path, e.g. `noise::assets::noise::planet`. */
+  module;
+  wgsl;
+  /** Hash of the program: equal hashes sample equal values. */
+  hash;
+  constructor(source, graph, program, name, module, wgsl, hash) {
+    this.source = source;
+    this.graph = graph;
+    this.program = program;
+    this.name = name;
+    this.module = module;
+    this.wgsl = wgsl;
+    this.hash = hash;
+  }
+  /** The WGSL function for positions near the origin. */
+  get fn() {
+    return `noise_${this.name}`;
+  }
+  /** Parses, validates, and compiles a graph. Throws its first error, with the rest in `details`. */
+  static fromJson(json, options = {}) {
+    let source = json;
+    if (source && typeof source === "object" && !Array.isArray(source) && "$schema" in source) {
+      const { $schema: _, ...rest } = source;
+      source = rest;
+    }
+    const { graph, errors } = parseGraph(source);
+    if (!graph) throwFirst(errors);
+    const program = compileGraph(graph);
+    const names = options.name ? { name: options.name, module: options.module ?? `noise::${options.name}` } : noiseNames("graph");
+    const wgsl = generateWgsl(program, { name: names.name });
+    return new NoiseGraph(
+      source,
+      graph,
+      program,
+      names.name,
+      names.module,
+      wgsl,
+      programHash(program)
+    );
+  }
+  /** `fromJson` once the kernel is loaded, so the graph can be sampled synchronously. */
+  static async create(json, options = {}) {
+    await loadNoiseKernel();
+    return NoiseGraph.fromJson(json, options);
+  }
+  static fromArtifact(artifact) {
+    const { graph, errors } = parseGraph(artifact.source);
+    if (!graph) throwFirst(errors);
+    return new NoiseGraph(
+      artifact.source,
+      graph,
+      programFromJson(artifact.program),
+      artifact.name,
+      artifact.module,
+      artifact.wgsl,
+      artifact.hash
+    );
+  }
+  toArtifact() {
+    return {
+      format: 1,
+      name: this.name,
+      module: this.module,
+      source: this.source,
+      program: programToJson(this.program),
+      wgsl: this.wgsl,
+      hash: this.hash
+    };
+  }
+  /** The program with `node` as its output (the graph's own output by default), for previews. */
+  programFor(node) {
+    if (node === void 0 || node === this.graph.output) return this.program;
+    let p = this.nodePrograms.get(node);
+    if (!p) {
+      p = compileGraph(this.graph, node);
+      this.nodePrograms.set(node, p);
+    }
+    return p;
+  }
+  /** Hot reload: takes `next`'s graph, program, and WGSL, and bumps `version`. */
+  copyFrom(next) {
+    this.source = next.source;
+    this.graph = next.graph;
+    this.program = next.program;
+    this.name = next.name;
+    this.module = next.module;
+    this.wgsl = next.wgsl;
+    this.hash = next.hash;
+    this.nodePrograms = /* @__PURE__ */ new Map();
+    this.version++;
+  }
+}
+class NoiseGraphStore extends AssetStore {
+  constructor() {
+    super("NoiseGraph");
+  }
+}
+const NoiseGraphs = defineResource("noise/NoiseGraphs", {
+  description: "Loaded noise graphs by guid.",
+  init: () => new NoiseGraphStore()
+});
+const NoiseGraphAssetType = defineAssetType("NoiseGraph", {
+  store: NoiseGraphs,
+  // The kernel loads with the first graph, so every loaded graph can be sampled synchronously.
+  load: async (artifact) => {
+    await loadNoiseKernel();
+    return NoiseGraph.fromArtifact(artifact.json);
+  },
+  update: (existing, next) => existing.copyFrom(next)
+});
+const NoSettings = defineSchema(
+  "noise/NoSettings",
+  {},
+  { description: "None: the graph is the file." }
+);
+const NoiseGraphImporter = defineImporter({
+  name: "noise",
+  version: 1,
+  extensions: [".noise.json"],
+  settings: NoSettings,
+  async import(source) {
+    let json;
+    try {
+      json = JSON.parse(source.text());
+    } catch (cause) {
+      throw new ShardError("assets/import-failed", `${source.path} isn't valid JSON`, {
+        path: source.path,
+        cause
+      });
+    }
+    const names = noiseNames(source.path);
+    const graph = NoiseGraph.fromJson(json, names);
+    return {
+      assets: [
+        {
+          label: "",
+          type: "NoiseGraph",
+          json: graph.toArtifact(),
+          info: {
+            nodes: graph.graph.nodes.size,
+            instructions: graph.program.instructions,
+            octaves: graph.program.terms.skew.length,
+            module: graph.module,
+            function: graph.fn
+          }
+        }
+      ]
+    };
+  }
+});
+const noiseGraphSchema = defineAssetSchema("noise.schema.json", noiseJsonSchema);
+export {
+  NoiseGraph,
+  NoiseGraphAssetType,
+  NoiseGraphImporter,
+  NoiseGraphStore,
+  NoiseGraphs,
+  noiseGraphSchema,
+  noiseNames
+};