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

package/lib/web/types/src/media/speech.d.ts

@@ -0,0 +1,37 @@
+export type SpeechOptions = {
+    /** BCP 47 language tag, such as en-US or hi-IN. Defaults to the system language. */
+    language?: string;
+    /** Identifier returned by getAvailableVoicesAsync. */
+    voice?: string;
+    /** Speed relative to the platform default, 0.1..2. Default 1. */
+    rate?: number;
+    /** Pitch multiplier, 0.5..2. Default 1. */
+    pitch?: number;
+    /** Loudness, 0..1. Default 1. */
+    volume?: number;
+};
+export type SpeechVoice = {
+    identifier: string;
+    name: string;
+    language: string;
+    quality: 'Default' | 'Enhanced';
+};
+/** System text-to-speech. Independent of the engine mixer, microphone and asset loading. */
+export declare const speech: {
+    /** API availability; installed voices and Android TTS initialization may still fail. */
+    readonly supported: boolean;
+    /**
+     * Queues text using the system synthesizer. Resolves when queued, not when speech finishes.
+     * No audio files are created. Call stop on leaving a screen to cancel its queued speech.
+     */
+    speak(text: string, options?: SpeechOptions): Promise<void>;
+    /** Stops current speech and clears the entire speech queue. */
+    stop(): Promise<void>;
+    /** iOS and web only; rejects on Android, which has no system pause API. */
+    pause(): Promise<void>;
+    /** iOS and web only; rejects on Android. */
+    resume(): Promise<void>;
+    /** Includes speech paused on iOS/web. */
+    isSpeakingAsync(): Promise<boolean>;
+    getAvailableVoicesAsync(): Promise<SpeechVoice[]>;
+};

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

@@ -0,0 +1,4 @@
+export declare const speechPlatform: {
+    readonly supported: boolean;
+    request(command: string): Promise<string>;
+};

package/lib/web/types/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/web/types/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/web/types/src/render/GameView.d.ts

@@ -15,12 +15,19 @@ import { type RenderQuality, type RenderQualitySetting } from './quality';
 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/web/types/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/web/types/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/web/types/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/web/types/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/native/android/src/main/AndroidManifest.xml

@@ -0,0 +1,10 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+  <uses-permission android:name="android.permission.VIBRATE" />
+
+  <!-- Android 11+ package visibility for installed system speech engines. -->
+  <queries>
+    <intent>
+      <action android:name="android.intent.action.TTS_SERVICE" />
+    </intent>
+  </queries>
+</manifest>

package/native/android/src/main/java/com/nayanui/engine/EngineMicrophone.java

@@ -0,0 +1,60 @@
+package com.nayanui.engine;
+
+import android.Manifest;
+import android.app.Activity;
+import android.content.Context;
+import android.content.pm.PackageManager;
+import com.facebook.react.bridge.ReactContext;
+import com.facebook.react.bridge.UiThreadUtil;
+import com.facebook.react.modules.core.PermissionAwareActivity;
+import java.lang.ref.WeakReference;
+
+/**
+ * The microphone permission for the engine's recording (`microphone` in JS). The app declares
+ * RECORD_AUDIO in its manifest; this asks for it at runtime through React Native's
+ * permission-aware activity and reports the answer to the C++ module, which resolves the JS promise.
+ */
+public final class EngineMicrophone {
+  private static final int REQUEST_CODE = 0x4e4d; // "NM"
+  private static WeakReference<ReactContext> react = new WeakReference<>(null);
+
+  private EngineMicrophone() {}
+
+  /** The React context to ask through (set by the package and by every engine view). */
+  static void remember(Context context) {
+    if (context instanceof ReactContext) react = new WeakReference<>((ReactContext) context);
+  }
+
+  /** 1 if recording is allowed, 0 if not (yet). */
+  public static int permission() {
+    ReactContext context = react.get();
+    if (context == null) return 0;
+    return context.checkSelfPermission(Manifest.permission.RECORD_AUDIO) == PackageManager.PERMISSION_GRANTED ? 1 : 0;
+  }
+
+  /** Asks for the microphone (the system prompt) and reports through nativePermissionResult(token, granted). */
+  public static void request(final long token) {
+    UiThreadUtil.runOnUiThread(() -> {
+      if (permission() == 1) {
+        nativePermissionResult(token, true);
+        return;
+      }
+      ReactContext context = react.get();
+      Activity activity = context == null ? null : context.getCurrentActivity();
+      if (!(activity instanceof PermissionAwareActivity)) {
+        nativePermissionResult(token, false);
+        return;
+      }
+      ((PermissionAwareActivity) activity).requestPermissions(
+          new String[] {Manifest.permission.RECORD_AUDIO},
+          REQUEST_CODE,
+          (requestCode, permissions, results) -> {
+            if (requestCode != REQUEST_CODE) return false;
+            nativePermissionResult(token, results.length > 0 && results[0] == PackageManager.PERMISSION_GRANTED);
+            return true;
+          });
+    });
+  }
+
+  private static native void nativePermissionResult(long token, boolean granted);
+}

