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

package/lib/module/assets/ProceduralCache.js

@@ -0,0 +1,249 @@
+"use strict";
+
+import NativeEngine from '../native/NativeNayanEngine';
+import { meshInfo } from "../render/meshes.js";
+import { registerModelMesh } from "./model.js";
+import { proceduralStorage } from './storage';
+
+/** Optional storage override. The engine selects a best-effort platform cache by default. */
+
+const MAGIC = 0x3143504e; // NPC1: static vertices (11 floats) and u32 indices, little endian.
+const LIMIT = 32 * 1024 * 1024;
+// JSON is escaped to ASCII so Hermes hosts need no TextEncoder/TextDecoder polyfill.
+function encodeJson(value) {
+  const text = JSON.stringify(value).replace(/[\u007f-\uffff]/g, char => '\\u' + char.charCodeAt(0).toString(16).padStart(4, '0'));
+  const bytes = new Uint8Array(text.length);
+  for (let i = 0; i < text.length; i++) bytes[i] = text.charCodeAt(i);
+  return bytes;
+}
+function decodeJson(bytes) {
+  let text = '';
+  for (let i = 0; i < bytes.length; i += 4096) text += String.fromCharCode(...bytes.subarray(i, i + 4096));
+  return JSON.parse(text);
+}
+function checksum(bytes) {
+  let hash = 2166136261;
+  for (let i = 0; i < bytes.length; i++) hash = Math.imul(hash ^ bytes[i], 16777619);
+  return hash >>> 0;
+}
+
+/**
+ * Persists the output of a deterministic model factory, including nested model arrays/objects.
+ * Hits register saved vertices directly: no procedural tessellation, painting or optimization.
+ * Imported/skinned/textured models are intentionally excluded; their own loaders retain their rigs.
+ */
+export class ProceduralCache {
+  memory = new Map();
+  hits = 0;
+  builds = 0;
+  invalid = 0;
+  failures = 0;
+  writes = new Set();
+  constructor(revision, storage = proceduralStorage(revision)) {
+    this.revision = revision;
+    this.storage = storage;
+  }
+  get stats() {
+    return {
+      hits: this.hits,
+      builds: this.builds,
+      invalid: this.invalid,
+      failures: this.failures,
+      pendingWrites: this.writes.size
+    };
+  }
+  async flush() {
+    await Promise.all([...this.writes]);
+  }
+
+  /**
+   * A value already cached (in memory, or saved by an earlier launch), without building anything:
+   * undefined when there is none yet. Lets work that's spread over many frames (a level generated
+   * step by step) skip itself entirely when a saved result exists, then save with `get`.
+   */
+  peek(key) {
+    if (this.memory.has(key)) return this.memory.get(key);
+    if (!this.storage) return undefined;
+    try {
+      const bytes = this.storage.read(key);
+      if (!bytes) return undefined;
+      const value = this.restore(bytes, key);
+      this.memory.set(key, value);
+      this.hits++;
+      return value;
+    } catch {
+      this.invalid++;
+      return undefined;
+    }
+  }
+  get(key, build) {
+    if (this.memory.has(key)) return this.memory.get(key);
+    if (this.storage) {
+      try {
+        const bytes = this.storage.read(key);
+        if (bytes) {
+          try {
+            const value = this.restore(bytes, key);
+            this.memory.set(key, value);
+            this.hits++;
+            return value;
+          } catch {
+            this.invalid++;
+          }
+        }
+      } catch {
+        this.failures++;
+      }
+    }
+    const value = build();
+    this.builds++;
+    this.memory.set(key, value);
+    if (this.storage) {
+      try {
+        const result = this.storage.write(key, this.encode(value, key));
+        if (result) {
+          const pending = Promise.resolve(result).catch(() => {
+            this.failures++;
+          }).finally(() => {
+            this.writes.delete(pending);
+          });
+          this.writes.add(pending);
+        }
+      } catch {
+        this.failures++;
+      } // Storage/unsupported values never prevent a game from running.
+    }
+    return value;
+  }
+  encode(value, key) {
+    const models = [];
+    const ids = new Map();
+    const visit = v => {
+      if (v === undefined) return {
+        $undefined: true
+      };
+      if (v === null || typeof v === 'string' || typeof v === 'boolean') return v;
+      if (typeof v === 'number' && Number.isFinite(v)) return v;
+      if (Array.isArray(v)) return v.map(visit);
+      if (typeof v !== 'object' || !v || Object.getPrototypeOf(v) !== Object.prototype) throw Error('not a plain procedural asset');
+      const obj = v;
+      if (Number.isSafeInteger(obj.id) && Array.isArray(obj.size) && obj.size.length === 3) {
+        const model = v;
+        const info = meshInfo(model.id);
+        if (!info || info.texture !== undefined || 'jointCount' in obj || 'animations' in obj) throw Error('not a static procedural model');
+        let index = ids.get(model.id);
+        if (index === undefined) {
+          index = models.length;
+          ids.set(model.id, index);
+          models.push(model);
+        }
+        return {
+          $mesh: index
+        };
+      }
+      if (Number.isSafeInteger(obj.id)) throw Error('native handles cannot be persisted as plain data');
+      const result = {};
+      for (const name of Object.keys(obj)) {
+        if (name.startsWith('$')) throw Error('reserved cache key');
+        if (Object.getOwnPropertyDescriptor(obj, name)?.get) throw Error('lazy values must be cached separately');
+        result[name] = visit(obj[name]);
+      }
+      return result;
+    };
+    const root = visit(value);
+    const infos = models.map(model => meshInfo(model.id));
+    const header = {
+      revision: this.revision,
+      key,
+      value: root,
+      meshes: infos.map(info => ({
+        floats: info.geometry.vertices.length,
+        indices: info.geometry.indices.length,
+        shine: info.shine ?? 0
+      }))
+    };
+    const json = encodeJson(header);
+    const start = 16 + json.length + 3 & ~3;
+    const length = start + infos.reduce((sum, info) => sum + info.geometry.vertices.byteLength + info.geometry.indices.byteLength, 0);
+    if (length > LIMIT) throw Error('procedural asset too large');
+    const bytes = new Uint8Array(length),
+      view = new DataView(bytes.buffer);
+    view.setUint32(0, MAGIC, true);
+    view.setUint32(4, json.length, true);
+    view.setUint32(8, length, true);
+    bytes.set(json, 16);
+    let offset = start;
+    for (const {
+      geometry
+    } of infos) for (const data of [geometry.vertices, geometry.indices]) {
+      bytes.set(new Uint8Array(data.buffer, data.byteOffset, data.byteLength), offset);
+      offset += data.byteLength;
+    }
+    // A verifying store checksums the record itself: hashing every byte again in JS cost more than
+    // building small models.
+    view.setUint32(12, this.storage?.verified ? 0 : checksum(bytes.subarray(16)), true);
+    return bytes;
+  }
+  restore(raw, key) {
+    if (raw.length < 16 || raw.length > LIMIT) throw Error('cache size');
+    const bytes = raw.byteOffset % 4 ? raw.slice() : raw;
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    const jsonLength = view.getUint32(4, true);
+    if (view.getUint32(0, true) !== MAGIC || view.getUint32(8, true) !== bytes.length || jsonLength > bytes.length - 16 || !this.storage?.verified && view.getUint32(12, true) !== checksum(bytes.subarray(16))) throw Error('cache integrity');
+    const header = decodeJson(bytes.subarray(16, 16 + jsonLength));
+    if (!('value' in header) || header.revision !== this.revision || header.key !== key || !Array.isArray(header.meshes)) throw Error('cache revision');
+    let offset = 16 + jsonLength + 3 & ~3;
+    const payloads = [];
+    // Validate the complete record before registering any mesh (including the value's references).
+    for (const mesh of header.meshes) {
+      if (!Number.isSafeInteger(mesh.floats) || mesh.floats <= 0 || mesh.floats % 11 || !Number.isSafeInteger(mesh.indices) || mesh.indices <= 0 || mesh.indices % 3 || !Number.isFinite(mesh.shine) || mesh.shine < 0 || mesh.shine > 1) throw Error('cache geometry');
+      const end = offset + (mesh.floats + mesh.indices) * 4;
+      if (end > bytes.length) throw Error('cache truncated');
+      const vertices = new Float32Array(bytes.buffer, bytes.byteOffset + offset, mesh.floats);
+      const indices = new Uint32Array(bytes.buffer, bytes.byteOffset + offset + mesh.floats * 4, mesh.indices);
+      // A verified record is the one this cache wrote, and the core rejects bad geometry anyway:
+      // scanning millions of floats in JS was most of a relaunch's loading time.
+      if (!this.storage?.verified) {
+        for (const value of vertices) if (!Number.isFinite(value)) throw Error('cache vertex');
+        for (const index of indices) if (index >= mesh.floats / 11) throw Error('cache index');
+      }
+      payloads.push({
+        vertices,
+        indices,
+        shine: mesh.shine
+      });
+      offset = end;
+    }
+    if (offset !== bytes.length) throw Error('cache length');
+    const mapValue = (v, models) => {
+      if (v === null || typeof v !== 'object') return v;
+      if (Array.isArray(v)) return v.map(item => mapValue(item, models));
+      if ('$mesh' in v) {
+        const index = v.$mesh;
+        if (!Number.isSafeInteger(index) || typeof index !== 'number' || index < 0 || index >= header.meshes.length || Object.keys(v).length !== 1) throw Error('cache model reference');
+        return models?.[index];
+      }
+      if ('$undefined' in v) return undefined;
+      const result = {};
+      for (const name of Object.keys(v)) {
+        if (name.startsWith('$') || name === '__proto__') throw Error('cache value');
+        result[name] = mapValue(v[name], models);
+      }
+      return result;
+    };
+    mapValue(header.value);
+    if (!NativeEngine) throw Error('native engine unavailable');
+    const restored = payloads.map(mesh => {
+      let id = NativeEngine.meshCreate(mesh.vertices.slice().buffer, mesh.indices.slice().buffer);
+      if (id < 0) throw Error('cache registration');
+      id = registerModelMesh(id, mesh.shine);
+      const [x, y, z] = NativeEngine.modelSize(id);
+      return {
+        id,
+        size: [x, y, z]
+      };
+    });
+    return mapValue(header.value, restored);
+  }
+}
+//# sourceMappingURL=ProceduralCache.js.map

