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

package/lib/web/types/src/world/desc.d.ts

@@ -0,0 +1,16 @@
+import type { EntityOptions } from './types';
+export declare const DESC_LEN = 64;
+/** Writes `options` into `d`, with the mesh id already resolved. Only the fields present are flagged. */
+export declare function encode(d: Float64Array, o: EntityOptions, mesh: number | undefined): void;
+export declare const ANIM_HEADER = 12;
+export declare const ANIM_KEY_LEN = 23;
+export declare const BURST_LEN = 36;
+export declare const EASING: {
+    readonly linear: 0;
+    readonly easeIn: 1;
+    readonly easeOut: 2;
+    readonly easeInOut: 3;
+    readonly back: 4;
+    readonly bounce: 5;
+    readonly elastic: 6;
+};

package/lib/web/types/src/world/effects.d.ts

@@ -0,0 +1,155 @@
+import type { Vec3 } from '../types';
+import type { BurstOptions, Color, Entity } from './types';
+import type { World } from './World';
+/** Shared options of the layered effects (confetti, sparkle, shatter, splash, sparks, explosion). */
+export type EffectOptions = {
+    position: Vec3;
+    /** One color, or several to pick from at random. */
+    colors: Color | readonly Color[];
+    /** Typical particle size. */
+    size: number;
+    /** Top speed. */
+    speed: number;
+    /** About how many particles (a few extra go to the flash and puffs). */
+    count: number;
+    /** Seconds. */
+    lifetime: number;
+    /** Vertical acceleration (negative falls). Default 0. */
+    gravity?: number;
+    /** Main direction. Default up. */
+    direction?: Vec3;
+    /** Half-angle of the cone around `direction`. Default π (every direction). */
+    spread?: number;
+    /** A brief glow at the source. Default true. */
+    flash?: boolean;
+};
+/** A soft cloud of puffs that swell and fade: landing dust, kicked-up sand, sawdust, steam, muzzle smoke. */
+export type DustOptions = {
+    position: Vec3;
+    /** Start color (alpha is how thick it looks), or several to pick from. */
+    color: Color | readonly Color[];
+    /** Puff size at the start. */
+    size: number;
+    /** Top speed. */
+    speed: number;
+    count: number;
+    /** Seconds. */
+    lifetime: number;
+    /** Default up. */
+    direction?: Vec3;
+    /** Half-angle around `direction`. Default π. */
+    spread?: number;
+    /** Default 0 (dust hangs; positive rises like smoke). */
+    gravity?: number;
+    /** How much each puff grows by the end. Default 2. */
+    endSize?: number;
+    /** Color at the end. Default: a single `color` faded to transparent; several colors keep theirs. */
+    endColor?: Color;
+    /** Default "puff" (blended); "flame" adds light instead. */
+    mesh?: BurstOptions['mesh'];
+};
+/** One glow that swells and fades at a point: a hit, a strike, a muzzle flash. */
+export type FlashOptions = {
+    position: Vec3;
+    /** Use channels above 1 to glow (see `effects.hot`). */
+    color: Color;
+    size: number;
+    /** Seconds. Default 0.22. */
+    lifetime?: number;
+    /** How much it grows by the end. Default 2.2. */
+    endSize?: number;
+    /** Default: `color` faded to transparent. */
+    endColor?: Color;
+    /** Default "flame" (adds light); "sphere" or "puff" for a solid or soft flash. */
+    mesh?: BurstOptions['mesh'];
+    /** Glows drawn at once (slightly scattered when `speed` > 0). Default 1. */
+    count?: number;
+    /** Default 0. */
+    speed?: number;
+};
+/** The cleared-piece pop: swell, flash white, settle, shrink away. */
+export type PopOptions = {
+    /** Its scale at rest (what it has now): one number, or per axis. */
+    scale: number | Vec3;
+    /** Its color at rest, to return to after the white flash. Omit to flash `flash` only (or nothing). */
+    color?: Color;
+    /** Parts to flash white as well (a group's visible children, whose rest color is white). */
+    flash?: readonly Entity[];
+    /** Seconds before it starts. Default 0. */
+    delay?: number;
+    /** Seconds it takes. Default `effects.POP_TIME`. */
+    duration?: number;
+};
+type Rgba = [number, number, number, number];
+/** The same hue, self-lit: its brightest channel lifted to `peak` (above 1 glows, through light, shadow and fog). */
+declare function hot(c: Color, peak?: number, alpha?: number): Rgba;
+/** Part way (`t`, 0..1) to white, with `alpha`. */
+declare function pale(c: Color, t: number, alpha?: number): Rgba;
+declare function flash(world: World, o: FlashOptions): number;
+declare function dust(world: World, o: DustOptions): number;
+/** Celebration confetti: tumbling paper in two layers, a few glinting sparkles, and a pop of light. */
+declare function confetti(world: World, e: EffectOptions): void;
+/** Glitter for a reward: solid bright beads (seen on any background) with additive glints around them. */
+declare function sparkle(world: World, e: EffectOptions): void;
+/**
+ * Something breaking apart: big slow chunks, small fast crumbs, a glow at the break and a puff of
+ * its dust. `mesh` is the chunks' shape.
+ */
+declare function shatter(world: World, e: EffectOptions & {
+    mesh?: BurstOptions['mesh'];
+    dust?: boolean;
+}): void;
+/** Liquid: droplets in two sizes thrown out of a fine mist of the same color. */
+declare function splash(world: World, e: EffectOptions): void;
+/** Hot metal sparks: additive streaks that burn out, with a few solid beads and a flash where they strike. */
+declare function sparks(world: World, e: EffectOptions): void;
+/**
+ * A fiery blast: a white-hot flash, a fireball that cools into smoke, embers thrown out and, given
+ * `debris` colors, chunks of whatever blew up. `size` is the fireball's puff size; `colors` its fire.
+ * The fire and smoke swell every way; `direction`, `spread` and `gravity` aim the embers and debris.
+ */
+declare function explosion(world: World, e: Omit<EffectOptions, 'colors'> & {
+    colors?: EffectOptions['colors'];
+    debris?: readonly Color[];
+    smoke?: Color;
+}): void;
+/** The piece swells, flashes white, settles and shrinks away. Resolves when it's gone (despawning it is the caller's). */
+declare function pop(world: World, entity: Entity, o: PopOptions): Promise<void>;
+/**
+ * Ready-made effects. Each is one call; particles then live, fall, shrink and recolor in Rust.
+ *
+ * ```ts
+ * effects.confetti(world, { position, colors: [RED, GOLD], size: 0.12, speed: 6, count: 40, lifetime: 1.2, gravity: -6 });
+ * effects.dust(world, { position: feet, color: [0.8, 0.75, 0.65, 0.6], size: 0.3, speed: 1.5, count: 6, lifetime: 0.5 });
+ * effects.flash(world, { position: hit, color: effects.hot(ORANGE), size: 0.8 });
+ * await effects.pop(world, candy, { scale: 1, color: RED });
+ * world.despawn(candy);
+ * ```
+ */
+export declare const effects: {
+    /** Celebration: tumbling paper, glints and a pop of light (wins, level-ups). */
+    confetti: typeof confetti;
+    /** Reward glitter: bright beads and glints (pickups, perfect moves). */
+    sparkle: typeof sparkle;
+    /** Breaking apart: chunks, crumbs, a glow and dust (bricks, crates, glass). `mesh` shapes the chunks. */
+    shatter: typeof shatter;
+    /** Liquid: droplets and mist (water, juice, paint). */
+    splash: typeof splash;
+    /** Hot metal: additive streaks and beads (scrapes, strikes, electricity). */
+    sparks: typeof sparks;
+    /** Fiery blast: flash, fireball cooling to smoke, embers and optional debris. */
+    explosion: typeof explosion;
+    /** Soft swelling puffs: dust, sand, sawdust, steam, smoke. */
+    dust: typeof dust;
+    /** One swelling glow: hits, strikes, muzzle flashes. */
+    flash: typeof flash;
+    /** The cleared-piece animation: swell, flash white, settle, shrink to nothing. */
+    pop: typeof pop;
+    /** Default `pop` duration in seconds. */
+    POP_TIME: number;
+    /** The same hue made self-lit (brightest channel lifted to `peak`), for glows. */
+    hot: typeof hot;
+    /** Part way (`t`, 0..1) to white. */
+    pale: typeof pale;
+};
+export {};

