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

package/lib/module/render/quality.js

@@ -1,44 +1,93 @@
 "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.
+// limited by fill rate, so resolution and anti-aliasing matter most, then shadows.
 
 /** `"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).
+  // Ordered by what each step costs the eye. Shadows always use a full-resolution map: a low-resolution
+  // map's soft, smeared edges look worse than no shadow. "medium" keeps them with crisp single-tap
+  // edges (cheaper than the 3x3 filter); "low" drops the shadow pass entirely (which also saves its
+  // GPU time) and 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). Fill rate dominates a low-end GPU: an Adreno 610 tablet drew 2.4 MP in
+  // 42 ms and 0.78 MP in 21 ms (23 -> 41 fps).
   high: {
     maxPixelRatio: 3,
     samples: 4,
+    shadows: true,
     shadowSize: 2048,
     softShadows: true
   },
   medium: {
     maxPixelRatio: 3,
     samples: 4,
-    shadowSize: 1024,
-    softShadows: true
+    shadows: true,
+    shadowSize: 2048,
+    softShadows: false
   },
   low: {
     maxPixelRatio: 3,
     samples: 1,
-    shadowSize: 1024,
-    softShadows: false
+    shadows: false,
+    shadowSize: 2048,
+    softShadows: true
   },
   lowest: {
     maxPixelRatio: 2,
     samples: 1,
-    shadowSize: 512,
-    softShadows: false
+    fxaa: true,
+    shadows: false,
+    shadowSize: 2048,
+    softShadows: true,
+    maxPixels: 800_000
   }
 };
 
-/** A typical frame slower than this (under ~50 fps) is a frame the device can't hold. */
-const SLOW_FRAME_MS = 20;
+/**
+ * What "auto" walks through, from best to cheapest: a level, and the most pixels its 3D scene is drawn
+ * with. Before giving up an effect it draws the scene a little smaller, as native games scale their
+ * resolution: stretched over the screen under the full-resolution HUD, 1.5 MP (0.8x a 1200x2000
+ * tablet) can't be told from the screen's own resolution and 1.1 MP barely, while every effect stays.
+ * On the Adreno 610 tablet that took Crossy Road from 47 to 60 fps and Whack a Mole from 53 to 59 at
+ * "high": a tile-based GPU's cost under 4x MSAA grows with pixels times the triangles in each tile.
+ */
+
+export const AUTO_STEPS = [{
+  quality: 'high'
+}, {
+  quality: 'high',
+  maxPixels: 1_500_000
+}, {
+  quality: 'high',
+  maxPixels: 1_100_000
+}, {
+  quality: 'medium',
+  maxPixels: 1_100_000
+}, {
+  quality: 'low',
+  maxPixels: 1_100_000
+}, {
+  quality: 'lowest'
+}];
+
+/** A step's level: its quality's, with the step's pixel budget when that is smaller. */
+export function stepLevel(step) {
+  const level = QUALITY_LEVELS[step.quality];
+  if (!step.maxPixels || level.maxPixels && level.maxPixels <= step.maxPixels) return level;
+  return {
+    ...level,
+    maxPixels: step.maxPixels
+  };
+}
+
+/**
+ * A typical frame slower than this (under ~54 fps) is a frame the device can't hold: on a 60 Hz screen
+ * that is a visible stutter, and the first steps down cost only a little resolution.
+ */
+const SLOW_FRAME_MS = 18.5;
 /** 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. */
@@ -52,16 +101,69 @@ const SETTLE_MS = 1500;
 const SLOW_SECONDS = 3;
 const VERY_SLOW_SECONDS = 1;
 const FAST_SECONDS = 10;
+/**
+ * Seconds with the GPU drawing in at most this share of a 60 Hz frame: plenty of headroom (a light
+ * board game on a level below what it can hold, e.g. one remembered from a heavier version), so step
+ * up after only `HEADROOM_SECONDS` instead of FAST_SECONDS. These needn't be smooth: a frame now and
+ * then that the game loop (not drawing) drops can't be helped by a lower level, and would otherwise keep
+ * a game that draws in a few milliseconds at 57 fps on its remembered level for good.
+ */
+const HEADROOM_RENDER_MS = 10;
+const HEADROOM_SECONDS = 2;
 /** Stepping down again this soon after a step up means that level is too much: never return to it. */
 const RELAPSE_MS = 20_000;
 
