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

package/lib/module/render/quality.js

@@ -0,0 +1,119 @@
+"use strict";
+
+// Rendering quality: how many pixels are drawn and how much each costs. Phones' GPUs are mostly
+// limited by fill rate, so resolution and anti-aliasing matter most, then shadow quality.
+
+/** `"auto"` starts at "high" and steps down only while the device really can't keep up. */
+
+/** From best looking to cheapest; "auto" walks down this list only as far as it must. */
+export const QUALITIES = ['high', 'medium', 'low', 'lowest'];
+export const QUALITY_LEVELS = {
+  // Ordered by what each step costs the eye: shadow detail goes first (barely noticed), then
+  // anti-aliasing; only the last resort draws fewer pixels, since anything below the screen's own
+  // resolution is stretched up and looks soft (text most of all).
+  high: {
+    maxPixelRatio: 3,
+    samples: 4,
+    shadowSize: 2048,
+    softShadows: true
+  },
+  medium: {
+    maxPixelRatio: 3,
+    samples: 4,
+    shadowSize: 1024,
+    softShadows: true
+  },
+  low: {
+    maxPixelRatio: 3,
+    samples: 1,
+    shadowSize: 1024,
+    softShadows: false
+  },
+  lowest: {
+    maxPixelRatio: 2,
+    samples: 1,
+    shadowSize: 512,
+    softShadows: false
+  }
+};
+
+/** A typical frame slower than this (under ~50 fps) is a frame the device can't hold. */
+const SLOW_FRAME_MS = 20;
+/** Under ~33 fps the game is plainly struggling: one such second is enough to step down. */
+const VERY_SLOW_FRAME_MS = 30;
+/** A typical frame this quick (60 fps with room to spare) is one it holds comfortably. */
+const FAST_FRAME_MS = 17.4;
+/** Only a slow second spent mostly drawing is the GPU's fault (a slow game loop isn't helped by drawing less). */
+const RENDER_SHARE = 0.6;
+/** Ignore start-up (loading, shader compiles) and the moments after a change. */
+const STARTUP_MS = 2500;
+const SETTLE_MS = 1500;
+/** Consecutive slow seconds before stepping down (one when very slow), and smooth seconds before trying a step back up. */
+const SLOW_SECONDS = 3;
+const VERY_SLOW_SECONDS = 1;
+const FAST_SECONDS = 10;
+/** Stepping down again this soon after a step up means that level is too much: never return to it. */
+const RELAPSE_MS = 20_000;
+
+/** One second of frames, as the frame loop measured it. */
+
+/**
+ * Picks the level for "auto": starts at the best, steps down one level after `SLOW_SECONDS`
+ * consecutive seconds whose typical frame misses ~50 fps while drawing took most of it (after a
+ * single second when it misses ~33 fps, so a struggling phone recovers in seconds rather than
+ * stuttering through every level), and steps back up after `FAST_SECONDS` smooth seconds. A level that fails again soon after being restored
+ * becomes the ceiling, so it never bounces.
+ */
+export class AutoQuality {
+  index = 0;
+  /** The best level it may return to (raised past a level that keeps failing). */
+  ceiling = 0;
+  started = 0;
+  changed = 0;
+  raisedAt = -Infinity;
+  slow = 0;
+  verySlow = 0;
+  fast = 0;
+  get quality() {
+    return QUALITIES[this.index];
+  }
+
+  /** Feeds one second of frames; returns true when the level changed. */
+  report(now, frames) {
+    if (!this.started) this.started = this.changed = now;
+    if (now - this.started < STARTUP_MS || now - this.changed < SETTLE_MS) return false;
+    const gpuBound = frames.frameMs > SLOW_FRAME_MS && frames.renderMs > frames.frameMs * RENDER_SHARE;
+    const smooth = frames.frameMs <= FAST_FRAME_MS;
+    this.slow = gpuBound ? this.slow + 1 : 0;
+    this.verySlow = gpuBound && frames.frameMs > VERY_SLOW_FRAME_MS ? this.verySlow + 1 : 0;
+    this.fast = smooth ? this.fast + 1 : 0;
+    if ((this.slow >= SLOW_SECONDS || this.verySlow >= VERY_SLOW_SECONDS) && this.index < QUALITIES.length - 1) {
+      // Failing again right after being restored: this level is too much for the device
+      if (now - this.raisedAt < RELAPSE_MS) this.ceiling = Math.max(this.ceiling, this.index + 1);
+      this.index++;
+      return this.moved(now);
+    }
+    if (this.fast >= FAST_SECONDS && this.index > this.ceiling) {
+      this.index--;
+      this.raisedAt = now;
+      return this.moved(now);
+    }
+    return false;
+  }
+  moved(now) {
+    this.changed = now;
+    this.slow = 0;
+    this.verySlow = 0;
+    this.fast = 0;
+    return true;
+  }
+}
+
+/** The middle value of `values` (sorted in place). */
+export function median(values) {
+  if (!values.length) return 0;
+  values.sort((a, b) => a - b);
+  const mid = values.length >> 1;
+  return values.length % 2 ? values[mid] : (values[mid - 1] + values[mid]) / 2;
+}
+//# sourceMappingURL=quality.js.map