package/native/android/src/main/java/com/nayanui/engine/EngineSpeech.java

@@ -0,0 +1,28 @@
+package com.nayanui.engine;
+
+import android.content.Context;
+import android.os.Handler;
+import android.os.Looper;
+import android.speech.tts.TextToSpeech;
+
+/** Main-thread and Java interface glue only. Speech commands and lifecycle live in Rust. */
+public final class EngineSpeech {
+  private static final Handler MAIN = new Handler(Looper.getMainLooper());
+  private EngineSpeech() {}
+
+  public static boolean dispatch(long token) {
+    return MAIN.post(() -> nativeRun(token));
+  }
+
+  public static TextToSpeech create(Context context, long generation) {
+    final TextToSpeech[] holder = new TextToSpeech[1];
+    holder[0] = new TextToSpeech(context, status ->
+        MAIN.post(() -> nativeInitialized(holder[0], status, generation)));
+    MAIN.postDelayed(() -> nativeInitTimeout(generation), 15000);
+    return holder[0];
+  }
+
+  private static native void nativeRun(long token);
+  private static native void nativeInitTimeout(long generation);
+  private static native void nativeInitialized(TextToSpeech synth, int status, long generation);
+}

package/native/android/src/main/java/com/nayanui/engine/EngineSurfaceView.java

