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

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

@@ -0,0 +1,24 @@
+package com.nayanui.engine;
+
+import androidx.annotation.NonNull;
+import com.facebook.react.ReactPackage;
+import com.facebook.react.bridge.NativeModule;
+import com.facebook.react.bridge.ReactApplicationContext;
+import com.facebook.react.uimanager.ViewManager;
+import java.util.Collections;
+import java.util.List;
+
+/** Registers the EngineSurface view (the native module is a C++ TurboModule, registered separately). */
+public class NayanEnginePackage implements ReactPackage {
+  @NonNull
+  @Override
+  public List<NativeModule> createNativeModules(@NonNull ReactApplicationContext context) {
+    return Collections.emptyList();
+  }
+
+  @NonNull
+  @Override
+  public List<ViewManager> createViewManagers(@NonNull ReactApplicationContext context) {
+    return Collections.singletonList(new EngineSurfaceViewManager());
+  }
+}

package/native/core/build/EngineCore.xcframework/Info.plist

@@ -0,0 +1,43 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>AvailableLibraries</key>
+	<array>
+		<dict>
+			<key>BinaryPath</key>
+			<string>libengine_core.a</string>
+			<key>LibraryIdentifier</key>
+			<string>ios-arm64</string>
+			<key>LibraryPath</key>
+			<string>libengine_core.a</string>
+			<key>SupportedArchitectures</key>
+			<array>
+				<string>arm64</string>
+			</array>
+			<key>SupportedPlatform</key>
+			<string>ios</string>
+		</dict>
+		<dict>
+			<key>BinaryPath</key>
+			<string>libengine_core.a</string>
+			<key>LibraryIdentifier</key>
+			<string>ios-arm64-simulator</string>
+			<key>LibraryPath</key>
+			<string>libengine_core.a</string>
+			<key>SupportedArchitectures</key>
+			<array>
+				<string>arm64</string>
+			</array>
+			<key>SupportedPlatform</key>
+			<string>ios</string>
+			<key>SupportedPlatformVariant</key>
+			<string>simulator</string>
+		</dict>
+	</array>
+	<key>CFBundlePackageType</key>
+	<string>XFWK</string>
+	<key>XCFrameworkFormatVersion</key>
+	<string>1.0</string>
+</dict>
+</plist>

package/native/core/include/drawing-licenses.txt

@@ -0,0 +1,58 @@
+Drawing renderer dependencies
+=============================
+
+raqote 0.8.5
+https://github.com/jrmuizel/raqote
+
+Copyright (c) 2019 Jeff Muizelaar
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+* Neither the name of the copyright holder nor the names of its
+  contributors may be used to endorse or promote products derived from
+  this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+
+svgtypes 0.16.1 (MIT option)
+https://github.com/linebender/svgtypes
+
+Copyright (c) 2018 Yevhenii Reizner
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+

package/native/core/include/engine_core.h