package/lib/web/types/src/world/quat.d.ts

@@ -0,0 +1,30 @@
+import type { Quat } from './types';
+/** A writable quaternion; pass one as `out` to reuse it instead of allocating. */
+export type MutableQuat = [number, number, number, number];
+/**
+ * Quaternion helpers for `rotation` options, keyframes and geometry parts ([x, y, z, w]). Every
+ * function takes an optional `out` so per-frame code can reuse one array instead of allocating.
+ *
+ * ```ts
+ * world.set(car, { rotation: quat.y(heading) });
+ * const spin = quat.multiply(quat.y(yaw), quat.x(pitch), scratch); // pitch first, then yaw
+ * ```
+ */
+export declare const quat: {
+    /** No rotation. */
+    identity: Quat;
+    /** Rotation by `angle` radians around the unit axis (x, y, z). */
+    axisAngle(x: number, y: number, z: number, angle: number, out?: MutableQuat): MutableQuat;
+    /** Rotation around the x axis (pitch). */
+    x(angle: number, out?: MutableQuat): MutableQuat;
+    /** Rotation around the y axis (yaw, heading). */
+    y(angle: number, out?: MutableQuat): MutableQuat;
+    /** Rotation around the z axis (roll; spin for 2D games looking down -z). */
+    z(angle: number, out?: MutableQuat): MutableQuat;
+    /** `a` after `b`: `b` turns first. `out` may be `a` or `b`. */
+    multiply(a: Quat, b: Quat, out?: MutableQuat): MutableQuat;
+    /** Turns around x, then y, then z (radians): the same as `multiply(z(z), multiply(y(y), x(x)))`. */
+    fromEuler(x: number, y: number, z: number, out?: MutableQuat): MutableQuat;
+    /** Shortest-path interpolation from `a` (t = 0) to `b` (t = 1). */
+    slerp(a: Quat, b: Quat, t: number, out?: MutableQuat): MutableQuat;
+};

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

