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

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

@@ -8,19 +8,27 @@ import com.facebook.react.bridge.WritableMap;
 import com.facebook.react.uimanager.UIManagerHelper;
 import com.facebook.react.uimanager.events.Event;
 import com.facebook.react.uimanager.events.EventDispatcher;
-import android.graphics.SurfaceTexture;
+import android.graphics.PixelFormat;
+import android.os.Build;
 import android.view.Surface;
+import android.view.SurfaceHolder;
+import android.view.SurfaceView;
 import android.view.MotionEvent;
 import android.view.ScaleGestureDetector;
 import android.view.Choreographer;
-import android.view.TextureView;
 
 /**
- * A surface the Rust renderer draws into (Vulkan, or OpenGL ES when Vulkan isn't usable). A
- * TextureView keeps the last frame in the view tree during navigation's removal animation, even
- * after React stops rendering. JS refers to it by `surfaceId`.
+ * A surface the Rust renderer draws into (Vulkan, or OpenGL ES when Vulkan isn't usable). JS refers
+ * to it by `surfaceId`.
+ *
+ * A SurfaceView, not a TextureView: its frames go straight to the system compositor (often as a
+ * hardware overlay), instead of being copied into the app's own view tree by the UI thread's
+ * renderer every frame. With a TextureView each game frame also redraws the React Native window and
+ * makes the JS thread wait on the UI thread for a free buffer, which is what made heavy 3D scenes
+ * stutter and hang on Android. The surface keeps showing its last frame after the renderer detaches,
+ * until the view leaves the window, so navigation's exit animation still shows the game.
  */
