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

package/README.md

@@ -4,13 +4,29 @@
 
 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.
 
-**[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)**
+**[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)** · **[Prebuilt games](https://www.nayanui.com/games)**
+
+## Contents
+
+- [Features](#features)
+- [Install](#install)
+- [Quick start](#quick-start)
+- [Core concepts](#core-concepts)
+- [Guides](#guides): [Entities](#entities) · [Game loop](#game-loop) · [Physics](#physics) · [Animation](#animation) · [Characters](#characters) · [Effects](#effects) · [Input](#input) · [Assets](#assets) · [Sound and haptics](#sound-and-haptics) · [Score and timers](#score-and-timers) · [Shapes in code](#shapes-in-code) · [Flat boards](#flat-boards-and-puzzles) · [Drawing](#drawing) · [Colors](#colors)
+- [Performance](#performance)
+- [Troubleshooting](#troubleshooting)
+- [Prebuilt games](#prebuilt-games)
+- [Learn more](#learn-more)
+
+## Features
 
 - **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.
 
+### Platforms
+
 | Platform    | Renders with                   | Needs                                                     |
 | ----------- | ------------------------------ | --------------------------------------------------------- |
 | iOS         | Metal                          | A development or store build (Expo Go doesn't include it) |
@@ -78,7 +94,7 @@ export function BouncingBall() {
 
 `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
+## Core concepts
 
 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`).
@@ -86,197 +102,282 @@ export function BouncingBall() {
 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
+## Guides
 
-The engine is built so that a game written the obvious way stays smooth on mid-range Android phones.
+Each snippet assumes a `world` from `useWorld`.
 
-- **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.
+### Entities
 
-Keep these habits:
+```ts
+const box = world.spawn({ mesh: 'cube', position: [0, 1, 0], color: '#FF4757' });
+world.set(box, { color: '#2ED573', scale: 2 }); // only the options you pass change
+world.despawn(box);
+```
 
-- 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.
+Built-in meshes include `'cube'`, `'sphere'`, `'plane'` and `'cylinder'`.
 
-## Common tasks
+### Game loop
+
+```tsx
+<GameView
+  source={world}
+  onUpdate={(dt) => {
+    world.transforms.set(player, { position: [x, 0, z] }); // batched, applied as the world steps
+  }}
+/>
+```
 
-**Physics and collisions**
+### Physics
 
 ```ts
 const ball = world.spawn({ mesh: 'sphere', position: [0, 5, 0], physics: { type: 'dynamic', bounce: 0.6 } });
 const coin = world.spawn({ mesh: 'cylinder', position: [2, 1, 0], physics: { type: 'fixed', sensor: true } });
+
 world.impulse(ball, [0, 4, 0]);
 world.forEachCollision((a, b, { started }) => {
   if (started && (a === coin || b === coin)) world.despawn(coin);
 });
 ```
 
-**Animation** (runs in Rust and returns a Promise)
+### Animation
+
+Tweens run in Rust and return a Promise.
 
 ```ts
-await world.animate(piece, { position: [2, 0, 3] }, { duration: 0.25, easing: 'back' });
+await world.animate(box, { position: [2, 0, 3] }, { duration: 0.25, easing: 'back' });
 world.animate(star, { scale: 1.2 }, { repeat: 'forever', yoyo: true });
 ```
 
-**Skinned characters**: glTF clips play natively, with crossfades
+### 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.playClip(player, 'idle');
+world.playClip(player, 'run', { fade: 0.2 });
 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.
+Clip names are in `hero.animations`. `world.sampleSkinnedVertices` reads chosen vertices of the next pose (for planting feet on uneven ground).
 
-**Ready-made effects**
+### Effects
 
 ```ts
 import { effects } from '@nayan-ui/engine';
 
-effects.confetti(world, {
-  position: [0, 2, 0],
-  colors: ['#FF4D4D', '#FFD933'],
-  size: 0.12,
-  speed: 6,
-  count: 40,
-  lifetime: 1.2,
-  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: '#FF4D4D' }); // swell, flash white, shrink away
-world.despawn(piece);
+effects.confetti(world, { position: [0, 2, 0], colors: ['#FF4D4D', '#FFD933'], count: 40 });
+await effects.pop(world, box, { scale: 1, color: '#FF4D4D' }); // swell, flash, shrink away
 ```
 
-Also available: `sparkle`, `shatter`, `splash`, `sparks`, `explosion` and `flash`.
+Also available: `dust`, `sparkle`, `shatter`, `splash`, `sparks`, `explosion` and `flash`.
 
-**Per-frame movement without allocations**
+### Input
+
+```tsx
+<GameView
+  source={world}
+  onTap={(x, y) => {
+    const hit = world.pick(x, y);
+    if (hit) world.animate(hit.entity, { scale: 1.2 }, { yoyo: true, repeat: 1 });
+  }}
+  onSwipe={(direction) => move(direction)}
+/>
+```
+
+Also available: `onDrag`, `onLongPress`, `onPinch`, the on-screen `Joystick` and `createKeyboardInput` (web).
+
+### Assets
 
 ```ts
-import { type MutableQuat, quat } from '@nayan-ui/engine';
+import { loadFont, loadModel, loadTexture } from '@nayan-ui/engine';
 
-const turn: MutableQuat = [0, 0, 0, 1];
-const at: [number, number, number] = [0, 0, 0];
+const car = await loadModel(require('./car.glb'), { fit: 2 }); // or a URL on the web
+const crate = await loadTexture(require('./crate.png'));
+const font = await loadFont(require('./Inter-Bold.ttf'));
 
-function onUpdate(dt: number) {
-  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]); // applied in one native call as the world steps
-}
+world.spawn({ mesh: car });
+world.spawn({ mesh: 'cube', texture: crate });
+world.spawn({ text: '2048', font, position: [0, 2, 0], scale: 0.5 });
 ```
 
-**Models built in code**: bake a shape once, spawn it many times
+### Sound and haptics
 
 ```ts
-import { createShape, lathe, merge, tube } from '@nayan-ui/engine';
+import { audio, haptics } 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' });
+const sfx = audio.load({ coin: require('./coin.wav') });
+sfx.play('coin');
+haptics.impact(0.5);
+
+audio.enabled = settings.sounds; // respect the player's preferences
+haptics.enabled = settings.haptics;
 ```
 
-Also available: `extrude`, `loft`, `block`, `ellipsoid`, `parametricSurface`, `Solid` and `shapeGeometry` for the built-in shapes.
+### System speech
+
+```ts
+import { speech } from '@nayan-ui/engine';
+
+await speech.speak('Well done!', { language: 'en-US', rate: 1, pitch: 1, volume: 1 });
+const voices = await speech.getAvailableVoicesAsync();
+await speech.speak('Your next turn', { voice: voices[0]?.identifier });
+await speech.stop(); // Cancel current speech and clear the queue when leaving the screen.
+```
 
-**Score, lives and timers**
+Speech runs through the Rust core, using iOS AVSpeechSynthesizer through Objective-C bindings,
+Android TextToSpeech through JNI, and browser speechSynthesis through web-sys/WASM.
+It creates no audio files, needs no microphone permission or Expo Speech dependency,
+and plays independently of `audio` and its volume/mute settings. The web adapter automatically
+awaits engine warm-up before sending commands into WASM. Rebuild native apps after upgrading
+from an engine without speech support; `speech.supported` checks API availability.
+
+`speak` adds text to the system queue and returns a promise that resolves when queued, **not when
+playback ends**. Initialization, invalid voices, unsupported languages and Android's system text
+length limit can reject that promise. On Android, initialization times out after 15 seconds and a
+later request can retry. Stopping during initialization cancels pending speech immediately (those
+`speak` promises reject); it does not wait for a system callback. Empty/whitespace text is ignored. Options default to the
+system language/voice, rate 1, pitch 1 and volume 1. Rate accepts 0.1–2, pitch 0.5–2 and volume 0–1;
+the platform may clamp the effective rate. Voices and pronunciation depend on the installed system
+speech engine. `getAvailableVoicesAsync()` returns identifiers, names, BCP 47 languages and quality.
+Android lists installed voices that do not require a network connection.
+
+`isSpeakingAsync()` reports active speech (including paused speech on iOS/web). `pause()` and
+`resume()` work on iOS/web and reject on Android, whose system API has no pause/resume support.
+`stop()` resets paused browser state and ends the iOS synthesizer session so the next run starts cleanly.
+Browsers may require a user gesture before speaking, and voice discovery can initially be empty.
+As with [Expo Speech](https://docs.expo.dev/versions/latest/sdk/speech/), actual output depends on
+device settings such as silent mode. This API implements the options and methods above, not Expo's
+utterance event callbacks. System playback errors after an utterance is queued are not reported.
+
+For a muted iOS integration check, rebuild the core, boot an Apple Silicon simulator and run
+`bun test packages/engine/native/tests/speech-ios.test.ts` from the repository root. This checks the
+real Rust/native bridge, including stopping before playback begins and speaking again afterwards.
+
+### Score and timers
 
 ```ts
-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.handlers = { onTimeUp: () => endGame('lose') };
+world.scoreboard.listen({ onScore: setScore, onSecond: setTime }); // keep your UI in sync
+world.scoreboard.reset(3, 60); // 3 lives, 60 s countdown
+world.scoreboard.resume();
 world.scoreboard.add(10);
+
 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
+### Shapes in code
 
-```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)} />
-```
+Build a mesh once at module scope (after `warmUpEngine()`), then spawn it many times.
 
-**Input**
+```ts
+import { createShape, lathe } from '@nayan-ui/engine';
 
-```tsx
-<GameView
-  source={world}
-  onTap={(x, y) => {
-    const hit = world.pick(x, y);
-    if (hit) world.animate(hit.entity, { scale: 1.2 }, { yoyo: true, repeat: 1 });
-  }}
-  onSwipe={(direction) => move(direction)}
-  onDrag={({ phase, x, y }) => drag(phase, x, y)}
-/>
+const vase = createShape(
+  lathe(
+    [
+      [0, 0],
+      [0.4, 0.1],
+      [0.25, 0.8],
+      [0.3, 1]
+    ],
+    { segments: 24 }
+  )
+);
+world.spawn({ mesh: vase, color: '#C8763A' });
 ```
 
-`onLongPress`, `onPinch`, the on-screen `Joystick` and `createKeyboardInput` (web) cover other controls.
+Also available: `merge`, `tube`, `extrude`, `loft`, `block`, `ellipsoid`, `parametricSurface`, `Solid` and `shapeGeometry`.
 
-**Models, textures, text, sound and haptics**
+### Procedural worlds
+
+Describe terrain and placement rules as data; the native core generates the world on a background
+thread and answers walker queries, so none of that work runs in JavaScript.
 
 ```ts
-import { audio, haptics, loadFont, loadModel, loadTexture } from '@nayan-ui/engine';
+import { FieldGraph, generateWorldAsync } from '@nayan-ui/engine';
+
+const f = new FieldGraph();
+const bank = f.sub(f.abs(f.sub(f.x, f.sines(f.x, f.z, 0, [[0, 0.04, 0, 12]]))), 4); // a winding river
+f.output('bank', bank);
+f.output('height', f.select(bank, -1, f.bumps(f.x, f.z, [[30, 20, 5, 15, 12, 0]])));
+f.output('clear', f.sub(bank, 1));
+
+const world = await generateWorldAsync({
+  seed: 7,
+  fields: f,
+  terrain: {
+    axis: [...Array(101).keys()].map((i) => i * 2 - 100),
+    height: 'height',
+    regions: [{ field: 'bank', surface: 2, material: 1 }],
+    fallback: { surface: 1, material: 0 },
+    materials: 2
+  },
+  walk: { boundary: 95, clearance: 'clear', height: 2 },
+  steps: [
+    { kind: 'spawn', near: [-30, 0], rings: 20, samples: 16, radius: 1 },
+    { kind: 'reach', cell: 3, steps: 6, radius: 0.6, extent: 100 },
+    { kind: 'pick', groups: [{ name: 'coins', count: 10, spacing: 8 }] }
+  ]
+});
+const land = createShape(world.terrain(0), { center: false }); // one mesh per material
+world.move(player, dx, dz, 0.5); // swept move-and-slide; also ground, walkable, canSee, tilt
+```
 
-const car = await loadModel(require('./car.glb'), { fit: 2 }); // or a URL string on the web
-const crate = await loadTexture(require('./crate.png'));
-const font = await loadFont(require('./Inter-Bold.ttf'));
-world.spawn({ mesh: car, position: [0, 0, 0] });
-world.spawn({ mesh: 'cube', texture: crate });
-world.spawn({ text: '2048', font, position: [0, 2, 0], scale: 0.5 });
+Scatter steps place scenery with filters (fields, walkability, surfaces) and optional solids;
+`generateMesh` builds parametric surfaces and seeded cards. Pass `key` to save a world (tied to its
+exact recipe) and restore it on later visits.
 
-const sfx = audio.load({ coin: require('./coin.wav') });
-sfx.play('coin');
-haptics.impact(0.5);
-audio.enabled = settings.sounds; // respect the player's preferences
-haptics.enabled = settings.haptics;
+### 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)} />
 ```
 
-**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
 
-**Drawing**: a native paint canvas, also usable as a live texture inside games
+A native paint canvas, also usable as a live texture inside games.
 
 ```tsx
 import { DrawingCanvas, DrawingDocument } from '@nayan-ui/engine';
 
 const paper = new DrawingDocument(512, 512);
 paper.setBrush({ brushType: 'MARKER', color: '#e53935', width: 12, opacity: 1 });
+
 <DrawingCanvas document={paper} mode="draw" />;
 world.spawn({ mesh: 'plane', texture: paper.texture() }); // paint on a 3D object
 ```
 
 Drawings save as SVG paths and export transparent PNG snapshots.
 
+### Colors
+
+Use CSS strings (`'#FF4757'`, `'rgba(0, 0, 0, 0.5)'`) or linear 0..1 tuples (`[1, 0.3, 0.3]`; channels above 1 glow). `toColor('#FF4757')` converts a CSS color to numbers.
+
+## 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 (shadows off first, then anti-aliasing, resolution last) only while the device can't keep up. Shadows always come from a full-resolution map (soft at `high`, crisp at `medium`): `low` and `lowest` skip the shadow pass rather than show blurred low-resolution shadows. `lowest` smooths edges with FXAA (in the pass that stretches its reduced scene), and `lowest`'s pixel cap shrinks only the 3D scene (stretched to fill the view): the overlay, and so all HUD text, is always drawn at the screen's own resolution. With a `qualityKey` (games pass their id) the level it settles on is saved in the engine's durable store, so later visits, after app restarts too, start there. Pass `adaptQuality={false}` while what's on screen isn't the game being played (a menu, a results card): those frames then never change or save the level. `onStats` reports fps, update and render time, the quality chosen and the graphics backend.
+- **Cached backdrops.** Spawn scenery that never moves (a sky, distant hills, a board's background) with `still: true`, or a whole still scene into `world.backdropLayer(capacity)` (then `update(0)` it). `GameView` draws the world's backdrop layer once into an image behind the scene and draws that image each frame instead, redrawing it only after a still entity changes, the camera moves or the light changes. Live entities are always drawn in front of it and it receives no live shadows, so keep anything that moves, or that live pieces pass behind, in the world. A still entity takes `set` and `despawn` but can't be attached, animated, picked or given physics or text.
+- **Small things stay cheap.** Built-in spheres a few pixels across on screen (stars, pellets, beads) are drawn with 8- or 12-sided stand-ins, and instances scaled to nothing are never drawn, so pools of hidden pieces cost nothing on the GPU.
+- **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.
+
 ## Troubleshooting
 
 | Symptom                                         | Fix                                                                                                      |
@@ -287,10 +388,18 @@ Drawings save as SVG paths and export transparent PNG snapshots.
 | 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()`).         |
 
+## Prebuilt games
+
+[@nayan-ui/games](https://www.nayanui.com/games) offers 53 ready-made 3D games built on this engine. Each is one component with the same props.
+
+`@nayan-ui/games` is a **private package**. To use it in your application or website, reach out to [niranjan.devasani@gmail.com](mailto:niranjan.devasani@gmail.com).
+
+**[Play them in your browser](https://www.nayanui.com/games)**
+
 ## Learn more
 
-| Topic                                 | Guide                                                                                                          |
-| ------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| Topic                                 | Guide                                                                                                               |
+| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
 | 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)                                              |
@@ -302,7 +411,7 @@ Drawings save as SVG paths and export transparent PNG snapshots.
 
 ## License
 
-MIT © [Niranjan Devasani](https://github.com/ursnj)
+MIT
 
 ---
 

package/lib/module/assets/ProceduralCache.js

@@ -43,6 +43,11 @@ export class ProceduralCache {
     this.revision = revision;
     this.storage = storage;
   }
+
+  /** The engine storage key of `key` in this revision (for records the native core reads and writes itself). */
+  storageKey(key) {
+    return `procedural:${this.revision}:${key}`;
+  }
   get stats() {
     return {
       hits: this.hits,

package/lib/module/assets/loft.js

@@ -1,7 +1,7 @@
 "use strict";
 
-import { lathe, merge, recolor } from "./shape.js";
-import { parametricSurface } from "./surface.js";
+import { FieldFunction } from "./procedural.js";
+import { lathe, merge, nativeSweep, recolor } from "./shape.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
@@ -15,72 +15,24 @@ export function loft(sections, options = {}) {
     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 color = options.color;
+  const g = nativeSweep({
+    kind: 'loft',
+    sections: values,
+    around: n,
+    smoothness: steps,
+    color: typeof color === 'function' || color instanceof FieldFunction || !color ? undefined : [color[0], color[1], color[2]],
+    colorField: color instanceof FieldFunction ? color : undefined
   });
-  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);
+  return typeof color === 'function' ? paint(g, color) : g;
 }
 function paint(geometry, color) {
-  return color ? recolor(geometry, typeof color === 'function' ? ({
+  if (!color) return geometry;
+  if (color instanceof FieldFunction) return recolor(geometry, color);
+  return recolor(geometry, typeof color === 'function' ? ({
     position,
     normal
-  }) => color(position, normal) : () => color) : geometry;
+  }) => color(position, normal) : () => color);
 }
 
 /** A rounded rectangular cross-section with flat front/back caps, centered at the origin. */