@@ -0,0 +1,232 @@
+import type { Font, TextAlign } from '../assets/font';
+import type { Model } from '../assets/model';
+import type { Texture } from '../assets/texture';
+import type { Sound } from '../media/audio';
+import type { Vec3 } from '../types';
+/** Opaque entity handle. Handles of despawned entities are safely ignored. */
+export type Entity = number & {
+    readonly __entity: unique symbol;
+};
+export type Color = readonly [number, number, number] | readonly [number, number, number, number];
+export type Quat = readonly [number, number, number, number];
+/** Playback for one entity using a skeletal animation embedded in a loaded model. */
+export interface ClipOptions {
+    /** Repeat the clip. Default true. */
+    loop?: boolean;
+    /** Playback rate; zero holds a pose. Default 1. */
+    speed?: number;
+    /** Crossfade from the current pose, in seconds. Default 0.15. */
+    fade?: number;
+    /** Seek to this time in seconds. Omit to retain playback when reselecting a clip. */
+    time?: number;
+}
+/** Plane used by screenToWorld; defaults to the ground through the origin. */
+export interface ScreenPlane {
+    point?: Vec3;
+    normal?: Vec3;
+}
+/**
+ * - `dynamic`: moved by physics (gravity, collisions, impulses).
+ * - `kinematic`: moved by you; pushes dynamic bodies out of the way.
+ * - `fixed`: never moves (floors, walls).
+ */
+export type BodyType = 'dynamic' | 'kinematic' | 'fixed';
+export type PhysicsOptions = {
+    type: BodyType;
+    /** Default: matches the mesh (spheres get a ball, cylinders a cylinder, ...; anything else a box). */
+    shape?: 'ball' | 'box' | 'cylinder' | 'capsule' | 'cone';
+    /** Ball, cylinder, capsule or cone radius. Default: from the entity's size. */
+    radius?: number;
+    /** Cylinder, capsule or cone height (total). Default: from the entity's size. */
+    height?: number;
+    /** Box size (full width, height, depth). Default: the entity's size. */
+    size?: Vec3;
+    /** Layer bits this collider is on. Default 1. */
+    layer?: number;
+    /** Layers it interacts with. Either side's mask is enough. Default: all. */
+    mask?: number;
+    /** Reports touches but doesn't push: pickups, trigger zones. */
+    sensor?: boolean;
+    /** How grippy, default 0.5. */
+    friction?: number;
+    /** Bounciness 0..1, default 0. */
+    bounce?: number;
+    /** Mass per volume, default 1. */
+    density?: number;
+    /** Slows movement over time (air resistance), default 0. */
+    drag?: number;
+    /** Slows spinning over time, default 0.05. */
+    angularDrag?: number;
+    /** Multiplier on world gravity, default 1. */
+    gravityScale?: number;
+    /** Stays upright: never tumbles. */
+    upright?: boolean;
+    /** Stops fast, small bodies passing through walls. */
+    ccd?: boolean;
+    /** 2D games: stays in its XY plane (moves in x/y, spins only around z). Keep the camera looking down -z. */
+    planar?: boolean;
+};
+/** Sound/haptic the core plays by itself when the entity hits something solid. */
+export type ImpactFeedback = {
+    /** A loaded sound, e.g. `sfx.get("bump")`. Omit for haptics only. */
+    sound?: Sound;
+    /** Slower impacts are silent. Default 1. */
+    minSpeed?: number;
+    /** Full volume and strength at this speed. Default 10. */
+    maxSpeed?: number;
+    /** Volume at full strength, 0..2. Default 1. */
+    volume?: number;
+    /** Vibration at full strength, 0..1. Default 0 (none). */
+    haptic?: number;
+};
+/**
+ * Everything about an entity. `spawn` and `set` take the same options; in `set`, only what you
+ * pass changes, and `null` removes something (physics, parent, follow, bob, lifetime, impact).
+ */
+export type EntityOptions = {
+    /** A built-in shape or a model from `loadModel`. Default "cube". */
+    mesh?: Shape | Model;
+    /** An image from `loadTexture`, drawn on the mesh (`null` = none). In `set`, pass `mesh` with it. */
+    texture?: Texture | null;
+    /** Part of the texture to show, [u0, v0, u1, v1] from 0..1 (sprite sheets, card atlases). */
+    textureRegion?: readonly [number, number, number, number];
+    /** 3D text instead of a mesh (needs `font`). Letters are 1 unit tall at scale 1. */
+    text?: string;
+    /** A font from `loadFont`, for `text`. */
+    font?: Font;
+    /** Text alignment around `position`. Default "center". */
+    align?: TextAlign;
+    /** Extra space between letters, in ems. Default 0. */
+    letterSpacing?: number;
+    /** Digits all as wide as the widest, so changing scores and timers don't shift. Default false. */
+    tabular?: boolean;
+    /** Relative to the parent when attached. */
+    position?: Vec3;
+    rotation?: Quat;
+    /** A number scales uniformly. Children scale with their parent. Visual only after the body exists. */
+    scale?: Vec3 | number;
+    /** Alpha below 1 makes it see-through. Channels above 1 glow: at 2 it's self-lit, ignoring light and shadow (fire, lamps). */
+    color?: Color;
+    /** Units per second. */
+    velocity?: Vec3;
+    /** Sets horizontal speed [x, z] and keeps the vertical one: steer a body and it still falls. */
+    groundVelocity?: readonly [number, number];
+    /** Units per second², for entities without a dynamic body (falling debris, thrown items). */
+    acceleration?: Vec3;
+    /** Radians per second around each axis. */
+    spin?: Vec3;
+    /** Visual bob: the drawn position moves by amplitude * sin(phase), phase advancing at `speed`. */
+    bob?: {
+        amplitude: Vec3;
+        speed: number;
+        phase?: number;
+    } | null;
+    /** Chase `target` along the ground at `speed`. */
+    follow?: {
+        target: Entity;
+        speed: number;
+    } | null;
+    /** Seconds until it shrinks away and is despawned. */
+    lifetime?: number | null;
+    /** Attach to another entity: it moves, turns and scales with the parent and is despawned with it. Visual only. */
+    parent?: Entity | null;
+    physics?: BodyType | PhysicsOptions | null;
+    impact?: ImpactFeedback | null;
+    /** Whether `pick` can hit it. Default true. */
+    pickable?: 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). */
+export type AnimateTarget = {
+    position?: Vec3;
+    rotation?: Quat;
+    scale?: Vec3 | number;
+    color?: Color;
+    /** Move by this offset from where the animation starts (instead of to a `position`). */
+    moveBy?: Vec3;
+    /** Turn by these angles (radians around x, y, z) from the starting rotation. 2π spins once; more spins more. */
+    turn?: Vec3;
+    /** Shake by up to this distance, fading out. Only the drawn position shakes (hits, wrong moves). */
+    shake?: number;
+};
+/** A step of a keyframed animation: values to pass through, and when (0..1 of the duration; default evenly spaced). */
+export type Keyframe = AnimateTarget & {
+    at?: number;
+};
+export type SpringOptions = {
+    /** How strongly it pulls toward the target. Default 170. */
+    stiffness?: number;
+    /** How quickly it calms down. Lower bounces more. Default 26 (no overshoot). */
+    damping?: number;
+    /** Heavier moves slower and swings further. Default 1. */
+    mass?: number;
+};
+export type AnimateOptions = {
+    /** Seconds (ignored by springs). Default 0.3. */
+    duration?: number;
+    /** Seconds before it starts. Default 0. */
+    delay?: number;
+    /** Default "easeOut". "back" overshoots, "bounce" bounces, "elastic" springs. */
+    easing?: Easing;
+    /** Extra runs after the first, or "forever". Default 0. */
+    repeat?: number | 'forever';
+    /** Every other run plays backwards (pulses, ping-pong). */
+    yoyo?: boolean;
+    /** With several entities: extra delay for each next one, in seconds (waves, board reveals). */
+    stagger?: number;
+    /** "smooth" moves along a curve through the keyframes (arcs, hops) instead of straight lines. */
+    path?: 'linear' | 'smooth';
+    /**
+     * Physically simulated motion instead of a fixed duration: true (smooth), "bouncy", or your own
+     * settings. Interrupting a spring with another keeps its speed, so it never jerks.
+     */
+    spring?: boolean | 'bouncy' | SpringOptions;
+};
+export type BurstOptions = {
+    position: Vec3;
+    /** How many particles. Default 16. */
+    count?: number;
+    /** Main direction. Default up. */
+    direction?: Vec3;
+    /** Half-angle of the cone around `direction`, in radians. Default π (every direction). */
+    spread?: number;
+    /** Default "cube". */
+    mesh?: Shape | Model;
+    /** Particle size. Default 0.15. */
+    size?: number;
+    /** Top speed. Default 5. */
+    speed?: number;
+    /** Seconds. Default 0.8. */
+    lifetime?: number;
+    /** Vertical acceleration. Default -9.81 (falls); 0 floats. */
+    gravity?: number;
+    /** One color, or up to 4 to pick from at random. Default white. */
+    color?: Color | readonly Color[];
+    /** Size at the end of each particle's life, as a multiple of its start size: above 1 grows (smoke), below shrinks (embers). Default 1. */
+    endSize?: number;
+    /** Color every particle shifts to over its life, e.g. flame to dark red; an alpha below 1 fades it out. Default: keeps its color. */
+    endColor?: Color;
+};
+export type CollisionInfo = {
+    /** True when the touch started; false when it ended. */
+    started: boolean;
+    /** A sensor was involved. */
+    sensor: boolean;
+    /** Impact speed (0 when a touch ends). */
+    speed: number;
+};
+export type RaycastHit = {
+    entity: Entity;
+    distance: number;
+    normal: [number, number, number];
+    point: [number, number, number];
+};
+export type PickHit = {
+    entity: Entity;
+    /** Where the tap ray hit the entity's bounding box, in world space. */
+    point: [number, number, number];
+    distance: number;
+};
+export type Bounds = readonly [minX: number, minZ: number, maxX: number, maxZ: number];
+import type { Shape } from '../types';
+export type { Shape };