package/lib/module/render/responder.js

@@ -0,0 +1,4 @@
+"use strict";
+
+export { PanResponder } from 'react-native';
+//# sourceMappingURL=responder.js.map

package/lib/module/render/responder.web.js

@@ -0,0 +1,97 @@
+"use strict";
+
+/** Adapt DOM pointer capture to the gesture recognizer used on mobile. Coordinates stay in CSS pixels. */
+export const PanResponder = {
+  create(callbacks) {
+    const pointers = new Map();
+    let origin = {
+      x: 0,
+      y: 0
+    };
+    let last = {
+      nativeEvent: {
+        pageX: 0,
+        pageY: 0,
+        locationX: 0,
+        locationY: 0,
+        touches: []
+      }
+    };
+    let gesture = {
+      dx: 0,
+      dy: 0
+    };
+    let primary = -1;
+    const event = e => {
+      const rect = e.currentTarget.getBoundingClientRect();
+      const nativeEvent = {
+        pageX: e.clientX,
+        pageY: e.clientY,
+        locationX: e.clientX - rect.left,
+        locationY: e.clientY - rect.top,
+        touches: [...pointers.values()]
+      };
+      if (e.pointerId === primary) gesture = {
+        dx: e.clientX - origin.x,
+        dy: e.clientY - origin.y
+      };
+      return last = {
+        nativeEvent
+      };
+    };
+    const cancel = () => {
+      if (pointers.size) callbacks.onPanResponderTerminate(last, gesture);
+      pointers.clear();
+      primary = -1;
+    };
+    return {
+      cancel,
+      panHandlers: {
+        onPointerDown(e) {
+          if (e.button !== 0) return;
+          e.preventDefault();
+          // Keyboard pointers already retain their target; only physical pointers can be captured.
+          if (e.isTrusted) e.currentTarget.setPointerCapture(e.pointerId);
+          pointers.set(e.pointerId, {
+            pageX: e.clientX,
+            pageY: e.clientY
+          });
+          if (pointers.size === 1) {
+            primary = e.pointerId;
+            origin = {
+              x: e.clientX,
+              y: e.clientY
+            };
+            gesture = {
+              dx: 0,
+              dy: 0
+            };
+            callbacks.onPanResponderGrant(event(e));
+          } else callbacks.onPanResponderMove(event(e), gesture);
+        },
+        onPointerMove(e) {
+          if (!pointers.has(e.pointerId)) return;
+          pointers.set(e.pointerId, {
+            pageX: e.clientX,
+            pageY: e.clientY
+          });
+          callbacks.onPanResponderMove(event(e), gesture);
+        },
+        onPointerUp(e) {
+          if (!pointers.has(e.pointerId)) return;
+          const current = event(e);
+          if (e.pointerId === primary || pointers.size >= 2) {
+            callbacks.onPanResponderRelease(current, gesture);
+            pointers.clear();
+            primary = -1;
+          } else pointers.delete(e.pointerId);
+        },
+        onPointerCancel: cancel,
+        onLostPointerCapture(e) {
+          if (pointers.has(e.pointerId)) cancel();
+        }
+      }
+    };
+  }
+};
+//# sourceMappingURL=responder.web.js.map

