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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Niranjan Devasani
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NayanEngine.podspec

@@ -0,0 +1,28 @@
+require "json"
+
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+
+Pod::Spec.new do |s|
+  s.name         = "NayanEngine"
+  s.version      = package["version"]
+  s.summary      = package["description"]
+  s.homepage     = package["homepage"]
+  s.license      = package["license"]
+  s.authors      = package["author"]
+
+  s.platforms    = { :ios => min_ios_version_supported }
+  s.source       = { :git => "https://github.com/ursnj/nayan-ui.git", :tag => "engine-v#{s.version}" }
+
+  s.source_files = "native/cpp/**/*.{h,cpp}", "native/ios/**/*.{h,m,mm}"
+  s.vendored_frameworks = "native/core/build/EngineCore.xcframework"
+  # The Rust core's audio (cpal / CoreAudio), haptics (Core Haptics) and renderer (wgpu on Metal) need
+  # these system frameworks.
+  s.frameworks = "AudioToolbox", "AVFAudio", "CoreAudio", "CoreHaptics", "Foundation", "Metal", "QuartzCore", "UIKit"
+
+  s.pod_target_xcconfig = {
+    "HEADER_SEARCH_PATHS" => "\"$(PODS_TARGET_SRCROOT)/native/core/include\" \"$(PODS_TARGET_SRCROOT)/native/cpp\"",
+    "CLANG_CXX_LANGUAGE_STANDARD" => "c++20"
+  }
+
+  install_modules_dependencies(s)
+end

package/README.md

