@yali-engine/core 0.0.0-stage → 0.4.0

package/dist/abi.gen.d.ts

@@ -0,0 +1,76 @@
+/** The ABI version these declarations describe. */
+export declare const ABI_VERSION = 20;
+/** The core module's exports. Optional members exist only in bench builds or core variants. */
+export interface CoreExports {
+    readonly memory: WebAssembly.Memory;
+    yali_abi_version(): number;
+    yali_alloc(size: number): number;
+    yali_dealloc(ptr: number, size: number): void;
+    yali_world_new(): number;
+    yali_features(): number;
+    yali_features_install(w: number): number;
+    yali_anim_add_skeleton?(w: number, parents: number, n: number, rest: number): number;
+    yali_anim_add_clip?(w: number, skeleton: number, data: number, words: number): number;
+    yali_anim_add_graph?(w: number, skeleton: number, data: number, words: number): number;
+    yali_anim_add_mask?(w: number, skeleton: number, weights: number, n: number): number;
+    yali_anim_add_skin?(w: number, skeleton: number, n: number, joints: number, ibm: number, rest_error: number): number;
+    yali_anim_joint_model?(w: number, e: number, joint: number, out: number): number;
+    yali_anim_update?(w: number, dt: number): number;
+    yali_anim_palette?(w: number, out: number): number;
+    yali_anim_clip_duration?(w: number, clip: number): number;
+    yali_physics_settings?(w: number, fixed_dt: number, gx: number, gy: number, gz: number, substeps: number): number;
+    yali_physics_debug?(w: number, flags: number, max_segments: number, out: number): number;
+    yali_physics_ray_casts?(w: number, input: number, n: number, output: number): number;
+    yali_physics_add_hull?(w: number, points: number, n: number): number;
+    yali_physics_add_mesh?(w: number, verts: number, nv: number, indices: number, ni: number, double_sided: number): number;
+    yali_physics_add_heightfield?(w: number, rows: number, cols: number, heights: number, sx: number, sy: number, sz: number): number;
+    yali_physics_snapshot?(w: number): number;
+    yali_physics_restore?(w: number, id: number): number;
+    yali_physics_snapshot_free?(w: number, id: number): number;
+    yali_physics_stats?(w: number, out: number): number;
+    yali_cloth_step?(w: number, params: number, cloths: number, ncloths: number, st: number, st_len: number, particles: number, vertices: number, colliders: number, ncolliders: number, torn: number, torn_len: number): number;
+    yali_cloth_write?(w: number, params: number, cloths: number, ncloths: number, st: number, st_len: number, particles: number, vertices: number, out: number, out_len: number): number;
+    yali_world_free(w: number): void;
+    yali_error_text(w: number): number;
+    yali_error_text_len(w: number): number;
+    yali_register_component(w: number, ptr: number, len: number): number;
+    yali_field_id(w: number, c: number, ptr: number, len: number): number;
+    yali_spawn(w: number, comps: number, n: number, count: number, out: number): number;
+    yali_despawn(w: number, e: number): number;
+    yali_insert(w: number, e: number, c: number, data: number, len: number): number;
+    yali_remove(w: number, e: number, c: number): number;
+    yali_set_parent(w: number, child: number, parent: number): number;
+    yali_is_alive(w: number, e: number): number;
+    yali_entity_count(w: number): number;
+    yali_end_frame(w: number): number;
+    yali_schedule_add_external(w: number, stage: number, ext: number, desc: number, len: number): number;
+    yali_schedule_remove(w: number, name: number, len: number): number;
+    yali_schedule_plan(w: number, stage: number, out: number, cap: number): number;
+    yali_schedule_run_batch(w: number, stage: number, batch: number): number;
+    yali_schedule_finish_stage(w: number, stage: number): number;
+    yali_transforms_install(w: number): number;
+    yali_frame_begin(w: number, alpha: number): number;
+    yali_query_new(w: number, desc: number, desc_len: number, cols: number, ncols: number): number;
+    yali_query_run(w: number, q: number): number;
+    yali_query_header(w: number, q: number): number;
+    yali_extract_transforms(w: number, q: number, cx: number, cy: number, cz: number, out: number, cap: number): number;
+    yali_extract_instances(w: number, q: number, ax: number, ay: number, az: number, out: number, cap: number, counts: number, meshes: number, changed: number, dirty: number, dirty_cap: number): number;
+    yali_bench_cull_selftest?(n: number): number;
+    yali_extract_culled(w: number, q: number, cx: number, cy: number, cz: number, cull: number, mesh_info: number, meshes: number, out: number, cap: number, slot_counts: number): number;
+    yali_query_write(w: number, q: number, col: number, src: number, kind: number, rows: number, lanes: number): number;
+    yali_jobs_new(w: number, workers: number): number;
+    yali_jobs_worker(pool: number): void;
+    yali_jobs_shutdown(pool: number): void;
+    yali_jobs_help(pool: number): number;
+    yali_jobs_park(pool: number, seen: number): void;
+    yali_jobs_wake_all(pool: number): void;
+    yali_jobs_wake(pool: number): number;
+    yali_jobs_running(pool: number): number;
+    yali_bench_integrate_par?(w: number, q: number, dt: number): number;
+    yali_bench_integrate?(w: number, q: number, dt: number): number;
+    yali_bench_integrate_simd?(w: number, q: number, dt: number): number;
+    yali_bench_math_selftest?(n: number): number;
+    yali_bench_raw?(pos: number, vel: number, n: number, dt: number): void;
+}
+/** Every required export, for the load-time check. */
+export declare const REQUIRED_EXPORTS: readonly ["yali_abi_version", "yali_alloc", "yali_dealloc", "yali_world_new", "yali_features", "yali_features_install", "yali_world_free", "yali_error_text", "yali_error_text_len", "yali_register_component", "yali_field_id", "yali_spawn", "yali_despawn", "yali_insert", "yali_remove", "yali_set_parent", "yali_is_alive", "yali_entity_count", "yali_end_frame", "yali_schedule_add_external", "yali_schedule_remove", "yali_schedule_plan", "yali_schedule_run_batch", "yali_schedule_finish_stage", "yali_transforms_install", "yali_frame_begin", "yali_query_new", "yali_query_run", "yali_query_header", "yali_extract_transforms", "yali_extract_instances", "yali_extract_culled", "yali_query_write", "yali_jobs_new", "yali_jobs_worker", "yali_jobs_shutdown", "yali_jobs_help", "yali_jobs_park", "yali_jobs_wake_all", "yali_jobs_wake", "yali_jobs_running"];