package/lib/module/render/touch.js

@@ -0,0 +1,185 @@
+"use strict";
+
+// Gesture recognition for GameView: tap, swipe, drag, long press, pinch.
+import { PanResponder } from './responder';
+const TAP_SLOP = 10; // points a finger may wander and still tap
+const TAP_TIME = 300; // ms
+const SWIPE_DISTANCE = 30; // points
+const SWIPE_SPEED = 0.3; // points per ms
+const LONG_PRESS_TIME = 500; // ms
+
+/**
+ * Creates a PanResponder that recognizes taps, swipes, drags, long presses and pinches.
+ * `getHandlers` is called on each event so the caller can swap handlers without recreating the responder.
+ */
+export function createTouchResponder(getHandlers) {
+  let start = {
+    x: 0,
+    y: 0,
+    time: 0
+  };
+  let origin = {
+    x: 0,
+    y: 0
+  };
+  let mode = 'none';
+  let pinch0 = {
+    distance: 1,
+    angle: 0
+  };
+  let lastPinch = {
+    phase: 'end',
+    scale: 1,
+    rotation: 0,
+    x: 0,
+    y: 0
+  };
+  let longPress;
+  let longPressed = false;
+  const drag = (phase, x, y, cancelled) => getHandlers().onDrag?.({
+    phase,
+    x,
+    y,
+    dx: x - start.x,
+    dy: y - start.y,
+    ...(cancelled && {
+      cancelled
+    })
+  });
+  const twoFingers = (touches, phase) => {
+    const [a, b] = touches;
+    const distance = Math.max(1, Math.hypot(b.pageX - a.pageX, b.pageY - a.pageY));
+    const angle = Math.atan2(b.pageY - a.pageY, b.pageX - a.pageX);
+    if (phase === 'start') pinch0 = {
+      distance,
+      angle
+    };
+    lastPinch = {
+      phase,
+      scale: distance / pinch0.distance,
+      rotation: angle - pinch0.angle,
+      x: (a.pageX + b.pageX) / 2 - origin.x,
+      y: (a.pageY + b.pageY) / 2 - origin.y
+    };
+    getHandlers().onPinch?.(lastPinch);
+  };
+  const stopLongPress = () => {
+    clearTimeout(longPress);
+    longPress = undefined;
+  };
+  const responder = PanResponder.create({
+    onStartShouldSetPanResponder: () => true,
+    onMoveShouldSetPanResponder: () => true,
+    onPanResponderGrant: e => {
+      const {
+        locationX,
+        locationY,
+        pageX,
+        pageY
+      } = e.nativeEvent;
+      start = {
+        x: locationX,
+        y: locationY,
+        time: Date.now()
+      };
+      origin = {
+        x: pageX - locationX,
+        y: pageY - locationY
+      };
+      if (getHandlers().onOverlayTouch?.('start', start.x, start.y) === true) {
+        mode = 'overlay';
+        return;
+      }
+      mode = 'drag';
+      longPressed = false;
+      drag('start', start.x, start.y);
+      if (getHandlers().onLongPress) {
+        longPress = setTimeout(() => {
+          longPress = undefined;
+          if (mode !== 'drag') return;
+          longPressed = true;
+          getHandlers().onLongPress?.(start.x, start.y);
+        }, LONG_PRESS_TIME);
+      }
+    },
+    onPanResponderMove: (e, g) => {
+      if (mode === 'overlay') {
+        getHandlers().onOverlayTouch?.('move', start.x + g.dx, start.y + g.dy);
+        return;
+      }
+      const touches = e.nativeEvent.touches;
+      if (touches.length >= 2 && getHandlers().onPinch) {
+        if (mode === 'drag') {
+          stopLongPress();
+          drag('end', start.x + g.dx, start.y + g.dy, true);
+          mode = 'pinch';
+          twoFingers(touches, 'start');
+        } else if (mode === 'pinch') {
+          twoFingers(touches, 'move');
+        }
+        return;
+      }
+      if (mode !== 'drag') return;
+      if (Math.hypot(g.dx, g.dy) >= TAP_SLOP) stopLongPress();
+      drag('move', start.x + g.dx, start.y + g.dy);
+    },
+    onPanResponderRelease: (_, g) => {
+      stopLongPress();
+      const was = mode;
+      mode = 'none';
+      if (was === 'none') return;
+      if (was === 'overlay') {
+        getHandlers().onOverlayTouch?.('end', start.x + g.dx, start.y + g.dy);
+        return;
+      }
+      if (was === 'pinch') {
+        getHandlers().onPinch?.({
+          ...lastPinch,
+          phase: 'end'
+        });
+        return;
+      }
+      const x = start.x + g.dx;
+      const y = start.y + g.dy;
+      drag('end', x, y);
+      if (longPressed) return;
+      const {
+        onTap,
+        onSwipe
+      } = getHandlers();
+      const distance = Math.hypot(g.dx, g.dy);
+      const time = Date.now() - start.time;
+      if (distance < TAP_SLOP && time < TAP_TIME) onTap?.(start.x, start.y);else if (distance > SWIPE_DISTANCE && distance / Math.max(1, time) > SWIPE_SPEED) {
+        onSwipe?.(Math.abs(g.dx) > Math.abs(g.dy) ? g.dx > 0 ? 'right' : 'left' : g.dy > 0 ? 'down' : 'up');
+      }
+    },
+    onPanResponderTerminate: (_, g) => {
+      stopLongPress();
+      const was = mode;
+      mode = 'none';
+      if (was === 'overlay') getHandlers().onOverlayTouch?.('cancel', start.x + g.dx, start.y + g.dy);else if (was === 'pinch') getHandlers().onPinch?.({
+        ...lastPinch,
+        phase: 'end'
+      });else if (was === 'drag') drag('end', start.x + g.dx, start.y + g.dy, true);
+    }
+  });
+  const cancel = () => {
+    responder.cancel?.();
+    stopLongPress();
+    const was = mode;
+    mode = 'none';
+    if (was === 'overlay') getHandlers().onOverlayTouch?.('cancel', start.x, start.y);else if (was === 'pinch') getHandlers().onPinch?.({
+      ...lastPinch,
+      phase: 'end'
+    });else if (was === 'drag') drag('end', start.x, start.y, true);
+  };
+  return {
+    responder,
+    dispose: cancel,
+    cancel
+  };
+}
+
+// Re-export threshold constants for testing.
+export { TAP_SLOP, TAP_TIME, SWIPE_DISTANCE, SWIPE_SPEED, LONG_PRESS_TIME };
+//# sourceMappingURL=touch.js.map