package/native/android/CMakeLists.txt

@@ -0,0 +1,34 @@
+# Android build of the engine's native module. React Native's autolinking adds this directory to the
+# app's native build (see react-native.config.js); there is no Gradle project, so this is a "pure C++"
+# dependency and the codegen header ships in native/cpp/generated (regenerate with `bun run codegen`).
+cmake_minimum_required(VERSION 3.13)
+project(NayanEngine CXX)
+
+get_filename_component(NATIVE_ROOT "${CMAKE_CURRENT_LIST_DIR}/.." ABSOLUTE)
+
+# Rust core, prebuilt per ABI by native/core/scripts/build-android.sh.
+add_library(engine_core STATIC IMPORTED)
+set_target_properties(engine_core PROPERTIES
+  IMPORTED_LOCATION "${NATIVE_ROOT}/core/build/android/${ANDROID_ABI}/libengine_core.a")
+
+# The codegen target autolinking expects (react_codegen_<codegenConfig.name>). It must be a real
+# library: autolinking links `common_flags` into it with a plain target_link_libraries call.
+add_library(react_codegen_NayanEngineSpec STATIC "${NATIVE_ROOT}/cpp/generated/NayanEngineSpecJSI.cpp")
+# android/ holds NayanEngineSpec.h, the (empty) Java module provider autolinking includes.
+target_include_directories(react_codegen_NayanEngineSpec PUBLIC "${NATIVE_ROOT}/cpp/generated" "${CMAKE_CURRENT_LIST_DIR}")
+target_compile_features(react_codegen_NayanEngineSpec PUBLIC cxx_std_20)
+target_link_libraries(react_codegen_NayanEngineSpec jsi reactnative)
+
+# The TurboModule (shared with iOS) and the Rust core it calls.
+add_library(NayanEngine STATIC "${NATIVE_ROOT}/cpp/NayanEngineModule.cpp")
+target_include_directories(NayanEngine PUBLIC "${NATIVE_ROOT}/cpp" "${NATIVE_ROOT}/core/include")
+target_compile_features(NayanEngine PUBLIC cxx_std_20)
+target_link_libraries(NayanEngine
+  react_codegen_NayanEngineSpec
+  engine_core
+  fbjni
+  jsi
+  reactnative
+  aaudio   # audio output (cpal's AAudio backend)
+  android
+  log)