package/lib/module/assets/font.js

@@ -0,0 +1,139 @@
+"use strict";
+
+// Fonts for 3D text: each character becomes an extruded mesh, built by the Rust core.
+
+import { AssetLoader } from "./AssetLoader.js";
+import { registerCoreMesh } from "./model.js";
+/** Printable ASCII plus common arithmetic and typography, prewarmed for ordinary labels. */
+export const DEFAULT_CHARS = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz !"#$%&\'()*+,-./:;<=>?@[\\]^_`{|}~×÷±−°·•–—…‘’“”';
+
+/** A loaded font. Use it on an entity with `text`: `{ text: "2048", font }`. */
+
+const loader = new AssetLoader('loadFont');
+const extend = new WeakMap();
+
+// Format controls affect presentation, not glyph count or spacing. In particular, a text/emoji
+// variation selector must not append a second fallback question mark to a symbol.
+function isInvisible(ch) {
+  const code = ch.codePointAt(0);
+  return code >= 0x200b && code <= 0x200f || code >= 0x202a && code <= 0x202e || code >= 0x2060 && code <= 0x206f || code >= 0xfe00 && code <= 0xfe0f || code === 0xfeff || code >= 0xe0100 && code <= 0xe01ef;
+}
+const WHITESPACE = /\s/u;
+
+/**
+ * Initializes the engine automatically. Loads a TrueType / OpenType font (.ttf / .otf) for 3D text. The source/depth/weight are cached independently of the requested prewarm characters. Letters are real meshes: lit, shadowed,
+ * and every copy of a letter on screen is drawn in one call. At scale 1, letters are 1 unit tall (em).
+ * Additional Unicode glyphs are built on demand from the same font and cached. The font must contain
+ * an outline for the character; missing characters still use ?, including unsupported emoji.
+ *
+ * ```ts
+ * const font = await loadFont(require("./assets/Inter-Bold.ttf"), { chars: "0123456789" });
+ * world.spawn({ text: "2048", font, scale: 0.5, color: [1, 1, 1] });
+ * ```
+ */
+export function loadFont(source, options = {}) {
+  const depth = options.depth ?? 0.2;
+  const chars = [...new Set(`${options.chars ?? DEFAULT_CHARS} ?`.normalize('NFC'))].filter(ch => !isInvisible(ch)).join('');
+  const weight = options.weight ?? 0;
+  const pending = loader.load(source, (native, bytes) => {
+    // Outlines and glyph meshes are built on a background native thread where the app's build supports it.
+    if (typeof native.fontLoadAsync === 'function') return native.fontLoadAsync(bytes, depth, chars, weight).then(id => finish(native, bytes, id));
+    return finish(native, bytes, native.fontLoad(bytes, depth, chars, weight));
+  }, [depth, weight]);
+  /** The loaded font's glyphs, registered for drawing in Rust, and its on-demand extension. */
+  function finish(native, bytes, id) {
+    if (id < 0) throw new Error(native.loadError() || 'not a TrueType / OpenType font');
+    const glyphs = new Map();
+    const registered = new Set();
+    const read = fontId => {
+      const data = native.fontGlyphs(fontId);
+      for (let i = 0; i + 3 <= data.length - 1; i += 3) {
+        const mesh = data[i + 1];
+        if (mesh >= 0 && !registered.has(mesh)) {
+          registerCoreMesh(mesh);
+          registered.add(mesh);
+        }
+        glyphs.set(String.fromCodePoint(data[i]), {
+          mesh,
+          advance: data[i + 2]
+        });
+      }
+      return data[data.length - 1];
+    };
+    const font = {
+      id,
+      capHeight: read(id),
+      glyphs
+    };
+    const attempted = new Set(chars);
+    extend.set(font, text => {
+      let missing = '';
+      for (const ch of text) {
+        if (isInvisible(ch) || attempted.has(ch)) continue;
+        attempted.add(ch);
+        missing += ch;
+      }
+      if (!missing) return;
+      // One native call per group of new codepoints, never one per letter or repeated label.
+      try {
+        const extra = native.fontLoad(bytes, depth, missing, weight);
+        if (extra < 0) throw new Error(native.loadError());
+        read(extra);
+      } catch (error) {
+        for (const ch of missing) attempted.delete(ch);
+        throw new Error(`loadFont: couldn't build additional glyphs: ${error instanceof Error ? error.message : String(error)}`, {
+          cause: error
+        });
+      }
+    });
+    return font;
+  }
+  return pending.then(font => {
+    extend.get(font)?.(chars);
+    return font;
+  });
+}
+const DIGIT = /[0-9]/;
+/** Walk one normalized line for both measuring and placing, so fallback widths always agree. */
+function walkText(font, text, options, placed) {
+  text = text.normalize('NFC');
+  extend.get(font)?.(options.tabular ? `${text}0123456789` : text);
+  const spacing = options.letterSpacing ?? 0;
+  let digit = 0;
+  if (options.tabular) for (const d of '0123456789') digit = Math.max(digit, font.glyphs.get(d)?.advance ?? 0);
+  let width = 0;
+  let letters = 0;
+  for (const ch of text) {
+    if (isInvisible(ch)) continue;
+    const glyph = font.glyphs.get(ch) ?? (WHITESPACE.test(ch) ? font.glyphs.get(' ') : undefined) ?? font.glyphs.get('?');
+    if (!glyph) continue;
+    const advance = digit > 0 && DIGIT.test(ch) ? digit : glyph.advance;
+    if (letters++ > 0) width += spacing;
+    if (placed && glyph.mesh >= 0) placed.push({
+      mesh: glyph.mesh,
+      x: width + (advance - glyph.advance) / 2,
+      y: 0
+    });
+    width += advance;
+  }
+  return width;
+}
+
+/** A line's advance in ems, with the same Unicode glyph loading, spacing and fallbacks as rendering. */
+export function measureText(font, text, options = {}) {
+  return walkText(font, text, options);
+}
+
+/** Glyph placements for a line of text: centered vertically on capitals, aligned horizontally. */
+export function layoutText(font, text, align, options = {}) {
+  const placed = [];
+  const width = walkText(font, text, options, placed);
+  const shift = align === 'left' ? 0 : align === 'right' ? -width : -width / 2;
+  const lift = -font.capHeight / 2;
+  for (const p of placed) {
+    p.x += shift;
+    p.y = lift;
+  }
+  return placed;
+}
+//# sourceMappingURL=font.js.map

