murow 0.0.60 → 0.0.71

package/dist/types/game/loop/loop.d.ts

@@ -0,0 +1,175 @@
+import { DriverType, EventSystem, FixedTicker } from "../../core";
+import { InputManager } from "../../core/input";
+/**
+ * GameLoop class that manages the main game loop with tick events and optional rendering.
+ * It supports both client and server types, emitting appropriate events for both.
+ */
+export declare class GameLoop<T extends GameLoopType = DriverType> {
+    options: GameLoopOptions<T>;
+    private _driver?;
+    private _input;
+    private readonly _isClient;
+    private readonly _isManual;
+    /**
+     * FixedTicker instance that handles tick timing and updates.
+     */
+    ticker: FixedTicker;
+    /**
+     * Event emitter system for the game loop, emitting various lifecycle events.
+     */
+    events: EventSystem<BaseEvents> & T extends ClientLike ? EventSystem<ClientEvents> : EventSystem<ServerEvents>;
+    /**
+     * Current frames per second (FPS) measurement.
+     */
+    fps: number;
+    /**
+     * Current status of the game loop: 'running', 'paused', or 'stopped'.
+     */
+    status: "running" | "paused" | "stopped";
+    private _tickData;
+    private _skipData;
+    private _renderData;
+    constructor(options: GameLoopOptions<T>);
+    step(deltaTime: number): void;
+    /**
+     * Pauses the game ticker and emits a 'toggle-pause' event.
+     */
+    pause(): void;
+    /**
+     * Resumes the game ticker and emits a 'toggle-pause' event.
+     */
+    resume(): void;
+    /**
+     * Starts the game ticker and emits a 'start' event.
+     */
+    start(): void;
+    /**
+     * Stops the game ticker and emits a 'stop' event.
+     */
+    stop(): void;
+}
+interface GameLoopOptions<T extends GameLoopType> {
+    tickRate: number;
+    type: T;
+    onTick?: (dt: number, tick: number, input: ReturnType<InputManager["snapshot"]>) => void;
+    onRender?: (dt: number, alpha: number, input: ReturnType<InputManager["peek"]>) => void;
+}
+type BaseEvents = [
+    [
+        "start",
+        {
+            /**
+             * Timestamp when the loop was started.
+             */
+            startedAt: number;
+        }
+    ],
+    [
+        "pre-tick",
+        {
+            /**
+             * Current tick number.
+             */
+            tick: number;
+            /**
+             * Delta time since the last tick.
+             */
+            deltaTime: number;
+            /**
+             * Input snapshot at the start of the tick.
+             *
+             * **Only available in client loops.**
+             */
+            input: ReturnType<InputManager["snapshot"]>;
+        }
+    ],
+    [
+        "tick",
+        {
+            /**
+             * Current tick number.
+             */
+            tick: number;
+            /**
+             * Delta time since the last tick.
+             */
+            deltaTime: number;
+            /**
+             * Input snapshot at the start of the tick.
+             *
+             * **Only available in client loops.**
+             */
+            input: ReturnType<InputManager["snapshot"]>;
+        }
+    ],
+    [
+        "post-tick",
+        {
+            /**
+             * Current tick number.
+             */
+            tick: number;
+            /**
+             * Delta time since the last tick.
+             */
+            deltaTime: number;
+            /**
+             * Input snapshot at the start of the tick.
+             *
+             * **Only available in client loops.**
+             */
+            input: ReturnType<InputManager["snapshot"]>;
+        }
+    ],
+    [
+        "skip",
+        {
+            /**
+             * Number of ticks that were skipped.
+             */
+            ticks: number;
+        }
+    ],
+    [
+        "stop",
+        {
+            /**
+             * Timestamp when the loop was stopped.
+             */
+            stoppedAt: number;
+        }
+    ],
+    [
+        "toggle-pause",
+        {
+            /**
+             * Current paused state of the loop.
+             */
+            paused: boolean;
+            /**
+             * Timestamp when the pause state was last toggled.
+             */
+            lastToggledAt: number;
+            /**
+             * Tick number when the pause state was last toggled.
+             */
+            lastToggleTick: number;
+        }
+    ]
+];
+type ClientEvents = [
+    ...BaseEvents,
+    [
+        "render",
+        {
+            deltaTime: number;
+            alpha: number;
+            input: ReturnType<InputManager["peek"]>;
+        }
+    ]
+];
+type ServerEvents = BaseEvents;
+type Manual = "manual-client" | "manual-server";
+type ClientLike = "client" | "manual-client";
+export type GameLoopType = DriverType | Manual;
+export {};

