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

package/lib/typescript/src/media/speechPlatform.web.d.ts

@@ -0,0 +1,5 @@
+export declare const speechPlatform: {
+    readonly supported: boolean;
+    request(command: string): Promise<string>;
+};
+//# sourceMappingURL=speechPlatform.web.d.ts.map

package/lib/typescript/src/native/EngineBridge.d.ts

@@ -10,15 +10,21 @@ type BufferMethod<T> = T extends (...args: infer A) => infer R ? (...args: {
 }) => BufferValue<R, ArrayBuffer> : T;
 /** Native-only (a display clock and a render thread): absent on the web core and on older app builds. */
 type NativeFrames = 'publishFrame' | 'renderStats' | 'hasFrameClock' | 'startFrames' | 'stopFrames';
-type BinarySpec = Omit<Spec, 'geometrySolid' | 'geometryOptimize' | 'modelSize' | 'textureSize' | NativeFrames>;
+type BinarySpec = Omit<Spec, 'speechRequest' | 'geometrySolid' | 'geometryOptimize' | 'modelSize' | 'modelBake' | 'textureSize' | 'worldgenTerrain' | 'worldgenMesh' | 'worldgenTilt' | 'worldgenMove' | NativeFrames>;
 /** The same runtime ABI on JSI and WASM, with precise TypeScript buffer and tuple contracts. */
 export type EngineBridge = {
     [K in keyof BinarySpec]: BufferMethod<BinarySpec[K]>;
 } & {
+    speechRequest?: Spec['speechRequest'];
     geometrySolid(recipe: string): NativeGeometry;
     geometryOptimize(vertices: ArrayBufferLike, indices: ArrayBufferLike, ratio: number, error: number, lockBorders: boolean): NativeGeometry;
     modelSize(mesh: number): [x: number, y: number, z: number];
+    modelBake(mesh: number, spec: string): [] | [texture: number, x: number, y: number, extent: number];
     textureSize(texture: number): [width: number, height: number];
+    worldgenTerrain(world: number, material: number): NativeGeometry;
+    worldgenMesh(recipe: string): NativeGeometry;
+    worldgenTilt(world: number, x: number, z: number, yaw: number): [x: number, y: number, z: number, w: number];
+    worldgenMove(world: number, x: number, z: number, dx: number, dz: number, radius: number, bodies: ArrayBufferLike): [x: number, z: number];
 } & {
     [K in NativeFrames]?: BufferMethod<Spec[K]>;
 };

package/lib/typescript/src/native/spec/NativeNayanEngine.d.ts

