@nayan-ui/engine 1.0.0-beta.4 → 1.0.0-beta.6

package/lib/module/assets/procedural.js

@@ -0,0 +1,500 @@
+"use strict";
+
+// Data-driven procedural worlds and meshes, built by the native core. A game describes its fields
+// (terrain height, material contours, walkable clearance, placement rules, model surfaces) with a
+// `FieldGraph`, puts them in a recipe, and the core generates terrain, scenery, reachable ground and
+// picked spots, and answers walker queries, without any of that work running in JavaScript.
+
+import NativeEngine from '../native/NativeNayanEngine';
+/** A node of a field graph. Plain numbers are constants wherever a field is expected. */
+export class FieldRef {
+  constructor(id) {
+    this.id = id;
+  }
+}
+
+/** A 2D primitive in a field's (x, z) plane; `offset` is subtracted from its distance, `width` is its fade length. */
+
+/**
+ * Builds a field graph: generic math and geometry nodes evaluated by the native core. Shared nodes
+ * are computed once per sample point and `select` evaluates only the branch it takes.
+ *
+ * ```ts
+ * const f = new FieldGraph();
+ * const bank = f.sub(f.abs(f.sub(f.x, f.sines(f.x, f.z, 10, [[0, 0.035, 0, 11]]))), 5);
+ * f.output('bank', bank);
+ * ```
+ */
+export class FieldGraph {
+  nodes = [];
+  outputs = {};
+  constants = new Map();
+  inputs = new Map();
+  node(node) {
+    this.nodes.push(node);
+    return new FieldRef(this.nodes.length - 1);
+  }
+  ref(value) {
+    return (value instanceof FieldRef ? value : this.constant(value)).id;
+  }
+  refs(values) {
+    return values.map(v => this.ref(v));
+  }
+  constant(value) {
+    if (!Number.isFinite(value)) throw new Error('FieldGraph: constants must be finite');
+    let ref = this.constants.get(value);
+    if (!ref || Object.is(value, -0) !== Object.is(this.nodes[ref.id]?.value, -0)) {
+      ref = this.node({
+        op: 'const',
+        value
+      });
+      this.constants.set(value, ref);
+    }
+    return ref;
+  }
+  /** A named input: `x`/`z` (local frame) for terrain fields; u, v, row, col, i, count, r0… elsewhere. */
+  input(name) {
+    let ref = this.inputs.get(name);
+    if (!ref) {
+      ref = this.node({
+        op: 'var',
+        name
+      });
+      this.inputs.set(name, ref);
+    }
+    return ref;
+  }
+  get x() {
+    return this.input('x');
+  }
+  get z() {
+    return this.input('z');
+  }
+  add(a, b) {
+    return this.node({
+      op: 'add',
+      a: this.ref(a),
+      b: this.ref(b)
+    });
+  }
+  sub(a, b) {
+    return this.node({
+      op: 'sub',
+      a: this.ref(a),
+      b: this.ref(b)
+    });
+  }
+  mul(a, b) {
+    return this.node({
+      op: 'mul',
+      a: this.ref(a),
+      b: this.ref(b)
+    });
+  }
+  div(a, b) {
+    return this.node({
+      op: 'div',
+      a: this.ref(a),
+      b: this.ref(b)
+    });
+  }
+  /** a + b + c… left to right. */
+  sum(...values) {
+    if (!values.length) return this.constant(0);
+    let total = values[0] instanceof FieldRef ? values[0] : this.constant(values[0]);
+    for (const value of values.slice(1)) total = this.add(total, value);
+    return total;
+  }
+  /** a · b · c… left to right. */
+  product(...values) {
+    if (!values.length) return this.constant(1);
+    let total = values[0] instanceof FieldRef ? values[0] : this.constant(values[0]);
+    for (const value of values.slice(1)) total = this.mul(total, value);
+    return total;
+  }
+  min(...args) {
+    return this.node({
+      op: 'min',
+      args: this.refs(args)
+    });
+  }
+  max(...args) {
+    return this.node({
+      op: 'max',
+      args: this.refs(args)
+    });
+  }
+  neg(a) {
+    return this.node({
+      op: 'neg',
+      a: this.ref(a)
+    });
+  }
+  abs(a) {
+    return this.node({
+      op: 'abs',
+      a: this.ref(a)
+    });
+  }
+  sqrt(a) {
+    return this.node({
+      op: 'sqrt',
+      a: this.ref(a)
+    });
+  }
+  floor(a) {
+    return this.node({
+      op: 'floor',
+      a: this.ref(a)
+    });
+  }
+  square(a) {
+    return this.node({
+      op: 'square',
+      a: this.ref(a)
+    });
+  }
+  sin(a) {
+    return this.node({
+      op: 'sin',
+      a: this.ref(a)
+    });
+  }
+  cos(a) {
+    return this.node({
+      op: 'cos',
+      a: this.ref(a)
+    });
+  }
+  exp(a) {
+    return this.node({
+      op: 'exp',
+      a: this.ref(a)
+    });
+  }
+  /** `a` to the power `b`. */
+  pow(a, b) {
+    return this.node({
+      op: 'pow',
+      a: this.ref(a),
+      b: this.ref(b)
+    });
+  }
+  /** `a − floor(a)`. */
+  fract(a) {
+    return this.node({
+      op: 'fract',
+      a: this.ref(a)
+    });
+  }
+  /**
+   * Value noise in 0..1 on a unit lattice: the common sine-hash shader noise, smoothstep-blended.
+   * With `period`, it repeats every `period` cells in x (to wrap around a lathe without a seam).
+   */
+  noise(x, z, period = 0) {
+    return this.node({
+      op: 'noise',
+      x: this.ref(x),
+      z: this.ref(z),
+      period
+    });
+  }
+  /** a + (b − a) · t, componentwise on numbers or fields. */
+  mix(a, b, t) {
+    return this.add(a, this.mul(this.sub(b, a), t));
+  }
+  hypot(...args) {
+    return this.node({
+      op: 'hypot',
+      args: this.refs(args)
+    });
+  }
+  /** Hermite smoothstep of `a` clamped to 0..1. */
+  smooth(a) {
+    return this.node({
+      op: 'smooth',
+      a: this.ref(a)
+    });
+  }
+  clamp(a, lo, hi) {
+    return this.node({
+      op: 'clamp',
+      a: this.ref(a),
+      lo: this.ref(lo),
+      hi: this.ref(hi)
+    });
+  }
+  /** `le` where `test` <= 0, otherwise `gt` (only the chosen branch is evaluated). */
+  select(test, le, gt) {
+    return this.node({
+      op: 'select',
+      test: this.ref(test),
+      le: this.ref(le),
+      gt: this.ref(gt)
+    });
+  }
+  /** base + Σ amp · sin(fx·x + fz·z + phase), terms as [fx, fz, phase, amp]. */
+  sines(x, z, base, terms) {
+    return this.node({
+      op: 'sines',
+      x: this.ref(x),
+      z: this.ref(z),
+      base,
+      terms
+    });
+  }
+  /** Σ height · max(0, 1 − u² − v²)^power over oriented ellipses [x, z, height, radiusU, radiusV, yaw]. */
+  bumps(x, z, items, power = 2) {
+    return this.node({
+      op: 'bumps',
+      x: this.ref(x),
+      z: this.ref(z),
+      items,
+      power
+    });
+  }
+  /** The smallest signed distance to the shapes (minus each one's offset); +∞ with none. */
+  distance(x, z, shapes) {
+    return this.node({
+      op: 'distance',
+      x: this.ref(x),
+      z: this.ref(z),
+      shapes
+    });
+  }
+  /** Π smoothstep((distance − offset) / width): 0 at the shapes, 1 beyond their fade. */
+  falloff(x, z, shapes) {
+    return this.node({
+      op: 'falloff',
+      x: this.ref(x),
+      z: this.ref(z),
+      shapes
+    });
+  }
+  /** The largest depth inside any of the boxes (min of side clearances, minus offset); −∞ with none. */
+  depth(x, z, shapes) {
+    return this.node({
+      op: 'depth',
+      x: this.ref(x),
+      z: this.ref(z),
+      shapes
+    });
+  }
+
+  /** Names a field so recipes can refer to it. Returns the name. */
+  output(name, value) {
+    this.outputs[name] = this.ref(value);
+    return name;
+  }
+  toJSON() {
+    return {
+      nodes: this.nodes,
+      outputs: this.outputs
+    };
+  }
+}
+
+// Field functions: per-point model functions (colors, displacement) evaluated by the native core.
+
+/**
+ * A function of named inputs written as a field graph, for model options that would otherwise call
+ * a JS function per vertex: `lathe`/`tube`/`loft` colors and `lathe` displacement, `recolor`. Build
+ * one with `surfaceColor`, `faceColor`, `sectionColor` or `surfaceDisplacement`.
+ */
+export class FieldFunction {
+  constructor(fields, outputs) {
+    this.fields = fields;
+    this.outputs = outputs;
+  }
+  toJSON() {
+    return {
+      fields: this.fields,
+      out: Array.from({
+        length: this.outputs
+      }, (_, i) => `out${i}`)
+    };
+  }
+}
+function fieldFunction(names, build) {
+  const f = new FieldGraph();
+  const inputs = Object.fromEntries(names.map(name => [name, f.input(name)]));
+  const result = build(f, inputs);
+  const out = Array.isArray(result) ? result : [result];
+  out.forEach((value, i) => f.output(`out${i}`, value));
+  return new FieldFunction(f, out.length);
+}
+
+/**
+ * A color of each surface point: `u`, `v` (texture coordinates; around and along a lathe or tube),
+ * position `x`, `y`, `z` and normal `nx`, `ny`, `nz`. Returns [r, g, b].
+ */
+export const surfaceColor = build => fieldFunction(['u', 'v', 'x', 'y', 'z', 'nx', 'ny', 'nz'], build);
+/** A color across a round end face: `r` from its center (0) to its rim (1), `angle` around it (radians). */
+export const faceColor = build => fieldFunction(['r', 'angle'], build);
+/** A color across a lathe's cut face: `r` from the axis (0) to the skin (1) at that height, and the height `y`. */
+export const sectionColor = build => fieldFunction(['r', 'y'], build);
+/** A lathe's displacement along its normal at (`u` around, `v` down the profile). */
+export const surfaceDisplacement = build => fieldFunction(['u', 'v'], build);
+
+// Recipes (mirrors of the native core's schema).
+
+const engine = () => {
+  const native = NativeEngine;
+  if (!native) throw new Error('procedural worlds: the native core is not linked into this build');
+  if (typeof native.worldgenBuild !== 'function') throw new Error("procedural worlds: this app's native core predates them: rebuild it");
+  return native;
+};
+const recipeText = recipe => JSON.stringify(recipe, (_key, value) => value instanceof FieldGraph ? value.toJSON() : value);
+const geometry = buffers => ({
+  vertices: new Float32Array(buffers.vertices),
+  indices: new Uint32Array(buffers.indices)
+});
+const spots = points => points.map(([x, z]) => ({
+  x,
+  z
+}));
+const bodyBuffers = new Map();
+
+/** A generated world held by the native core; queries take world coordinates. */
+export class ProceduralWorld {
+  /** True when it was restored from storage rather than generated. */
+
+  fields = new Map();
+  disposed = false;
+  constructor(handle) {
+    this.handle = handle;
+    const info = JSON.parse(engine().worldgenInfo(handle));
+    this.spawn = {
+      x: info.spawn[0],
+      z: info.spawn[1]
+    };
+    this.restored = info.restored;
+    this.layers = info.layers;
+    this.picks = Object.fromEntries(Object.entries(info.picks).map(([name, points]) => [name, spots(points)]));
+  }
+  get id() {
+    if (this.disposed) throw new Error('ProceduralWorld: used after dispose');
+    return this.handle;
+  }
+
+  /** A scatter layer's items: [x, y, z, ...attributes] per item (see `layers[name].stride`). */
+  layer(name) {
+    return new Float64Array(engine().worldgenLayer(this.id, name));
+  }
+  /** Reachable cells as [x, z] pairs. */
+  reachable() {
+    return new Float64Array(engine().worldgenReachable(this.id));
+  }
+  /** The overview step's surface codes, row by row (0 outside the walk boundary). */
+  overview() {
+    return new Uint8Array(engine().worldgenOverview(this.id));
+  }
+  /** Re-picks the spots for run `run` (0 = as generated); false keeps the previous ones. */
+  pick(run) {
+    const native = engine();
+    if (!native.worldgenPick(this.id, run)) return false;
+    const info = JSON.parse(native.worldgenInfo(this.id));
+    this.picks = Object.fromEntries(Object.entries(info.picks).map(([name, points]) => [name, spots(points)]));
+    return true;
+  }
+  /** The terrain mesh of `material` (built once; each material is handed over once). */
+  terrain(material) {
+    return geometry(engine().worldgenTerrain(this.id, material));
+  }
+  ground(x, z) {
+    return engine().worldgenGround(this.id, x, z);
+  }
+  surface(x, z) {
+    return engine().worldgenSurface(this.id, x, z);
+  }
+  /** The platform (recipe index) under a point, or -1. */
+  platformAt(x, z) {
+    return engine().worldgenPlatform(this.id, x, z);
+  }
+  walkable(x, z, radius) {
+    return engine().worldgenWalkable(this.id, x, z, radius);
+  }
+  /** How far a walker of `radius` is from anything blocking it (negative when blocked). */
+  clearance(x, z, radius) {
+    return engine().worldgenClearance(this.id, x, z, radius);
+  }
+  solidClearance(x, z, radius, bottom, top) {
+    return engine().worldgenSolidClearance(this.id, x, z, radius, bottom, top);
+  }
+  /** A named field of the recipe at a world point. */
+  field(name, x, z) {
+    let index = this.fields.get(name);
+    if (index === undefined) {
+      index = engine().worldgenFieldIndex(this.id, name);
+      if (index < 0) throw new Error(`ProceduralWorld: no field named ${name}`);
+      this.fields.set(name, index);
+    }
+    return engine().worldgenField(this.id, index, x, z);
+  }
+  /** The ground's tilt as a quaternion [x, y, z, w], in a frame turned by `yaw`. */
+  tilt(x, z, yaw = 0) {
+    return engine().worldgenTilt(this.id, x, z, yaw);
+  }
+  /** Whether a walker of `radius` could walk straight from a to b, ends at most `rise` apart in height. */
+  canSee(a, b, {
+    radius = 0.25,
+    step = 0.4,
+    rise = Infinity
+  } = {}) {
+    return engine().worldgenSight(this.id, a.x, a.z, b.x, b.z, radius, step, rise === Infinity ? Number.MAX_VALUE : rise);
+  }
+  /** Sweeps a walker by (dx, dz), sliding along obstacles and other `bodies`; updates `point`. */
+  move(point, dx, dz, radius, bodies = []) {
+    let buffer = bodyBuffers.get(bodies.length);
+    if (!buffer) bodyBuffers.set(bodies.length, buffer = new Float64Array(bodies.length * 3));
+    for (let i = 0; i < bodies.length; i++) {
+      const b = bodies[i];
+      buffer[i * 3] = b.x;
+      buffer[i * 3 + 1] = b.z;
+      buffer[i * 3 + 2] = b.radius;
+    }
+    const [x, z] = engine().worldgenMove(this.id, point.x, point.z, dx, dz, radius, buffer.buffer);
+    point.x = x;
+    point.z = z;
+  }
+  dispose() {
+    if (this.disposed) return;
+    this.disposed = true;
+    engine().worldgenFree(this.handle);
+  }
+}
+const opened = handle => {
+  if (!handle) throw new Error(`procedural world: ${engine().worldgenError() || 'generation failed'}`);
+  return new ProceduralWorld(handle);
+};
+
+/** Generates (or restores, see `WorldOptions.key`) a world on this thread. */
+export function generateWorld(recipe, options = {}) {
+  return opened(engine().worldgenBuild(recipeText(recipe), options.key ?? '', options.prepareTerrain ?? false));
+}
+
+/** `generateWorld` on a background native thread (the web core builds at once). */
+export async function generateWorldAsync(recipe, options = {}) {
+  return opened(await engine().worldgenBuildAsync(recipeText(recipe), options.key ?? '', options.prepareTerrain ?? false));
+}
+
+/** Whether a world was saved under `key` (cheap: doesn't read the world). */
+export function isWorldKept(key) {
+  return engine().worldgenKept(key);
+}
+
+/** Builds a procedural mesh (parametric surfaces and seeded cards) in the native core. */
+export function generateMesh(recipe) {
+  return geometry(engine().worldgenMesh(recipeText(recipe)));
+}
+
+/** Recolors geometry in place (and returns it) by a `surfaceColor`, in the native core. */
+export function paintGeometry(geometry, color) {
+  const v = geometry.vertices;
+  const whole = v.byteOffset === 0 && v.byteLength === v.buffer.byteLength;
+  const buffer = whole ? v.buffer : v.slice().buffer;
+  if (!engine().worldgenPaint(buffer, JSON.stringify(color))) throw new Error(`recolor: ${engine().worldgenError()}`);
+  if (!whole) v.set(new Float32Array(buffer));
+  return geometry;
+}
+//# sourceMappingURL=procedural.js.map