package/lib/module/assets/loft.js

@@ -0,0 +1,142 @@
+"use strict";
+
+import { lathe, merge, recolor } from "./shape.js";
+import { parametricSurface } from "./surface.js";
+/**
+ * Smooth closed body through rounded rectangular cross sections along Z. Useful for vehicle
+ * shells, cabins, shoes and fairings. Caps have separate flat normals and planar UVs; sides have
+ * continuous longitudinal UVs and a welded seam. Input sections may increase or decrease in Z.
+ */
+export function loft(sections, options = {}) {
+  if (sections.length < 2 || sections.some(s => ![s.z, s.bottom, s.top, s.width, s.topWidth ?? s.width, s.square ?? 4].every(Number.isFinite) || s.width < 0 || (s.topWidth ?? s.width) < 0 || s.top <= s.bottom || (s.square ?? 4) < 1)) throw new Error('loft: needs at least two valid cross sections');
+  const ordered = sections[0].z > sections[sections.length - 1].z ? [...sections].reverse() : sections;
+  if (ordered.some((s, i) => i > 0 && s.z <= ordered[i - 1].z)) throw new Error('loft: sections must be ordered along Z');
+  const n = options.around ?? 32,
+    steps = options.smoothness ?? 4;
+  if (!Number.isInteger(n) || n < 6 || n > 512 || !Number.isInteger(steps) || steps < 1 || steps > 64) throw new Error('loft: invalid around/smoothness');
+  const values = ordered.map(s => [s.z, s.bottom, s.top, s.width, s.topWidth ?? s.width, s.square ?? 4]);
+  const at = i => values[Math.max(0, Math.min(values.length - 1, i))];
+  const row = v => {
+    const cursor = v * (values.length - 1),
+      i = Math.min(values.length - 2, Math.floor(cursor)),
+      t = cursor - i;
+    const a = at(i - 1),
+      b = at(i),
+      c = at(i + 1),
+      d = at(i + 2);
+    const f = b.map((_, k) => 0.5 * (2 * b[k] + (-a[k] + c[k]) * t + (2 * a[k] - 5 * b[k] + 4 * c[k] - d[k]) * t * t + (-a[k] + 3 * b[k] - 3 * c[k] + d[k]) * t * t * t));
+    f[2] = Math.max(f[1] + 1e-6, f[2]);
+    f[3] = Math.max(0, f[3]);
+    f[4] = Math.max(0, f[4]);
+    f[5] = Math.max(1, f[5]);
+    return f;
+  };
+  const rowCount = (sections.length - 1) * steps;
+  const rows = Array.from({
+    length: rowCount + 1
+  }, (_, i) => row(i / rowCount));
+  const point = (u, v) => {
+    const [z, bottom, top, width, topWidth, square] = rows[Math.round(v * rowCount)],
+      angle = -Math.PI / 2 + u * Math.PI * 2;
+    const c = Math.cos(angle),
+      s = Math.sin(angle),
+      exponent = 2 / square;
+    const x = Math.sign(c) * Math.abs(c) ** exponent,
+      y = Math.sign(s) * Math.abs(s) ** exponent;
+    return [x * (y > 0 ? width + (topWidth - width) * y : width), (bottom + top) / 2 + y * (top - bottom) / 2, z];
+  };
+  const side = parametricSurface(point, {
+    uSegments: n,
+    vSegments: rowCount,
+    wrapU: true
+  });
+  const parts = [{
+    geometry: side
+  }];
+  for (const [v, facing] of [[0, -1], [1, 1]]) {
+    const section = rows[v * rowCount],
+      cy = (section[1] + section[2]) / 2;
+    const vertices = new Float32Array((n + 1) * 11),
+      indices = [];
+    vertices.set([0, cy, section[0], 0, 0, facing, 1, 1, 1, 0.5, 0.5]);
+    for (let j = 0; j < n; j++) {
+      const p = point(j / n, v),
+        width = Math.max(section[3], section[4], 1e-6);
+      vertices.set([p[0], p[1], p[2], 0, 0, facing, 1, 1, 1, 0.5 + p[0] / (2 * width), (p[1] - section[1]) / (section[2] - section[1])], (j + 1) * 11);
+      const a = j + 1,
+        b = (j + 1) % n + 1;
+      if (facing === 1) indices.push(0, a, b);else indices.push(0, b, a);
+    }
+    parts.push({
+      geometry: {
+        vertices,
+        indices: new Uint32Array(indices)
+      }
+    });
+  }
+  return paint(merge(parts), options.color);
+}
+function paint(geometry, color) {
+  return color ? recolor(geometry, typeof color === 'function' ? ({
+    position,
+    normal
+  }) => color(position, normal) : () => color) : geometry;
+}
+
+/** A rounded rectangular cross-section with flat front/back caps, centered at the origin. */
+export function block(w, h, d, square = 6, color) {
+  return loft([{
+    z: -d / 2,
+    bottom: -h / 2,
+    top: h / 2,
+    width: w / 2,
+    square
+  }, {
+    z: d / 2,
+    bottom: -h / 2,
+    top: h / 2,
+    width: w / 2,
+    square
+  }], {
+    around: 16,
+    smoothness: 1,
+    color
+  });
+}
+
+/** An exact ellipsoid with analytic normals, rather than capped/truncated poles. */
+export function ellipsoid(radii, color, around = 16) {
+  if (radii.some(r => !Number.isFinite(r) || r <= 0)) throw new Error('ellipsoid: radii must be positive');
+  const profile = Array.from({
+    length: 9
+  }, (_, i) => [i === 0 || i === 8 ? 0 : Math.sin(i * Math.PI / 8), Math.cos(i * Math.PI / 8)]);
+  return paint(merge([{
+    geometry: lathe(profile, {
+      segments: around
+    }),
+    scale: radii
+  }]), color);
+}
+
+/** Smooth Hermite interpolation through increasing [x,value] points; clamped beyond the ends. */
+export function smoothCurve(points) {
+  if (points.length < 2 || points.some((p, i) => !p.every(Number.isFinite) || i > 0 && p[0] <= points[i - 1][0])) throw new Error('smoothCurve: needs increasing finite points');
+  const n = points.length;
+  const slope = i => {
+    const a = points[Math.max(0, i - 1)],
+      b = points[Math.min(n - 1, i + 1)];
+    return (b[1] - a[1]) / (b[0] - a[0]);
+  };
+  return x => {
+    if (x <= points[0][0]) return points[0][1];
+    if (x >= points[n - 1][0]) return points[n - 1][1];
+    let i = 0;
+    while (points[i + 1][0] < x) i++;
+    const [x0, y0] = points[i],
+      [x1, y1] = points[i + 1],
+      h = x1 - x0,
+      t = (x - x0) / h;
+    return (2 * t * t * t - 3 * t * t + 1) * y0 + (t * t * t - 2 * t * t + t) * h * slope(i) + (-2 * t * t * t + 3 * t * t) * y1 + (t * t * t - t * t) * h * slope(i + 1);
+  };
+}
+//# sourceMappingURL=loft.js.map