package/dist/abi.gen.js

@@ -0,0 +1,49 @@
+// GENERATED by tools/abi-gen.mjs from crates/yali-core-wasm/src/lib.rs. Do not edit.
+// Regenerate with `node tools/abi-gen.mjs`; CI runs it with --check.
+/** The ABI version these declarations describe. */
+export const ABI_VERSION = 20;
+/** Every required export, for the load-time check. */
+export const REQUIRED_EXPORTS = [
+    'yali_abi_version',
+    'yali_alloc',
+    'yali_dealloc',
+    'yali_world_new',
+    'yali_features',
+    'yali_features_install',
+    'yali_world_free',
+    'yali_error_text',
+    'yali_error_text_len',
+    'yali_register_component',
+    'yali_field_id',
+    'yali_spawn',
+    'yali_despawn',
+    'yali_insert',
+    'yali_remove',
+    'yali_set_parent',
+    'yali_is_alive',
+    'yali_entity_count',
+    'yali_end_frame',
+    'yali_schedule_add_external',
+    'yali_schedule_remove',
+    'yali_schedule_plan',
+    'yali_schedule_run_batch',
+    'yali_schedule_finish_stage',
+    'yali_transforms_install',
+    'yali_frame_begin',
+    'yali_query_new',
+    'yali_query_run',
+    'yali_query_header',
+    'yali_extract_transforms',
+    'yali_extract_instances',
+    'yali_extract_culled',
+    'yali_query_write',
+    'yali_jobs_new',
+    'yali_jobs_worker',
+    'yali_jobs_shutdown',
+    'yali_jobs_help',
+    'yali_jobs_park',
+    'yali_jobs_wake_all',
+    'yali_jobs_wake',
+    'yali_jobs_running',
+];
+//# sourceMappingURL=abi.gen.js.map