+/** The pixel ratio a level draws a `width` x `height` point view at, on a screen of ratio `screen`. */
+export function levelPixelRatio(level, screen, width, height) {
+  const ratio = Math.min(screen, level.maxPixelRatio);
+  const area = width * height;
+  if (!level.maxPixels || area <= 0) return ratio;
+  return Math.min(ratio, Math.sqrt(level.maxPixels / area));
+}
+
+/** Durable records (the engine's Rust store); absent on builds without it, which then remember per session. */
+
+// Steps of AUTO_STEPS (the older `quality:` records held a level's index).
+const storeKey = key => `quality-step:${key}`;
+
+/**
+ * The step (of AUTO_STEPS) "auto" settled on per `qualityKey` (e.g. a game's id), kept in `store`
+ * across app launches: every visit of the same game starts there instead of spending its first seconds
+ * at "high" on a device that can't hold it (it still steps back up after smooth seconds).
+ */
+const settled = new Map();
+export function settledQuality(key, store) {
+  if (!key) return undefined;
+  const known = settled.get(key);
+  if (known !== undefined || typeof store?.cacheRead !== 'function') return known;
+  try {
+    const bytes = new Uint8Array(store.cacheRead(storeKey(key)));
+    const step = bytes.length === 1 && bytes[0] < AUTO_STEPS.length ? bytes[0] : undefined;
+    if (step !== undefined) settled.set(key, step);
+    return step;
+  } catch {
+    return undefined;
+  }
+}
+/** Records the step for `key`, writing it to `store` only when it changes. */
+export function rememberQuality(key, step, store) {
+  if (!key || settledQuality(key, store) === step) return;
+  settled.set(key, step);
+  try {
+    store?.cacheWrite?.(storeKey(key), new Uint8Array([step]).buffer);
+  } catch {
+    // Remembered for this session; the next launch starts from the stored (or default) step.
+  }
+}
+
 /** 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`
+ * Picks the step (of AUTO_STEPS) for "auto": starts at the best, steps down one 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
+ * stuttering through every level), and steps back up after `FAST_SECONDS` smooth seconds (`HEADROOM_SECONDS` when
+ * the GPU has plenty of time to spare). A level that fails again soon after being restored
  * becomes the ceiling, so it never bounces.
  */
 export class AutoQuality {
@@ -74,8 +176,25 @@ export class AutoQuality {
   slow = 0;
   verySlow = 0;
   fast = 0;
+  headroom = 0;
+
+  /** `start`: the step to begin at (one remembered from an earlier visit), or a quality's first step. */
+  constructor(start = 0) {
+    const index = typeof start === 'number' ? Math.floor(start) : AUTO_STEPS.findIndex(s => s.quality === start);
+    this.index = Math.min(Math.max(0, index), AUTO_STEPS.length - 1);
+  }
+
+  /** The current step's index in AUTO_STEPS. */
+  get step() {
+    return this.index;
+  }
   get quality() {
-    return QUALITIES[this.index];
+    return AUTO_STEPS[this.index].quality;
+  }
+
+  /** What to draw with: the step's level and pixel budget. */
+  get level() {
+    return stepLevel(AUTO_STEPS[this.index]);
   }
 
   /** Feeds one second of frames; returns true when the level changed. */
@@ -87,24 +206,39 @@ export class AutoQuality {
     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) {
+    this.headroom = !gpuBound && frames.renderMs <= HEADROOM_RENDER_MS ? this.headroom + 1 : 0;
+    if ((this.slow >= SLOW_SECONDS || this.verySlow >= VERY_SLOW_SECONDS) && this.index < AUTO_STEPS.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) {
+    if ((this.fast >= FAST_SECONDS || this.headroom >= HEADROOM_SECONDS) && this.index > this.ceiling) {
       this.index--;
       this.raisedAt = now;
       return this.moved(now);
     }
     return false;
   }
+
+  /**
+   * Frames that don't count (a results card over the game): forgets the streaks and, once frames
+   * count again, waits `SETTLE_MS` before judging, as after a change of level.
+   */
+  hold(now) {
+    if (!this.started) this.started = now;
+    this.changed = now;
+    this.slow = 0;
+    this.verySlow = 0;
+    this.fast = 0;
+    this.headroom = 0;
+  }
   moved(now) {
     this.changed = now;
     this.slow = 0;
     this.verySlow = 0;
     this.fast = 0;
+    this.headroom = 0;
     return true;
   }
 }

package/lib/module/world/World.js

@@ -77,6 +77,10 @@ export class World {
   boundsValue = null;
   listenerValue = null;
   updates = 0;
+  /** The layer still entities live in, the stand-in each one has here, and whether one changed. */
+  backdropValue = null;
+  stills = new Map();
+  stillChanged = false;
   constructor(capacity) {
     this.capacity = capacity;
     if (!NativeEngine) {
@@ -114,6 +118,7 @@ export class World {
 
   /** Adds an entity (one native call; text adds one per letter). Throws if the world is full or an option is invalid. */
   spawn(options = {}) {
+    if (options.still) return this.spawnStill(options);
     if (options.parent != null && options.physics != null) {
       throw new Error("World.spawn: attached entities can't have physics (put it on the parent)");
     }
@@ -146,12 +151,57 @@ export class World {
     return e;
   }
 
+  /**
+   * The still entities' layer (see `EntityOptions.still`), drawn once into a cached image behind this
+   * world; null until it's first used. GameView draws it; it's disposed with this world.
+   */
+  get backdrop() {
+    return this.backdropValue;
+  }
+
+  /**
+   * The still layer itself, made on first use with room for `capacity` entities: for a whole still
+   * scene (a meadow) spawned straight into it. Step it (`update(0)`) after changing it, which is
+   * what tells GameView to draw it again; it isn't stepped otherwise, so nothing in it moves.
+   */
+  backdropLayer(capacity = 64) {
+    if (this.disposed) throw new Error('World: used after dispose()');
+    return this.backdropValue ??= new World(capacity);
+  }
+  spawnStill({
+    still: _,
+    ...options
+  }) {
+    if (options.parent != null || options.physics != null || options.text !== undefined) {
+      throw new Error("World.spawn: a still entity can't be attached or have physics or text");
+    }
+    const layer = this.backdropLayer();
+    const entity = layer.spawn({
+      pickable: false,
+      ...options
+    });
+    // A stand-in here keeps the handle this world's own (unique, and cleared with it)
+    const standIn = this.spawn({
+      mesh: 'none',
+      pickable: false
+    });
+    this.stills.set(standIn, entity);
+    this.stillChanged = true;
+    return standIn;
+  }
+
   /**
    * Changes an entity (one native call). Only the options you pass change; `null` removes.
    * Returns false if the entity is gone, the world is disposed, or an option was rejected (the others still apply).
    */
   set(e, options) {
     if (this.disposed) return false;
+    const still = this.stills.get(e);
+    if (still !== undefined) {
+      if (options.parent != null || options.physics != null) throw new Error("World.set: a still entity can't be attached or have physics");
+      this.stillChanged = true;
+      return this.backdropValue.set(still, options);
+    }
     const text = this.texts.get(e);
     // A text entity stays an invisible root; its letters are rebuilt or recolored below.
     encode(this.desc, options, text ? undefined : this.resolveMesh(options, 'set'));
@@ -203,6 +253,12 @@ export class World {
   /** Removes an entity and anything attached to it. Returns false if it was already gone. */
   despawn(e) {
     if (this.disposed) return false;
+    const still = this.stills.get(e);
+    if (still !== undefined) {
+      this.stills.delete(e);
+      this.backdropValue.despawn(still);
+      this.stillChanged = true;
+    }
     const existed = this.native.despawn(this.id, e);
     this.texts.delete(e);
     this.resolveFinished(); // its animations, and those of attached entities that went with it
@@ -667,6 +723,11 @@ export class World {
     this.resolveFinished();
     this.runFallbackTimers(dt);
     if (!this.disposed) this.scoreboardValue?.dispatch();
+    // Still entities changed: step their layer once, which tells GameView to have it drawn again
+    if (this.stillChanged && this.backdropValue && !this.disposed) {
+      this.stillChanged = false;
+      this.backdropValue.update(0);
+    }
   }
 
   /**
@@ -698,6 +759,8 @@ export class World {
     this.pending.clear();
     this.timers.clear();
     this.fallbackTimers = [];
+    this.stills.clear();
+    this.backdropValue?.dispose();
     NativeEngine.destroyWorld(this.id);
   }
 }

package/lib/typescript/src/assets/ProceduralCache.d.ts

@@ -24,6 +24,8 @@ export declare class ProceduralCache {
     private failures;
     private writes;
     constructor(revision: string, storage?: ProceduralStorage | undefined);
+    /** The engine storage key of `key` in this revision (for records the native core reads and writes itself). */
+    storageKey(key: string): string;
     get stats(): {
         hits: number;
         builds: number;

package/lib/typescript/src/assets/loft.d.ts

@@ -1,5 +1,6 @@
 import type { Vec3 } from '../types.js';
 import type { Color } from '../world/types.js';
+import { FieldFunction } from './procedural.js';
 import { type Geometry } from './shape.js';
 export interface LoftSection {
     z: number;
@@ -14,7 +15,8 @@ export interface LoftSection {
 export interface LoftOptions {
     around?: number;
     smoothness?: number;
-    color?: Color | ((position: Vec3, normal: Vec3) => Color);
+    /** One color, a function of position and normal, or a `surfaceColor` field function (native). */
+    color?: Color | ((position: Vec3, normal: Vec3) => Color) | FieldFunction;
 }
 /**
  * Smooth closed body through rounded rectangular cross sections along Z. Useful for vehicle