package/lib/module/assets/model.js

@@ -0,0 +1,96 @@
+"use strict";
+
+import NativeEngine from '../native/NativeNayanEngine';
+import { meshInfo, registerMesh } from "../render/meshes.js";
+import { AssetLoader } from "./AssetLoader.js";
+// External 3D models: glTF 2.0 (.glb, or .gltf with embedded buffers), parsed by the Rust core.
+
+/** A loaded model: pass it as an entity's `mesh`. Colliders sized from the mesh fit its bounding box. */
+
+/** An animation embedded in a loaded GLB. */
+
+const loader = new AssetLoader('loadModel');
+
+/** A registered mesh's geometry, aliasing native memory. */
+export function nativeGeometry(mesh) {
+  return {
+    vertices: new Float32Array(NativeEngine.modelVertices(mesh)),
+    indices: new Uint32Array(NativeEngine.modelIndices(mesh))
+  };
+}
+
+/**
+ * Registers a mesh the core already holds (a created, cached or loaded model, a glyph, an alias):
+ * the renderer copies it inside Rust, and JS reads its geometry only if something asks for it
+ * (merging, caching). Apps built before `renderModel` upload it through JS as before.
+ */
+export function registerCoreMesh(mesh, info = {}, geometry = () => nativeGeometry(mesh)) {
+  const native = NativeEngine;
+  let cached;
+  const inRust = typeof native.renderModel === 'function' && native.renderModel(mesh, info.texture ?? -1, info.shine ?? 0);
+  registerMesh(mesh, {
+    get geometry() {
+      return cached ??= geometry();
+    },
+    texture: info.texture,
+    shine: info.shine
+  }, !inRust);
+}
+const materials = new Map();
+
+/** Independent materials share core geometry without overwriting an existing model's appearance. */
+export function registerModelMesh(mesh, shine) {
+  const info = meshInfo(mesh);
+  if (info && (info.shine ?? 0) === shine) return mesh;
+  const key = `${mesh}:${shine}`;
+  const cached = materials.get(key);
+  if (cached !== undefined) return cached;
+  const id = info ? NativeEngine.meshAlias(mesh) : mesh;
+  if (id < 0) throw new Error(NativeEngine.loadError() || "couldn't register a material variant");
+  registerCoreMesh(id, {
+    texture: info?.texture,
+    shine
+  }, info ? () => info.geometry : undefined);
+  materials.set(key, id);
+  return id;
+}
+
+/**
+ * Initializes the engine automatically. Loads a glTF model once; pass it as an entity's `mesh`. Meshes, node transforms, material colors
+ * and the base color texture are kept (one texture per model); skeletal animation clips are available through `animations` and `World.playClip`.
+ * Every entity using the model is drawn in one instanced draw call.
+ *
+ * ```ts
+ * const tree = await loadModel(require("./assets/tree.glb"), { fit: 2 });
+ * world.spawn({ mesh: tree, position: [0, 1, 0], physics: "fixed" });
+ * ```
+ */
+export function loadModel(source, options = {}) {
+  const center = options.center ?? true;
+  const fit = options.fit ?? 0;
+  const shine = Math.max(0, Math.min(1, options.shine ?? 0));
+  return loader.load(source, (native, bytes) => {
+    // Parsed on a background native thread where the app's build supports it.
+    if (typeof native.modelLoadAsync === 'function') return native.modelLoadAsync(bytes, center, fit).then(mesh => finishModel(native, mesh, shine));
+    return finishModel(native, native.modelLoad(bytes, center, fit), shine);
+  }, [center, fit, shine]);
+}
+
+/** A parsed glTF's handle: registered for drawing (in Rust) with its rig's clips. */
+function finishModel(native, mesh, shine) {
+  if (mesh < 0) throw new Error(native.loadError() || 'not a glTF model');
+  const texture = native.modelTexture(mesh);
+  registerCoreMesh(mesh, {
+    texture: texture >= 0 ? texture : undefined,
+    shine
+  });
+  const [x, y, z] = native.modelSize(mesh);
+  const rig = JSON.parse(native.modelRig(mesh));
+  return {
+    animations: rig.clips,
+    jointCount: rig.joints,
+    id: mesh,
+    size: [x, y, z]
+  };
+}
+//# sourceMappingURL=model.js.map