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

package/lib/module/native/BrowserEngine.js

@@ -204,6 +204,8 @@ export function createBrowserEngine(core) {
     fn(name, id, p);
     return Array.from(float ? new Float32Array(memory(), p, count) : new Uint32Array(memory(), p, count));
   };
+  /** A promise for work that runs right here (its errors reject it). */
+  const settle = work => new Promise(resolve => resolve(work()));
   const engine = {
     createWorld(capacity) {
       if (!Number.isInteger(capacity) || capacity < 1 || capacity > 1_000_000) throw new Error('World: capacity must be an integer in 1..1000000');
@@ -402,6 +404,21 @@ export function createBrowserEngine(core) {
       const [x, y, z] = dimensions('model_size', mesh, 3, true);
       return [x, y, z];
     },
+    // The browser core is single-threaded: the "background" loads settle at once with the same work.
+    modelLoadAsync(value, center, fit) {
+      return settle(() => engine.modelLoad(value, center, fit));
+    },
+    textureLoadAsync(value) {
+      return settle(() => engine.textureLoad(value));
+    },
+    fontLoadAsync(value, depth, chars, weight) {
+      return settle(() => engine.fontLoad(value, depth, chars, weight));
+    },
+    audioLoadAsync(value) {
+      return settle(() => engine.audioLoad(value));
+    },
+    // An older core without it uploads through JS instead (see registerCoreMesh).
+    renderModel: (mesh, texture, shine) => typeof core.engine_render_model === 'function' && fn('render_model', mesh, texture, shine) !== 0,
     modelTexture: mesh => fn('model_texture', mesh),
     meshAlias: mesh => fn('mesh_alias', mesh),
     meshCreate(vertices, indices) {

package/lib/module/render/GameView.js

@@ -3,6 +3,7 @@
 import { useEffect, useMemo, useRef } from 'react';
 import NativeEngine from '../native/NativeNayanEngine';
 import { MAX_MESHES } from "../types.js";
+import { resolveColor } from "../world/color.js";
 import { follow, shake } from "./camera.js";
 import { createTouchResponder, pixelRatio, Surface, useActive } from './host';
 import { getMeshIdLimit, uploadBuiltInMeshes } from "./meshes.js";
@@ -21,6 +22,44 @@ const defaultLight = () => ({
   direction: [0.4, 0.8, 0.5],
   ambient: 0.35
 });
+
+/** Callbacks waiting for the next frame any GameView finishes (see `afterNextFrame`). */
+let afterFrame = [];
+/** GameView frame loops running now. */
+let runningLoops = 0;
+function runAfterFrame() {
+  if (afterFrame.length === 0) return;
+  const due = afterFrame;
+  afterFrame = [];
+  for (const fn of due) fn();
+}
+
+/**
+ * Runs `fn` right after the next frame a GameView hands to the screen, on the same display clock
+ * (the native one where the platform has it): the time a frame leaves is the best moment for
+ * background work, such as loading in slices. With no GameView running it falls back to
+ * requestAnimationFrame. Returns a function that cancels it.
+ *
+ * ```ts
+ * const cancel = afterNextFrame(() => buildNextChunk());
+ * ```
+ */
+export function afterNextFrame(fn) {
+  let cancelled = false;
+  const run = () => {
+    if (!cancelled) fn();
+  };
+  if (runningLoops > 0) afterFrame.push(run);else {
+    const raf = requestAnimationFrame(run);
+    return () => {
+      cancelled = true;
+      cancelAnimationFrame(raf);
+    };
+  }
+  return () => {
+    cancelled = true;
+  };
+}
 export function GameView(props) {
   const {
     source,
@@ -75,6 +114,11 @@ export function GameView(props) {
     let alive = true;
     let raf = 0;
     let errors = 0;
+    // Where the platform has them (Android), frames come from the display's own clock and are drawn
+    // on the engine's render thread: this loop only runs the game and publishes what to draw.
+    const native2 = native;
+    const threaded = native2.hasFrameClock?.() === true && typeof native2.publishFrame === 'function' && typeof native2.startFrames === 'function';
+    let presentedAt = 0;
     if (autoQuality.current?.source !== source) autoQuality.current = {
       source,
       auto: new AutoQuality()
@@ -132,7 +176,7 @@ export function GameView(props) {
     let shown = false;
     const frame = now => {
       if (!alive) return;
-      raf = requestAnimationFrame(frame);
+      if (!threaded) raf = requestAnimationFrame(frame);
       if (!last) last = fpsStart = now;
       if (now > last) intervals.push(now - last);
       const dt = shown ? Math.min((now - last) / 1000, 0.1) : 0;
@@ -144,7 +188,13 @@ export function GameView(props) {
         environment
       } = live.current;
       const t0 = performance.now();
+      const layer = current.overlay;
+      const sourceSteps = source.updateCount;
+      const layerSteps = layer?.updateCount;
       current.onUpdate?.(dt);
+      // Step what onUpdate didn't (a World counts its own updates), so the loop needs no boilerplate.
+      if (source.update && !source.isDisposed && source.updateCount === sourceSteps) source.update(dt);
+      if (layer?.update && !layer.isDisposed && layer.updateCount === layerSteps) layer.update(dt);
       updateTime += performance.now() - t0;
       follow(camera, source, followed, dt);
       const view = shake(camera, shaken, dt);
@@ -166,11 +216,11 @@ export function GameView(props) {
       f[12] = light.shadows ?? true ? 1 : 0;
       f[13] = light.shadowExtent ?? 30;
       // Exactly three channels each: either color may carry an alpha that must not spill over.
-      const lightColor = light.color ?? WHITE;
+      const lightColor = light.color === undefined ? WHITE : resolveColor(light.color);
       f[14] = lightColor[0];
       f[15] = lightColor[1];
       f[16] = lightColor[2];
-      const sky = environment.background;
+      const sky = resolveColor(environment.background);
       f[17] = sky[0];
       f[18] = sky[1];
       f[19] = sky[2];
@@ -181,7 +231,6 @@ export function GameView(props) {
       f[24] = level.shadowSize;
       f[25] = level.softShadows ? 1 : 0;
       const t1 = performance.now();
-      const layer = current.overlay;
       if (layer) {
         if (overlay?.source !== layer) overlay = {
           source: layer,
@@ -192,28 +241,42 @@ export function GameView(props) {
         overlay = null;
         native.renderOverlay(surfaceId, regions.buffer, regions.buffer, regions.buffer, regions.buffer, 0, 0, 0); // removes it
       }
-      const rendered = native.renderFrame(surfaceId, f.buffer, source.matrices.buffer, source.colors.buffer, regions.buffer, source.ranges.buffer, drawn(source), viewProj.buffer, source.nativeWorld ?? -1);
+      const render = threaded ? native2.publishFrame : native.renderFrame;
+      const rendered = render(surfaceId, f.buffer, source.matrices.buffer, source.colors.buffer, regions.buffer, source.ranges.buffer, drawn(source), viewProj.buffer, source.nativeWorld ?? -1);
       const drawMs = performance.now() - t1;
-      renderTime += drawMs;
-      draws.push(drawMs);
-      if (rendered === 1) {
-        shown = true;
-        source.setView?.(viewProj, width, height);
-      } else if (rendered < 0 && errors++ < 3) {
-        report(new Error(native.renderError() || 'rendering failed'));
+      if (!threaded) {
+        renderTime += drawMs;
+        draws.push(drawMs);
       }
+      // A published frame's camera is known at once (picking needs it), whether or not it's presented yet.
+      if (rendered === 1 || threaded && rendered === 0) source.setView?.(viewProj, width, height);
+      if (rendered === 1) shown = true;else if (rendered < 0 && errors++ < 3) report(new Error(native.renderError() || 'rendering failed'));
       frames++;
       if (now - fpsStart >= 1000) {
+        const elapsed = now - fpsStart;
+        let fps = frames * 1000 / elapsed;
+        let frameMs = median(intervals);
+        let renderMs = median(draws);
+        let meanRenderMs = renderTime / frames;
+        if (threaded) {
+          // What the display actually got: frames presented by the render thread, and how long each took to draw.
+          const [presented = 0, nativeMs = 0] = native2.renderStats?.(surfaceId) ?? [];
+          const shownFrames = presented - presentedAt;
+          presentedAt = presented;
+          fps = shownFrames * 1000 / elapsed;
+          frameMs = shownFrames > 0 ? Math.max(frameMs, elapsed / shownFrames) : elapsed;
+          renderMs = meanRenderMs = nativeMs;
+        }
         auto.report(now, {
-          frameMs: median(intervals),
-          renderMs: median(draws)
+          frameMs,
+          renderMs
         });
         intervals.length = 0;
         draws.length = 0;
         current.onStats?.({
-          fps: frames * 1000 / (now - fpsStart),
+          fps,
           updateMs: updateTime / frames,
-          renderMs: renderTime / frames,
+          renderMs: meanRenderMs,
           quality,
           backend: native.renderBackend()
         });
@@ -222,11 +285,16 @@ export function GameView(props) {
         renderTime = 0;
         fpsStart = now;
       }
+      runAfterFrame();
     };
-    raf = requestAnimationFrame(frame);
+    if (threaded) native2.startFrames(surfaceId, frame);else raf = requestAnimationFrame(frame);
+    runningLoops++;
     return () => {
       alive = false;
-      cancelAnimationFrame(raf);
+      runningLoops--;
+      // Work waiting on this loop's frames moves to requestAnimationFrame if it was the last one.
+      if (runningLoops === 0 && afterFrame.length) requestAnimationFrame(runAfterFrame);
+      if (threaded) native2.stopFrames(surfaceId);else cancelAnimationFrame(raf);
     };
     // A new source or resuming a paused view restarts drawing; other props are read live.
     // eslint-disable-next-line react-hooks/exhaustive-deps

package/lib/module/render/light.js

@@ -0,0 +1,24 @@
+"use strict";
+
+/**
+ * A light for flat, front-facing scenes (boards, puzzles, 2D games looking down -z): surfaces facing
+ * the camera (+z) are lit at exactly 1, so flat panels show their color unchanged, while rounded
+ * shapes keep their shading (lighter toward the light, darker away). Shadows are off.
+ *
+ * ```tsx
+ * <GameView source={world} light={frontLight([-0.45, 0.6, 1], 0.5)} />
+ * ```
+ */
+export function frontLight(direction, ambient) {
+  const [x, y, z] = direction;
+  const facing = z / Math.hypot(x, y, z);
+  // Mirrors the renderer's shading: ambient × hemisphere (0.8 for a sideways normal) plus diffuse.
+  const k = 1 / (ambient * 0.8 + (1 - ambient) * facing);
+  return {
+    direction,
+    ambient,
+    shadows: false,
+    color: [k, k, k]
+  };
+}
+//# sourceMappingURL=light.js.map

package/lib/module/render/quality.js

@@ -39,15 +39,18 @@ export const QUALITY_LEVELS = {
 
 /** 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 = 2000;
-/** Consecutive slow seconds before stepping down, and smooth seconds before trying a step back up. */
+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;
@@ -56,8 +59,9 @@ const RELAPSE_MS = 20_000;
 
 /**
  * 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, and steps
- * back up after `FAST_SECONDS` smooth seconds. A level that fails again soon after being restored
+ * 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 {
@@ -68,6 +72,7 @@ export class AutoQuality {
   changed = 0;
   raisedAt = -Infinity;
   slow = 0;
+  verySlow = 0;
   fast = 0;
   get quality() {
     return QUALITIES[this.index];
@@ -80,8 +85,9 @@ export class AutoQuality {
     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.index < QUALITIES.length - 1) {
+    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++;
@@ -97,6 +103,7 @@ export class AutoQuality {
   moved(now) {
     this.changed = now;
     this.slow = 0;
+    this.verySlow = 0;
     this.fast = 0;
     return true;
   }

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/world/Scoreboard.js

@@ -33,17 +33,21 @@ const FLAG = {
 /**
  * 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.
+ * 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 = { onScore: setScore, onSecond: setTime, onTimeUp: () => end(true) };
+ * 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;
@@ -127,12 +131,26 @@ export class Scoreboard {
     }
   }
 
+  /**
+   * 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;
-    const h = this.handlers;
+    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);

package/lib/module/world/TransformBatch.js

@@ -1,10 +1,11 @@
 "use strict";
 
+import { resolveColor } from "./color.js";
 export const TRANSFORM_STRIDE = 16;
 
 /**
- * Explicit draw-only updates, applied in one native call by `flush()`. Flush before reading
- * positions, animating, or stepping the world. Records and scratch storage are reused; values are
+ * Explicit draw-only updates, applied in one native call by `flush()`. `world.update` flushes
+ * `world.transforms` before stepping; flush yourself before reading positions or animating. Records and scratch storage are reused; values are
  * copied when queued, never retained by reference. The scalar methods (`position`, `rotation`,
  * `scale`, `color`, `transform`) allocate nothing; consecutive calls for the same entity share one
  * record.
@@ -105,7 +106,8 @@ export class TransformBatch {
     if (typeof scale === 'number') this.data.fill(scale, offset + 9, offset + 12);else if (scale) this.data.set(scale, offset + 9);
     if (color) this.writeColor(offset, color);
   }
-  writeColor(offset, color) {
+  writeColor(offset, input) {
+    const color = resolveColor(input);
     this.data[offset + 12] = color[0];
     this.data[offset + 13] = color[1];
     this.data[offset + 14] = color[2];

package/lib/module/world/World.js

@@ -4,6 +4,7 @@ import { layoutText } from "../assets/font.js";
 import { texturedMesh } from "../assets/texture.js";
 import NativeEngine from '../native/NativeNayanEngine';
 import { SHAPE_MESH } from "../types.js";
+import { resolveColor, resolveColors } from "./color.js";
 import { ANIM_HEADER, ANIM_KEY_LEN, BURST_LEN, DESC_LEN, EASING, encode } from "./desc.js";
 import { Scoreboard } from "./Scoreboard.js";
 import { TRANSFORM_STRIDE, TransformBatch } from "./TransformBatch.js";
@@ -75,6 +76,7 @@ export class World {
   gravityValue = [0, -9.81, 0];
   boundsValue = null;
   listenerValue = null;
+  updates = 0;
   constructor(capacity) {
     this.capacity = capacity;
     if (!NativeEngine) {
@@ -130,7 +132,7 @@ export class World {
           letterSpacing: options.letterSpacing,
           tabular: options.tabular
         },
-        color: options.color ?? [1, 1, 1],
+        color: resolveColor(options.color ?? WHITE),
         glyphs: []
       };
       try {
@@ -163,7 +165,7 @@ export class World {
         letterSpacing: options.letterSpacing ?? text.layout.letterSpacing,
         tabular: options.tabular ?? text.layout.tabular
       };
-      if (options.color) text.color = options.color;
+      if (options.color) text.color = resolveColor(options.color);
       if (rebuild) this.buildText(e, text);else if (options.color) {
         const desc = this.encodeColor(options.color);
         for (const g of text.glyphs) this.native.setDesc(this.id, g, desc);
@@ -174,7 +176,8 @@ export class World {
 
   /**
    * This world's shared draw-only transform batch (created on first use). Queue per-frame moves with
-   * its allocation-free methods after `update()`, then `flush()` once before the frame is drawn.
+   * its allocation-free methods; the next `update()` applies them first (or `flush()` them yourself
+   * before reading positions or animating).
    */
   get transforms() {
     return this.transformsValue ??= this.createTransformBatch();
@@ -358,10 +361,11 @@ export class World {
     }
     if (k.color) {
       flags |= KEY_FLAG.color;
-      a[o + 12] = k.color[0];
-      a[o + 13] = k.color[1];
-      a[o + 14] = k.color[2];
-      a[o + 15] = k.color[3] ?? 1;
+      const c = resolveColor(k.color);
+      a[o + 12] = c[0];
+      a[o + 13] = c[1];
+      a[o + 14] = c[2];
+      a[o + 15] = c[3] ?? 1;
     }
     if (k.moveBy) {
       flags |= KEY_FLAG.moveBy;
@@ -393,9 +397,8 @@ export class World {
    */
   burst(options) {
     const b = this.burstDesc;
-    const color = options.color ?? WHITE;
-    const single = typeof color[0] === 'number';
-    const colorCount = single ? 1 : Math.max(1, Math.min(4, color.length));
+    const colors = resolveColors(options.color ?? WHITE);
+    const colorCount = Math.max(1, Math.min(4, colors.length));
     b.set(options.position, 0);
     b.set(options.direction ?? UP, 3);
     b[6] = options.spread ?? Math.PI;
@@ -406,11 +409,11 @@ export class World {
     b[11] = options.lifetime ?? 0.8;
     b[12] = options.gravity ?? -9.81;
     b[13] = colorCount;
-    for (let k = 0; k < colorCount; k++) writeRgba(b, 14 + k * 4, single ? color : color[k]);
+    for (let k = 0; k < colorCount; k++) writeRgba(b, 14 + k * 4, colors[k]);
     b[30] = options.endSize ?? 1;
     const end = options.endColor;
     b[31] = end ? 1 : 0;
-    if (end) writeRgba(b, 32, end);
+    if (end) writeRgba(b, 32, resolveColor(end));
     return this.native.burst(this.id, b.buffer);
   }
 
@@ -468,6 +471,11 @@ export class World {
     return this.scoreboardValue ??= new Scoreboard(this.id);
   }
 
+  /** How many times `update` has run. GameView reads it to step the world only when `onUpdate` didn't. */
+  get updateCount() {
+    return this.updates;
+  }
+
   /** Timers waiting to fire. */
   get timerCount() {
     return this.timers.size + this.fallbackTimers.length;
@@ -647,8 +655,14 @@ export class World {
 
   // ── Simulation ───────────────────────────────────────────────────────
 
-  /** Advances the simulation (fixed 60 Hz steps), resolves finished animations, refreshes what GameView draws. */
+  /**
+   * Advances the simulation (fixed 60 Hz steps), resolves finished animations, runs due timers and
+   * scoreboard handlers, and refreshes what GameView draws. `GameView` calls it for you each frame;
+   * call it yourself from `onUpdate` only to step with a different `dt` (it is then not stepped twice).
+   */
   update(dt) {
+    this.updates++;
+    this.transformsValue?.flush(); // moves queued this frame land before the step
     this.native.update(this.id, dt);
     this.resolveFinished();
     this.runFallbackTimers(dt);

package/lib/module/world/color.js

@@ -0,0 +1,80 @@
+"use strict";
+
+// Colors: every engine option that takes a color accepts either a linear 0..1 tuple or a CSS color
+// string, so theme colors go straight in: `world.spawn({ color: '#FF4757' })`.
+
+/** A color as an option takes it: `[r, g, b]` / `[r, g, b, a]` (0..1, channels above 1 glow) or a CSS string. */
+
+const HEX = /^#([0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})$/i;
+const RGB = /^rgba?\(\s*([\d.]+)\s*,\s*([\d.]+)\s*,\s*([\d.]+)\s*(?:,\s*([\d.]+%?)\s*)?\)$/i;
+const NAMED = {
+  transparent: [0, 0, 0, 0],
+  black: [0, 0, 0, 1],
+  white: [1, 1, 1, 1],
+  red: [1, 0, 0, 1],
+  green: [0, 128 / 255, 0, 1],
+  blue: [0, 0, 1, 1],
+  yellow: [1, 1, 0, 1],
+  orange: [1, 165 / 255, 0, 1],
+  purple: [128 / 255, 0, 128 / 255, 1],
+  gray: [128 / 255, 128 / 255, 128 / 255, 1],
+  grey: [128 / 255, 128 / 255, 128 / 255, 1]
+};
+
+// Theme colors repeat endlessly; parse each string once.
+const parsed = new Map();
+const PARSED_LIMIT = 1024;
+function parse(css) {
+  const text = css.trim();
+  const named = NAMED[text.toLowerCase()];
+  if (named) return named;
+  const hex = HEX.exec(text);
+  if (hex) {
+    let digits = hex[1];
+    if (digits.length <= 4) digits = [...digits].map(d => d + d).join('');
+    const n = i => parseInt(digits.slice(i, i + 2), 16) / 255;
+    return [n(0), n(2), n(4), digits.length === 8 ? n(6) : 1];
+  }
+  const rgb = RGB.exec(text);
+  if (rgb) {
+    const alpha = rgb[4] === undefined ? 1 : rgb[4].endsWith('%') ? parseFloat(rgb[4]) / 100 : Number(rgb[4]);
+    return [Number(rgb[1]) / 255, Number(rgb[2]) / 255, Number(rgb[3]) / 255, alpha];
+  }
+  throw new Error(`@nayan-ui/engine: "${css}" is not a color (use '#RRGGBB', '#RGB', '#RRGGBBAA', 'rgb(…)', 'rgba(…)' or a 0..1 tuple)`);
+}
+
+/**
+ * Any color input as an `[r, g, b, a]` tuple (0..1), with its alpha multiplied by `alpha`. Use it when
+ * you need the numbers (to brighten, mix or fade a theme color); options take strings directly.
+ *
+ * ```ts
+ * toColor('#FF4757'); // [1, 0.278, 0.341, 1]
+ * toColor('#FF4757', 0.5); // half see-through
+ * ```
+ */
+export function toColor(color, alpha = 1) {
+  let c;
+  if (typeof color === 'string') {
+    let hit = parsed.get(color);
+    if (!hit) {
+      hit = parse(color);
+      if (parsed.size >= PARSED_LIMIT) parsed.clear();
+      parsed.set(color, hit);
+    }
+    c = hit;
+  } else c = color;
+  return [c[0], c[1], c[2], (c[3] ?? 1) * alpha];
+}
+
+/** A color input as a tuple, without copying tuples (the hot path of `spawn`, `set` and `animate`). */
+export function resolveColor(color) {
+  return typeof color === 'string' ? toColor(color) : color;
+}
+
+/** One color input, or a list to pick from, as tuples. */
+export function resolveColors(colors) {
+  if (typeof colors === 'string') return [toColor(colors)];
+  if (typeof colors[0] === 'number') return [colors];
+  return colors.map(resolveColor);
+}
+//# sourceMappingURL=color.js.map

package/lib/module/world/desc.js

@@ -3,7 +3,7 @@
 // Encodes entity options into the flat layout the Rust core decodes (native/core/include/engine_core.h,
 // native/core/src/world/desc.rs). One reusable Float64Array per world: spawning or changing an entity is
 // a single native call, and doubles keep entity ids and layer bits exact.
-
+import { resolveColor } from "./color.js";
 export const DESC_LEN = 64;
 const FLAG = {
   MESH: 1 << 0,
@@ -102,10 +102,11 @@ export function encode(d, o, mesh) {
   }
   if (o.color) {
     flags |= FLAG.COLOR;
-    d[SLOT.COLOR] = o.color[0];
-    d[SLOT.COLOR + 1] = o.color[1];
-    d[SLOT.COLOR + 2] = o.color[2];
-    d[SLOT.COLOR + 3] = o.color[3] ?? 1;
+    const c = resolveColor(o.color);
+    d[SLOT.COLOR] = c[0];
+    d[SLOT.COLOR + 1] = c[1];
+    d[SLOT.COLOR + 2] = c[2];
+    d[SLOT.COLOR + 3] = c[3] ?? 1;
   }
   if (o.velocity) {
     flags |= FLAG.VELOCITY;