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

package/src/native/spec/NativeNayanEngine.ts

@@ -0,0 +1,265 @@
+/* eslint-disable @typescript-eslint/no-wrapper-object-types -- Codegen requires Object for JSI buffers; EngineBridge supplies their precise TypeScript types. */
+import { type TurboModule, TurboModuleRegistry } from 'react-native';
+
+/**
+ * Bridge to the Rust core. Use the `World`, `audio` and `haptics` APIs instead of calling this.
+ *
+ * Worlds are identified by the number `createWorld` returns; entity ids are opaque numbers.
+ * Entities are created and changed with one call each: `spawnDesc` / `setDesc` take a
+ * Float64Array's ArrayBuffer encoding every option (layout in native/core/include/engine_core.h).
+ * Capacity is fixed at creation, so the buffers returned by `get*` alias Rust memory (zero-copy)
+ * and stay valid until `destroyWorld`.
+ */
+export interface Spec extends TurboModule {
+  createWorld(capacity: number): number;
+  destroyWorld(world: number): void;
+
+  /** Returns the entity id, or -1 if the world is full or the description is rejected. */
+  spawnDesc(world: number, desc: Object): number;
+  /** Returns false if the entity is gone or a field was rejected (the rest still apply). */
+  setDesc(world: number, entity: number, desc: Object): boolean;
+  /** Packed draw transforms, 16 doubles per record: id, flags, position, rotation, scale, color. */
+  setTransforms(world: number, data: Object, count: number): number;
+  /** Returns false for stale or unknown ids. */
+  despawn(world: number, entity: number): boolean;
+  /** Instant change in momentum (dynamic bodies only). */
+  impulse(world: number, entity: number, x: number, y: number, z: number): void;
+
+  setGravity(world: number, x: number, y: number, z: number): void;
+  setBounds(world: number, minX: number, minZ: number, maxX: number, maxZ: number): void;
+  /** Entity used to pan/attenuate impact sounds (-1 clears). */
+  setListener(world: number, entity: number): void;
+
+  /** Returns the hit entity or -1; on a hit the scratch buffer holds distance, normal, point. */
+  raycast(world: number, ox: number, oy: number, oz: number, dx: number, dy: number, dz: number, maxDistance: number, mask: number): number;
+  /** Nearest pickable entity along a ray (as last drawn), or -1; on a hit the scratch buffer holds distance, point. */
+  pick(world: number, ox: number, oy: number, oz: number, dx: number, dy: number, dz: number): number;
+  /** Nearest pickable entity under a screen point (in view points), or -1; scratch holds distance, point. */
+  pickScreen(world: number, x: number, y: number): number;
+  /** Stores the view-projection matrix (16 column-major floats) and view size in points. */
+  setView(world: number, viewProj: Object, width: number, height: number): void;
+  /** World ray [origin xyz, direction xyz] through a view point. Writes into scratch[0..6]. Returns true on success. */
+  screenRay(world: number, x: number, y: number): boolean;
+  /** Where a view point lands on a plane. Writes into scratch[0..3]. Returns true on success. */
+  screenToWorld(world: number, x: number, y: number, ppx: number, ppy: number, ppz: number, pnx: number, pny: number, pnz: number): boolean;
+  /** Where a world position appears on screen (points from top-left). Writes into scratch[0..2]. */
+  toScreen(world: number, x: number, y: number, z: number): boolean;
+  /**
+   * Write position / velocity to the scratch buffer (`getScratch`). Return false if not alive.
+   * `rendered`: where it was last drawn, in world space (otherwise simulated, relative to its parent).
+   */
+  readPosition(world: number, entity: number, rendered: boolean): boolean;
+  readVelocity(world: number, entity: number): boolean;
+
+  /** Starts an animation (Float64Array buffer, layout in engine_core.h). Returns its id, or 0 if nothing started. */
+  animate(world: number, animation: Object): number;
+  stopAnimation(world: number, entity: number): boolean;
+  /** Spawns a particle burst (Float64Array buffer). Returns how many particles were spawned. */
+  burst(world: number, burst: Object): number;
+
+  update(world: number, dt: number): void;
+  /** Starts a timer firing `seconds` of update time from now; its id is reported in `getDone`. Returns the id, or 0. */
+  after(world: number, seconds: number): number;
+  /** Drops every pending timer. Returns how many were dropped. */
+  cancelTimers(world: number): number;
+  /** Score / lives / clock operation (layout in engine_core.h). Returns the score after it. */
+  scoreboard(world: number, op: number, a: number, b: number): number;
+  /** 8 doubles: score, lives, seconds, shown seconds, changed flags, running, points per second, best. Aliases native memory. */
+  getScoreboard(world: number): Object;
+  count(world: number): number;
+
+  /** capacity * 16 floats, column-major, grouped by mesh. */
+  getMatrices(world: number): Object;
+  /** capacity * 4 floats (rgba), same order as the matrices. */
+  getColors(world: number): Object;
+  /** capacity * 4 floats: texture region (u0 v0 u1 v1), same order as the matrices. */
+  getRegions(world: number): Object;
+  /** MAX_MESHES * 4 u32: [first, count] per mesh id for opaque instances, then for transparent ones. */
+  getRanges(world: number): Object;
+  /** Ids of animations that ended since the last update began (room for capacity * 5 + 64). */
+  getDone(world: number): Object;
+  doneLength(world: number): number;
+  /** Collision events from the last update, 4 u32 each: [a, b, flags, speed as f32 bits]. */
+  getEvents(world: number): Object;
+  eventLength(world: number): number;
+  /** 16 floats. */
+  getScratch(world: number): Object;
+
+  // Meshes, models, textures, fonts (global)
+  /** Parses a glTF/GLB ArrayBuffer. Returns its mesh id, or -1 (see `loadError`). */
+  /** Joint count and animation clips as JSON, loaded once with the model. */
+  modelRig(mesh: number): string;
+  playClip(world: number, entity: number, clip: string, loop: boolean, speed: number, fade: number, time: number): boolean;
+  stopClip(world: number, entity: number, reset: boolean): boolean;
+  skinPoints(world: number, entity: number, vertices: Object, output: Object, after: number): boolean;
+  /** Rust owns cache hashing, persistence, validation and mesh preparation. */
+  cacheRead(key: string): Object;
+  cacheWrite(key: string, data: Object): boolean;
+  cacheRemove(key: string): boolean;
+  cacheClear(): boolean;
+  shapePrepare(vertices: Object, indices: Object, options: string): number;
+  solidPrepare(recipe: string, options: string): number;
+  modelLoad(data: Object, center: boolean, fit: number): number;
+  /** `modelLoad` on a background native thread (the data is copied first): resolves to the mesh id, or -1. */
+  modelLoadAsync(data: Object, center: boolean, fit: number): Promise<number>;
+  /** 11 floats per vertex (position, normal, color, uv); aliases native memory. */
+  modelVertices(mesh: number): Object;
+  /** u32 triangle indices; aliases native memory. */
+  modelIndices(mesh: number): Object;
+  /** Full bounding-box size [x, y, z]. */
+  modelSize(mesh: number): Array<number>;
+  /** 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. */
+  meshAlias(base: number): number;
+  /** Registers geometry (copied): 11 floats per vertex, u32 triangle indices. Returns the mesh id, or -1. */
+  meshCreate(vertices: Object, indices: Object): number;
+  /**
+   * Hands a core model's own geometry (from `meshCreate`, `modelLoad`, a font) to the renderer, in
+   * Rust: nothing is copied through JS. `texture` -1 for none. False if the mesh is unknown.
+   */
+  renderModel(mesh: number, texture: number, shine: number): boolean;
+  /**
+   * Fills 2D contours ([x, y] f32 pairs, `counts[k]` points per contour) by the non-zero or even-odd
+   * rule and extrudes them `depth` deep. Returns an ArrayBuffer of 11 floats per vertex (unindexed).
+   */
+  pathExtrude(points: Object, counts: Array<number>, depth: number, evenOdd: boolean): Object;
+  /** Recomputes normals in place (vertex / u32 index ArrayBuffers), averaged across vertices at the same place. */
+  geometrySmoothNormals(vertices: Object, indices: Object): void;
+  /** Tessellates a solid recipe; returns independent vertex/index ArrayBuffers, with no mesh registration. */
+  geometrySolid(recipe: string): Object;
+  /** Cleans, simplifies and optimizes a mesh, preserving normal/color/UV attributes. */
+  geometryOptimize(vertices: Object, indices: Object, ratio: number, error: number, lockBorders: boolean): Object;
+  /** Flips triangles in place whose winding disagrees with their vertex normals. */
+  geometryFaceOutward(vertices: Object, indices: Object): void;
+  /**
+   * Bakes a part into merged buffers: `placement` = position xyz, rotation quat xyzw, scale xyz, color
+   * rgb. Writes at `vertexOffset` floats / `indexOffset` indices, indices offset by `first`.
+   */
+  geometryPlace(
+    vertices: Object,
+    indices: Object,
+    placement: Array<number>,
+    first: number,
+    outVertices: Object,
+    vertexOffset: number,
+    outIndices: Object,
+    indexOffset: number
+  ): void;
+  /** Decodes a PNG/JPEG ArrayBuffer. Returns the texture id, or -1. */
+  textureLoad(data: Object): number;
+  /** `textureLoad` on a background native thread: resolves to the texture id, or -1. */
+  textureLoadAsync(data: Object): Promise<number>;
+  /** RGBA8 pixels, top row first; aliases native memory. */
+  texturePixels(texture: number): Object;
+  /** [width, height]. */
+  textureSize(texture: number): Array<number>;
+  /** Builds extruded glyph meshes for `chars`. Returns the font id, or -1. */
+  fontLoad(data: Object, depth: number, chars: string, weight: number): number;
+  /** `fontLoad` (outlines and glyph meshes) on a background native thread: resolves to the font id, or -1. */
+  fontLoadAsync(data: Object, depth: number, chars: string, weight: number): Promise<number>;
+  /** [codepoint, mesh (-1 = nothing drawn), advance, ...] followed by the cap height. */
+  fontGlyphs(font: number): Array<number>;
+  /** Why the last model / texture / font / alias load failed ("" after a success). */
+  loadError(): string;
+
+  // Rendering (global; surfaces come from the native EngineSurface view)
+  /** Generates and registers all built-in shape meshes (cube, sphere, etc.) in the native renderer. */
+  generateBuiltinMeshes(): void;
+  /**
+   * Builds the GPU device and shader pipelines on a background thread, ahead of the first surface.
+   * Returns at once; repeat calls do nothing.
+   */
+  renderWarmUp(): void;
+  /** Returns a copy of a registered mesh's vertices (11 floats per vertex), or empty if not found. */
+  renderMeshVertices(mesh: number): Object;
+  /** Returns a copy of a registered mesh's indices (u32 triangle list), or empty if not found. */
+  renderMeshIndices(mesh: number): Object;
+  /** Geometry (copied) drawn for a mesh id: 11 floats per vertex, u32 indices. `texture` -1 = none. */
+  renderMesh(mesh: number, vertices: Object, indices: Object, texture: number, shine: number): void;
+  /**
+   * Draws a frame into surface `surface`. `frame`: Float64Array buffer (layout in engine_core.h);
+   * instance buffers hold the same number of instances; `viewProj` (16 floats) gets the camera used.
+   * Returns 1 (drawn), 0 (surface not ready yet / frame skipped) or -1 (see `renderError`).
+   */
+  renderFrame(
+    surface: number,
+    frame: Object,
+    matrices: Object,
+    colors: Object,
+    regions: Object,
+    ranges: Object,
+    count: number,
+    viewProj: Object,
+    world: number
+  ): number;
+  /**
+   * `renderFrame`'s arguments, but the frame is copied and drawn on the native render thread: returns
+   * at once, with `viewProj` written. 1 once the surface has presented a frame, 0 before, -1 if the
+   * last frame failed (see `renderError`).
+   */
+  publishFrame(
+    surface: number,
+    frame: Object,
+    matrices: Object,
+    colors: Object,
+    regions: Object,
+    ranges: Object,
+    count: number,
+    viewProj: Object,
+    world: number
+  ): number;
+  /** [frames presented, smoothed render milliseconds] for a surface drawn by the render thread. */
+  renderStats(surface: number): Array<number>;
+  /** True where the platform drives frames from its display clock (`startFrames`); else use requestAnimationFrame. */
+  hasFrameClock(): boolean;
+  /**
+   * Calls `onFrame` on the JS thread once per display refresh while the surface is attached and
+   * visible, with the frame time in milliseconds. A frame JS hasn't started yet isn't queued again.
+   */
+  startFrames(surface: number, onFrame: (timeMs: number) => void): void;
+  stopFrames(surface: number): void;
+  /**
+   * The screen-space overlay drawn over surface `surface` from its next frame on, copied from a world's
+   * buffers. In points: x right and y up from the view's top-left (on screen y <= 0), z toward the
+   * viewer within -100..100; `width` x `height` is the view in points. Unlit, always in front of the
+   * scene. count 0 removes it.
+   */
+  renderOverlay(
+    surface: number,
+    matrices: Object,
+    colors: Object,
+    regions: Object,
+    ranges: Object,
+    count: number,
+    width: number,
+    height: number
+  ): void;
+  renderError(): string;
+  /** "vulkan", "gl" or "metal" ("" before the first surface). */
+  renderBackend(): string;
+
+  /** Native 2D drawing documents; commands return owned JSON results. */
+  drawingCreate(width: number, height: number, ratio: number): number;
+  drawingCommand(document: number, command: string): string;
+  drawingDestroy(document: number): void;
+
+  // Audio (global)
+  /** Decodes a WAV ArrayBuffer. Returns a sound id, or -1. */
+  audioLoad(data: Object): number;
+  /** `audioLoad` on a background native thread: resolves to the sound id, or -1. */
+  audioLoadAsync(data: Object): Promise<number>;
+  /** Returns a voice id (> 0), or 0 if nothing played. */
+  audioPlay(sound: number, volume: number, pan: number, pitch: number, loop: boolean): number;
+  audioStop(voice: number): void;
+  audioSetVolume(volume: number): void;
+  audioSetMuted(muted: boolean): void;
+  audioIsRunning(): boolean;
+
+  // Haptics (global)
+  hapticsSupported(): boolean;
+  /** Taps as flat [time, intensity, sharpness, ...] triples. */
+  hapticsPlay(taps: Array<number>, throttle: boolean): void;
+}
+
+export default TurboModuleRegistry.get<Spec>('NativeNayanEngine');