package/dist/{index.d.ts → types/index.d.ts}

@@ -18,3 +18,5 @@ export * from "./core";
 export * from "./protocol";
 export * from "./net";
 export * from "./ecs";
+export * from "./game";
+export * from "./renderer";

package/dist/{net → types/net}/index.d.ts

@@ -14,8 +14,8 @@
  *
  * @example
  * ```typescript
- * import { ServerNetwork, ClientNetwork } from '@mococa/net';
- * import { BunWebSocketServerTransport } from '@mococa/net/transports/bun-websocket';
+ * import { ServerNetwork, ClientNetwork } from 'murow/net';
+ * import { BunWebSocketServerTransport } from 'murow/net/transports/bun-websocket';
  * import { IntentRegistry, SnapshotRegistry } from '@mococa/protocol';
  *
  * // Server setup

package/dist/{net → types/net}/server.d.ts

@@ -30,8 +30,9 @@ export interface ServerNetworkConfig<TPeer extends TransportAdapter, TSnapshots>
  *
  * @remarks
  * **Client-Side Prediction Support:**
- * - Automatically tracks the last processed client tick for each peer
+ * - Tracks the last VALIDATED client tick for each peer (only intents passing validation update this)
  * - All intents include a 'tick' field (added by defineIntent())
+ * - Use validators in `onIntent()` to reject stale/invalid intents - rejected intents don't update the confirmed tick
  * - Use `getConfirmedClientTick(peerId)` to get the confirmed tick for snapshots
  * - Use `onAnyIntent()` to track which peers need snapshot responses
  *
@@ -56,14 +57,20 @@ export interface ServerNetworkConfig<TPeer extends TransportAdapter, TSnapshots>
  *   pendingResponses.add(peerId);
  * });
  *
- * // Type-safe intent handlers
- * server.onIntent<MoveIntent>(IntentKind.Move, (peerId, intent) => {
- *   intent.tick // ✅ Automatically included in all intents
- *   intent.dx // ✅ Correctly typed
+ * // Type-safe intent handlers with validation (prevents stale intents from updating confirmed tick)
+ * // The validator can use getConfirmedClientTick to reject out-of-order intents
+ * server.onIntent(Intents.Move, (peerId, intent) => {
+ *   // Process the intent
+ *   applyMovement(peerId, intent);
+ * }, (peerId, intent) => {
+ *   // Validator: reject out-of-order intents using the network layer's tracking
+ *   const lastTick = server.getConfirmedClientTick(peerId, intent.kind);
+ *   if (intent.tick <= lastTick) return false; // Rejected - confirmed tick NOT updated
+ *   return true; // Accepted - confirmed tick WILL be updated
  * });
  *
- * // Send snapshot with confirmed client tick (for client-side prediction)
- * const confirmedTick = server.getConfirmedClientTick(peerId);
+ * // Send snapshot with confirmed client tick for the relevant intent type (for client-side prediction)
+ * const confirmedTick = server.getConfirmedClientTick(peerId, Intents.Move.kind);
  * server.sendSnapshotToPeer(peerId, 'players', {
  *   tick: confirmedTick, // Client can reconcile based on this
  *   updates: { players: [...] }
@@ -80,7 +87,7 @@ export declare class ServerNetwork<TPeer extends TransportAdapter = TransportAda
     private peers;
     /** Per-peer snapshot registries - this is the key feature! */
     private peerSnapshotRegistries;
-    /** Track last processed client tick per peer (for client-side prediction) */
+    /** Track last processed client tick per peer per intent kind (for client-side prediction) */
     private lastProcessedClientTick;
     /** Track last sent snapshot hashes per peer per type (for delta detection) */
     private lastSnapshotHashes;
@@ -106,8 +113,17 @@ export declare class ServerNetwork<TPeer extends TransportAdapter = TransportAda
      * Register a handler for a specific intent kind (type-safe)
      * Supports multiple handlers per intent type
      * @template T The intent type for this handler
-     * @param validator Optional validation function - if it returns false, intent is rejected
+     * @param intent The intent definition
+     * @param handler Callback invoked for valid intents
+     * @param validator Optional validation function - if it returns false, intent is rejected and lastProcessedClientTick is NOT updated
      * @returns Unsubscribe function to remove this handler
+     *
+     * @remarks
+     * **Important:** The validator controls tick confirmation for client-side prediction.
+     * - If validator returns `true`: intent is processed AND lastProcessedClientTick is updated
+     * - If validator returns `false`: intent is rejected AND lastProcessedClientTick is NOT updated
+     *
+     * This ensures only valid, non-stale intents update the confirmed client tick used for reconciliation.
      */
     onIntent<T extends Intent>(intent: DefinedIntent<T['kind'], T>, handler: (peerId: string, intent: T) => void, validator?: (peerId: string, intent: T) => boolean): () => void;
     /**
@@ -305,29 +321,33 @@ export declare class ServerNetwork<TPeer extends TransportAdapter = TransportAda
      */
     isPeerBackpressured(peerId: string): boolean;
     /**
-     * Get the last confirmed client tick for a peer.
+     * Get the last confirmed (validated) client tick for a peer and intent kind.
      * Used for client-side prediction reconciliation.
      *
      * @param peerId The peer ID to query
-     * @returns The last processed client tick number, or 0 if peer not found
+     * @param intentKind The intent kind to query (different intent types have independent tick sequences)
+     * @returns The last validated client tick number for this intent kind, or 0 if not found
      *
      * @remarks
-     * This is automatically tracked when intents arrive, as all intents
-     * include a 'tick' field (added by defineIntent).
+     * This is automatically tracked when intents pass validation.
+     * Only intents that pass the validator (if provided to onIntent) will update this value.
+     * Each intent kind has its own tick sequence, allowing different types of intents
+     * (e.g., Move, Shoot, Chat) to have independent tick tracking.
      */
-    getConfirmedClientTick(peerId: string): number;
+    getConfirmedClientTick(peerId: string, intentKind: number): number;
     /**
-     * Set the confirmed client tick for a peer.
-     * Rarely needed as this is automatically tracked by handleIntent.
+     * Set the confirmed client tick for a peer and intent kind.
+     * Rarely needed as this is automatically tracked when intents pass validation.
      *
      * @param peerId The peer ID
+     * @param intentKind The intent kind
      * @param tick The client tick number to set
      *
      * @remarks
-     * All intents automatically include a 'tick' field via defineIntent(),
-     * so this is tracked automatically when intents are received.
+     * This is automatically updated when intents pass validation in onIntent handlers.
+     * Manual use of this method is rarely needed.
      */
-    setConfirmedClientTick(peerId: string, tick: number): void;
+    setConfirmedClientTick(peerId: string, intentKind: number, tick: number): void;
     /**
      * Close the server and all connections
      */

package/dist/{protocol → types/protocol}/intent/define-intent.d.ts

@@ -29,6 +29,21 @@ export type InferIntentType<K extends number, S extends Record<string, any>> = {
         read(dv: DataView, o: number): infer R;
     } ? R : never;
 };
+/**
+ * Helper type to extract just the data fields from a DefinedIntent (excluding kind and tick).
+ * This is useful for APIs that work with intent data without the metadata fields.
+ *
+ * @example
+ * ```ts
+ * const MoveIntent = defineIntent({
+ *   kind: 1,
+ *   schema: { vx: BinaryCodec.f32, vy: BinaryCodec.f32 }
+ * });
+ *
+ * type MoveData = IntentDataOnly<typeof MoveIntent>; // { vx: number, vy: number }
+ * ```
+ */
+export type IntentDataOnly<T> = T extends DefinedIntent<infer _K, infer U extends Intent> ? Omit<U, 'kind' | 'tick'> : never;
 /**
  * Result of defineIntent - provides both the type and codec.
  * @template K The intent kind literal

package/dist/{protocol → types/protocol}/intent/index.d.ts

@@ -90,4 +90,4 @@
 export type { Intent } from "./intent";
 export { IntentRegistry } from "./intent-registry";
 export { defineIntent } from "./define-intent";
-export type { DefinedIntent, InferIntentType } from "./define-intent";
+export type { DefinedIntent, InferIntentType, IntentDataOnly } from "./define-intent";

package/dist/types/renderer/base-2d-renderer.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Abstract base for 2D renderers. Defines the sprite-based rendering API.
+ */
+import { BaseRenderer } from "./base-renderer";
+import type { Camera2DState, Renderer2DOptions, SpriteHandle, SpriteOptions, SpritesheetHandle, SpritesheetSource } from "./types";
+export declare abstract class Base2DRenderer extends BaseRenderer<Renderer2DOptions> {
+    readonly maxSprites: number;
+    abstract readonly camera: Camera2DState;
+    constructor(canvas: HTMLCanvasElement, options: Renderer2DOptions);
+    abstract loadSpritesheet(source: SpritesheetSource): Promise<SpritesheetHandle>;
+    abstract addSprite(options: SpriteOptions): SpriteHandle;
+    abstract removeSprite(sprite: SpriteHandle): void;
+}

package/dist/types/renderer/base-3d-renderer.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Abstract base for 3D renderers. Defines the model/instance-based rendering API.
+ */
+import { BaseRenderer } from "./base-renderer";
+import type { Camera3DState, Renderer3DOptions } from "./types";
+export declare abstract class Base3DRenderer extends BaseRenderer<Renderer3DOptions> {
+    readonly maxModels: number;
+    abstract readonly camera: Camera3DState;
+    constructor(canvas: HTMLCanvasElement, options: Renderer3DOptions);
+}

package/dist/types/renderer/base-renderer.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Abstract base for all renderers. Provides lifecycle and canvas management.
+ */
+import type { ClearColor, RendererOptions } from "./types";
+export declare abstract class BaseRenderer<TOptions extends RendererOptions = RendererOptions> {
+    readonly canvas: HTMLCanvasElement;
+    protected readonly options: TOptions;
+    protected _clearColor: ClearColor;
+    protected _width: number;
+    protected _height: number;
+    protected _initialized: boolean;
+    constructor(canvas: HTMLCanvasElement, options: TOptions);
+    get clearColor(): ClearColor;
+    set clearColor(value: ClearColor);
+    get width(): number;
+    get height(): number;
+    get initialized(): boolean;
+    abstract init(): Promise<void>;
+    abstract render(alpha: number): void;
+    abstract destroy(): void;
+}

package/dist/types/renderer/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./types";
+export * from "./base-renderer";
+export * from "./base-2d-renderer";
+export * from "./base-3d-renderer";

package/dist/types/renderer/types.d.ts

@@ -0,0 +1,79 @@
+import type { Ray3D } from '../core/ray/ray-3d';
+export type ClearColor = [r: number, g: number, b: number, a: number];
+export interface RendererOptions {
+    clearColor?: ClearColor;
+    /** Automatically resize the canvas and reconfigure the GPU context on window resize. */
+    autoResize?: boolean;
+}
+export interface Renderer2DOptions extends RendererOptions {
+    maxSprites: number;
+}
+export interface Renderer3DOptions extends RendererOptions {
+    maxModels: number;
+    enableLighting?: boolean;
+}
+export interface Camera2DState {
+    x: number;
+    y: number;
+    zoom: number;
+    rotation: number;
+    setPosition(x: number, y: number): void;
+    move(x: number, y: number): void;
+    screenToWorld(screenX: number, screenY: number): [number, number];
+}
+export interface Camera3DState {
+    position: [x: number, y: number, z: number];
+    target: [x: number, y: number, z: number];
+    up: [x: number, y: number, z: number];
+    fov: number;
+    near: number;
+    far: number;
+    aspect: number;
+    movement: 'local' | 'grounded' | 'global';
+    setPosition(x: number, y: number, z: number): void;
+    move(right: number, up: number, forward: number): void;
+    screenToRay(screenX: number, screenY: number): Ray3D;
+}
+export interface SpritesheetSource {
+    image: string;
+    frameWidth?: number;
+    frameHeight?: number;
+    data?: string;
+}
+export interface SpriteOptions {
+    sheet: SpritesheetHandle;
+    sprite?: number;
+    x?: number;
+    y?: number;
+    layer?: number;
+    scaleX?: number;
+    scaleY?: number;
+    rotation?: number;
+    opacity?: number;
+    flipX?: boolean;
+    flipY?: boolean;
+    tint?: [r: number, g: number, b: number, a: number];
+}
+export interface SpritesheetHandle {
+    readonly id: number;
+    readonly frameCount: number;
+    getUV(spriteIndex: number): SpriteUV;
+}
+export interface SpriteUV {
+    minX: number;
+    minY: number;
+    maxX: number;
+    maxY: number;
+}
+export interface SpriteHandle {
+    readonly slot: number;
+    x: number;
+    y: number;
+    rotation: number;
+    scaleX: number;
+    scaleY: number;
+    opacity: number;
+    layer: number;
+    flipX: boolean;
+    flipY: boolean;
+}