@@ -73,6 +73,7 @@ public class EngineSurfaceView extends SurfaceView implements SurfaceHolder.Call
 
   public EngineSurfaceView(Context context) {
     super(context);
+    EngineMicrophone.remember(context);
     getHolder().addCallback(this);
     // Frames are opaque: the compositor can skip blending the layer.
     getHolder().setFormat(PixelFormat.OPAQUE);

package/native/android/src/main/java/com/nayanui/engine/NayanEnginePackage.java

@@ -13,12 +13,14 @@ public class NayanEnginePackage implements ReactPackage {
   @NonNull
   @Override
   public List<NativeModule> createNativeModules(@NonNull ReactApplicationContext context) {
+    EngineMicrophone.remember(context);
     return Collections.emptyList();
   }
 
   @NonNull
   @Override
   public List<ViewManager> createViewManagers(@NonNull ReactApplicationContext context) {
+    EngineMicrophone.remember(context);
     return Collections.singletonList(new EngineSurfaceViewManager());
   }
 }

package/native/core/include/engine_core.h

@@ -184,6 +184,9 @@ uint32_t engine_model_vertex_count(uint32_t mesh);
 const uint32_t *engine_model_indices(uint32_t mesh);
 uint32_t engine_model_index_count(uint32_t mesh);
 int32_t engine_model_size(uint32_t mesh, float *out_xyz); // full bounding-box size; 1 if known
+// Bakes a model into a new texture (BakeSpec JSON); out = [texture, center x, center y, extent]. 1, or 0 (engine_load_error).
+int32_t engine_model_bake(uint32_t mesh, const uint8_t *spec, size_t len, float *out);
+int32_t engine_bake_kept(const uint8_t *key, size_t len); // 1 if a picture is kept under the key
 int32_t engine_model_texture(uint32_t mesh);              // base color texture id, or -1
 // A new mesh id drawn with base's geometry (so it can have its own texture). Returns it, or -1.
 int32_t engine_mesh_alias(uint32_t base);
@@ -251,6 +254,35 @@ int32_t engine_audio_load_wav(const uint8_t *data, size_t len); // sound id, or
 uint64_t engine_audio_play(uint32_t sound, float volume, float pan, float pitch, int32_t looping); // voice id, 0 = none
 void engine_audio_stop(uint64_t voice);
 void engine_audio_set_volume(float volume);
+// Frees a sound's samples (a played recording); its id then plays nothing.
+void engine_audio_release(uint32_t sound);
+// A sound's length in seconds (0 if unknown or released).
+float engine_audio_duration(uint32_t sound);
+// Writes up to `capacity` loudness values (one per 1/per_second s) into `out`; returns how many the
+// sound has (pass a null `out` to ask).
+size_t engine_audio_levels(uint32_t sound, float per_second, float *out, size_t capacity);
+/* System speech: reply bytes are borrowed for the callback; completion means queued, not spoken. */
+void engine_speech_request(const uint8_t *data, size_t len, void (*done)(void *context, const uint8_t *data, size_t len), void *context);
+void engine_speech_shutdown(void);
+
+// Microphone. Permission: 1 granted, 0 not asked yet, -1 denied (iOS; 1 elsewhere, the host asks).
+int32_t engine_audio_mic_permission(void);
+// Asks for the microphone and calls done(context, granted) once, possibly on another thread.
+void engine_audio_mic_request(void (*done)(void *context, int32_t granted), void *context);
+// Starts listening, keeping the last `max_seconds` of input. 1 if it's opening.
+int32_t engine_audio_mic_start(float max_seconds);
+void engine_audio_mic_stop(void);
+// 0 off, 1 opening, 2 listening, -1 failed (no device or permission).
+int32_t engine_audio_mic_state(void);
+// How loud the input is now: 0 (-60 dBFS or quieter) .. 1 (full scale).
+float engine_audio_mic_level(void);
+// Seconds of input held.
+float engine_audio_mic_held(void);
+// A sound of the `seconds` of input that ended `skip_end` seconds ago; forgets what was heard.
+// Returns its sound id, or -1.
+int32_t engine_audio_mic_take(float seconds, float skip_end);
+// Browser input: `count` mono samples at `rate`.
+void engine_audio_mic_push(const float *samples, size_t count, uint32_t rate);
 void engine_audio_set_muted(int32_t muted);
 int32_t engine_audio_is_running(void);
 
@@ -281,7 +313,7 @@ size_t engine_render_mesh_vertices(uint32_t mesh, float *out, size_t cap);
 size_t engine_render_mesh_indices(uint32_t mesh, uint32_t *out, size_t cap);
 
 // ── Renderer (wgpu: Vulkan, else GLES 3.0, on Android; Metal on iOS) ───────
-#define ENGINE_FRAME_LEN 26
+#define ENGINE_FRAME_LEN 26 // at least: the scene scale (26) and FXAA (27) are optional
 // Geometry (copied) drawn for a mesh id: vertex_count * 11 floats, u32 indices; texture -1 = none.
 void engine_render_mesh(uint32_t mesh, const float *vertices, size_t vertex_count, const uint32_t *indices, size_t index_count,
                         int32_t texture, float shine);
@@ -305,6 +337,8 @@ int32_t engine_render_frame(int32_t surface, const double *frame, size_t frame_l
 // Unlit and always in front of the scene. count 0 (or NULL buffers) removes it.
 void engine_render_overlay(int32_t surface, const float *matrices, const float *colors, const float *regions, size_t capacity,
                            const uint32_t *ranges, size_t ranges_len, size_t count, float width, float height);
+// Static scenery behind the scene, cached in a texture (same buffers as engine_render_overlay; count 0 removes it).
+void engine_render_backdrop(int32_t surface, const float *matrices, const float *colors, const float *regions, size_t capacity, const uint32_t *ranges, size_t ranges_len, size_t count);
 size_t engine_render_error(char *out, size_t cap);
 // "vulkan", "gl", "metal", or "" before the first attach.
 size_t engine_render_backend(char *out, size_t cap);
@@ -326,6 +360,34 @@ void engine_drawing_transform(int32_t document, float dx, float dy, float scale)
 void engine_drawing_invalidate(int32_t document);
 int32_t engine_drawing_present(int32_t document, int32_t surface, float width, float height, uint32_t background_rgb);
 
+// Data-driven procedural worlds (JSON recipes of field graphs, terrain, solids and generation steps).
+// Handles are u32 (0 = failed; see engine_worldgen_error). Building is reentrant on any thread. With
+// a non-empty key, a world saved under it from the same recipe is restored, and a new one is saved.
+// Out-buffer functions return the full length and copy only when `capacity` is large enough.
+uint32_t engine_worldgen_build(const uint8_t *recipe, size_t len, const uint8_t *key, size_t key_len, int32_t prepare_terrain);
+size_t engine_worldgen_error(uint8_t *out, size_t capacity);
+int32_t engine_worldgen_kept(const uint8_t *key, size_t len);
+void engine_worldgen_free(uint32_t world);
+size_t engine_worldgen_info(uint32_t world, uint8_t *out, size_t capacity);
+size_t engine_worldgen_layer(uint32_t world, const uint8_t *name, size_t len, double *out, size_t capacity);
+size_t engine_worldgen_reachable(uint32_t world, double *out, size_t capacity);
+size_t engine_worldgen_overview(uint32_t world, uint8_t *out, size_t capacity);
+int32_t engine_worldgen_pick(uint32_t world, uint32_t run);
+EngineGeometry *engine_worldgen_terrain(uint32_t world, uint32_t material);
+EngineGeometry *engine_worldgen_mesh(const uint8_t *recipe, size_t len);
+int32_t engine_worldgen_paint(float *vertices, size_t vertex_count, const uint8_t *recipe, size_t len);
+double engine_worldgen_ground(uint32_t world, double x, double z);
+int32_t engine_worldgen_surface(uint32_t world, double x, double z);
+int32_t engine_worldgen_platform(uint32_t world, double x, double z);
+int32_t engine_worldgen_walkable(uint32_t world, double x, double z, double radius);
+double engine_worldgen_clearance(uint32_t world, double x, double z, double radius);
+double engine_worldgen_solid_clearance(uint32_t world, double x, double z, double radius, double bottom, double top);
+int32_t engine_worldgen_field_index(uint32_t world, const uint8_t *name, size_t len);
+double engine_worldgen_field(uint32_t world, uint32_t field, double x, double z);
+void engine_worldgen_tilt(uint32_t world, double x, double z, double yaw, double *out);
+int32_t engine_worldgen_sight(uint32_t world, double ax, double az, double bx, double bz, double radius, double step, double rise);
+void engine_worldgen_move(uint32_t world, double *point, double dx, double dz, double radius, const double *bodies, size_t count);
+
 #ifdef __cplusplus
 }
 #endif