@rpgjs/client 5.0.0-alpha.9 → 5.0.0-beta.1

package/dist/RpgClientEngine.d.ts

@@ -1,10 +1,11 @@
-import { Context } from '@signe/di';
 import { AbstractWebsocket } from './services/AbstractSocket';
-import { EffectManager } from './Game/EffectManager';
+import { Direction } from '@rpgjs/common';
+import { RpgClientMap } from './Game/Map';
+import { AnimationManager } from './Game/AnimationManager';
 import { Observable } from 'rxjs';
 import * as PIXI from "pixi.js";
 export declare class RpgClientEngine<T = any> {
-    context: Context;
+    context: any;
     private guiService;
     private webSocket;
     private loadMapService;
@@ -18,33 +19,392 @@ export declare class RpgClientEngine<T = any> {
     height: import('canvasengine').WritableSignal<string>;
     spritesheets: Map<string, any>;
     sounds: Map<string, any>;
-    effects: any[];
+    componentAnimations: any[];
+    private spritesheetResolver?;
+    private soundResolver?;
     particleSettings: {
         emitters: any[];
     };
     renderer: PIXI.Renderer;
     tick: Observable<number>;
+    private canvasApp?;
+    private canvasElement?;
     playerIdSignal: import('canvasengine').WritableSignal<string | null>;
     spriteComponentsBehind: import('canvasengine').WritableArraySignal<any[]>;
     spriteComponentsInFront: import('canvasengine').WritableArraySignal<any[]>;
-    constructor(context: Context);
+    /** ID of the sprite that the camera should follow. null means follow the current player */
+    cameraFollowTargetId: import('canvasengine').WritableSignal<string | null>;
+    /** Trigger for map shake animation */
+    mapShakeTrigger: import('canvasengine').Trigger<any>;
+    controlsReady: import('canvasengine').WritableSignal<undefined>;
+    gamePause: import('canvasengine').WritableSignal<boolean>;
+    private predictionEnabled;
+    private prediction?;
+    private readonly SERVER_CORRECTION_THRESHOLD;
+    private inputFrameCounter;
+    private pendingPredictionFrames;
+    private lastClientPhysicsStepAt;
+    private frameOffset;
+    private rtt;
+    private pingInterval;
+    private readonly PING_INTERVAL_MS;
+    private lastInputTime;
+    private readonly MOVE_PATH_RESEND_INTERVAL_MS;
+    private readonly MAX_MOVE_TRAJECTORY_POINTS;
+    private lastMovePathSentAt;
+    private lastMovePathSentFrame;
+    private mapLoadCompleted$;
+    private playerIdReceived$;
+    private playersReceived$;
+    private eventsReceived$;
+    private onAfterLoadingSubscription?;
+    private sceneResetQueued;
+    private tickSubscriptions;
+    private resizeHandler?;
+    private notificationManager;
+    constructor(context: any);
+    /**
+     * Assigns a CanvasEngine KeyboardControls instance to the dependency injection context
+     *
+     * This method registers a KeyboardControls instance from CanvasEngine into the DI container,
+     * making it available for injection throughout the application. The particularity is that
+     * this method is automatically called when a sprite is displayed on the map, allowing the
+     * controls to be automatically associated with the active sprite.
+     *
+     * ## Design
+     *
+     * - The instance is stored in the DI context under the `KeyboardControls` token
+     * - It's automatically assigned when a sprite component mounts (in `character.ce`)
+     * - The controls instance comes from the CanvasEngine component's directives
+     * - Once registered, it can be retrieved using `inject(KeyboardControls)` from anywhere
+     *
+     * @param controlInstance - The CanvasEngine KeyboardControls instance to register
+     *
+     * @example
+     * ```ts
+     * // The method is automatically called when a sprite is displayed:
+     * // client.setKeyboardControls(element.directives.controls)
+     *
+     * // Later, retrieve and use the controls instance:
+     * import { Input, inject, KeyboardControls } from '@rpgjs/client'
+     *
+     * const controls = inject(KeyboardControls)
+     * const control = controls.getControl(Input.Enter)
+     *
+     * if (control) {
+     *   console.log(control.actionName) // 'action'
+     * }
+     * ```
+     */
+    setKeyboardControls(controlInstance: any): void;
     start(): Promise<void>;
+    private prepareSyncPayload;
+    private normalizeAckWithSyncState;
     private initListeners;
+    /**
+     * Start periodic ping/pong for client-server synchronization
+     *
+     * Sends ping requests to the server to measure round-trip time (RTT) and
+     * calculate the frame offset between client and server ticks.
+     *
+     * ## Design
+     *
+     * - Sends ping every 5 seconds
+     * - Measures RTT for latency compensation
+     * - Calculates frame offset to map client frames to server ticks
+     * - Used for accurate server reconciliation
+     *
+     * @example
+     * ```ts
+     * // Called automatically when connection opens
+     * this.startPingPong();
+     * ```
+     */
+    private startPingPong;
+    /**
+     * Stop periodic ping/pong
+     *
+     * Stops the ping interval when disconnecting or changing maps.
+     *
+     * @example
+     * ```ts
+     * // Called automatically when connection closes
+     * this.stopPingPong();
+     * ```
+     */
+    private stopPingPong;
+    /**
+     * Send a ping request to the server
+     *
+     * Sends current client time and frame counter to the server,
+     * which will respond with its server tick for synchronization.
+     *
+     * @example
+     * ```ts
+     * // Send a ping to measure RTT
+     * this.sendPing();
+     * ```
+     */
+    private sendPing;
     private loadScene;
     addSpriteSheet<T = any>(spritesheetClass: any, id?: string): any;
+    /**
+     * Set a resolver function for spritesheets
+     *
+     * The resolver is called when a spritesheet is requested but not found in the cache.
+     * It can be synchronous (returns directly) or asynchronous (returns a Promise).
+     * The resolved spritesheet is automatically cached for future use.
+     *
+     * @param resolver - Function that takes a spritesheet ID and returns a spritesheet or Promise of spritesheet
+     *
+     * @example
+     * ```ts
+     * // Synchronous resolver
+     * engine.setSpritesheetResolver((id) => {
+     *   if (id === 'dynamic-sprite') {
+     *     return { id: 'dynamic-sprite', image: 'path/to/image.png', framesWidth: 32, framesHeight: 32 };
+     *   }
+     *   return undefined;
+     * });
+     *
+     * // Asynchronous resolver (loading from API)
+     * engine.setSpritesheetResolver(async (id) => {
+     *   const response = await fetch(`/api/spritesheets/${id}`);
+     *   const data = await response.json();
+     *   return data;
+     * });
+     * ```
+     */
+    setSpritesheetResolver(resolver: (id: string) => any | Promise<any>): void;
+    /**
+     * Get a spritesheet by ID, using resolver if not found in cache
+     *
+     * This method first checks if the spritesheet exists in the cache.
+     * If not found and a resolver is set, it calls the resolver to create the spritesheet.
+     * The resolved spritesheet is automatically cached for future use.
+     *
+     * @param id - The spritesheet ID to retrieve
+     * @returns The spritesheet if found or created, or undefined if not found and no resolver
+     * @returns Promise<any> if the resolver is asynchronous
+     *
+     * @example
+     * ```ts
+     * // Synchronous usage
+     * const spritesheet = engine.getSpriteSheet('my-sprite');
+     *
+     * // Asynchronous usage (when resolver returns Promise)
+     * const spritesheet = await engine.getSpriteSheet('dynamic-sprite');
+     * ```
+     */
+    getSpriteSheet(id: string): any | Promise<any>;
+    /**
+     * Add a sound to the engine
+     *
+     * Adds a sound to the engine's sound cache. The sound can be:
+     * - A simple object with `id` and `src` properties
+     * - A Howler instance
+     * - An object with a `play()` method
+     *
+     * If the sound has a `src` property, a Howler instance will be created automatically.
+     *
+     * @param sound - The sound object or Howler instance
+     * @param id - Optional sound ID (if not provided, uses sound.id)
+     * @returns The added sound
+     *
+     * @example
+     * ```ts
+     * // Simple sound object
+     * engine.addSound({ id: 'click', src: 'click.mp3' });
+     *
+     * // With explicit ID
+     * engine.addSound({ src: 'music.mp3' }, 'background-music');
+     * ```
+     */
     addSound(sound: any, id?: string): any;
+    /**
+     * Set a resolver function for sounds
+     *
+     * The resolver is called when a sound is requested but not found in the cache.
+     * It can be synchronous (returns directly) or asynchronous (returns a Promise).
+     * The resolved sound is automatically cached for future use.
+     *
+     * @param resolver - Function that takes a sound ID and returns a sound or Promise of sound
+     *
+     * @example
+     * ```ts
+     * // Synchronous resolver
+     * engine.setSoundResolver((id) => {
+     *   if (id === 'dynamic-sound') {
+     *     return { id: 'dynamic-sound', src: 'path/to/sound.mp3' };
+     *   }
+     *   return undefined;
+     * });
+     *
+     * // Asynchronous resolver (loading from API)
+     * engine.setSoundResolver(async (id) => {
+     *   const response = await fetch(`/api/sounds/${id}`);
+     *   const data = await response.json();
+     *   return data;
+     * });
+     * ```
+     */
+    setSoundResolver(resolver: (id: string) => any | Promise<any>): void;
+    /**
+     * Get a sound by ID, using resolver if not found in cache
+     *
+     * This method first checks if the sound exists in the cache.
+     * If not found and a resolver is set, it calls the resolver to create the sound.
+     * The resolved sound is automatically cached for future use.
+     *
+     * @param id - The sound ID to retrieve
+     * @returns The sound if found or created, or undefined if not found and no resolver
+     * @returns Promise<any> if the resolver is asynchronous
+     *
+     * @example
+     * ```ts
+     * // Synchronous usage
+     * const sound = engine.getSound('my-sound');
+     *
+     * // Asynchronous usage (when resolver returns Promise)
+     * const sound = await engine.getSound('dynamic-sound');
+     * ```
+     */
+    getSound(id: string): any | Promise<any>;
+    /**
+     * Play a sound by its ID
+     *
+     * This method retrieves a sound from the cache or resolver and plays it.
+     * If the sound is not found, it will attempt to resolve it using the soundResolver.
+     * Uses Howler.js for audio playback instead of native Audio elements.
+     *
+     * @param soundId - The sound ID to play
+     * @param options - Optional sound configuration
+     * @param options.volume - Volume level (0.0 to 1.0, overrides sound default)
+     * @param options.loop - Whether the sound should loop (overrides sound default)
+     *
+     * @example
+     * ```ts
+     * // Play a sound synchronously
+     * engine.playSound('item-pickup');
+     *
+     * // Play a sound with volume and loop
+     * engine.playSound('background-music', { volume: 0.5, loop: true });
+     *
+     * // Play a sound asynchronously (when resolver returns Promise)
+     * await engine.playSound('dynamic-sound', { volume: 0.8 });
+     * ```
+     */
+    playSound(soundId: string, options?: {
+        volume?: number;
+        loop?: boolean;
+    }): Promise<void>;
+    /**
+     * Stop a sound that is currently playing
+     *
+     * This method stops a sound that was previously started with `playSound()`.
+     *
+     * @param soundId - The sound ID to stop
+     *
+     * @example
+     * ```ts
+     * // Start a looping sound
+     * engine.playSound('background-music', { loop: true });
+     *
+     * // Later, stop it
+     * engine.stopSound('background-music');
+     * ```
+     */
+    stopSound(soundId: string): void;
+    /**
+     * Stop all currently playing sounds
+     *
+     * This method stops all sounds that are currently playing.
+     * Useful when changing maps to prevent sound overlap.
+     *
+     * @example
+     * ```ts
+     * // Stop all sounds
+     * engine.stopAllSounds();
+     * ```
+     */
+    stopAllSounds(): void;
+    /**
+     * Set the camera to follow a specific sprite
+     *
+     * This method changes which sprite the camera viewport should follow.
+     * The camera will smoothly animate to the target sprite if smoothMove options are provided.
+     *
+     * ## Design
+     *
+     * The camera follow target is stored in a signal that is read by sprite components.
+     * Each sprite checks if it should be followed by comparing its ID with the target ID.
+     * When smoothMove options are provided, the viewport animation is handled by CanvasEngine's
+     * viewport system.
+     *
+     * @param targetId - The ID of the sprite to follow. Set to null to follow the current player
+     * @param smoothMove - Animation options. Can be a boolean (default: true) or an object with time and ease
+     * @param smoothMove.time - Duration of the animation in milliseconds (optional)
+     * @param smoothMove.ease - Easing function name from https://easings.net (optional)
+     *
+     * @example
+     * ```ts
+     * // Follow another player with default smooth animation
+     * engine.setCameraFollow(otherPlayerId, true);
+     *
+     * // Follow an event with custom smooth animation
+     * engine.setCameraFollow(eventId, {
+     *   time: 1000,
+     *   ease: "easeInOutQuad"
+     * });
+     *
+     * // Follow without animation (instant)
+     * engine.setCameraFollow(targetId, false);
+     *
+     * // Return to following current player
+     * engine.setCameraFollow(null);
+     * ```
+     */
+    setCameraFollow(targetId: string | null, smoothMove?: boolean | {
+        time?: number;
+        ease?: string;
+    }): void;
     addParticle(particle: any): any;
     /**
      * Add a component to render behind sprites
      * Components added with this method will be displayed with a lower z-index than the sprite
      *
-     * @param component - The component to add behind sprites
-     * @returns The added component
+     * Supports multiple formats:
+     * 1. Direct component: `ShadowComponent`
+     * 2. Configuration object: `{ component: LightHalo, props: {...} }`
+     * 3. With dynamic props: `{ component: LightHalo, props: (object) => {...} }`
+     * 4. With dependencies: `{ component: HealthBar, dependencies: (object) => [object.hp, object.param.maxHp] }`
+     *
+     * Components with dependencies will only be displayed when all dependencies are resolved (!= undefined).
+     * The object (sprite) is passed to the dependencies function to allow sprite-specific dependency resolution.
+     *
+     * @param component - The component to add behind sprites, or a configuration object
+     * @param component.component - The component function to render
+     * @param component.props - Static props object or function that receives the sprite object and returns props
+     * @param component.dependencies - Function that receives the sprite object and returns an array of Signals
+     * @returns The added component or configuration
      *
      * @example
      * ```ts
      * // Add a shadow component behind all sprites
      * engine.addSpriteComponentBehind(ShadowComponent);
+     *
+     * // Add a component with static props
+     * engine.addSpriteComponentBehind({
+     *   component: LightHalo,
+     *   props: { radius: 30 }
+     * });
+     *
+     * // Add a component with dynamic props and dependencies
+     * engine.addSpriteComponentBehind({
+     *   component: HealthBar,
+     *   props: (object) => ({ hp: object.hp(), maxHp: object.param.maxHp() }),
+     *   dependencies: (object) => [object.hp, object.param.maxHp]
+     * });
      * ```
      */
     addSpriteComponentBehind(component: any): any;
@@ -52,31 +412,272 @@ export declare class RpgClientEngine<T = any> {
      * Add a component to render in front of sprites
      * Components added with this method will be displayed with a higher z-index than the sprite
      *
-     * @param component - The component to add in front of sprites
-     * @returns The added component
+     * Supports multiple formats:
+     * 1. Direct component: `HealthBarComponent`
+     * 2. Configuration object: `{ component: StatusIndicator, props: {...} }`
+     * 3. With dynamic props: `{ component: HealthBar, props: (object) => {...} }`
+     * 4. With dependencies: `{ component: HealthBar, dependencies: (object) => [object.hp, object.param.maxHp] }`
+     *
+     * Components with dependencies will only be displayed when all dependencies are resolved (!= undefined).
+     * The object (sprite) is passed to the dependencies function to allow sprite-specific dependency resolution.
+     *
+     * @param component - The component to add in front of sprites, or a configuration object
+     * @param component.component - The component function to render
+     * @param component.props - Static props object or function that receives the sprite object and returns props
+     * @param component.dependencies - Function that receives the sprite object and returns an array of Signals
+     * @returns The added component or configuration
      *
      * @example
      * ```ts
      * // Add a health bar component in front of all sprites
      * engine.addSpriteComponentInFront(HealthBarComponent);
+     *
+     * // Add a component with static props
+     * engine.addSpriteComponentInFront({
+     *   component: StatusIndicator,
+     *   props: { type: 'poison' }
+     * });
+     *
+     * // Add a component with dynamic props and dependencies
+     * engine.addSpriteComponentInFront({
+     *   component: HealthBar,
+     *   props: (object) => ({ hp: object.hp(), maxHp: object.param.maxHp() }),
+     *   dependencies: (object) => [object.hp, object.param.maxHp]
+     * });
      * ```
      */
-    addSpriteComponentInFront(component: any): any;
-    addEffect(effect: {
+    addSpriteComponentInFront(component: any | {
+        component: any;
+        props: (object: any) => any;
+        dependencies?: (object: any) => any[];
+    }): any;
+    /**
+     * Add a component animation to the engine
+     *
+     * Component animations are temporary visual effects that can be displayed
+     * on sprites or objects, such as hit indicators, spell effects, or status animations.
+     *
+     * @param componentAnimation - The component animation configuration
+     * @param componentAnimation.id - Unique identifier for the animation
+     * @param componentAnimation.component - The component function to render
+     * @returns The added component animation configuration
+     *
+     * @example
+     * ```ts
+     * // Add a hit animation component
+     * engine.addComponentAnimation({
+     *   id: 'hit',
+     *   component: HitComponent
+     * });
+     *
+     * // Add an explosion effect component
+     * engine.addComponentAnimation({
+     *   id: 'explosion',
+     *   component: ExplosionComponent
+     * });
+     * ```
+     */
+    addComponentAnimation(componentAnimation: {
         component: any;
         id: string;
     }): {
         component: any;
         id: string;
     };
-    getEffect(id: string): EffectManager;
+    /**
+     * Get a component animation by its ID
+     *
+     * Retrieves the EffectManager instance for a specific component animation,
+     * which can be used to display the animation on sprites or objects.
+     *
+     * @param id - The unique identifier of the component animation
+     * @returns The EffectManager instance for the animation
+     * @throws Error if the component animation is not found
+     *
+     * @example
+     * ```ts
+     * // Get the hit animation and display it
+     * const hitAnimation = engine.getComponentAnimation('hit');
+     * hitAnimation.displayEffect({ text: "Critical!" }, player);
+     * ```
+     */
+    getComponentAnimation(id: string): AnimationManager;
+    /**
+     * Start a transition
+     *
+     * Convenience method to display a transition by its ID using the GUI system.
+     *
+     * @param id - The unique identifier of the transition to start
+     * @param props - Props to pass to the transition component
+     *
+     * @example
+     * ```ts
+     * // Start a fade transition
+     * engine.startTransition('fade', { duration: 1000, color: 'black' });
+     *
+     * // Start with onFinish callback
+     * engine.startTransition('fade', {
+     *   duration: 1000,
+     *   onFinish: () => console.log('Fade complete')
+     * });
+     * ```
+     */
+    startTransition(id: string, props?: any): void;
     processInput({ input }: {
-        input: number;
-    }): void;
+        input: Direction;
+    }): Promise<void>;
     processAction({ action }: {
         action: number;
     }): void;
     get PIXI(): typeof PIXI;
     get socket(): AbstractWebsocket;
     get playerId(): string | null;
+    get scene(): RpgClientMap;
+    private getPhysicsTick;
+    private ensureCurrentPlayerBody;
+    private stepClientPhysicsTick;
+    private flushPendingPredictedStates;
+    private buildPendingMoveTrajectory;
+    private emitMovePacket;
+    private flushPendingMovePath;
+    private getLocalPlayerState;
+    private applyAuthoritativeState;
+    private initializePredictionController;
+    getCurrentPlayer(): import('.').RpgClientPlayer;
+    emitSceneMapHook(hookName: string, ...args: any[]): void;
+    /**
+     * Setup RxJS observer to wait for all conditions before calling onAfterLoading hook
+     *
+     * This method uses RxJS `combineLatest` to wait for all conditions to be met,
+     * regardless of the order in which they arrive:
+     * 1. The map loading is completed (loadMapService.load is finished)
+     * 2. We received a player ID (pId)
+     * 3. Players array has at least one element
+     * 4. Events property is present in the sync data
+     *
+     * Once all conditions are met, it uses `switchMap` to call the onAfterLoading hook once.
+     *
+     * ## Design
+     *
+     * Uses BehaviorSubjects to track each condition state, allowing events to arrive
+     * in any order. The `combineLatest` operator waits until all observables emit `true`,
+     * then `take(1)` ensures the hook is called only once, and `switchMap` handles
+     * the hook execution.
+     *
+     * @example
+     * ```ts
+     * // Called automatically in loadScene to setup the observer
+     * this.setupOnAfterLoadingObserver();
+     * ```
+     */
+    private setupOnAfterLoadingObserver;
+    /**
+     * Clear client prediction states for cleanup
+     *
+     * Removes old prediction states and input history to prevent memory leaks.
+     * Should be called when changing maps or disconnecting.
+     *
+     * @example
+     * ```ts
+     * // Clear prediction states when changing maps
+     * engine.clearClientPredictionStates();
+     * ```
+     */
+    clearClientPredictionStates(): void;
+    /**
+     * Trigger a flash animation on a sprite
+     *
+     * This method allows you to trigger a flash effect on any sprite from client-side code.
+     * The flash can be configured with various options including type (alpha, tint, or both),
+     * duration, cycles, and color.
+     *
+     * ## Design
+     *
+     * The flash is applied directly to the sprite object using its flash trigger.
+     * This is useful for client-side visual feedback, UI interactions, or local effects
+     * that don't need to be synchronized with the server.
+     *
+     * @param spriteId - The ID of the sprite to flash. If not provided, flashes the current player
+     * @param options - Flash configuration options
+     * @param options.type - Type of flash effect: 'alpha' (opacity), 'tint' (color), or 'both' (default: 'alpha')
+     * @param options.duration - Duration of the flash animation in milliseconds (default: 300)
+     * @param options.cycles - Number of flash cycles (flash on/off) (default: 1)
+     * @param options.alpha - Alpha value when flashing, from 0 to 1 (default: 0.3)
+     * @param options.tint - Tint color when flashing as hex value or color name (default: 0xffffff - white)
+     *
+     * @example
+     * ```ts
+     * // Flash the current player with default settings
+     * engine.flash();
+     *
+     * // Flash a specific sprite with red tint
+     * engine.flash('sprite-id', { type: 'tint', tint: 0xff0000 });
+     *
+     * // Flash with both alpha and tint for dramatic effect
+     * engine.flash(undefined, {
+     *   type: 'both',
+     *   alpha: 0.5,
+     *   tint: 0xff0000,
+     *   duration: 200,
+     *   cycles: 2
+     * });
+     *
+     * // Quick damage flash on current player
+     * engine.flash(undefined, {
+     *   type: 'tint',
+     *   tint: 'red',
+     *   duration: 150,
+     *   cycles: 1
+     * });
+     * ```
+     */
+    flash(spriteId?: string, options?: {
+        type?: 'alpha' | 'tint' | 'both';
+        duration?: number;
+        cycles?: number;
+        alpha?: number;
+        tint?: number | string;
+    }): void;
+    private applyServerAck;
+    private reconcilePrediction;
+    /**
+     * Replay unacknowledged inputs from a given frame to resimulate client prediction
+     * after applying server authority at a certain frame.
+     *
+     * @param startFrame - The last server-acknowledged frame
+     *
+     * @example
+     * ```ts
+     * // After applying a server correction at frame N
+     * this.replayUnackedInputsFromFrame(N);
+     * ```
+     */
+    private replayUnackedInputsFromFrame;
+    /**
+     * Clear all client resources and reset state
+     *
+     * This method should be called to clean up all client-side resources when
+     * shutting down or resetting the client engine. It:
+     * - Destroys the PIXI renderer
+     * - Stops all sounds
+     * - Cleans up subscriptions and event listeners
+     * - Resets scene map
+     * - Stops ping/pong interval
+     * - Clears prediction states
+     *
+     * ## Design
+     *
+     * This method is used primarily in testing environments to ensure clean
+     * state between tests. In production, the client engine typically persists
+     * for the lifetime of the application.
+     *
+     * @example
+     * ```ts
+     * // In test cleanup
+     * afterEach(() => {
+     *   clientEngine.clear();
+     * });
+     * ```
+     */
+    clear(): void;
 }