@adatechnology/game-runtime 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anderson Fernandes
+
+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/README.md

@@ -1,3 +1,34 @@
-# Temporary Holding Version
+# @adatechnology/game-runtime
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The owner of the frame. A phased scheduler with a fixed simulation step, and one time budget shared by every deferred queue of the kit. Layer L1: no three.js, no DOM unless `startLoop` runs on a page.
+
+```ts
+import { createScheduler, startLoop } from '@adatechnology/game-runtime'
+
+const scheduler = createScheduler({ fixedDt: 1 / 60, maxFrameSeconds: 0.05 })
+scheduler.add((ctx) => stepWorld(ctx.dt), { phase: 'fixedSimulate' })
+scheduler.add((ctx) => drawWorld(ctx.alpha), { phase: 'present' })
+scheduler.add(() => renderer.render(scene, camera), { phase: 'render' })
+const stop = startLoop(scheduler)
+```
+
+## Phases
+
+`input` (real time) → `fixedSimulate` (0 to `maxSubsteps` steps of `fixedDt`, seeded work) → `lateSimulate` (scaled time, what `ModuleHost.onFrame` has always been) → `present` (state to the scene, queues of `present`) → `render` → `idle` (queues of `idle`).
+
+- Pause stops `fixedSimulate` and `lateSimulate`; `timeScale` scales the accumulator and the dt of `lateSimulate` and `present`.
+- The accumulator counts whole microseconds, so 60 frames of 1/60 give exactly 60 steps. A frame within `snapMs` (0.25) of a whole number of steps is snapped to it.
+- `frame(seconds, { exact: true })` uses the time as given (no clamp, no snap, no cap): for tests and hosts without a loop.
+- `advance(seconds, { dt })` steps the world synchronously with the budget unbounded and `ctx.scripted = true`: scenarios and tests.
+- What input does to the simulation goes through `scheduler.commands` and is consumed at the next fixed tick.
+
+## Budget
+
+`scheduler.budget.register(queue, { priority, phase, reserveMs, minEveryFrames })` takes a `DeferredQueue` (a contract of `@adatechnology/game-contracts`) and calls its `attach()`: from then on the owner stops draining on its own. Queues of one phase run by priority inside a shared time budget (4 ms by default); a unit that goes over becomes debt for the next frame; a queue with work never waits more than `minEveryFrames`; `reserveMs` keeps time for a queue the others must not starve. A queue that was never registered keeps its own draining.
+
+## Errors, bad times and teardown
+
+- A system or a queue that throws is reported (`onError`, default: logged once per id; a queue's id is `queue:<id>`) and the frame goes on; a queue that threw counts 0 units. If a frame fails outside any system the scheduler is left usable: the next frame runs.
+- A frame time that is NaN, infinite or negative counts as no time; a negative `timeScale` is 0 and a NaN one is 1; `advance` with a bad `dt` uses `fixedDt`.
+- `budget.register` throws for a queue that is already registered. After `scheduler.dispose()`, `frame` and `advance` throw, `add` does nothing and the systems that were waiting to join are dropped.
+- A host that runs the scheduler itself must call `frame` every frame: queues registered with the budget stop draining on their own.

package/dist/index.d.ts

@@ -0,0 +1,183 @@
+import { DeferredQueue, DeferredQueueOptions, FramePhase } from '@adatechnology/game-contracts';
+export { DEFERRED_PRIORITY, DeferredQueue, DeferredQueueOptions, FRAME_PHASES, FramePhase } from '@adatechnology/game-contracts';
+
+interface FrameContext {
+    /** Seconds this phase advances (see the phase table of the design). */
+    readonly dt: number;
+    /** Real seconds of this frame after the clamp and the snap, never scaled, not 0 when paused. */
+    readonly realDt: number;
+    /** The fixed step, seconds (1/60 by default). */
+    readonly fixedDt: number;
+    /** Accumulator / fixedDt after the fixed phase, in [0, 1). 0 inside and right after `advance`. */
+    readonly alpha: number;
+    /** Frames since start. */
+    readonly frame: number;
+    /** Fixed steps run since start: the clock of everything seeded. Inside `fixedSimulate`, the index of the step being run. */
+    readonly tick: number;
+    /** Index of the substep inside this frame (fixedSimulate only), else 0. */
+    readonly substep: number;
+    /** Simulated seconds since start (sum of the dt given to lateSimulate). */
+    readonly simTime: number;
+    readonly paused: boolean;
+    /** true inside `advance` (a scenario steps the world): systems that do not run in a scenario step read it and skip. */
+    readonly scripted: boolean;
+    /** false in a frame run with `simulate: false` (the display frame while a scenario steps the world), true otherwise. */
+    readonly simulated: boolean;
+}
+type SystemFn = (ctx: FrameContext) => void;
+interface SystemOptions {
+    readonly phase: FramePhase;
+    /** Lower first; ties keep the order of registration. Default 0. */
+    readonly order?: number;
+    /** For stats and errors. */
+    readonly id?: string;
+}
+interface SchedulerOptions {
+    /** Default 1/60. */
+    readonly fixedDt?: number;
+    /** Default 4. What is left after the last substep is dropped (`stats().droppedSeconds`). */
+    readonly maxSubsteps?: number;
+    /** Real seconds of one frame are clamped to this. Default 0.25. */
+    readonly maxFrameSeconds?: number;
+    /** A frame time within this many ms of a whole number of fixed steps is snapped to it. Default 0.25. 0 turns it off. */
+    readonly snapMs?: number;
+    /** Frame budget for the deferred queues, ms. Default 4. */
+    readonly budgetMs?: number;
+    /** Milliseconds clock; default `performance.now` (or `Date.now`). Tests inject a fake. */
+    readonly clock?: () => number;
+    /** A system that throws: default logs once per system id and keeps the frame going. */
+    readonly onError?: (error: unknown, system: {
+        id: string;
+        phase: FramePhase;
+    }) => void;
+}
+interface FrameRunOptions {
+    /** false skips the render phase (headless tests, `room.update`). Default true. */
+    readonly render?: boolean;
+    /** false skips input, fixedSimulate and lateSimulate (a scenario is stepping the world synchronously). Default true. */
+    readonly simulate?: boolean;
+    /**
+     * true: `realSeconds` is used as given. No clamp, no snap, no `maxSubsteps` cap (every whole fixed step runs, the remainder stays in the
+     * accumulator, nothing goes to `droppedSeconds`), one `input` with `dt = realSeconds` and one `lateSimulate` with `dt = realSeconds * scale`.
+     */
+    readonly exact?: boolean;
+}
+interface Command {
+    readonly kind: string;
+    readonly tick: number;
+    readonly payload?: unknown;
+}
+interface CommandBuffer {
+    /** From `input`: valid from the next fixed tick (or from `tick`, for a replay). */
+    push(kind: string, payload?: unknown, tick?: number): void;
+    /** From the first fixedSimulate system: the commands due at this tick or before, in push order. They leave the buffer. */
+    take(tick: number): readonly Command[];
+    /** Drops every pending command. */
+    clear(): void;
+}
+interface QueueStats {
+    readonly id: string;
+    readonly pending: number;
+    readonly ranUnits: number;
+    readonly spentMs: number;
+    readonly framesWaiting: number;
+    readonly maxFramesWaiting: number;
+    readonly forced: number;
+}
+interface BudgetStats {
+    readonly ms: number;
+    /** Milliseconds spent by the queues in the last frame. */
+    readonly spentMs: number;
+    /** Milliseconds the last frame went over; repaid by the next one (capped at one budget). */
+    readonly debtMs: number;
+    readonly queues: readonly QueueStats[];
+}
+interface FrameBudget {
+    /** Milliseconds per frame shared by every queue. Default 4. */
+    ms: number;
+    /** Calls `queue.attach?.()`; the returned function calls `queue.detach?.()` and takes it out. */
+    register(queue: DeferredQueue, options: DeferredQueueOptions): () => void;
+    /** Starts a frame: counter, reserves and debt. The scheduler calls it; `drain('present')` starts one by itself when none is open. */
+    beginFrame(): void;
+    /** Drains the queues of one phase; the scheduler calls it, a host without the scheduler may too. */
+    drain(phase: 'present' | 'idle'): void;
+    /** Every queue to empty, now (synchronous step, clear). */
+    flushAll(): void;
+    /** Unbounded: every drain runs every queue to empty (scenarios, goldens). */
+    unbounded: boolean;
+    stats(): BudgetStats;
+    /** Detaches every queue (each owner goes back to its internal draining). */
+    dispose(): void;
+}
+interface SchedulerStats {
+    readonly frame: number;
+    readonly tick: number;
+    readonly substepsLastFrame: number;
+    readonly droppedSeconds: number;
+    /** Milliseconds per phase in the last frame. */
+    readonly phaseMs: Readonly<Record<FramePhase, number>>;
+    readonly budget: BudgetStats;
+}
+interface Scheduler {
+    add(system: SystemFn, options: SystemOptions): () => void;
+    /** Runs one frame with `realSeconds` of wall time. */
+    frame(realSeconds: number, options?: FrameRunOptions): void;
+    /**
+     * Advances `seconds` of simulation synchronously, in steps of `dt` (default fixedDt), with no render, `ctx.scripted = true` and the budget
+     * unbounded (every queue drained each step). Resets the accumulator before and after (`alpha = 0`). For scenarios and tests.
+     */
+    advance(seconds: number, options?: {
+        readonly dt?: number;
+    }): void;
+    pause(): void;
+    resume(): void;
+    readonly paused: boolean;
+    /** 1 = real time, 0.25 = slow motion. Scales fixedSimulate's accumulator and lateSimulate/present dt. */
+    timeScale: number;
+    /** Forgets the accumulator and the snap residue (after the tab comes back, after a reset). */
+    resetClock(): void;
+    readonly budget: FrameBudget;
+    /** Commands the input phase leaves for the next fixed tick. */
+    readonly commands: CommandBuffer;
+    stats(): SchedulerStats;
+    dispose(): void;
+}
+interface LoopOptions {
+    /** Default `globalThis.requestAnimationFrame` / `cancelAnimationFrame`; a host without them passes its own (tests, workers). */
+    readonly requestFrame?: (callback: (nowMs: number) => void) => number;
+    readonly cancelFrame?: (handle: number) => void;
+    /** Timestamp the first frame is measured from; default `performance.now()`. */
+    readonly startMs?: number;
+    /** Called first in every frame with the unclamped real seconds (the room's metrics). */
+    readonly onFrame?: (realSeconds: number) => void;
+    /** true: this frame only presents and renders (a scenario is stepping the world). */
+    readonly skipSimulation?: () => boolean;
+    /**
+     * The least milliseconds between two frames that run (a frame cap): a display frame that comes sooner is skipped and its time goes to the next one. Asked on
+     * every display frame, so the cap may change while the loop runs; 0 or absent runs every display frame.
+     */
+    readonly minFrameMs?: () => number;
+}
+
+interface FrameBudgetOptions {
+    readonly ms?: number;
+    readonly clock?: () => number;
+    /** A queue that throws in `run`: default logs once per queue id. The frame goes on and the queue counts 0 units. */
+    readonly onError?: (error: unknown, queue: {
+        readonly id: string;
+        readonly phase: 'present' | 'idle';
+    }) => void;
+}
+declare function createFrameBudget(options?: FrameBudgetOptions): FrameBudget;
+
+/** `order` of the fixedSimulate system that takes the tick's commands: it runs before every other fixed system. */
+declare const COMMAND_SYSTEM_ORDER = -10000;
+/** `nextTick` answers which fixed tick runs next: that is the tick a command pushed from `input` becomes valid at. */
+declare function createCommandBuffer(nextTick: () => number): CommandBuffer;
+
+/** Drives `scheduler.frame` from the display's frames; listens to `visibilitychange` when there is a document. Returns the stop function. */
+declare function startLoop(scheduler: Scheduler, options?: LoopOptions): () => void;
+
+declare function createScheduler(options?: SchedulerOptions): Scheduler;
+
+export { type BudgetStats, COMMAND_SYSTEM_ORDER, type Command, type CommandBuffer, type FrameBudget, type FrameBudgetOptions, type FrameContext, type FrameRunOptions, type LoopOptions, type QueueStats, type Scheduler, type SchedulerOptions, type SchedulerStats, type SystemFn, type SystemOptions, createCommandBuffer, createFrameBudget, createScheduler, startLoop };