package/dist/abi.gen.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"abi.gen.js","sourceRoot":"","sources":["../src/abi.gen.ts"],"names":[],"mappings":"AAAA,qFAAqF;AACrF,qEAAqE;AAErE,mDAAmD;AACnD,MAAM,CAAC,MAAM,WAAW,GAAG,EAAE,CAAC;AA2E9B,sDAAsD;AACtD,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,kBAAkB;IAClB,YAAY;IACZ,cAAc;IACd,gBAAgB;IAChB,eAAe;IACf,uBAAuB;IACvB,iBAAiB;IACjB,iBAAiB;IACjB,qBAAqB;IACrB,yBAAyB;IACzB,eAAe;IACf,YAAY;IACZ,cAAc;IACd,aAAa;IACb,aAAa;IACb,iBAAiB;IACjB,eAAe;IACf,mBAAmB;IACnB,gBAAgB;IAChB,4BAA4B;IAC5B,sBAAsB;IACtB,oBAAoB;IACpB,yBAAyB;IACzB,4BAA4B;IAC5B,yBAAyB;IACzB,kBAAkB;IAClB,gBAAgB;IAChB,gBAAgB;IAChB,mBAAmB;IACnB,yBAAyB;IACzB,wBAAwB;IACxB,qBAAqB;IACrB,kBAAkB;IAClB,eAAe;IACf,kBAAkB;IAClB,oBAAoB;IACpB,gBAAgB;IAChB,gBAAgB;IAChB,oBAAoB;IACpB,gBAAgB;IAChB,mBAAmB;CACX,CAAC"}

package/dist/app/app.d.ts

