@nayan-ui/engine 0.0.0-stage → 1.0.0-beta.3

package/lib/module/assets/modelling.js

@@ -0,0 +1,254 @@
+"use strict";
+
+// Declarative solid modelling and native mesh preparation. These produce ordinary Geometry,
+// so solids, lathes, lofts, imported geometry and hand-authored parts compose through merge().
+import NativeEngine from '../native/NativeNayanEngine';
+import { preparedModel, prepareOptions, smoothNormals } from "./shape.js";
+const vector = v => [v[0], v[1], v[2]];
+
+/**
+ * An immutable, code-authored solid. Join primitives into a single surface, blend organic forms,
+ * drill holes, hollow shells and add reproducible rock/terrain detail before tessellating once.
+ * Distances use world units; primitives are centered at the origin, cylinders/tori use the Y axis.
+ *
+ * const torso = Solid.ellipsoid([0.5, 0.7, 0.3]).paint([0.5, 0.1, 0.9]);
+ * const neck = Solid.capsule([0, 0.5, 0], [0, 0.9, 0], 0.15);
+ * const geometry = solidGeometry(torso.blend(neck, 0.15), { resolution: 48 });
+ */
+export class Solid {
+  constructor(node) {
+    this.node = node;
+  }
+  static sphere(radius = 0.5) {
+    return new Solid({
+      kind: 'sphere',
+      radius
+    });
+  }
+  static ellipsoid(radii) {
+    return new Solid({
+      kind: 'ellipsoid',
+      radii: vector(radii)
+    });
+  }
+  /** Full width/height/depth. Rounding stays inside these dimensions. */
+  static box(size, radius = 0) {
+    return new Solid({
+      kind: 'box',
+      size: vector(size),
+      radius
+    });
+  }
+  static capsule(start, end, radius) {
+    return new Solid({
+      kind: 'capsule',
+      start: vector(start),
+      end: vector(end),
+      radius
+    });
+  }
+  static cylinder(radius, height) {
+    return new Solid({
+      kind: 'cylinder',
+      radius,
+      height
+    });
+  }
+  /** Major radius to the tube center; minor radius of the tube itself. */
+  static torus(radius, tube) {
+    return new Solid({
+      kind: 'torus',
+      radius,
+      tube
+    });
+  }
+  /** Balanced union for many parts; avoids building a deeply nested operation chain. */
+  static union(...solids) {
+    if (solids.length === 0) throw new Error('Solid.union needs at least one solid');
+    if (solids.length === 1) return solids[0];
+    const middle = Math.floor(solids.length / 2);
+    return Solid.union(...solids.slice(0, middle)).union(Solid.union(...solids.slice(middle)));
+  }
+  union(other) {
+    return new Solid({
+      kind: 'union',
+      a: this.node,
+      b: other.node,
+      blend: 0
+    });
+  }
+  /** Smoothly weld overlapping forms; blend controls the transition width in world units. */
+  blend(other, blend) {
+    return new Solid({
+      kind: 'union',
+      a: this.node,
+      b: other.node,
+      blend
+    });
+  }
+  subtract(other) {
+    return new Solid({
+      kind: 'subtract',
+      a: this.node,
+      b: other.node
+    });
+  }
+  intersect(other) {
+    return new Solid({
+      kind: 'intersect',
+      a: this.node,
+      b: other.node
+    });
+  }
+  translate(position) {
+    return this.transform(position, [0, 0, 0, 1], [1, 1, 1]);
+  }
+  rotate(rotation) {
+    return this.transform([0, 0, 0], rotation, [1, 1, 1]);
+  }
+  scale(scale) {
+    return this.transform([0, 0, 0], [0, 0, 0, 1], typeof scale === 'number' ? [scale, scale, scale] : scale);
+  }
+  transform(position, rotation, scale) {
+    return new Solid({
+      kind: 'transform',
+      child: this.node,
+      position: vector(position),
+      rotation: [...rotation],
+      scale: vector(scale)
+    });
+  }
+  /** Vertex colors blend with the surface at smooth joins. Apply after subtract() to color cut walls. */
+  paint(color) {
+    return new Solid({
+      kind: 'paint',
+      child: this.node,
+      color: [color[0], color[1], color[2]]
+    });
+  }
+  /** A shell centered on the original surface; thickness is its full wall thickness. */
+  shell(thickness) {
+    return new Solid({
+      kind: 'shell',
+      child: this.node,
+      thickness
+    });
+  }
+  /** Seeded fractal value noise. Use a resolution fine enough to sample its smallest features. */
+  displace(options) {
+    return new Solid({
+      kind: 'displace',
+      child: this.node,
+      amplitude: options.amplitude,
+      frequency: options.frequency ?? 2,
+      seed: options.seed ?? 0,
+      octaves: options.octaves ?? 3
+    });
+  }
+  /** Serializable recipe for caching or inspecting a generated asset. */
+  toJSON() {
+    return this.node;
+  }
+}
+function unpack(buffers) {
+  if (!(buffers.vertices instanceof ArrayBuffer) || !(buffers.indices instanceof ArrayBuffer)) throw new Error('modelling: invalid native geometry result');
+  return {
+    vertices: new Float32Array(buffers.vertices),
+    indices: new Uint32Array(buffers.indices)
+  };
+}
+
+/** Tessellates into editable, unregistered geometry. Prefer createSolid() for automatic model reuse. */
+export function solidGeometry(solid, options = {}) {
+  if (typeof NativeEngine?.geometrySolid !== 'function') throw new Error("solidGeometry: rebuild the app with the engine's native modelling tools");
+  return unpack(NativeEngine.geometrySolid(JSON.stringify({
+    solid,
+    resolution: options.resolution ?? 48,
+    uv: options.uv ?? 'xy'
+  })));
+}
+
+/**
+ * Tessellates, cleans and registers a solid once, then returns its cached model on later calls
+ * with the same recipe/options. White vertex colors can be tinted per spawned entity. Temporary
+ * intermediate meshes consume no IDs. Prepared solids persist automatically when platform storage
+ * is available; storage failure falls back to building. Call after warmUpEngine(), before spawning a run.
+ */
+export function createSolid(solid, options = {}) {
+  if (typeof NativeEngine?.solidPrepare !== 'function') throw new Error("createSolid: rebuild the app with the engine's Rust asset preparation");
+  const {
+    resolution = 48,
+    uv = 'xy',
+    shine = 0,
+    optimize = true
+  } = options;
+  const mesh = NativeEngine.solidPrepare(JSON.stringify({
+    solid,
+    resolution,
+    uv
+  }), prepareOptions({
+    ...options,
+    optimize
+  }));
+  if (mesh < 0) throw new Error(`createSolid: ${NativeEngine.loadError()}`);
+  return preparedModel(mesh, shine);
+}
+const wholeBuffer = array => array.byteOffset === 0 && array.byteLength === array.buffer.byteLength ? array.buffer : array.slice().buffer;
+
+/**
+ * Returns new geometry, preserving the input and its normal/color/UV seams. Removes degenerate
+ * triangles and unused/identical vertices, simplifies within the error bound, then orders buffers
+ * for GPU reuse. The error bound may prevent reaching the requested ratio. Opaque static meshes only:
+ * do not use on skinning buffers or meshes whose vertex indices are used by external code.
+ */
+export function optimizeGeometry(geometry, options = {}) {
+  if (typeof NativeEngine?.geometryOptimize !== 'function') throw new Error("optimizeGeometry: rebuild the app with the engine's native modelling tools");
+  return unpack(NativeEngine.geometryOptimize(wholeBuffer(geometry.vertices), wholeBuffer(geometry.indices), options.ratio ?? 1, options.error ?? 0.001, options.lockBorders ?? true));
+}
+
+/**
+ * Independently simplifies the original at each requested ratio, avoiding accumulated error.
+ * Cache/register the results once. The caller selects a level when camera distance changes.
+ */
+export function createGeometryLods(geometry, ratios = [1, 0.5, 0.25], options = {}) {
+  if (ratios.length === 0 || ratios.some((r, i) => !Number.isFinite(r) || r <= 0 || r > 1 || i > 0 && r >= ratios[i - 1])) throw new Error('createGeometryLods: ratios must strictly decrease within (0, 1]');
+  return ratios.map(ratio => optimizeGeometry(geometry, {
+    ...options,
+    ratio
+  }));
+}
+/** Cheap counts and bounds without registering a mesh. */
+export function getGeometryStats(geometry) {
+  const v = geometry.vertices;
+  const min = [Infinity, Infinity, Infinity];
+  const max = [-Infinity, -Infinity, -Infinity];
+  for (let i = 0; i < v.length; i += 11) for (let k = 0; k < 3; k++) {
+    min[k] = Math.min(min[k], v[i + k]);
+    max[k] = Math.max(max[k], v[i + k]);
+  }
+  return {
+    vertices: v.length / 11,
+    triangles: geometry.indices.length / 3,
+    bytes: v.byteLength + geometry.indices.byteLength,
+    bounds: v.length ? {
+      min,
+      max,
+      size: [max[0] - min[0], max[1] - min[1], max[2] - min[2]]
+    } : null
+  };
+}
+
+/** Copies/sculpts one smooth surface and updates its normals. Deform hard-edged parts separately. */
+export function deformGeometry(geometry, deform) {
+  const vertices = geometry.vertices.slice();
+  for (let i = 0; i < vertices.length; i += 11) {
+    const point = deform([vertices[i], vertices[i + 1], vertices[i + 2]], [vertices[i + 9], vertices[i + 10]]);
+    if (point.some(v => !Number.isFinite(v))) throw new Error('deformGeometry: position must be finite');
+    vertices.set(point, i);
+  }
+  return smoothNormals({
+    vertices,
+    indices: geometry.indices.slice()
+  });
+}
+//# sourceMappingURL=modelling.js.map