package/lib/module/render/useWorld.js

@@ -0,0 +1,72 @@
+"use strict";
+
+import { useEffect, useRef, useState } from 'react';
+import { isEngineAvailable, World } from "../world/World.js";
+import { warmUpEngine } from "./meshes.js";
+
+/** What `useWorld`'s setup may return: a cleanup, run just before the world is disposed. */
+
+/**
+ * A `World` owned by a component: the engine is warmed up (needed on the web, cheap on mobile), the
+ * world is created with `capacity` entity slots and handed to `setup` to fill, and it is disposed on
+ * unmount. A change in `deps` replaces it with a fresh one. Returns null until it's ready (one frame),
+ * and while the engine is unavailable (Expo Go) or failed to start (`onError`, console by default).
+ *
+ * ```tsx
+ * const world = useWorld(100, (w) => {
+ *   w.spawn({ mesh: 'plane', scale: [20, 1, 20], color: '#4C9A4C', physics: 'fixed' });
+ *   w.spawn({ mesh: 'sphere', position: [0, 4, 0], color: '#3399FF', physics: 'dynamic' });
+ * });
+ * return world && <GameView source={world} style={{ flex: 1 }} />;
+ * ```
+ */
+export function useWorld(capacity, setup, deps = [], onError) {
+  const [world, setWorld] = useState(null);
+  // The latest callbacks, so passing inline functions doesn't recreate the world each render.
+  const latest = useRef({
+    setup,
+    onError
+  });
+  latest.current = {
+    setup,
+    onError
+  };
+  useEffect(() => {
+    let active = true;
+    let created = null;
+    let cleanup;
+    const report = error => {
+      const e = error instanceof Error ? error : new Error(String(error));
+      (latest.current.onError ?? (x => console.error(`useWorld: ${x.message}`)))(e);
+    };
+    if (!isEngineAvailable) {
+      report(new Error('the native engine is not linked into this build (a development build is needed, not Expo Go)'));
+      return;
+    }
+    warmUpEngine().then(() => {
+      if (!active) return;
+      try {
+        created = new World(capacity);
+        cleanup = latest.current.setup?.(created);
+        setWorld(created);
+      } catch (error) {
+        created?.dispose();
+        created = null;
+        report(error);
+      }
+    }, report);
+    return () => {
+      active = false;
+      setWorld(null);
+      if (!created) return;
+      try {
+        cleanup?.();
+      } finally {
+        created.dispose();
+      }
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [capacity, ...deps]);
+  return world;
+}
+//# sourceMappingURL=useWorld.js.map

package/lib/module/types.js

@@ -0,0 +1,30 @@
+"use strict";
+
+/** Number of mesh ids: built-in shapes (0..15), then loaded models, glyphs and textured variants. */
+export const MAX_MESHES = 4096;
+
+/** What the renderer draws. `World` implements it; so can any custom simulation. */
+
+/**
+ * Built-in shapes, each 1 unit across before scaling. "none" isn't drawn (groups, pivots, trigger zones).
+ * "puff" is a soft, round sprite that always faces the camera and is always see-through: overlapping
+ * puffs blend into smoke, dust, steam and clouds. "flame" is the same sprite drawn additively: it adds
+ * light to what's behind it, so overlapping flames build up to a hot white core and stay bright over
+ * smoke (fire, sparks, explosions, magic, glows). Use them as a burst's `mesh`.
+ */
+
+/** Mesh ids of the built-in shapes, as the core and renderer know them. */
+export const SHAPE_MESH = {
+  cube: 0,
+  sphere: 1,
+  plane: 2,
+  cylinder: 3,
+  cone: 4,
+  capsule: 5,
+  torus: 6,
+  roundedBox: 7,
+  puff: 8,
+  flame: 9,
+  none: 15
+};
+//# sourceMappingURL=types.js.map

package/lib/module/world/Scoreboard.js

@@ -0,0 +1,161 @@
+"use strict";
+
+import NativeEngine from '../native/NativeNayanEngine';
+const OP = {
+  addScore: 0,
+  setScore: 1,
+  addLives: 2,
+  setLives: 3,
+  startClock: 4,
+  stopClock: 5,
+  resumeClock: 6,
+  reset: 7,
+  addTime: 8,
+  timeBonus: 9
+};
+const S = {
+  score: 0,
+  lives: 1,
+  seconds: 2,
+  shown: 3,
+  flags: 4,
+  running: 5,
+  rate: 6,
+  best: 7
+};
+const FLAG = {
+  score: 1,
+  lives: 2,
+  second: 4,
+  timeUp: 8,
+  livesOut: 16
+};
+/**
+ * Score, lives and the game clock, kept and advanced in Rust by `world.update`: countdowns, elapsed
+ * time and time-based points (survival, distance) cost no JS per frame. Handlers run from `update`
+ * only when something they show changed. Set `handlers` for the game's own rules, and `listen` for
+ * anything else that follows along (a UI showing the score), so neither replaces the other.
+ *
+ * ```ts
+ * world.scoreboard.handlers = { onTimeUp: () => end(true) };
+ * const stop = world.scoreboard.listen({ onScore: setScore, onSecond: setTime });
+ * world.scoreboard.reset(3);
+ * world.scoreboard.startCountdown(60);
+ * world.scoreboard.add(10);
+ * ```
+ */
+export class Scoreboard {
+  /** The game's own handlers. `listen` adds more without replacing these. */
+  handlers = {};
+  listeners = new Set();
+  /** @internal */
+  constructor(world) {
+    this.world = world;
+    if (!NativeEngine || typeof NativeEngine.getScoreboard !== 'function') {
+      throw new Error("Scoreboard: this app's native core predates the scoreboard: rebuild it");
+    }
+    this.state = new Float64Array(NativeEngine.getScoreboard(world));
+  }
+  op(op, a = 0, b = 0) {
+    return NativeEngine.scoreboard(this.world, op, a, b);
+  }
+  get score() {
+    return this.state[S.score];
+  }
+  get best() {
+    return this.state[S.best];
+  }
+  get lives() {
+    return this.state[S.lives];
+  }
+  /** Seconds left (countdown) or elapsed, fractional. */
+  get seconds() {
+    return this.state[S.seconds];
+  }
+  /** Whole seconds as shown: rounded up while counting down, down while counting up. */
+  get shownSeconds() {
+    return this.state[S.shown];
+  }
+  get running() {
+    return this.state[S.running] !== 0;
+  }
+
+  /** Adds points (negative to take away). Returns the score. */
+  add(points) {
+    return this.op(OP.addScore, points);
+  }
+  set(score) {
+    return this.op(OP.setScore, score);
+  }
+  addLives(n) {
+    this.op(OP.addLives, n);
+    return this.lives;
+  }
+  setLives(n) {
+    this.op(OP.setLives, n);
+  }
+  /** Counts `seconds` down to 0 (then `onTimeUp`), earning `pointsPerSecond` meanwhile. */
+  startCountdown(seconds, pointsPerSecond = 0) {
+    this.op(OP.startClock, Math.max(1e-6, seconds), pointsPerSecond);
+  }
+  /** Counts up from 0, earning `pointsPerSecond` (survival and distance scores). */
+  startClock(pointsPerSecond = 0) {
+    this.op(OP.startClock, 0, pointsPerSecond);
+  }
+  stop() {
+    this.op(OP.stopClock);
+  }
+  resume() {
+    this.op(OP.resumeClock);
+  }
+  /** Time bonus (or penalty) on the clock. */
+  addTime(seconds) {
+    this.op(OP.addTime, seconds);
+  }
+  /**
+   * Adds `pointsPerSecond` for each whole second saved: the seconds left on a countdown, or
+   * `expectedSeconds` minus the seconds elapsed on a clock counting up. Returns the score.
+   */
+  awardTimeBonus(pointsPerSecond, expectedSeconds = 0) {
+    return this.op(OP.timeBonus, pointsPerSecond, expectedSeconds);
+  }
+  /**
+   * A new run: score 0, `lives`, clock stopped at 0. With `countdownSeconds`, the stopped clock shows
+   * that countdown in full (a ready screen); `resume()` starts it.
+   */
+  reset(lives = 0, countdownSeconds = 0) {
+    this.op(OP.reset, lives);
+    if (countdownSeconds > 0) {
+      this.startCountdown(countdownSeconds);
+      this.stop();
+    }
+  }
+
+  /**
+   * Adds handlers alongside `handlers` (and other listeners); they run after them, in order of
+   * listening. Returns a function that removes them.
+   */
+  listen(handlers) {
+    this.listeners.add(handlers);
+    return () => {
+      this.listeners.delete(handlers);
+    };
+  }
+
+  /** @internal Runs handlers for what changed since the last call. */
+  dispatch() {
+    const flags = this.state[S.flags];
+    if (flags === 0) return;
+    this.state[S.flags] = 0;
+    this.run(this.handlers, flags);
+    if (this.listeners.size) for (const h of [...this.listeners]) this.run(h, flags);
+  }
+  run(h, flags) {
+    if (flags & FLAG.score) h.onScore?.(this.score);
+    if (flags & FLAG.lives) h.onLives?.(this.lives);
+    if (flags & FLAG.second) h.onSecond?.(this.shownSeconds);
+    if (flags & FLAG.timeUp) h.onTimeUp?.();
+    if (flags & FLAG.livesOut) h.onLivesOut?.();
+  }
+}
+//# sourceMappingURL=Scoreboard.js.map