@@ -9,6 +9,8 @@ import { type TurboModule } from 'react-native';
  * and stay valid until `destroyWorld`.
  */
 export interface Spec extends TurboModule {
+    /** System speech commands; JSON envelope contains value or error. */
+    speechRequest(command: string): Promise<string>;
     createWorld(capacity: number): number;
     destroyWorld(world: number): void;
     /** Returns the entity id, or -1 if the world is full or the description is rejected. */
@@ -98,6 +100,10 @@ export interface Spec extends TurboModule {
     modelIndices(mesh: number): Object;
     /** Full bounding-box size [x, y, z]. */
     modelSize(mesh: number): Array<number>;
+    /** Bakes a model into a new texture (spec: BakeSpec JSON): [texture, center x, center y, extent], or [] on failure (`loadError`). */
+    modelBake(mesh: number, spec: string): Array<number>;
+    /** Whether a baked picture is kept under `key`. */
+    bakeKept(key: string): boolean;
     /** The model's base color texture id, or -1. */
     modelTexture(mesh: number): number;
     /** A new mesh id with `base`'s geometry (to give it another texture), or -1. */
@@ -185,6 +191,12 @@ export interface Spec extends TurboModule {
      * scene. count 0 removes it.
      */
     renderOverlay(surface: number, matrices: Object, colors: Object, regions: Object, ranges: Object, count: number, width: number, height: number): void;
+    /**
+     * Static scenery behind the scene (the world's instance buffers, as `renderOverlay`): drawn into a
+     * cached texture with each frame's camera and light, and again only when this is called again or
+     * the view, light, size or quality change. count 0 removes it.
+     */
+    renderBackdrop(surface: number, matrices: Object, colors: Object, regions: Object, ranges: Object, count: number): void;
     renderError(): string;
     /** "vulkan", "gl" or "metal" ("" before the first surface). */
     renderBackend(): string;
@@ -202,9 +214,69 @@ export interface Spec extends TurboModule {
     audioSetVolume(volume: number): void;
     audioSetMuted(muted: boolean): void;
     audioIsRunning(): boolean;
+    /** Frees a sound's samples (a played recording); its id then plays nothing. */
+    audioRelease(sound: number): void;
+    /** A sound's length in seconds (0 if unknown or released). */
+    audioDuration(sound: number): number;
+    /** Loudness per `1 / perSecond` s of a sound, as a Float32 ArrayBuffer. */
+    audioLevels(sound: number, perSecond: number): Object;
+    /** 1 granted, 0 not asked yet (or not granted on Android), -1 denied. */
+    micPermission(): number;
+    /** Shows the system prompt the first time; resolves to whether recording is allowed. */
+    micRequestPermission(): Promise<boolean>;
+    /** Starts listening, keeping the last `maxSeconds` of input; true if it's opening. */
+    micStart(maxSeconds: number): boolean;
+    micStop(): void;
+    /** 0 off, 1 opening, 2 listening, -1 failed. */
+    micState(): number;
+    /** Input loudness now, 0..1. */
+    micLevel(): number;
+    /** Seconds of input held. */
+    micHeld(): number;
+    /** A sound id of the `seconds` of input that ended `skipEnd` seconds ago, or -1; forgets what was heard. */
+    micTake(seconds: number, skipEnd: number): number;
     hapticsSupported(): boolean;
     /** Taps as flat [time, intensity, sharpness, ...] triples. */
     hapticsPlay(taps: Array<number>, throttle: boolean): void;
+    /** Builds (or, with a `key` saved from the same recipe, restores) a world. 0 on failure (`worldgenError`). */
+    worldgenBuild(recipe: string, key: string, prepareTerrain: boolean): number;
+    /** `worldgenBuild` on a background native thread. */
+    worldgenBuildAsync(recipe: string, key: string, prepareTerrain: boolean): Promise<number>;
+    worldgenError(): string;
+    /** Whether a world was saved under `key`. */
+    worldgenKept(key: string): boolean;
+    worldgenFree(world: number): void;
+    /** Spawn, restored flag, layer sizes and picked spots as JSON. */
+    worldgenInfo(world: number): string;
+    /** A scatter layer's items (f64, stride from `worldgenInfo`). */
+    worldgenLayer(world: number, name: string): Object;
+    /** Reachable cells as f64 [x, z] pairs. */
+    worldgenReachable(world: number): Object;
+    /** Overview surface codes (u8, size × size). */
+    worldgenOverview(world: number): Object;
+    /** Re-picks the spots for `run`; false keeps the previous ones. */
+    worldgenPick(world: number, run: number): boolean;
+    /** The terrain mesh of a material, handed over once: { vertices, indices }. */
+    worldgenTerrain(world: number, material: number): Object;
+    /** Builds a procedural mesh recipe: { vertices, indices }. */
+    worldgenMesh(recipe: string): Object;
+    /** Recolors 11-float vertices in place by a field function (`{ fields, out }`) of each surface point. */
+    worldgenPaint(vertices: Object, recipe: string): boolean;
+    worldgenGround(world: number, x: number, z: number): number;
+    worldgenSurface(world: number, x: number, z: number): number;
+    /** The platform under a point, or -1. */
+    worldgenPlatform(world: number, x: number, z: number): number;
+    worldgenWalkable(world: number, x: number, z: number, radius: number): boolean;
+    worldgenClearance(world: number, x: number, z: number, radius: number): number;
+    worldgenSolidClearance(world: number, x: number, z: number, radius: number, bottom: number, top: number): number;
+    /** A named field's index for `worldgenField`, or -1. */
+    worldgenFieldIndex(world: number, name: string): number;
+    worldgenField(world: number, field: number, x: number, z: number): number;
+    /** Ground tilt as a quaternion [x, y, z, w]. */
+    worldgenTilt(world: number, x: number, z: number, yaw: number): Array<number>;
+    worldgenSight(world: number, ax: number, az: number, bx: number, bz: number, radius: number, step: number, rise: number): boolean;
+    /** Swept move-and-slide; `bodies` is an f64 buffer of [x, z, radius] triples. Returns [x, z]. */
+    worldgenMove(world: number, x: number, z: number, dx: number, dz: number, radius: number, bodies: Object): Array<number>;
 }
 declare const _default: Spec | null | undefined;
 export default _default;

package/lib/typescript/src/render/GameView.d.ts

@@ -15,12 +15,19 @@ import { type RenderQuality, type RenderQualitySetting } from './quality.js';
 export declare function afterNextFrame(fn: () => void): () => void;
 export type GameViewStats = {
     fps: number;
-    /** Mean time spent in `onUpdate` per frame, in milliseconds. */
+    /** Mean time spent in `onUpdate` and stepping the worlds per frame, in milliseconds. */
     updateMs: number;
+    /**
+     * Mean JS-thread time per frame spent handing the frame and overlay to the renderer, in
+     * milliseconds. With a render thread this is copying only; otherwise it includes drawing.
+     */
+    publishMs: number;
     /** Average milliseconds per frame spent drawing (CPU side, including waiting on the GPU). */
     renderMs: number;
     /** The quality level drawn with (with `quality="auto"`, the one it settled on so far). */
     quality: RenderQuality;
+    /** The 3D scene's resolution per axis relative to the screen's: 1, or less under a pixel budget. */
+    sceneScale: number;
     /** The graphics API drawing: "vulkan", "gl" (OpenGL ES) or "metal". */
     backend: string;
 };
@@ -65,11 +72,22 @@ export type GameViewProps = {
     /** Distance fog density towards `background` (e.g. 0.02). Default 0 (off). */
     fog?: number;
     /**
-     * Resolution, anti-aliasing and shadow quality. "auto" (default) starts at "high", steps down only
-     * while the GPU really can't keep up (shadow detail first, then anti-aliasing, resolution last) and
+     * Resolution, anti-aliasing and shadows. "auto" (default) starts at "high", steps down only while
+     * the GPU really can't keep up (crisper shadows, then no shadows or anti-aliasing, resolution last) and
      * steps back up once frames are smooth again, so every phone gets the best look it can hold.
      */
     quality?: RenderQualitySetting;
+    /**
+     * Remembers the level "auto" settles on under this key (e.g. the game's id) in the engine's durable
+     * store, so every later view with the same key, after app restarts too, starts there rather than at "high".
+     */
+    qualityKey?: string;
+    /**
+     * Whether "auto" judges the device by the frames now (default true). Pass false while what's on
+     * screen isn't the game being played (a results card, a menu, a ready screen): their cost says
+     * nothing about the game, and a level chosen there would be remembered for the next visit.
+     */
+    adaptQuality?: boolean;
     /** Suspend updates and drawing while keeping the native surface mounted. */
     paused?: boolean;
     style?: ViewStyle;
@@ -92,6 +110,15 @@ export type GameViewProps = {
      * frame like `source`.
      */
     overlay?: RenderSource;
+    /**
+     * Static scenery behind `source` (a meadow, sky and hills; a board's backdrop): the renderer draws it
+     * once into a cached image with this view's camera and light, and draws it again only when it
+     * changes or the camera, light, size or quality do. Each frame then costs one full-screen image
+     * instead of the whole scenery, and `source` is always drawn in front of it. It isn't stepped (its
+     * velocities and animations stand still): call `backdrop.update(0)` after spawning or changing it.
+     * Defaults to `source.backdrop`: a World's still entities (`still: true`, `backdropLayer`).
+     */
+    backdrop?: RenderSource;
     /**
      * Touches for the overlay, in points in the view. Return true from "start" to claim the touch (a
      * button was hit): its moves and end come here, and the game gets no drag, tap or swipe for it.

package/lib/typescript/src/render/quality.d.ts

@@ -6,14 +6,53 @@ export type QualityLevel = {
     maxPixelRatio: number;
     /** MSAA samples: 4 or 1 (off). */
     samples: 1 | 4;
+    /**
+     * Smooths edges after drawing (FXAA), in the pass that stretches a reduced scene to the screen (so
+     * only with `maxPixels`): there it costs a few texture reads per pixel. At full resolution it would
+     * need that whole extra pass, which costs a tile-based phone GPU more than 4x MSAA. The overlay (HUD
+     * text) is drawn after it, untouched.
+     */
+    fxaa?: boolean;
+    /** Whether shadows are drawn at all (a scene's light may still turn them off). */
+    shadows: boolean;
     /** Shadow map width and height in texels. */
     shadowSize: number;
     /** 3x3 filtered (soft) shadow edges, or a single tap (hard). */
     softShadows: boolean;
+    /**
+     * Most device pixels drawn per frame, whatever the screen's ratio: a cap on the pixel ratio alone
+     * leaves a low-density tablet (1.75x on 1200x2000) drawing its full resolution even at "lowest".
+     */
+    maxPixels?: number;
 };
 /** From best looking to cheapest; "auto" walks down this list only as far as it must. */
 export declare const QUALITIES: readonly RenderQuality[];
 export declare const QUALITY_LEVELS: Record<RenderQuality, QualityLevel>;
+/**
+ * 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 type QualityStep = {
+    quality: RenderQuality;
+    maxPixels?: number;
+};
+export declare const AUTO_STEPS: readonly QualityStep[];
+/** A step's level: its quality's, with the step's pixel budget when that is smaller. */
+export declare function stepLevel(step: QualityStep): QualityLevel;
+/** The pixel ratio a level draws a `width` x `height` point view at, on a screen of ratio `screen`. */
+export declare function levelPixelRatio(level: QualityLevel, screen: number, width: number, height: number): number;
+/** Durable records (the engine's Rust store); absent on builds without it, which then remember per session. */
+export type QualityStore = {
+    cacheRead?: (key: string) => ArrayBuffer;
+    cacheWrite?: (key: string, bytes: ArrayBuffer) => boolean;
+};
+export declare function settledQuality(key: string | undefined, store?: QualityStore): number | undefined;
+/** Records the step for `key`, writing it to `store` only when it changes. */
+export declare function rememberQuality(key: string | undefined, step: number, store?: QualityStore): void;
 /** One second of frames, as the frame loop measured it. */
 export type FrameReport = {
     /** The typical (median) time between frames, in ms: hiccups (garbage collection, a busy JS frame) don't move it. */
@@ -22,10 +61,11 @@ export type FrameReport = {
     renderMs: number;
 };
 /**
- * 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 declare class AutoQuality {
@@ -38,9 +78,21 @@ export declare class AutoQuality {
     private slow;
     private verySlow;
     private fast;
+    private headroom;
+    /** `start`: the step to begin at (one remembered from an earlier visit), or a quality's first step. */
+    constructor(start?: number | RenderQuality);
+    /** The current step's index in AUTO_STEPS. */
+    get step(): number;
     get quality(): RenderQuality;
+    /** What to draw with: the step's level and pixel budget. */
+    get level(): QualityLevel;
     /** Feeds one second of frames; returns true when the level changed. */
     report(now: number, frames: FrameReport): boolean;
+    /**
+     * 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: number): void;
     private moved;
 }
 /** The middle value of `values` (sorted in place). */

package/lib/typescript/src/types.d.ts

@@ -7,6 +7,8 @@ export declare const MAX_MESHES = 4096;
 export interface RenderSource {
     /** Native world id, when this source supports skeletal characters. */
     readonly nativeWorld?: number;
+    /** Still scenery drawn once into a cached image behind this source (a World's still entities). */
+    readonly backdrop?: RenderSource | null;
     /** Column-major mat4 per instance (16 floats), grouped by mesh. Only the first `count` are valid. */
     readonly matrices: Float32Array;
     /** RGBA per instance (4 floats), same order as `matrices`. Alpha below 1 draws see-through. */
@@ -67,8 +69,13 @@ export type Light = {
     direction: [number, number, number];
     /** 0..1 ambient term. */
     ambient: number;
-    /** Cast shadows (one directional shadow map centred on the camera target). Default true. */
-    shadows?: boolean;
+    /**
+     * Cast shadows (one directional shadow map centred on the camera target). Default true.
+     * `'backdrop'`: only the cached backdrop layer draws its shadow map (and its own shadows); live
+     * entities still receive those shadows but cast none, so a frame skips the shadow pass. For scenes
+     * whose ground is all backdrop, where live shadows would land on nothing that shows them.
+     */
+    shadows?: boolean | 'backdrop';
     /** Half-size in world units of the shadowed area around the camera target. Default 30. */
     shadowExtent?: number;
     /**

package/lib/typescript/src/world/World.d.ts

@@ -45,6 +45,10 @@ export declare class World implements RenderSource {
     private boundsValue;
     private listenerValue;
     private updates;
+    /** The layer still entities live in, the stand-in each one has here, and whether one changed. */
+    private backdropValue;
+    private readonly stills;
+    private stillChanged;
     constructor(capacity: number);
     private get native();
     /** True once `dispose()` has run. Cleanup calls (despawn, set, has, queries, stopping animations
@@ -55,6 +59,18 @@ export declare class World implements RenderSource {
     get count(): number;
     /** Adds an entity (one native call; text adds one per letter). Throws if the world is full or an option is invalid. */
     spawn(options?: EntityOptions): Entity;
+    /**
+     * 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(): World | null;
+    /**
+     * 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?: number): World;
+    private spawnStill;
     /**
      * 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).

package/lib/typescript/src/world/types.d.ts

@@ -138,6 +138,14 @@ export type EntityOptions = {
     impact?: ImpactFeedback | null;
     /** Whether `pick` can hit it. Default true. */
     pickable?: boolean;
+    /**
+     * Scenery that never moves (a board's background, a sky): drawn with the world's other still
+     * entities into one cached image behind everything else (`World.backdrop`), redrawn only when one
+     * of them changes, the camera moves or the light changes, instead of every frame. Spawn-only. The
+     * returned entity takes `set` and `despawn` (and goes with the world); it can't be attached, have
+     * physics or text, be animated or be picked, and everything live draws in front of it.
+     */
+    still?: boolean;
 };
 export type Easing = 'linear' | 'easeIn' | 'easeOut' | 'easeInOut' | 'back' | 'bounce' | 'elastic';
 /** What `animate` changes. Anything left out stays as it is (and keeps any animation it already has). */

package/lib/web/audio-worklet.js

@@ -27,3 +27,30 @@ class NayanMixer extends AudioWorkletProcessor {
   }
 }
 registerProcessor('nayan-mixer', NayanMixer);
+
+// The page's microphone: mixes each input block to mono and posts ~43 ms batches to the main thread,
+// which hands them to the core's capture buffer.
+class NayanMicrophone extends AudioWorkletProcessor {
+  constructor() {
+    super();
+    this.batch = new Float32Array(2048);
+    this.filled = 0;
+  }
+  process(inputs) {
+    const channels = inputs[0];
+    if (!channels || !channels.length) return true;
+    const frames = channels[0].length;
+    for (let i = 0; i < frames; i++) {
+      let sum = 0;
+      for (let c = 0; c < channels.length; c++) sum += channels[c][i];
+      this.batch[this.filled++] = sum / channels.length;
+      if (this.filled === this.batch.length) {
+        this.port.postMessage(this.batch, [this.batch.buffer]);
+        this.batch = new Float32Array(2048);
+        this.filled = 0;
+      }
+    }
+    return true;
+  }
+}
+registerProcessor('nayan-microphone', NayanMicrophone);