@@ -0,0 +1,331 @@
+// C interface to the engine core. Keep in sync with src/ffi/ and src/world/{desc,animation,particles}.rs.
+#pragma once
+#include <stddef.h>
+#include <stdint.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+typedef struct World World;
+
+#define ENGINE_NO_ENTITY UINT32_MAX
+#define ENGINE_MAX_MESHES 4096     // 0..15 built-in shapes (15 = not drawn), 16.. models, glyphs, aliases
+#define ENGINE_MAX_EVENTS 4096
+#define ENGINE_EVENT_STRIDE 4      // u32s per event: entity_a, entity_b, flags, impact speed (f32 bits)
+#define ENGINE_EVENT_STARTED 1u    // flag: started touching (otherwise stopped)
+#define ENGINE_EVENT_SENSOR 2u     // flag: a sensor was involved
+#define ENGINE_FIXED_DT (1.0f / 60.0f)
+
+// ── Entity descriptions ──────────────────────────────────────────────────
+// Entities are created and changed with one call, from ENGINE_DESC_LEN doubles. Slot 0 holds
+// flags saying which fields are present; the rest live at the offsets below.
+#define ENGINE_DESC_LEN 64
+
+#define ENGINE_DESC_MESH (1u << 0)
+#define ENGINE_DESC_POSITION (1u << 1)
+#define ENGINE_DESC_ROTATION (1u << 2)
+#define ENGINE_DESC_SCALE (1u << 3)
+#define ENGINE_DESC_COLOR (1u << 4)
+#define ENGINE_DESC_VELOCITY (1u << 5)
+#define ENGINE_DESC_GROUND_VELOCITY (1u << 6)
+#define ENGINE_DESC_SPIN (1u << 7)
+#define ENGINE_DESC_BOB (1u << 8)
+#define ENGINE_DESC_FOLLOW (1u << 9)
+#define ENGINE_DESC_LIFETIME (1u << 10)
+#define ENGINE_DESC_PARENT (1u << 11)
+#define ENGINE_DESC_PHYSICS (1u << 12)
+#define ENGINE_DESC_IMPACT (1u << 13)
+#define ENGINE_DESC_ACCELERATION (1u << 14)
+#define ENGINE_DESC_PICKABLE (1u << 15)
+#define ENGINE_DESC_REGION (1u << 16)
+
+#define ENGINE_SLOT_FLAGS 0
+#define ENGINE_SLOT_MESH 1             // mesh id
+#define ENGINE_SLOT_POSITION 2         // x y z
+#define ENGINE_SLOT_ROTATION 5         // quaternion x y z w
+#define ENGINE_SLOT_SCALE 9            // x y z
+#define ENGINE_SLOT_COLOR 12           // r g b a
+#define ENGINE_SLOT_VELOCITY 16        // x y z
+#define ENGINE_SLOT_GROUND_VELOCITY 19 // x z (keeps vertical speed)
+#define ENGINE_SLOT_SPIN 21            // x y z, radians/second
+#define ENGINE_SLOT_BOB 24             // amplitude x y z, speed, phase
+#define ENGINE_SLOT_FOLLOW 29          // target (-1 = stop), speed
+#define ENGINE_SLOT_LIFETIME 31        // seconds (<= 0 clears)
+#define ENGINE_SLOT_PARENT 32          // entity (-1 = detach)
+// kind (0 remove, 1 dynamic, 2 kinematic, 3 fixed), shape (0 ball, 1 box, 2 from the mesh, 3 cylinder,
+// 4 capsule, 5 cone), size x y z (ball: radius in x; box: half extents; cylinder/capsule/cone: radius in x,
+// half the total height in y; <= 0 = sized from the entity's mesh and scale), layer, mask, sensor,
+// friction, bounce, density, drag, angular drag, gravity scale, upright, ccd, planar (stays in its XY plane).
+// Pairs interact if (a.mask & b.layer) || (b.mask & a.layer).
+#define ENGINE_SLOT_PHYSICS 33
+// enabled, sound (-1 = none), min speed, max speed, volume, haptic.
+#define ENGINE_SLOT_IMPACT 50
+#define ENGINE_SLOT_ACCELERATION 56 // x y z (entities without a dynamic body)
+#define ENGINE_SLOT_PICKABLE 59     // 0 or 1
+#define ENGINE_SLOT_REGION 60       // texture region u0 v0 u1 v1
+
+// ── Animations and particle bursts ───────────────────────────────────────
+// Animation: a header, then `entity count` entity ids, then `keyframe count` keyframes.
+// Header: entity count, keyframe count (1..64), duration, delay, easing (0 linear, 1 in, 2 out, 3 in-out,
+// 4 back, 5 bounce, 6 elastic), repeat (-1 = forever), yoyo, stagger (seconds per entity), smooth path,
+// spring stiffness (0 = timed tween), spring damping, spring mass.
+// Keyframe: flags (1 position, 2 rotation, 4 scale, 8 color, 16 move by, 32 turn, 64 shake, 128 has time),
+// time 0..1, position xyz, rotation xyzw, scale xyz, color rgba, move by xyz, turn xyz (radians), shake.
+// Each animated property is its own track: a new one replaces only the same property on the same entity.
+#define ENGINE_ANIM_HEADER 12
+#define ENGINE_ANIM_KEY_LEN 23
+#define ENGINE_DONE_PER_ENTITY 5 // room in engine_world_done: capacity * 5 + 64 ids
+// Burst: position xyz, direction xyz, spread (radians), count, mesh, size, speed, lifetime, gravity,
+// color count (1..4), colors rgba x 4, end size (x start size), has end color (0 / 1), end color rgba.
+#define ENGINE_BURST_LEN 36
+
+// ── Worlds and entities ──────────────────────────────────────────────────
+// Capacity is fixed: every pointer below stays valid until engine_world_free.
+World *engine_world_new(uint32_t capacity);
+void engine_world_free(World *w);
+
+// Returns the entity id, or ENGINE_NO_ENTITY if the world is full or the description is rejected.
+uint32_t engine_world_spawn_desc(World *w, const double *desc, size_t len);
+// Returns 1 if everything was applied; 0 if the entity is gone or a field was rejected.
+int32_t engine_world_set_desc(World *w, uint32_t id, const double *desc, size_t len);
+// Draw-only transform batch: 16 doubles per record (id, flags, position xyz, rotation xyzw,
+// scale xyz, color rgba). Flags match ENGINE_FLAG_POSITION/ROTATION/SCALE/COLOR. Returns applied count.
+uint32_t engine_world_set_transforms(World *w, const double *data, size_t len, size_t count);
+// Returns 1 if the entity existed. Stale ids are ignored everywhere.
+int32_t engine_world_despawn(World *w, uint32_t id);
+
+// Instant change in momentum (dynamic bodies only).
+void engine_world_apply_impulse(World *w, uint32_t id, float x, float y, float z);
+void engine_world_set_gravity(World *w, float x, float y, float z);
+// Moving non-dynamic entities are clamped to this XZ rectangle (dynamic bodies use walls).
+void engine_world_set_bounds(World *w, float min_x, float min_z, float max_x, float max_z);
+// Entity used to pan/attenuate impact sounds; ENGINE_NO_ENTITY clears it.
+void engine_world_set_listener(World *w, uint32_t id);
+
+// Hits non-sensor colliders whose layer & mask != 0. Returns the entity or ENGINE_NO_ENTITY;
+// on a hit scratch[0..7] = distance, normal xyz, point xyz.
+uint32_t engine_world_raycast(World *w, float ox, float oy, float oz, float dx, float dy, float dz,
+                              float max_distance, uint32_t mask);
+// Nearest pickable, visible entity along a ray (bounding boxes, as last drawn). Returns it or
+// ENGINE_NO_ENTITY; on a hit scratch[0..4] = distance, point xyz.
+uint32_t engine_world_pick(World *w, float ox, float oy, float oz, float dx, float dy, float dz);
+// Write position / velocity to engine_world_scratch()[0..3]. Return 1 on success. Positions are simulated
+// (relative to the parent), or with rendered != 0 where the entity was last drawn, in world space.
+int32_t engine_world_read_position(World *w, uint32_t id, int32_t rendered);
+int32_t engine_world_read_velocity(World *w, uint32_t id);
+
+// Starts an animation (layout above). Returns its id (> 0), reported by engine_world_done when every
+// track has ended (finished, replaced, stopped or despawned); 0 if nothing started.
+uint32_t engine_world_animate(World *w, const double *anim, size_t len);
+// Stops every animation on the entity where it is. Returns 1 if it had any.
+int32_t engine_world_stop_animation(World *w, uint32_t id);
+// Spawns particles (ENGINE_BURST_LEN doubles). Returns how many were spawned.
+uint32_t engine_world_burst(World *w, const double *burst, size_t len);
+
+// Runs whole ENGINE_FIXED_DT steps and interpolates the render output between the last two.
+void engine_world_update(World *w, float dt);
+// Timers on the world's clock (update dt): the id is reported in done (like an animation's) at the
+// end of the update that reaches it. Returns the id, or 0.
+uint32_t engine_world_after(World *w, float seconds);
+// Drops every pending timer (they never fire). Returns how many were dropped.
+uint32_t engine_world_cancel_timers(World *w);
+// Score, lives and the game clock, advanced by engine_world_update. op: 0 add score, 1 set score,
+// 2 add lives, 3 set lives, 4 start clock (a = countdown seconds or 0 to count up, b = points per
+// second), 5 stop, 6 resume, 7 reset (a = lives), 8 add time (a = seconds), 9 time bonus (a = points per second saved, b = expected seconds
+// for a clock counting up). Returns the score.
+#define ENGINE_SCOREBOARD_LEN 8
+double engine_world_scoreboard(World *w, uint32_t op, double a, double b);
+// [score, lives, seconds, shown seconds, changed flags, running, points per second, best].
+double *engine_world_scoreboard_state(World *w);
+uint32_t engine_world_count(World *w);
+uint32_t engine_world_capacity(World *w);
+
+// Render output, valid after engine_world_update. Instances are grouped by mesh id.
+const float *engine_world_matrices(World *w);  // capacity * 16 floats, column-major
+const float *engine_world_colors(World *w);    // capacity * 4 floats (rgba)
+const float *engine_world_regions(World *w);   // capacity * 4 floats (texture region u0 v0 u1 v1)
+// ENGINE_MAX_MESHES * 4 u32: [first, count] per mesh for opaque instances, then for transparent ones.
+const uint32_t *engine_world_ranges(World *w);
+// Ids of animations that ended since the last update began (room for capacity * 5 + 64).
+const uint32_t *engine_world_done(World *w);
+uint32_t engine_world_done_len(World *w);
+
+// Collision events from the last update, ENGINE_EVENT_STRIDE u32s each; event_len counts u32 values.
+const uint32_t *engine_world_events(World *w);
+uint32_t engine_world_event_len(World *w);
+
+const float *engine_world_scratch(World *w); // 16 floats
+
+// ── Camera math (per world, after setView) ────────────────────────────
+// Stores the view-projection matrix (16 column-major floats) and view size in points.
+void engine_world_set_view(World *w, const float *view_proj, float width, float height);
+// World-space ray through a view point. Writes origin xyz + direction xyz into scratch[0..6]. 1 on success.
+int32_t engine_world_screen_ray(World *w, float x, float y);
+// Where a view point lands on a plane. Writes into scratch[0..3]. 1 on success.
+int32_t engine_world_screen_to_world(World *w, float x, float y, float ppx, float ppy, float ppz, float pnx, float pny, float pnz);
+// Where a world position appears on screen (points from top-left). Writes into scratch[0..2]. 1 on success.
+int32_t engine_world_to_screen(World *w, float x, float y, float z);
+// Nearest pickable entity under a screen point. Returns it or ENGINE_NO_ENTITY; scratch[0..4] on hit.
+uint32_t engine_world_pick_screen(World *w, float x, float y);
+
+// ── Meshes, models, textures, fonts (global) ─────────────────────────────
+// glTF 2.0 (.glb, or .gltf with embedded data), merged into one mesh. Returns the mesh id, or -1.
+/* Skeletal models: metadata JSON; named clips loop/seek/crossfade natively. */
+size_t engine_model_rig(uint32_t mesh, uint8_t *out, size_t capacity);
+int32_t engine_world_play_clip(World *w, uint32_t entity, const uint8_t *name, size_t name_len, int32_t looping, float speed, float fade, float time);
+int32_t engine_world_stop_clip(World *w, uint32_t entity, int32_t reset);
+/* Model-space vertex samples. out has count*3 floats; after previews the next update. */
+int32_t engine_world_skin_points(World *w, uint32_t entity, const uint32_t *indices, size_t count, float *out, float after);
+int32_t engine_model_load(const uint8_t *data, size_t len, int32_t center, float fit);
+// Geometry of a registered mesh (model, glyph, or what an alias points to). Valid for the process.
+const float *engine_model_vertices(uint32_t mesh);  // vertex_count * 11 floats: position, normal, color, uv
+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
+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);
+// Registers geometry (copied): vertex_count * 11 floats (position, normal, color, uv) and u32 triangle
+// indices. Colliders use a box around the origin holding every vertex. Returns the mesh id, or -1.
+/* Persistent assets: app-private storage, no TTL/eviction. cache_read results own their bytes. */
+typedef struct EngineCacheBlob EngineCacheBlob;
+int32_t engine_cache_directory(const uint8_t *path, size_t length);
+EngineCacheBlob *engine_cache_read(const uint8_t *key, size_t length);
+const uint8_t *engine_cache_data(const EngineCacheBlob *blob);
+size_t engine_cache_size(const EngineCacheBlob *blob);
+void engine_cache_free(EngineCacheBlob *blob);
+int32_t engine_cache_write(const uint8_t *key, size_t length, const uint8_t *bytes, size_t count);
+int32_t engine_cache_remove(const uint8_t *key, size_t length);
+int32_t engine_cache_clear(void);
+int32_t engine_shape_prepare(const float *vertices, size_t floats, const uint32_t *indices, size_t count, const uint8_t *options, size_t length);
+int32_t engine_solid_prepare(const uint8_t *recipe, size_t count, const uint8_t *options, size_t length);
+
+int32_t engine_mesh_create(const float *vertices, size_t vertex_count, const uint32_t *indices, size_t index_count);
+// Fills 2D contours (points = [x, y] pairs, counts[k] points per contour; y up) by the non-zero or
+// even-odd rule and extrudes them depth deep (0 = front face only, facing +Z). Returns the number of
+// floats made (11 per vertex, unindexed triangles), copied out by engine_path_extrude_copy.
+size_t engine_path_extrude(const float *points, const uint32_t *counts, size_t contour_count, float depth, int32_t even_odd);
+size_t engine_path_extrude_copy(float *out, size_t cap);
+// Geometry passes, in place (11 floats per vertex). Smooth: normals from the triangles, averaged
+// across vertices at the same place. Face outward: flips triangles whose winding disagrees with
+// their normals.
+void engine_geometry_smooth_normals(float *vertices, size_t vertex_count, const uint32_t *indices, size_t index_count);
+
+// Intermediate modelling results own their memory and allocate no registered mesh IDs. Data is
+// [vertex_count, index_count, 11 floats per vertex (as u32 bits), u32 indices], valid until free.
+typedef struct EngineGeometry EngineGeometry;
+EngineGeometry *engine_geometry_solid(const uint8_t *recipe, size_t len);
+EngineGeometry *engine_geometry_optimize(const float *vertices, size_t floats, const uint32_t *indices, size_t count, float ratio, float error, int32_t lock_borders);
+const uint32_t *engine_geometry_data(const EngineGeometry *result);
+size_t engine_geometry_size(const EngineGeometry *result);
+const char *engine_geometry_error(const EngineGeometry *result);
+void engine_geometry_free(EngineGeometry *result);
+void engine_geometry_face_outward(const float *vertices, size_t vertex_count, uint32_t *indices, size_t index_count);
+// Bakes a part into merged buffers: placement = position xyz, rotation quat xyzw, scale xyz, color
+// rgb (13 floats). Writes vertex_count vertices and index_count indices (plus first).
+void engine_geometry_place(const float *vertices, size_t vertex_count, const uint32_t *indices, size_t index_count, const float *placement,
+                           uint32_t first, float *out_vertices, uint32_t *out_indices);
+
+// PNG or JPEG. Returns the texture id, or -1.
+int32_t engine_texture_load(const uint8_t *data, size_t len);
+const uint8_t *engine_texture_pixels(uint32_t id); // width * height RGBA8, top row first
+int32_t engine_texture_size(uint32_t id, uint32_t *out_wh);
+
+// TrueType / OpenType: one extruded mesh per character of `chars` (UTF-8), depth in ems. Returns the
+// font id, or -1. `weight` picks a variable font's weight (0 = its default). Glyphs: [codepoint, mesh
+// (-1 = nothing drawn), advance in ems] floats.
+int32_t engine_font_load(const uint8_t *data, size_t len, float depth, const char *chars, size_t chars_len, float weight);
+const float *engine_font_glyphs(uint32_t font);
+uint32_t engine_font_glyph_floats(uint32_t font);
+float engine_font_cap_height(uint32_t font);
+
+// Why the last model / texture / font / alias load failed (NUL-terminated into out). Returns the full
+// length (0 = no error).
+size_t engine_load_error(char *out, size_t cap);
+
+// ── Audio (global) ───────────────────────────────────────────────────────
+// The output stream starts on first use. WAV (PCM int or float, mono/stereo).
+int32_t engine_audio_load_wav(const uint8_t *data, size_t len); // sound id, or -1
+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);
+void engine_audio_set_muted(int32_t muted);
+int32_t engine_audio_is_running(void);
+
+// ── Android ──────────────────────────────────────────────────────────────
+#ifdef __ANDROID__
+// Call once at startup with the JavaVM and a JNI *global* reference to a Context (the Application):
+// audio and haptics need them. Repeat calls are ignored.
+void engine_android_init(void *java_vm, void *context);
+#endif
+
+// ── Built-in mesh generation and readback (global) ───────────────────
+// 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.
+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
+// 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);
+// Attaches (or resizes) surface `surface` drawing into `window` (ANativeWindow* on Android, CAMetalLayer*
+// on iOS) at width x height pixels. `window` must stay valid until engine_render_detach returns.
+// Returns 1, or 0 on failure (see engine_render_error).
+int32_t engine_render_attach(int32_t surface, void *window, uint32_t width, uint32_t height);
+// Builds the GPU device and pipelines on a background thread before any surface exists, so the first
+// engine_render_attach doesn't (it waits for a warm-up in progress). Returns at once; repeat calls do nothing.
+void engine_render_warm_up(void);
+void engine_render_detach(int32_t surface);
+// Draws a frame. `frame`: ENGINE_FRAME_LEN doubles (layout in native/core/src/render/gpu.rs, Frame::from_slice).
+// Instance buffers hold `capacity` instances (regions may be NULL); `ranges` as engine_world_ranges.
+// Returns 1 (drawn; out_view_proj gets 16 floats), 0 (surface not ready / frame skipped), -1 (error).
+int32_t engine_render_frame(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);
+// The screen-space overlay drawn over `surface` from its next frame on (scoreboards, buttons), copied
+// from a world's buffers (as engine_render_frame). 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 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);
+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);
+
+// ── Haptics (global; Core Haptics on iOS, the Vibrator service on Android) ──
+int32_t engine_haptics_supported(void);
+// `count` taps as [time, intensity 0..1, sharpness 0..1] triples.
+void engine_haptics_play(const float *taps, uint32_t count, int32_t throttle);
+
+// Engine-owned art documents. Positions are view points; pressure is normalized 0..1.
+int32_t engine_drawing_create(float width, float height, float ratio);
+void engine_drawing_destroy(int32_t document);
+char *engine_drawing_command(int32_t document, const uint8_t *json, size_t length);
+void engine_drawing_result_free(char *result);
+// Returns null when unchanged. Free non-null events with engine_drawing_result_free.
+char *engine_drawing_take_event(int32_t document);
+void engine_drawing_touch(int32_t document, int32_t phase, float x, float y, float pressure);
+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);
+
+#ifdef __cplusplus
+}
+#endif