@@ -0,0 +1,194 @@
+import type { Core } from '../core.ts';
+import type { ThreadsOptions } from '../threads.ts';
+import { WorkerPool } from '../worker-pool.ts';
+import type { Component, World } from '../world.ts';
+import { type DeviceLossInfo, type LeakReport, Lifecycle, type LifecycleEvent, type PauseReason } from './lifecycle.ts';
+import { type YaliPlugin } from './plugins.ts';
+import { Profiler } from './profiler.ts';
+import { type GovernorOptions, QualityGovernor, type QualityKnob } from './quality.ts';
+import { Rng } from './rng.ts';
+import { type ToolDef, ToolRegistry } from './tools.ts';
+import { Time } from './time.ts';
+/** The fixed frame stages, in order (DESIGN.md §4; the same names as the Rust scheduler). */
+export declare const STAGES: readonly ["Input", "PreUpdate", "FixedUpdate", "Update", "PostUpdate", "Extract", "RenderPrep", "Submit", "NetworkSend", "EndFrame"];
+/** One stage. */
+export type StageName = (typeof STAGES)[number];
+/** What a frame callback sees. One object, reused every frame (no allocation). */
+export interface FrameInfo {
+    readonly time: Time;
+    /** Frames run since start. */
+    readonly frame: number;
+    /** Fixed steps this frame (FixedUpdate runs this many times). */
+    readonly fixedSteps: number;
+}
+/**
+ * A TS system. With a core (`App.create({ core })`) it is an external system of the Rust
+ * schedule (ADR-0031): ordered with Rust systems by `before`/`after`/`sets`, and run alone
+ * in its batch unless it declares `access` (ADR-0044). Without a core, systems run in
+ * registration order and ordering is refused.
+ */
+export interface AppSystem {
+    /** Unique, conventionally `plugin.what`. */
+    readonly name: string;
+    readonly stage: StageName;
+    /** Runs before these systems or sets (same stage). Needs a core. */
+    readonly before?: readonly string[];
+    /** Runs after these systems or sets (same stage). Needs a core. */
+    readonly after?: readonly string[];
+    /** Named sets other systems can order against. Needs a core. */
+    readonly sets?: readonly string[];
+    /**
+     * The components this system reads and writes (ADR-0044). Declared, it shares a batch
+     * with Rust systems it does not conflict with, so those run in parallel instead of being
+     * split around it; it runs after them, on the main thread. Leave it out (exclusive) if
+     * the system touches resources, events, or components it cannot list.
+     */
+    readonly access?: {
+        readonly read?: readonly Component[];
+        readonly write?: readonly Component[];
+    };
+    run(frame: FrameInfo): void;
+}
+/** Rebuilds a plugin's GPU state after device loss. Resolves to counts of what it rebuilt. */
+export type RecoverFn = () => Promise<Readonly<Record<string, number>>>;
+/** Drives frames. `requestAnimationFrame` in a browser; a manual source in headless runs. */
+export interface FrameSource {
+    request(cb: (now: number) => void): number;
+    cancel(id: number): void;
+}
+/** App options. */
+export interface AppOptions {
+    readonly plugins: readonly YaliPlugin[];
+    /** The loaded core. The App then owns `app.world` and runs one Rust schedule for every
+     *  system, TS and Rust (ADR-0031). Without it the App runs TS systems on its own. */
+    readonly core?: Core;
+    /** Fixed simulation rate (default 60). */
+    readonly fixedHz?: number;
+    /** Most fixed steps per frame before time is dropped (default 4). */
+    readonly maxSubsteps?: number;
+    /**
+     * Let the governor lower the fixed steps per frame (`sim.substeps`: max, then 1) when frames
+     * are CPU-bound over budget (default true). A slow device then runs the simulation
+     * slower than real time instead of halving its frame rate: past 16.6 ms a frame needs two
+     * steps, which doubles the simulation's cost (measured on a Galaxy F04, ADR-0046).
+     */
+    readonly adaptiveSubsteps?: boolean;
+    /** Frame driver (default: requestAnimationFrame). */
+    readonly frames?: FrameSource;
+    /** Pause automatically when the page is hidden or frozen (default true in a browser). */
+    readonly pauseWhenHidden?: boolean;
+    /** Record frames into `app.profiler` (default true; ADR-0025). */
+    readonly profile?: boolean;
+    /** The profiler's clock in ms (default `performance.now`; tests and headless runs inject one). */
+    readonly clock?: () => number;
+    /** Seed of `app.rng` (default: random). Pass one for runs that must repeat exactly. */
+    readonly seed?: number;
+    /** The frame-budget governor (DESIGN.md §4). It reads the profiler, so it needs `profile`. */
+    readonly governor?: GovernorOptions;
+    /**
+     * The app's worker threads (ADR-0076): `app.pool`, one pool for the world's Rust jobs and
+     * the TS worker systems listed here (ADR-0037). Needs `core`. Take the count from
+     * `loadCore` (threads where the page can run them); `@yali-engine/vite`'s `virtual:yali/threads`
+     * builds the whole object. Without it the app has no pool.
+     */
+    readonly threads?: ThreadsOptions;
+}
+/**
+ * The registration surface plugins get (DESIGN.md §2). Everything registered here is
+ * recorded against the plugin and unwound automatically when the app is disposed.
+ */
+export interface AppBuilder {
+    readonly app: App;
+    /** Adds a TS system to a stage. Names are unique. */
+    system(system: AppSystem): void;
+    /** Listens for a lifecycle event while the plugin is alive. */
+    on<T extends LifecycleEvent['type']>(type: T, fn: (e: Extract<LifecycleEvent, {
+        type: T;
+    }>) => void): void;
+    /** Registers how to rebuild this plugin's GPU state after device loss. */
+    recover(fn: RecoverFn): void;
+    /** Reports live resources for the dispose leak check (GPU buffers, workers, handles…). */
+    leaks(fn: () => Partial<LeakReport>): void;
+    /** Runs on dispose, in reverse registration order. */
+    onDispose(fn: () => void | Promise<void>): void;
+    /** Shares a value with other plugins under a key (a TS-side resource). */
+    provide<T>(key: string, value: T): void;
+    /** Adds a profiler counter while the plugin is alive (`read` must be cheap, no allocation). */
+    counter(name: string, read: () => number, unit?: string): void;
+    /** Adds a quality knob for the governor while the plugin is alive (restored on dispose). */
+    quality(knob: QualityKnob): void;
+    /** Adds a tool agents can call on the running app (DESIGN.md §19), while the plugin is alive. */
+    tool(def: ToolDef): void;
+}
+/**
+ * One Yali application: a lifecycle (DESIGN.md §3), plugins built in dependency order, and
+ * a frame loop with a fixed-timestep simulation (§4). No global state: several apps can
+ * share a page.
+ *
+ * @example
+ * const app = App.create({ plugins: [renderPlugin({ canvas })] });
+ * await app.init();
+ * app.start();
+ */
+export declare class App {
+    #private;
+    readonly lifecycle: Lifecycle;
+    readonly time: Time;
+    /** Per-frame CPU, GPU and counter timings (ADR-0025). */
+    readonly profiler: Profiler;
+    /** The frame-budget governor and its quality knobs (DESIGN.md §4). */
+    readonly quality: QualityGovernor;
+    /** Tools agents call on the running app (`@yali-engine/mcp`); `app.*` tools are built in. */
+    readonly tools: ToolRegistry;
+    /** The app's seeded random numbers: gameplay draws from this, so a seed replays a run. */
+    readonly rng: Rng;
+    readonly options: AppOptions;
+    /** Errors thrown by systems this session (name → count), so a broken system is visible. */
+    readonly systemErrors: Map<string, number>;
+    private constructor();
+    /**
+     * The app's worker pool (ADR-0076; needs `App.create({ threads })`): `pool.run(system,
+     * query, args)` runs a TS worker system over a query's chunks in parallel, and the world's
+     * Rust systems split across the same workers. With 0 workers it all runs on this thread.
+     */
+    get pool(): WorkerPool;
+    /** The app's world (needs `App.create({ core })`). Plugins register components on it. */
+    get world(): World;
+    /** Creates and configures an app (state Configured): plugins are ordered and validated. */
+    static create(options: AppOptions): App;
+    /** A value a plugin provided. Throws `MISSING_RESOURCE` with the plugin to add. */
+    resource<T>(key: string): T;
+    /** Whether a plugin provided `key`. */
+    hasResource(key: string): boolean;
+    /**
+     * Initializing: builds every plugin in dependency order (each emits `init:plugin`), then
+     * moves to Running (not yet ticking; call `start`). A plugin that throws moves the app
+     * to Failed, and the error is rethrown.
+     */
+    init(): Promise<void>;
+    /** Starts driving frames from the frame source. */
+    start(): void;
+    /**
+     * Runs one frame of `seconds` synchronously: every stage in order, FixedUpdate once per
+     * fixed step. Headless tests drive the app with this. A system that throws is counted
+     * and logged; the frame continues.
+     */
+    step(seconds: number): void;
+    /** Pauses (DESIGN.md §3): frames keep arriving but no stage runs. */
+    pause(reason?: PauseReason): void;
+    /** Resumes. Accumulated time is reset, so a long pause causes no catch-up steps. */
+    resume(): void;
+    /**
+     * Reports GPU device loss (the render plugin calls this). Unless the app is disposing,
+     * it moves to Recovering and runs every plugin's recover function in build order. On
+     * success it returns to Running and emits `recovered`; on failure it moves to Failed.
+     * The simulation keeps its state; the game is not restarted.
+     */
+    deviceLost(info: DeviceLossInfo): Promise<void>;
+    /**
+     * Disposes: plugins in reverse build order (their registrations first, then their own
+     * `dispose`), then the leak check. `disposed.leaks` must be all zeros on a clean dispose;
+     * tests assert it.
+     */
+    dispose(): Promise<LeakReport>;
+}