@@ -1,3 +1,211 @@
-# Temporary Holding Version
+# @nayan-ui/engine
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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.
+
+**[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)**
+
+| 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         |
+
+## Install
+
+```sh
+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(...)`.
+
+```js
+config.resolver.assetExts.push('glb', 'gltf');
+```
+
+**React (web):** nothing else to configure. Call `await warmUpEngine()` before creating a world.
+
+## Quick start
+
+A complete scene that works unchanged on both platforms:
+
+```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 }}
+    />
+  );
+}
+```
+
+## 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`.
+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`.
+5. **Don't track disposal yourself**: check `world.isDisposed`. Cleanup calls are safe no-ops after `dispose()`.
+
+## Common tasks
+
+**Physics and collisions**
+
+```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)
+
+```ts
+await world.animate(piece, { position: [2, 0, 3] }, { duration: 0.25, easing: 'back' });
+world.animate(star, { scale: 1.2 }, { repeat: 'forever', yoyo: true });
+```
+
+**Ready-made effects**
+
+```ts
+import { effects } from '@nayan-ui/engine';
+
+effects.confetti(world, {
+  position: [0, 2, 0],
+  colors: [
+    [1, 0.3, 0.3],
+    [1, 0.85, 0.2]
+  ],
+  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: [1, 0.3, 0.3] }); // swell, flash white, shrink away
+world.despawn(piece);
+```
+
+Also available: `sparkle`, `shatter`, `splash`, `sparks`, `explosion` and `flash`.
+
+**Per-frame movement without allocations**
+
+```ts
+import { type MutableQuat, quat } from '@nayan-ui/engine';
+
+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
+}
+```
+
+**Score, lives and timers**
+
+```ts
+world.scoreboard.handlers = { onScore: setScore, onTimeUp: () => endGame('lose') };
+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);
+const timer = world.after(0.5, spawnWave); // game time: pauses with the game
+world.cancelTimer(timer);
+```
+
+**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)}
+  onDrag={({ phase, x, y }) => drag(phase, x, y)}
+/>
+```
+
+**Models, textures, text, sound and haptics**
+
+```ts
+import { audio, haptics, loadFont, loadModel, loadTexture } from '@nayan-ui/engine';
+
+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 });
+
+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;
+```
+
+**Drawing**: 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
+```
+
+## 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)**.
+
+## License
+
+MIT © [Niranjan Devasani](https://github.com/ursnj)

package/lib/module/assets/AssetBytesCache.js

@@ -0,0 +1,76 @@
+"use strict";
+
+import { cacheGeneration } from "./CacheGeneration.js";
+import { readPersistentAsset, removePersistentAsset, writePersistentAsset } from './storage';
+// Decoded resources own their lifetime. Only temporary download bytes are evictable.
+const BUDGET = 16 * 1024 * 1024;
+const MAX_ENTRIES = 128;
+const pending = new Map();
+const retained = new Map();
+let used = 0;
+
+/** Share concurrent requests across loader variants; failed requests can always be retried. */
+export function assetBytes(key, load) {
+  const bytes = retained.get(key);
+  if (bytes) {
+    retained.delete(key);
+    retained.set(key, bytes);
+    return Promise.resolve(bytes);
+  }
+  const existing = pending.get(key);
+  if (existing) return existing;
+  const epoch = cacheGeneration();
+  const request = Promise.resolve().then(async () => {
+    let saved = null;
+    try {
+      saved = await readPersistentAsset(key);
+    } catch {
+      /* Denied/corrupt storage is a miss. */
+    }
+    if (saved && epoch === cacheGeneration()) return saved;
+    const value = await load();
+    if (epoch === cacheGeneration()) {
+      // Await only the file write, never permission requests. Callers can rely on a completed load being saved.
+      try {
+        await writePersistentAsset(key, value);
+      } catch {
+        /* Keep existing records on quota/disk-full failures. */
+      }
+    }
+    return value;
+  }).then(value => {
+    if (epoch === cacheGeneration() && value.byteLength <= BUDGET) {
+      retained.set(key, value);
+      used += value.byteLength;
+      while (used > BUDGET || retained.size > MAX_ENTRIES) {
+        const oldest = retained.keys().next().value;
+        used -= retained.get(oldest).byteLength;
+        retained.delete(oldest);
+      }
+    }
+    return value;
+  }).finally(() => {
+    if (pending.get(key) === request) pending.delete(key);
+  });
+  pending.set(key, request);
+  return request;
+}
+
+/** A decoder rejected the payload: a later load must fetch fresh bytes, not replay bad data. */
+export function forgetAssetBytes(key) {
+  if (key === undefined) return;
+  void removePersistentAsset(key).catch(() => {});
+  const bytes = retained.get(key);
+  if (bytes) {
+    used -= bytes.byteLength;
+    retained.delete(key);
+  }
+}
+
+/** Clearing disk must also prevent an earlier request from retaining its old bytes. */
+export function clearAssetBytes() {
+  retained.clear();
+  pending.clear();
+  used = 0;
+}
+//# sourceMappingURL=AssetBytesCache.js.map

package/lib/module/assets/AssetCache.js

@@ -0,0 +1,19 @@
+"use strict";
+
+import { clearAssetBytes } from "./AssetBytesCache.js";
+import { advanceCacheGeneration } from "./CacheGeneration.js";
+import { clearPersistentStorage } from './storage';
+
+/**
+ * Explicitly removes the engine's saved geometry and original model/texture/font/audio files.
+ * Also clears temporary download bytes. Existing worlds and loaded handles remain usable;
+ * registrations are session resources and will be rebuilt/reloaded on a future app launch.
+ * Custom ProceduralStorage adapters belong to their host and are not cleared by this function.
+ * Rejects if storage cannot be cleared, allowing a settings screen to report the failure.
+ */
+export async function clearAssetCache() {
+  advanceCacheGeneration();
+  clearAssetBytes();
+  await clearPersistentStorage();
+}
+//# sourceMappingURL=AssetCache.js.map

package/lib/module/assets/AssetLoader.js

@@ -0,0 +1,52 @@
+"use strict";
+
+import NativeEngine from '../native/NativeNayanEngine';
+import { prepareEngine } from '../native/prepare';
+import { forgetAssetBytes } from "./AssetBytesCache.js";
+import { assetUri, loadAssetBytes } from './source';
+
+/** Shared session handles; source-byte persistence stays in AssetBytesCache and Rust. */
+export class AssetLoader {
+  loads = new Map();
+  constructor(name) {
+    this.name = name;
+  }
+  load(source, decode, variant = []) {
+    let uri;
+    try {
+      uri = assetUri(source);
+      if (!uri) throw new Error("couldn't resolve the asset source");
+    } catch (cause) {
+      return Promise.reject(this.error(String(source), cause));
+    }
+    // Tuple encoding prevents a URI containing separators from colliding with loader options.
+    const key = JSON.stringify([uri, ...variant]);
+    const existing = this.loads.get(key);
+    if (existing) return existing;
+    const pending = Promise.resolve().then(() => prepareEngine()).then(async () => {
+      if (!NativeEngine) throw new Error('the engine core is not linked into this build');
+      const {
+        bytes
+      } = await loadAssetBytes(source);
+      try {
+        return decode(NativeEngine, bytes);
+      } catch (cause) {
+        // Only rejected payloads invalidate saved bytes. Initialization/network failures don't.
+        forgetAssetBytes(uri);
+        throw cause;
+      }
+    }).catch(cause => {
+      this.loads.delete(key);
+      throw this.error(uri, cause);
+    });
+    this.loads.set(key, pending);
+    return pending;
+  }
+  error(source, cause) {
+    const message = cause instanceof Error ? cause.message : String(cause);
+    return new Error(`${this.name}: couldn't load ${source}: ${message}`, {
+      cause
+    });
+  }
+}
+//# sourceMappingURL=AssetLoader.js.map

package/lib/module/assets/CacheGeneration.js

@@ -0,0 +1,7 @@
+"use strict";
+
+// Operations started before an explicit clear may finish for their caller, but cannot refill storage.
+let generation = 0;
+export const cacheGeneration = () => generation;
+export const advanceCacheGeneration = () => ++generation;
+//# sourceMappingURL=CacheGeneration.js.map

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

@@ -0,0 +1,149 @@
+"use strict";
+
+// Browser I/O only. Rust owns cache keys, record validation, geometry and the warm-memory budget.
+const DATABASE = 'nayan-engine-assets-v1';
+function complete(transaction) {
+  return new Promise((resolve, reject) => {
+    transaction.oncomplete = () => resolve();
+    transaction.onabort = () => reject(transaction.error ?? new Error('Asset storage transaction aborted'));
+    transaction.onerror = () => reject(transaction.error ?? new Error('Asset storage transaction failed'));
+  });
+}
+function result(request) {
+  return new Promise((resolve, reject) => {
+    request.onsuccess = () => resolve(request.result);
+    request.onerror = () => reject(request.error ?? new Error('Asset storage request failed'));
+  });
+}
+export class IndexedDbCache {
+  tail = Promise.resolve();
+  pending = new Set();
+  generation = 0;
+  clearOperation = Promise.resolve();
+  constructor(database) {
+    this.database = database;
+    database.onversionchange = () => database.close();
+  }
+  static open() {
+    return new Promise((resolve, reject) => {
+      let settled = false;
+      let request;
+      try {
+        request = indexedDB.open(DATABASE, 1);
+      } catch (error) {
+        reject(error);
+        return;
+      }
+      request.onupgradeneeded = () => {
+        try {
+          const db = request.result;
+          db.createObjectStore('records');
+          db.createObjectStore('geometry').createIndex('writtenAt', 'writtenAt');
+        } catch {
+          request.transaction?.abort();
+        }
+      };
+      request.onsuccess = () => {
+        if (settled) {
+          request.result.close();
+          return;
+        }
+        settled = true;
+        resolve(new IndexedDbCache(request.result));
+      };
+      request.onerror = () => {
+        settled = true;
+        reject(request.error ?? new Error('Asset database unavailable'));
+      };
+      request.onblocked = () => {
+        settled = true;
+        reject(new Error('Another tab blocked the asset database upgrade'));
+      };
+    });
+  }
+  enqueue(operation) {
+    const task = this.tail.then(operation);
+    this.pending.add(task);
+    this.tail = task.catch(() => {}); // A failed write must not prevent a later clear/write.
+    void task.then(() => this.pending.delete(task), () => this.pending.delete(task));
+    return task;
+  }
+  /** The Uint8Array is an owned copy made by Rust, never a view into growable WASM memory. */
+  write(name, bytes, geometry) {
+    const epoch = this.generation;
+    return this.enqueue(async () => {
+      if (epoch !== this.generation) return;
+      const transaction = this.database.transaction(['records', 'geometry'], 'readwrite');
+      const saved = complete(transaction);
+      try {
+        transaction.objectStore('records').put(bytes, name);
+        if (geometry) transaction.objectStore('geometry').put({
+          bytes: bytes.byteLength,
+          writtenAt: Date.now()
+        }, name);
+      } catch (error) {
+        transaction.abort();
+        await saved.catch(() => {});
+        throw error;
+      }
+      await saved;
+    });
+  }
+  async read(name) {
+    await this.tail;
+    const transaction = this.database.transaction('records', 'readonly');
+    const finished = complete(transaction);
+    const value = await Promise.all([result(transaction.objectStore('records').get(name)), finished]);
+    const bytes = value[0];
+    return bytes instanceof Uint8Array ? bytes : undefined;
+  }
+  remove(name) {
+    return this.enqueue(async () => {
+      const transaction = this.database.transaction(['records', 'geometry'], 'readwrite');
+      const finished = complete(transaction);
+      transaction.objectStore('records').delete(name);
+      transaction.objectStore('geometry').delete(name);
+      await finished;
+    });
+  }
+  clear() {
+    this.generation++; // Cancel queued pre-clear writes; an active transaction finishes before clear.
+    this.clearOperation = this.enqueue(async () => {
+      const transaction = this.database.transaction(['records', 'geometry'], 'readwrite');
+      const finished = complete(transaction);
+      transaction.objectStore('records').clear();
+      transaction.objectStore('geometry').clear();
+      await finished;
+    });
+    return this.clearOperation;
+  }
+  flush() {
+    return Promise.all([...this.pending]).then(() => undefined);
+  }
+  cleared() {
+    return this.clearOperation;
+  }
+
+  /** Read recent geometry only. Large source files remain in IndexedDB until requested by a loader. */
+  warm(canFit, restore) {
+    const transaction = this.database.transaction(['records', 'geometry'], 'readonly');
+    const finished = complete(transaction);
+    const cursor = transaction.objectStore('geometry').index('writtenAt').openCursor(null, 'prev');
+    let scanned = 0;
+    cursor.onsuccess = () => {
+      const current = cursor.result;
+      if (!current || !canFit(0) || ++scanned > 4096) return;
+      const metadata = current.value;
+      if (typeof current.primaryKey === 'string' && metadata !== null && typeof metadata === 'object' && Number.isSafeInteger(metadata.bytes) && metadata.bytes > 0 && canFit(metadata.bytes)) {
+        const name = current.primaryKey;
+        const record = transaction.objectStore('records').get(name);
+        record.onsuccess = () => {
+          if (record.result instanceof Uint8Array && record.result.byteLength === metadata.bytes && canFit(record.result.byteLength)) restore(name, record.result);
+        };
+      }
+      current.continue();
+    };
+    return finished;
+  }
+}
+//# sourceMappingURL=IndexedDbCache.web.js.map