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

package/README.md

@@ -1,14 +1,21 @@
 # @nayan-ui/engine
 
-A fast 3D game engine for **React** and **React Native**. One TypeScript API, one Rust core: rendering (wgpu), physics (Rapier), animation, particles, audio, haptics and 2D drawing.
+[![npm](https://img.shields.io/npm/v/@nayan-ui/engine?label=npm)](https://www.npmjs.com/package/@nayan-ui/engine) [![license](https://img.shields.io/npm/l/@nayan-ui/engine)](#license)
 
-**[Documentation](https://www.nayanui.com/engine)** · **[First game tutorial](https://www.nayanui.com/engine/first-game)** · **[API reference](https://www.nayanui.com/engine/api-reference)** · **[Guide for AI agents](https://www.nayanui.com/engine/agent-guide)**
+A fast 3D game engine for **React** and **React Native**. One TypeScript API on one Rust core: rendering (wgpu), physics (Rapier), skeletal and tween animation, particles, audio, haptics and 2D drawing.
 
-| Platform    | Renders with                   | Needs                                            |
-| ----------- | ------------------------------ | ------------------------------------------------ |
-| iOS         | Metal                          | A development or store build (not Expo Go)       |
-| Android     | Vulkan or OpenGL ES            | `minSdkVersion` 26, a development or store build |
-| Web (React) | WebAssembly + WebGPU or WebGL2 | A modern browser over HTTPS or localhost         |
+**[Documentation](https://www.nayanui.com/game-engine)** · **[First game tutorial](https://www.nayanui.com/game-engine/first-game)** · **[API reference](https://www.nayanui.com/game-engine/api-reference)** · **[Guide for AI agents](https://www.nayanui.com/game-engine/agent-guide)**
+
+- **Native speed on phones.** Rendering, physics, animation, culling and audio mixing run in Rust. On iOS and Android the game loop follows the display's clock, and frames are drawn on the engine's own render thread, so your JavaScript never waits on the GPU.
+- **Small API.** `useWorld` + `GameView` is a complete scene. Spawn entities, move them, animate them: the engine steps, draws and cleans up.
+- **Fast loading.** Images, glTF models, fonts and sounds decode on native background threads, and procedural meshes can be cached on disk between launches.
+- **Same code on the web.** The core compiles to WebAssembly and draws with WebGPU, falling back to WebGL2.
+
+| Platform    | Renders with                   | Needs                                                     |
+| ----------- | ------------------------------ | --------------------------------------------------------- |
+| iOS         | Metal                          | A development or store build (Expo Go doesn't include it) |
+| Android     | Vulkan or OpenGL ES            | `minSdkVersion` 26, a development or store build          |
+| Web (React) | WebAssembly + WebGPU or WebGL2 | A modern browser over HTTPS or localhost                  |
 
 ## Install
 
@@ -16,65 +23,86 @@ A fast 3D game engine for **React** and **React Native**. One TypeScript API, on
 npm install @nayan-ui/engine
 ```
 
-**React Native (Expo):** add the model extensions to `metro.config.js`, then make a development build (`npx expo run:ios` / `npx expo run:android`). Install `expo-asset` if you load bundled files with `require(...)`.
+Peer dependencies: `react`, plus `react-native` for apps. `expo-asset` is optional and only needed to load bundled files with `require(...)` in Expo.
+
+### React Native (Expo)
+
+1. Let Metro bundle 3D models, in `metro.config.js`:
+
+   ```js
+   config.resolver.assetExts.push('glb', 'gltf');
+   ```
+
+2. Target Android 8.0 (API 26) or newer (with `expo-build-properties`), and allow vibration for haptics, in `app.json`:
 
-```js
-config.resolver.assetExts.push('glb', 'gltf');
+   ```json
+   {
+     "expo": {
+       "android": { "permissions": ["android.permission.VIBRATE"] },
+       "plugins": [["expo-build-properties", { "android": { "minSdkVersion": 26 } }]]
+     }
+   }
+   ```
+
+3. Make a development build: `npx expo run:ios` / `npx expo run:android` (or an EAS build). The engine ships prebuilt native libraries, so no Rust toolchain is needed.
+
+Bare React Native apps autolink the same way: run `pod install` in `ios/` and set `minSdkVersion` 26 in Gradle.
+
+Guard screens for builds without the native module (for example Expo Go) with `isEngineAvailable`:
+
+```tsx
+import { isEngineAvailable } from '@nayan-ui/engine';
+
+if (!isEngineAvailable) return <Text>This screen needs a development build.</Text>;
 ```
 
-**React (web):** nothing else to configure. Call `await warmUpEngine()` before creating a world.
+### React (web)
+
+Nothing to configure. `useWorld` loads the WebAssembly core for you; if you create worlds yourself, `await warmUpEngine()` first.
 
 ## Quick start
 
-A complete scene that works unchanged on both platforms:
+A complete scene that works unchanged on every platform:
 
 ```tsx
-import { useEffect, useState } from 'react';
-import { type Camera, GameView, warmUpEngine, World } from '@nayan-ui/engine';
-
-const camera: Camera = { eye: [0, 4, 8], target: [0, 0, 0], fov: 1 };
-
-export function SpinningCube() {
-  const [world, setWorld] = useState<World | null>(null);
-
-  useEffect(() => {
-    let created: World | undefined;
-    let active = true;
-    void warmUpEngine().then(() => {
-      if (!active) return;
-      created = new World(100); // fixed entity capacity
-      created.spawn({ mesh: 'plane', scale: [20, 1, 20], color: [0.3, 0.6, 0.3], physics: 'fixed' });
-      const cube = created.spawn({ mesh: 'cube', position: [0, 3, 0], color: [0.2, 0.6, 1], physics: 'dynamic' });
-      created.animate(cube, { scale: 1.2 }, { duration: 0.6, repeat: 'forever', yoyo: true });
-      setWorld(created);
-    });
-    return () => {
-      active = false;
-      created?.dispose();
-    };
-  }, []);
-
-  if (!world) return null;
-  return (
-    <GameView
-      source={world}
-      camera={camera}
-      light={{ direction: [0.4, 0.8, 0.5], ambient: 0.35 }}
-      onUpdate={(dt) => world.update(dt)}
-      style={{ flex: 1 }}
-    />
-  );
+import { GameView, useWorld } from '@nayan-ui/engine';
+
+export function BouncingBall() {
+  const world = useWorld(100, (w) => {
+    w.spawn({ mesh: 'plane', scale: [20, 1, 20], color: '#4C9A4C', physics: 'fixed' });
+    w.spawn({ mesh: 'sphere', position: [0, 5, 0], color: '#3399FF', physics: { type: 'dynamic', bounce: 0.6 } });
+  });
+  return world && <GameView source={world} camera={{ eye: [0, 4, 8], target: [0, 0, 0], fov: 1 }} style={{ flex: 1 }} />;
 }
 ```
 
+`useWorld` warms the engine up, creates the world (100 entity slots), runs your setup and disposes it on unmount. `GameView` draws it and steps it every frame.
+
 ## The five rules
 
-1. **Create** the world in an effect (after `await warmUpEngine()` on the web) and **dispose** it on unmount.
-2. **Step** it from one place: `world.update(dt)` inside `GameView`'s `onUpdate`.
+1. **Own** a world with `useWorld(capacity, setup)`, or create it yourself after `await warmUpEngine()` and `dispose()` it on unmount.
+2. **Play** in `GameView`'s `onUpdate(dt)`: read input, move things, spawn. The world is stepped for you right after (call `world.update(dt)` yourself only to step it earlier or with another `dt`).
 3. **Keep handles**: `spawn` returns an `Entity`; change it with `set`, remove it with `despawn`.
-4. **Batch per-frame moves** in `world.transforms`, then `flush()` once after `update`.
+4. **Batch per-frame moves** in `world.transforms`: they are applied in one native call when the world steps (`flush()` yourself before reading positions).
 5. **Don't track disposal yourself**: check `world.isDisposed`. Cleanup calls are safe no-ops after `dispose()`.
 
+## Performance
+
+The engine is built so that a game written the obvious way stays smooth on mid-range Android phones.
+
+- **Display clock and render thread (iOS and Android).** The display's vsync (`CADisplayLink` on iOS, `Choreographer` on Android) asks for each frame at 60 Hz. `onUpdate` steps the game and hands a copy of the frame to a native render thread, which culls, submits and presents it. The JS thread never waits on the GPU, and a frame that is still waiting when a newer one arrives is replaced, not queued. The clock stops while the app is in the background or the view is off screen. On the web, `requestAnimationFrame` drives the same loop.
+- **Culling in Rust.** Everything outside the camera's view (and outside the light's box for shadows) is skipped every frame, so open levels and long tracks only pay for what is on screen. Don't cull scenery in JS.
+- **Automatic quality.** `quality="auto"` (the default) starts at `high` and steps down (shadow detail first, then anti-aliasing, resolution last) only while the device can't keep up. `onStats` reports fps, update and render time, the quality chosen and the graphics backend.
+- **Background loading.** `loadTexture`, `loadModel`, `loadFont` and `audio.load` decode on native threads in parallel, and meshes are registered with the renderer inside Rust.
+- **Work between frames.** `afterNextFrame(fn)` runs `fn` right after the next frame leaves, so you can spread long setup work (map generation, mesh building) over several frames behind a loading screen.
+- **Cached procedural assets.** `ProceduralCache` saves built geometry on disk keyed by a recipe, so later launches restore it instead of rebuilding; `peek(key)` returns a saved value without building anything.
+
+Keep these habits:
+
+- Build meshes once, at module scope or behind a cache, and spawn new entities from them. Mesh ids are app-wide and never freed (`getMeshIdLimit()` tells you how many there are), so never create a mesh per spawn or per frame.
+- Move many things each frame through `world.transforms` and the `out` arguments of queries, which allocate nothing.
+- Keep long one-off jobs out of gameplay frames: a single slow frame stalls Android's Hermes far longer than desktop JavaScript suggests.
+
 ## Common tasks
 
 **Physics and collisions**
@@ -95,6 +123,19 @@ await world.animate(piece, { position: [2, 0, 3] }, { duration: 0.25, easing: 'b
 world.animate(star, { scale: 1.2 }, { repeat: 'forever', yoyo: true });
 ```
 
+**Skinned characters**: glTF clips play natively, with crossfades
+
+```ts
+const hero = await loadModel(require('./hero.glb'));
+console.log(hero.animations.map((clip) => clip.name)); // e.g. ['idle', 'walk', 'run']
+const player = world.spawn({ mesh: hero });
+world.playClip(player, 'idle', { speed: 0 }); // hold the first pose on the ready screen
+world.playClip(player, 'run', { fade: 0.2 }); // crossfade when play starts
+world.stopClip(player);
+```
+
+`world.sampleSkinnedVertices` reads chosen vertices of the next pose (for planting feet on uneven ground) without skinning the whole character in JS.
+
 **Ready-made effects**
 
 ```ts
@@ -102,10 +143,7 @@ import { effects } from '@nayan-ui/engine';
 
 effects.confetti(world, {
   position: [0, 2, 0],
-  colors: [
-    [1, 0.3, 0.3],
-    [1, 0.85, 0.2]
-  ],
+  colors: ['#FF4D4D', '#FFD933'],
   size: 0.12,
   speed: 6,
   count: 40,
@@ -113,7 +151,7 @@ effects.confetti(world, {
   gravity: -6
 });
 effects.dust(world, { position: [0, 0, 0], color: [0.8, 0.75, 0.65, 0.6], size: 0.3, speed: 1.5, count: 6, lifetime: 0.5 });
-await effects.pop(world, piece, { scale: 1, color: [1, 0.3, 0.3] }); // swell, flash white, shrink away
+await effects.pop(world, piece, { scale: 1, color: '#FF4D4D' }); // swell, flash white, shrink away
 world.despawn(piece);
 ```
 
@@ -128,18 +166,54 @@ const turn: MutableQuat = [0, 0, 0, 1];
 const at: [number, number, number] = [0, 0, 0];
 
 function onUpdate(dt: number) {
-  world.update(dt);
   world.position(player, at); // queries can fill an `out` array
   quat.y(heading, turn);
-  world.transforms.transform(car, carX, 0, carZ, turn[0], turn[1], turn[2], turn[3]);
-  world.transforms.flush(); // one native call per frame
+  world.transforms.transform(car, carX, 0, carZ, turn[0], turn[1], turn[2], turn[3]); // applied in one native call as the world steps
 }
 ```
 
+**Models built in code**: bake a shape once, spawn it many times
+
+```ts
+import { createShape, lathe, merge, tube } from '@nayan-ui/engine';
+
+// Built once per app (after warmUpEngine), at module scope.
+const vase = createShape(
+  merge([
+    {
+      geometry: lathe(
+        [
+          [0, 0],
+          [0.4, 0.1],
+          [0.25, 0.8],
+          [0.3, 1]
+        ],
+        { segments: 24 }
+      )
+    },
+    {
+      geometry: tube(
+        [
+          [0.3, 0.9, 0],
+          [0.5, 0.7, 0],
+          [0.3, 0.5, 0]
+        ],
+        { radius: 0.04 }
+      ),
+      color: [0.5, 0.25, 0.1]
+    } // part colors are 0..1 tuples
+  ])
+);
+world.spawn({ mesh: vase, color: '#C8763A' });
+```
+
+Also available: `extrude`, `loft`, `block`, `ellipsoid`, `parametricSurface`, `Solid` and `shapeGeometry` for the built-in shapes.
+
 **Score, lives and timers**
 
 ```ts
-world.scoreboard.handlers = { onScore: setScore, onTimeUp: () => endGame('lose') };
+world.scoreboard.handlers = { onTimeUp: () => endGame('lose') }; // the game's rules
+const stopListening = world.scoreboard.listen({ onScore: setScore, onSecond: setTime }); // UI follows along
 world.scoreboard.reset(3, 60); // 3 lives and a stopped 60 s countdown for the ready screen
 world.scoreboard.resume(); // Start
 world.scoreboard.add(10);
@@ -147,6 +221,12 @@ const timer = world.after(0.5, spawnWave); // game time: pauses with the game
 world.cancelTimer(timer);
 ```
 
+**Flat boards and puzzles**: `frontLight` keeps camera-facing surfaces at their exact color
+
+```tsx
+<GameView source={world} camera={{ eye: [0, 0, 50], target: [0, 0, 0], fov: 1, ortho: 10 }} light={frontLight([-0.4, 0.6, 1], 0.5)} />
+```
+
 **Input**
 
 ```tsx
@@ -161,6 +241,8 @@ world.cancelTimer(timer);
 />
 ```
 
+`onLongPress`, `onPinch`, the on-screen `Joystick` and `createKeyboardInput` (web) cover other controls.
+
 **Models, textures, text, sound and haptics**
 
 ```ts
@@ -180,6 +262,8 @@ audio.enabled = settings.sounds; // respect the player's preferences
 haptics.enabled = settings.haptics;
 ```
 
+**Colors** are CSS strings (`'#FF4757'`, `'rgba(0, 0, 0, 0.5)'`) or linear 0..1 tuples (`[1, 0.3, 0.3]`; channels above 1 glow) for entities, animations, particles, lights and the background. Vertex colors baked into geometry are tuples. `toColor('#FF4757')` converts a CSS color when you need the numbers.
+
 **Drawing**: a native paint canvas, also usable as a live texture inside games
 
 ```tsx
@@ -191,21 +275,35 @@ paper.setBrush({ brushType: 'MARKER', color: '#e53935', width: 12, opacity: 1 })
 world.spawn({ mesh: 'plane', texture: paper.texture() }); // paint on a 3D object
 ```
 
+Drawings save as SVG paths and export transparent PNG snapshots.
+
+## Troubleshooting
+
+| Symptom                                         | Fix                                                                                                      |
+| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| `isEngineAvailable` is `false`                  | You're in Expo Go or a build made before installing the engine: make a new development build.            |
+| `.glb` files fail to bundle                     | Add `glb` and `gltf` to Metro's `assetExts`.                                                             |
+| Android build fails on `minSdkVersion`          | Set it to 26 or higher.                                                                                  |
+| An Android screenshot of the game view is blank | The engine draws into a `SurfaceView`: use `captureScreen(..., { handleGLSurfaceViewOnAndroid: true })`. |
+| Out of mesh ids                                 | A mesh is being created per spawn or per frame: build it once and reuse it (`getMeshIdLimit()`).         |
+
 ## Learn more
 
 | Topic                                 | Guide                                                                                                          |
 | ------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
-| Build a complete game step by step    | [First game](https://www.nayanui.com/engine/first-game)                                                        |
-| Copy-paste solutions                  | [Recipes](https://www.nayanui.com/engine/recipes)                                                              |
-| Worlds, entities, rotations, disposal | [World & entities](https://www.nayanui.com/engine/world-entities)                                              |
-| Effects and particles                 | [Effects](https://www.nayanui.com/engine/particles)                                                            |
-| Procedural meshes and modelling       | [Geometry](https://www.nayanui.com/engine/procedural-geometry)                                                 |
-| Drawing and painting                  | [Drawing](https://www.nayanui.com/engine/drawing)                                                              |
-| Performance and caching               | [Performance](https://www.nayanui.com/engine/cache-performance)                                                |
-| Coding agents                         | [Agent guide](https://www.nayanui.com/engine/agent-guide) · [engine.json](https://www.nayanui.com/engine.json) |
-
-Ready-made games built on this engine: **[@nayan-ui/games](https://www.nayanui.com/games)**.
+| Build a complete game step by step    | [First game](https://www.nayanui.com/game-engine/first-game)                                                        |
+| Copy-paste solutions                  | [Recipes](https://www.nayanui.com/game-engine/recipes)                                                              |
+| Worlds, entities, rotations, disposal | [World & entities](https://www.nayanui.com/game-engine/world-entities)                                              |
+| Effects and particles                 | [Effects](https://www.nayanui.com/game-engine/particles)                                                            |
+| Procedural meshes and modelling       | [Geometry](https://www.nayanui.com/game-engine/procedural-geometry)                                                 |
+| Drawing and painting                  | [Drawing](https://www.nayanui.com/game-engine/drawing)                                                              |
+| Performance and caching               | [Performance](https://www.nayanui.com/game-engine/cache-performance)                                                |
+| Coding agents                         | [Agent guide](https://www.nayanui.com/game-engine/agent-guide) · [engine.json](https://www.nayanui.com/engine.json) |
 
 ## License
 
 MIT © [Niranjan Devasani](https://github.com/ursnj)
+
+---
+
+Made with ❤️ by [Niranjan Reddy Devasani](https://github.com/ursnj)

package/lib/module/assets/AssetLoader.js

@@ -29,7 +29,7 @@ export class AssetLoader {
         bytes
       } = await loadAssetBytes(source);
       try {
-        return decode(NativeEngine, bytes);
+        return await decode(NativeEngine, bytes);
       } catch (cause) {
         // Only rejected payloads invalidate saved bytes. Initialization/network failures don't.
         forgetAssetBytes(uri);

package/lib/module/assets/ProceduralCache.js

@@ -55,6 +55,27 @@ export class ProceduralCache {
   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) {
@@ -158,7 +179,9 @@ export class ProceduralCache {
       bytes.set(new Uint8Array(data.buffer, data.byteOffset, data.byteLength), offset);
       offset += data.byteLength;
     }
-    view.setUint32(12, checksum(bytes.subarray(16)), true);
+    // 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) {
@@ -166,7 +189,7 @@ export class ProceduralCache {
     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 || view.getUint32(12, true) !== checksum(bytes.subarray(16))) throw Error('cache integrity');
+    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;
@@ -178,8 +201,12 @@ export class ProceduralCache {
       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);
-      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');
+      // 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,

package/lib/module/assets/font.js

@@ -1,9 +1,9 @@
 "use strict";
 
 // Fonts for 3D text: each character becomes an extruded mesh, built by the Rust core.
-import { registerMesh } from "../render/meshes.js";
+
 import { AssetLoader } from "./AssetLoader.js";
-import { nativeGeometry } from "./model.js";
+import { registerCoreMesh } from "./model.js";
 /** Printable ASCII plus common arithmetic and typography, prewarmed for ordinary labels. */
 export const DEFAULT_CHARS = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz !"#$%&\'()*+,-./:;<=>?@[\\]^_`{|}~×÷±−°·•–—…‘’“”';
 
@@ -36,7 +36,12 @@ export function loadFont(source, options = {}) {
   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) => {
-    const id = native.fontLoad(bytes, depth, chars, weight);
+    // 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();
@@ -45,9 +50,7 @@ export function loadFont(source, options = {}) {
       for (let i = 0; i + 3 <= data.length - 1; i += 3) {
         const mesh = data[i + 1];
         if (mesh >= 0 && !registered.has(mesh)) {
-          registerMesh(mesh, {
-            geometry: nativeGeometry(mesh)
-          });
+          registerCoreMesh(mesh);
           registered.add(mesh);
         }
         glyphs.set(String.fromCodePoint(data[i]), {
@@ -84,7 +87,7 @@ export function loadFont(source, options = {}) {
       }
     });
     return font;
-  }, [depth, weight]);
+  }
   return pending.then(font => {
     extend.get(font)?.(chars);
     return font;

package/lib/module/assets/model.js

@@ -18,6 +18,24 @@ export function nativeGeometry(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. */
@@ -29,11 +47,10 @@ export function registerModelMesh(mesh, shine) {
   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");
-  registerMesh(id, {
-    geometry: info?.geometry ?? nativeGeometry(id),
+  registerCoreMesh(id, {
     texture: info?.texture,
     shine
-  });
+  }, info ? () => info.geometry : undefined);
   materials.set(key, id);
   return id;
 }
@@ -53,22 +70,27 @@ export function loadModel(source, options = {}) {
   const fit = options.fit ?? 0;
   const shine = Math.max(0, Math.min(1, options.shine ?? 0));
   return loader.load(source, (native, bytes) => {
-    const mesh = native.modelLoad(bytes, center, fit);
-    if (mesh < 0) throw new Error(native.loadError() || 'not a glTF model');
-    const texture = native.modelTexture(mesh);
-    registerMesh(mesh, {
-      geometry: nativeGeometry(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]
-    };
+    // 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

package/lib/module/assets/storage.shared.js

@@ -5,6 +5,8 @@ import NativeEngine from '../native/NativeNayanEngine';
 export function proceduralStorage(revision) {
   const native = NativeEngine;
   return {
+    // The Rust store checksums every record (SHA-256) and rejects any that don't match.
+    verified: true,
     read(key) {
       if (typeof native?.cacheRead !== 'function') return null;
       const data = native.cacheRead(`procedural:${revision}:${key}`);

package/lib/module/assets/storage.web.js

@@ -8,6 +8,7 @@ export function proceduralStorage(revision) {
   const storage = shared.proceduralStorage(revision);
   if (!storage) return;
   return {
+    verified: storage.verified,
     read: storage.read,
     write(key, bytes) {
       storage.write(key, bytes);

package/lib/module/assets/texture.js

@@ -2,8 +2,9 @@
 
 import NativeEngine from '../native/NativeNayanEngine';
 // Textures: PNG / JPEG images, decoded by the Rust core, drawn on built-in shapes or models.
-import { meshInfo, registerMesh } from "../render/meshes.js";
+import { meshInfo } from "../render/meshes.js";
 import { AssetLoader } from "./AssetLoader.js";
+import { registerCoreMesh } from "./model.js";
 
 /** A loaded image. Pass it as an entity's `texture`. */
 
@@ -20,14 +21,17 @@ const loader = new AssetLoader('loadTexture');
  */
 export function loadTexture(source) {
   return loader.load(source, (native, bytes) => {
-    const id = native.textureLoad(bytes);
-    if (id < 0) throw new Error(native.loadError() || 'not a PNG or JPEG image');
-    const [width, height] = native.textureSize(id);
-    return {
-      id,
-      width,
-      height
+    const finish = id => {
+      if (id < 0) throw new Error(native.loadError() || 'not a PNG or JPEG image');
+      const [width, height] = native.textureSize(id);
+      return {
+        id,
+        width,
+        height
+      };
     };
+    // Decoded on a background native thread where the app's build supports it.
+    return typeof native.textureLoadAsync === 'function' ? native.textureLoadAsync(bytes).then(finish) : finish(native.textureLoad(bytes));
   });
 }
 
@@ -54,11 +58,10 @@ export function texturedMesh(mesh, texture) {
     if (!base) throw new Error('texture: this mesh has nothing to draw');
     id = NativeEngine.meshAlias(mesh);
     if (id < 0) throw new Error(`texture: ${NativeEngine.loadError()}`);
-    registerMesh(id, {
-      geometry: base.geometry,
+    registerCoreMesh(id, {
       texture: texture.id,
       shine: base.shine
-    });
+    }, () => base.geometry);
     variants.set(key, id);
   }
   return id;

package/lib/module/index.js

@@ -5,10 +5,13 @@
 // World: entities, physics, collisions, animation, particles, picking.
 export { World, isEngineAvailable } from "./world/World.js";
 export { quat } from "./world/quat.js";
+export { toColor } from "./world/color.js";
 export { effects } from "./world/effects.js";
 export { Scoreboard } from "./world/Scoreboard.js";
 // Rendering and touch.
-export { GameView } from "./render/GameView.js";
+export { afterNextFrame, GameView } from "./render/GameView.js";
+export { useWorld } from "./render/useWorld.js";
+export { frontLight } from "./render/light.js";
 export { warmUpEngine, getMeshIdLimit } from "./render/meshes.js";
 
 // Models, custom shapes, textures and fonts.

package/lib/module/media/audio.js

@@ -14,9 +14,12 @@ import NativeEngine from '../native/NativeNayanEngine';
 const loader = new AssetLoader('audio');
 function loadSound(source) {
   return loader.load(source, (native, bytes) => {
-    const id = native.audioLoad(bytes);
-    if (id < 0) throw new Error(native.loadError() || 'not a supported WAV file');
-    return id;
+    const finish = id => {
+      if (id < 0) throw new Error(native.loadError() || 'not a supported WAV file');
+      return id;
+    };
+    // Decoded on a background native thread where the app's build supports it.
+    return typeof native.audioLoadAsync === 'function' ? native.audioLoadAsync(bytes).then(finish) : finish(native.audioLoad(bytes));
   }).catch(error => {
     console.warn(error instanceof Error ? error.message : String(error));
     return null;