-public class EngineSurfaceView extends TextureView implements TextureView.SurfaceTextureListener, Choreographer.FrameCallback {
+public class EngineSurfaceView extends SurfaceView implements SurfaceHolder.Callback, Choreographer.FrameCallback {
   private int surfaceId = -1;
   private Surface surface;
   private int width;
@@ -29,6 +37,33 @@ public class EngineSurfaceView extends TextureView implements TextureView.Surfac
   private int drawingMode;
   private int drawingBackground = 0xffffff;
   private boolean drawingTick;
+  private boolean clockRunning;
+
+  /**
+   * The game's display clock: once per refresh while the surface is attached and on screen, the
+   * engine is asked for its next frame on the JS thread (see `deliverFrame`). Unlike React Native's
+   * requestAnimationFrame, which can tick at half the display's rate, this follows every vsync; the
+   * frame itself is drawn on the engine's render thread.
+   */
+  private final Choreographer.FrameCallback clock = new Choreographer.FrameCallback() {
+    @Override public void doFrame(long frameTimeNanos) {
+      if (!clockRunning) return;
+      if (surfaceId >= 0 && surface != null) nativeVsync(surfaceId, frameTimeNanos);
+      Choreographer.getInstance().postFrameCallback(this);
+    }
+  };
+
+  private void startClock() {
+    if (!clockRunning && surfaceId >= 0 && surface != null && isShown()) {
+      clockRunning = true;
+      Choreographer.getInstance().postFrameCallback(clock);
+    }
+  }
+
+  private void stopClock() {
+    clockRunning = false;
+    Choreographer.getInstance().removeFrameCallback(clock);
+  }
   private long lastDrawingEvent;
   private int drawingPointer = -1;
   private boolean pencil;
@@ -38,7 +73,9 @@ public class EngineSurfaceView extends TextureView implements TextureView.Surfac
 
   public EngineSurfaceView(Context context) {
     super(context);
-    setSurfaceTextureListener(this);
+    getHolder().addCallback(this);
+    // Frames are opaque: the compositor can skip blending the layer.
+    getHolder().setFormat(PixelFormat.OPAQUE);
     density = context.getResources().getDisplayMetrics().density;
     scaleDetector = new ScaleGestureDetector(context, new ScaleGestureDetector.SimpleOnScaleGestureListener() {
       @Override public boolean onScale(ScaleGestureDetector detector) {
@@ -60,10 +97,12 @@ public class EngineSurfaceView extends TextureView implements TextureView.Surfac
   }
 
   /**
-   * Stops the renderer, but leaves the texture visible until navigation removes the view. Hiding it
-   * here would replace the game's last frame with an empty screen during the exit animation.
+   * Stops the renderer, but leaves the surface (and its last frame) visible until navigation removes
+   * the view. Hiding it here would replace the game's last frame with an empty screen during the
+   * exit animation.
    */
   public void release() {
+    stopClock();
     stopDrawing();
     drawingId = -1;
     if (surfaceId >= 0) {
@@ -73,49 +112,62 @@ public class EngineSurfaceView extends TextureView implements TextureView.Surfac
     releaseSurface();
   }
 
+  /**
+   * Games ask for 60 frames a second. A SurfaceView's frames never invalidate the view tree, so on
+   * Android 15+ the system otherwise judges the app idle and drops its vsync (and with it React
+   * Native's frame callbacks) to 30 or 20 Hz, halving the frame rate and doubling load times.
+   */
+  private static final float GAME_FRAME_RATE = 60f;
+
+  private void requestFrameRate() {
+    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R && surface != null && surface.isValid()) {
+      try {
+        surface.setFrameRate(GAME_FRAME_RATE, Surface.FRAME_RATE_COMPATIBILITY_DEFAULT);
+      } catch (IllegalArgumentException | IllegalStateException ignored) {
+        // A surface being torn down; the next attach asks again.
+      }
+    }
+    if (Build.VERSION.SDK_INT >= 35) setRequestedFrameRate(REQUESTED_FRAME_RATE_CATEGORY_HIGH);
+  }
+
   private void attach() {
     if (surfaceId >= 0 && surface != null && surface.isValid() && width > 0 && height > 0) {
       nativeAttach(surfaceId, surface, width, height);
+      requestFrameRate();
       if (drawingId >= 0) nativeDrawingInvalidate(drawingId);
       startDrawing();
+      startClock();
     }
   }
 
   @Override
-  public void onSurfaceTextureAvailable(SurfaceTexture texture, int w, int h) {
-    surface = new Surface(texture);
-    width = w;
-    height = h;
-    attach();
+  public void surfaceCreated(SurfaceHolder holder) {
+    surface = holder.getSurface();
   }
 
   @Override
-  public void onSurfaceTextureSizeChanged(SurfaceTexture texture, int w, int h) {
+  public void surfaceChanged(SurfaceHolder holder, int format, int w, int h) {
+    surface = holder.getSurface();
     width = w;
     height = h;
     attach();
   }
 
   @Override
-  public boolean onSurfaceTextureDestroyed(SurfaceTexture texture) {
+  public void surfaceDestroyed(SurfaceHolder holder) {
+    stopClock();
     stopDrawing();
-    // Wait for the renderer before Android destroys the texture. Keep the id so a screen covered by
+    // Wait for the renderer before Android destroys the surface. Keep the id so a screen covered by
     // another route can attach a new surface when it comes back from the back stack.
     if (surfaceId >= 0) {
       nativeDetach(surfaceId);
     }
     releaseSurface();
-    return true;
   }
 
-  @Override
-  public void onSurfaceTextureUpdated(SurfaceTexture texture) {}
-
+  /** The holder owns the surface: only forget it (releasing it here would break the next attach). */
   private void releaseSurface() {
-    if (surface != null) {
-      surface.release();
-      surface = null;
-    }
+    surface = null;
   }
 
   public void setDrawingId(int id) {
@@ -173,12 +225,19 @@ public class EngineSurfaceView extends TextureView implements TextureView.Surfac
     if (focused) startDrawing(); else stopDrawing();
   }
   @Override protected void onDetachedFromWindow() {
+    stopClock();
     stopDrawing();
     super.onDetachedFromWindow();
   }
   @Override protected void onWindowVisibilityChanged(int visibility) {
     super.onWindowVisibilityChanged(visibility);
-    if (visibility == VISIBLE) startDrawing(); else stopDrawing();
+    if (visibility == VISIBLE) {
+      startDrawing();
+      startClock();
+    } else {
+      stopDrawing();
+      stopClock();
+    }
   }
   @Override public boolean onTouchEvent(MotionEvent event) {
     if (drawingId < 0) return super.onTouchEvent(event);
@@ -231,4 +290,6 @@ public class EngineSurfaceView extends TextureView implements TextureView.Surfac
   private static native boolean nativeAttach(int surfaceId, Surface surface, int width, int height);
 
   private static native void nativeDetach(int surfaceId);
+
+  private static native void nativeVsync(int surfaceId, long frameTimeNanos);
 }

package/native/core/include/engine_core.h

@@ -265,6 +265,15 @@ void engine_android_init(void *java_vm, void *context);
 // Generates and registers all built-in shape meshes (cube, sphere, etc.) with the renderer.
 void engine_generate_builtin_meshes(void);
 // Vertex / index count of a registered renderer mesh, or 0.
+/* engine_render_frame's arguments, but the frame is copied and drawn on the render thread; returns at once with the
+ * view-projection written. 1 once the surface has presented a frame, 0 before, -1 if the last frame failed. */
+int32_t engine_render_publish(int32_t surface, const double *frame, size_t frame_len, const float *matrices, const float *colors,
+                              const float *regions, size_t capacity, const uint32_t *ranges, size_t ranges_len, size_t count,
+                              float *out_view_proj, const World *world);
+/* [frames presented, smoothed render ms] for a surface drawn by the render thread. */
+void engine_render_stats(int32_t surface, double *out);
+/* A core model's geometry (mesh_create, glTF, glyphs) to the renderer, inside Rust; texture < 0 = none. 1, or 0 if unknown. */
+int32_t engine_render_model(uint32_t mesh, int32_t texture, float shine);
 size_t engine_render_mesh_vertex_count(uint32_t mesh);
 size_t engine_render_mesh_index_count(uint32_t mesh);
 // Copies geometry into caller-owned buffers. Returns the actual count.

package/native/cpp/NayanEngineModule.cpp

@@ -3,7 +3,14 @@
 #include <engine_core.h>
 
 #include <algorithm>
+#include <atomic>
 #include <cstring>
+#include <mutex>
+#include <unordered_map>
+#include <unordered_set>
+#include <functional>
+#include <thread>
+#include <vector>
 
 #ifdef __ANDROID__
 #include <fbjni/fbjni.h>
@@ -130,8 +137,48 @@ void initAndroid() {
 
 } // namespace
 
+namespace {
+// Display-clock frames. The registry holds no JS values (those stay in the module, on the JS thread):
+// the clock's thread only schedules a call by surface id, and a module torn down by a reload is never
+// called again.
+struct FrameClient {
+  std::shared_ptr<CallInvoker> invoker;
+  NayanEngineModule *owner;
+  std::shared_ptr<std::atomic<bool>> pending;
+};
+std::mutex framesMutex;
+std::unordered_map<int, FrameClient> frameClients;
+std::unordered_set<NayanEngineModule *> liveModules; // guarded by framesMutex
+} // namespace
+
+void deliverFrame(int surface, double timeMs) {
+  std::shared_ptr<CallInvoker> invoker;
+  NayanEngineModule *owner = nullptr;
+  std::shared_ptr<std::atomic<bool>> pending;
+  {
+    std::lock_guard<std::mutex> lock(framesMutex);
+    auto it = frameClients.find(surface);
+    if (it == frameClients.end() || it->second.pending->exchange(true)) return; // none, or JS hasn't run the last one
+    invoker = it->second.invoker;
+    owner = it->second.owner;
+    pending = it->second.pending;
+  }
+  invoker->invokeAsync(SchedulerPriority::UserBlockingPriority, [owner, surface, timeMs, pending](jsi::Runtime &rt) {
+    pending->store(false);
+    {
+      std::lock_guard<std::mutex> lock(framesMutex);
+      if (liveModules.count(owner) == 0) return;
+    }
+    owner->callFrame(rt, surface, timeMs); // modules are destroyed on this (JS) thread, so it's still alive here
+  });
+}
+
 NayanEngineModule::NayanEngineModule(std::shared_ptr<CallInvoker> jsInvoker)
     : NativeNayanEngineCxxSpec(std::move(jsInvoker)) {
+  {
+    std::lock_guard<std::mutex> lock(framesMutex);
+    liveModules.insert(this);
+  }
 #ifdef __ANDROID__
   initAndroid();
 #endif
@@ -139,9 +186,45 @@ NayanEngineModule::NayanEngineModule(std::shared_ptr<CallInvoker> jsInvoker)
 
 // Worlds are freed when the module and every buffer aliasing them are gone.
 NayanEngineModule::~NayanEngineModule() {
+  {
+    std::lock_guard<std::mutex> lock(framesMutex);
+    liveModules.erase(this);
+    for (auto it = frameClients.begin(); it != frameClients.end();) it = it->second.owner == this ? frameClients.erase(it) : std::next(it);
+  }
   for (int document : drawings_) engine_drawing_destroy(document);
 }
 
+bool NayanEngineModule::hasFrameClock(jsi::Runtime &) {
+#if defined(__ANDROID__) || defined(__APPLE__)
+  return true; // EngineSurfaceView's Choreographer / NayanEngineSurfaceView's CADisplayLink call deliverFrame
+#else
+  return false;
+#endif
+}
+
+void NayanEngineModule::startFrames(jsi::Runtime &rt, double surface, jsi::Function onFrame) {
+  int s = static_cast<int>(surface);
+  frameCallbacks_.erase(s);
+  frameCallbacks_.emplace(s, std::move(onFrame));
+  std::lock_guard<std::mutex> lock(framesMutex);
+  frameClients[s] = FrameClient{jsInvoker_, this, std::make_shared<std::atomic<bool>>(false)};
+}
+
+void NayanEngineModule::stopFrames(jsi::Runtime &, double surface) {
+  int s = static_cast<int>(surface);
+  {
+    std::lock_guard<std::mutex> lock(framesMutex);
+    auto it = frameClients.find(s);
+    if (it != frameClients.end() && it->second.owner == this) frameClients.erase(it);
+  }
+  frameCallbacks_.erase(s);
+}
+
+void NayanEngineModule::callFrame(jsi::Runtime &rt, int surface, double timeMs) {
+  auto it = frameCallbacks_.find(surface);
+  if (it != frameCallbacks_.end()) it->second.call(rt, timeMs);
+}
+
 namespace {
 // NaN, fractional and out-of-range ids are unknown (casting them to int is undefined or aliases another id).
 bool knownWorldId(double worldId, int next) {
@@ -213,6 +296,26 @@ jsi::ArrayBuffer fileData(jsi::Runtime &rt, jsi::Object &data, const char *metho
   return data.getArrayBuffer(rt);
 }
 
+/** An ArrayBuffer's bytes, copied so a background thread can read them after the JS call returns. */
+std::vector<uint8_t> copyBytes(jsi::Runtime &rt, jsi::Object &data, const char *method) {
+  jsi::ArrayBuffer buffer = fileData(rt, data, method);
+  const uint8_t *bytes = buffer.data(rt);
+  return std::vector<uint8_t>(bytes, bytes + buffer.size(rt));
+}
+
+/**
+ * Runs `job` (which must not touch JSI) on its own native thread and settles a JS promise with its
+ * result on the JS thread. Decoding images, glTF models, fonts and sounds this way keeps them off
+ * the JS thread, and several loads run in parallel on the phone's cores. The core's asset
+ * registries are locked, so concurrent loads are safe.
+ */
+jsi::Value runInBackground(jsi::Runtime &rt, const std::shared_ptr<CallInvoker> &jsInvoker, std::function<double()> job) {
+  auto promise = std::make_shared<AsyncPromise<double>>(rt, jsInvoker);
+  jsi::Value result(rt, promise->get(rt));
+  std::thread([promise, job = std::move(job)]() { promise->resolve(job()); }).detach();
+  return result;
+}
+
 } // namespace
 
 double NayanEngineModule::spawnDesc(jsi::Runtime &rt, double world, jsi::Object desc) {
@@ -438,6 +541,13 @@ double NayanEngineModule::modelLoad(jsi::Runtime &rt, jsi::Object data, bool cen
   return engine_model_load(buffer.data(rt), buffer.size(rt), center ? 1 : 0, static_cast<float>(fit)); // copied
 }
 
+jsi::Value NayanEngineModule::modelLoadAsync(jsi::Runtime &rt, jsi::Object data, bool center, double fit) {
+  auto bytes = std::make_shared<std::vector<uint8_t>>(copyBytes(rt, data, "modelLoadAsync"));
+  return runInBackground(rt, jsInvoker_, [bytes, center, fit]() {
+    return static_cast<double>(engine_model_load(bytes->data(), bytes->size(), center ? 1 : 0, static_cast<float>(fit)));
+  });
+}
+
 jsi::Object NayanEngineModule::modelVertices(jsi::Runtime &rt, double mesh) {
   uint32_t m = id(mesh);
   return external(rt, nullptr, engine_model_vertices(m), static_cast<size_t>(engine_model_vertex_count(m)) * 11 * sizeof(float));
@@ -458,6 +568,11 @@ double NayanEngineModule::modelTexture(jsi::Runtime &, double mesh) {
   return engine_model_texture(id(mesh));
 }
 
+bool NayanEngineModule::renderModel(jsi::Runtime &, double mesh, double texture, double shine) {
+  int32_t t = texture >= 0 && texture <= INT32_MAX ? static_cast<int32_t>(texture) : -1;
+  return engine_render_model(id(mesh), t, static_cast<float>(shine)) != 0;
+}
+
 double NayanEngineModule::meshAlias(jsi::Runtime &, double base) {
   return engine_mesh_alias(id(base));
 }
@@ -556,6 +671,11 @@ double NayanEngineModule::textureLoad(jsi::Runtime &rt, jsi::Object data) {
   return engine_texture_load(buffer.data(rt), buffer.size(rt)); // decoded and copied
 }
 
+jsi::Value NayanEngineModule::textureLoadAsync(jsi::Runtime &rt, jsi::Object data) {
+  auto bytes = std::make_shared<std::vector<uint8_t>>(copyBytes(rt, data, "textureLoadAsync"));
+  return runInBackground(rt, jsInvoker_, [bytes]() { return static_cast<double>(engine_texture_load(bytes->data(), bytes->size())); });
+}
+
 jsi::Object NayanEngineModule::texturePixels(jsi::Runtime &rt, double texture) {
   uint32_t size[2] = {0, 0};
   engine_texture_size(id(texture), size);
@@ -574,6 +694,15 @@ double NayanEngineModule::fontLoad(jsi::Runtime &rt, jsi::Object data, double de
   return engine_font_load(buffer.data(rt), buffer.size(rt), static_cast<float>(depth), utf8.data(), utf8.size(), static_cast<float>(weight));
 }
 
+jsi::Value NayanEngineModule::fontLoadAsync(jsi::Runtime &rt, jsi::Object data, double depth, jsi::String chars, double weight) {
+  auto bytes = std::make_shared<std::vector<uint8_t>>(copyBytes(rt, data, "fontLoadAsync"));
+  auto utf8 = std::make_shared<std::string>(chars.utf8(rt));
+  return runInBackground(rt, jsInvoker_, [bytes, utf8, depth, weight]() {
+    return static_cast<double>(
+        engine_font_load(bytes->data(), bytes->size(), static_cast<float>(depth), utf8->data(), utf8->size(), static_cast<float>(weight)));
+  });
+}
+
 jsi::Array NayanEngineModule::fontGlyphs(jsi::Runtime &rt, double font) {
   uint32_t f = id(font);
   const float *glyphs = engine_font_glyphs(f);
@@ -655,6 +784,38 @@ double NayanEngineModule::renderFrame(
       r.size(rt) / sizeof(uint32_t), n, out.size(rt) >= 16 * sizeof(float) ? reinterpret_cast<float *>(out.data(rt)) : nullptr, find(world));
 }
 
+double NayanEngineModule::publishFrame(
+    jsi::Runtime &rt,
+    double surface,
+    jsi::Object frame,
+    jsi::Object matrices,
+    jsi::Object colors,
+    jsi::Object regions,
+    jsi::Object ranges,
+    double count,
+    jsi::Object viewProj,
+    double world) {
+  jsi::ArrayBuffer f = fileData(rt, frame, "publishFrame");
+  jsi::ArrayBuffer m = fileData(rt, matrices, "publishFrame");
+  jsi::ArrayBuffer c = fileData(rt, colors, "publishFrame");
+  jsi::ArrayBuffer g = fileData(rt, regions, "publishFrame");
+  jsi::ArrayBuffer r = fileData(rt, ranges, "publishFrame");
+  jsi::ArrayBuffer out = fileData(rt, viewProj, "publishFrame");
+  size_t capacity = std::min({m.size(rt) / (16 * sizeof(float)), c.size(rt) / (4 * sizeof(float)), g.size(rt) / (4 * sizeof(float))});
+  size_t n = count > 0 ? std::min(static_cast<size_t>(count), capacity) : 0;
+  return engine_render_publish(
+      static_cast<int32_t>(surface), reinterpret_cast<const double *>(f.data(rt)), f.size(rt) / sizeof(double),
+      reinterpret_cast<const float *>(m.data(rt)), reinterpret_cast<const float *>(c.data(rt)),
+      reinterpret_cast<const float *>(g.data(rt)), capacity, reinterpret_cast<const uint32_t *>(r.data(rt)),
+      r.size(rt) / sizeof(uint32_t), n, out.size(rt) >= 16 * sizeof(float) ? reinterpret_cast<float *>(out.data(rt)) : nullptr, find(world));
+}
+
+jsi::Array NayanEngineModule::renderStats(jsi::Runtime &rt, double surface) {
+  double out[2] = {0, 0};
+  engine_render_stats(static_cast<int32_t>(surface), out);
+  return jsi::Array::createWithElements(rt, out[0], out[1]);
+}
+
 void NayanEngineModule::renderOverlay(
     jsi::Runtime &rt,
     double surface,
@@ -713,6 +874,11 @@ double NayanEngineModule::audioLoad(jsi::Runtime &rt, jsi::Object data) {
   return engine_audio_load_wav(buffer.data(rt), buffer.size(rt)); // copied by the core
 }
 
+jsi::Value NayanEngineModule::audioLoadAsync(jsi::Runtime &rt, jsi::Object data) {
+  auto bytes = std::make_shared<std::vector<uint8_t>>(copyBytes(rt, data, "audioLoadAsync"));
+  return runInBackground(rt, jsInvoker_, [bytes]() { return static_cast<double>(engine_audio_load_wav(bytes->data(), bytes->size())); });
+}
+
 double NayanEngineModule::audioPlay(jsi::Runtime &, double sound, double volume, double pan, double pitch, bool loop) {
   return static_cast<double>(engine_audio_play(id(sound), volume, pan, pitch, loop ? 1 : 0));
 }
@@ -800,6 +966,11 @@ Java_com_nayanui_engine_EngineSurfaceView_nativeAttach(JNIEnv *env, jclass, jint
 extern "C" JNIEXPORT void JNICALL Java_com_nayanui_engine_EngineSurfaceView_nativeDetach(JNIEnv *, jclass, jint surface) {
   releaseWindow(surface);
 }
+
+/** Called by EngineSurfaceView's Choreographer once per display refresh while it's attached and visible. */
+extern "C" JNIEXPORT void JNICALL Java_com_nayanui_engine_EngineSurfaceView_nativeVsync(JNIEnv *, jclass, jint surface, jlong frameTimeNanos) {
+  facebook::react::deliverFrame(surface, static_cast<double>(frameTimeNanos) / 1e6);
+}
 extern "C" JNIEXPORT void JNICALL Java_com_nayanui_engine_EngineSurfaceView_nativeDrawingPresent(JNIEnv *, jclass, jint drawing, jint surface, jfloat width, jfloat height, jint color) {
   engine_drawing_present(drawing, surface, width, height, static_cast<uint32_t>(color));
 }

package/native/cpp/NayanEngineModule.h

@@ -63,12 +63,14 @@ class NayanEngineModule : public NativeNayanEngineCxxSpec<NayanEngineModule> {
   double shapePrepare(jsi::Runtime &rt, jsi::Object vertices, jsi::Object indices, jsi::String options);
   double solidPrepare(jsi::Runtime &rt, jsi::String recipe, jsi::String options);
   double modelLoad(jsi::Runtime &rt, jsi::Object data, bool center, double fit);
+  jsi::Value modelLoadAsync(jsi::Runtime &rt, jsi::Object data, bool center, double fit);
   jsi::Object modelVertices(jsi::Runtime &rt, double mesh);
   jsi::Object modelIndices(jsi::Runtime &rt, double mesh);
   jsi::Array modelSize(jsi::Runtime &rt, double mesh);
   double modelTexture(jsi::Runtime &rt, double mesh);
   double meshAlias(jsi::Runtime &rt, double base);
   double meshCreate(jsi::Runtime &rt, jsi::Object vertices, jsi::Object indices);
+  bool renderModel(jsi::Runtime &rt, double mesh, double texture, double shine);
   jsi::Object pathExtrude(jsi::Runtime &rt, jsi::Object points, jsi::Array counts, double depth, bool evenOdd);
   void geometrySmoothNormals(jsi::Runtime &rt, jsi::Object vertices, jsi::Object indices);
   jsi::Object geometrySolid(jsi::Runtime &rt, jsi::String recipe);
@@ -85,9 +87,11 @@ class NayanEngineModule : public NativeNayanEngineCxxSpec<NayanEngineModule> {
       jsi::Object outIndices,
       double indexOffset);
   double textureLoad(jsi::Runtime &rt, jsi::Object data);
+  jsi::Value textureLoadAsync(jsi::Runtime &rt, jsi::Object data);
   jsi::Object texturePixels(jsi::Runtime &rt, double texture);
   jsi::Array textureSize(jsi::Runtime &rt, double texture);
   double fontLoad(jsi::Runtime &rt, jsi::Object data, double depth, jsi::String chars, double weight);
+  jsi::Value fontLoadAsync(jsi::Runtime &rt, jsi::Object data, double depth, jsi::String chars, double weight);
   jsi::Array fontGlyphs(jsi::Runtime &rt, double font);
   jsi::String loadError(jsi::Runtime &rt);
   void generateBuiltinMeshes(jsi::Runtime &rt);
@@ -106,6 +110,23 @@ class NayanEngineModule : public NativeNayanEngineCxxSpec<NayanEngineModule> {
       double count,
       jsi::Object viewProj,
       double world);
+  double publishFrame(
+      jsi::Runtime &rt,
+      double surface,
+      jsi::Object frame,
+      jsi::Object matrices,
+      jsi::Object colors,
+      jsi::Object regions,
+      jsi::Object ranges,
+      double count,
+      jsi::Object viewProj,
+      double world);
+  jsi::Array renderStats(jsi::Runtime &rt, double surface);
+  bool hasFrameClock(jsi::Runtime &rt);
+  void startFrames(jsi::Runtime &rt, double surface, jsi::Function onFrame);
+  void stopFrames(jsi::Runtime &rt, double surface);
+  /** Runs a surface's frame callback (on the JS thread); see `deliverFrame`. */
+  void callFrame(jsi::Runtime &rt, int surface, double timeMs);
   void renderOverlay(
       jsi::Runtime &rt,
       double surface,
@@ -122,6 +143,7 @@ class NayanEngineModule : public NativeNayanEngineCxxSpec<NayanEngineModule> {
   jsi::String drawingCommand(jsi::Runtime &rt, double document, jsi::String command);
   void drawingDestroy(jsi::Runtime &rt, double document);
   double audioLoad(jsi::Runtime &rt, jsi::Object data);
+  jsi::Value audioLoadAsync(jsi::Runtime &rt, jsi::Object data);
   double audioPlay(jsi::Runtime &rt, double sound, double volume, double pan, double pitch, bool loop);
   void audioStop(jsi::Runtime &rt, double voice);
   void audioSetVolume(jsi::Runtime &rt, double volume);
@@ -139,6 +161,14 @@ class NayanEngineModule : public NativeNayanEngineCxxSpec<NayanEngineModule> {
   std::unordered_map<int, std::shared_ptr<::World>> worlds_;
   int next_ = 1;
   std::unordered_set<int> drawings_;
+  /** Frame callbacks by surface; only touched on the JS thread. */
+  std::unordered_map<int, jsi::Function> frameCallbacks_;
 };
 
+/**
+ * Called by the platform's display clock (any thread) once per refresh: schedules the surface's
+ * frame callback on the JS thread unless one is already waiting there.
+ */
+void deliverFrame(int surface, double timeMs);
+
 } // namespace facebook::react