package/native/android/NayanEngineSpec.h

@@ -0,0 +1,15 @@
+// Autolinking includes <NayanEngineSpec.h> and calls this provider for every library with a codegen
+// config. The engine has no Java module (it is registered through the C++ provider in
+// NayanEngineModule.h), so this always declines.
+#pragma once
+
+#include <ReactCommon/JavaTurboModule.h>
+
+namespace facebook::react {
+
+inline std::shared_ptr<TurboModule> NayanEngineSpec_ModuleProvider(
+    const std::string&, const JavaTurboModule::InitParams&) {
+  return nullptr;
+}
+
+} // namespace facebook::react

package/native/android/build.gradle

@@ -0,0 +1,26 @@
+// Java side of the engine: the EngineSurface view the renderer draws into. The native module itself is
+// pure C++ (CMakeLists.txt, built into the app by autolinking).
+apply plugin: "com.android.library"
+
+def safeExtGet(prop, fallback) {
+  rootProject.ext.has(prop) ? rootProject.ext.get(prop) : fallback
+}
+
+android {
+  namespace "com.nayanui.engine"
+  compileSdkVersion safeExtGet("compileSdkVersion", 35)
+
+  defaultConfig {
+    minSdkVersion safeExtGet("minSdkVersion", 24)
+    consumerProguardFiles "proguard-rules.pro"
+  }
+}
+
+repositories {
+  google()
+  mavenCentral()
+}
+
+dependencies {
+  implementation "com.facebook.react:react-android"
+}

package/native/android/codegen/CMakeLists.txt

@@ -0,0 +1,3 @@
+# Autolinking adds a codegen directory for every library with a Gradle project. The engine runs no
+# Gradle codegen: ../CMakeLists.txt defines react_codegen_NayanEngineSpec from native/cpp/generated.
+cmake_minimum_required(VERSION 3.13)

package/native/android/proguard-rules.pro

@@ -0,0 +1,2 @@
+# The native methods are looked up by name from C++ (JNI).
+-keep class com.nayanui.engine.** { *; }