@rpgjs/client 5.0.0-alpha.2 → 5.0.0-alpha.21

package/dist/RpgClientEngine.d.ts

@@ -1,5 +1,10 @@
 import { Context } from '@signe/di';
-import { EffectManager } from './Game/EffectManager';
+import { AbstractWebsocket } from './services/AbstractSocket';
+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;
     private guiService;
@@ -15,29 +20,397 @@ 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>;
+    playerIdSignal: import('canvasengine').WritableSignal<string | null>;
+    spriteComponentsBehind: import('canvasengine').WritableArraySignal<any[]>;
+    spriteComponentsInFront: import('canvasengine').WritableArraySignal<any[]>;
+    private predictionEnabled;
+    private prediction?;
+    private readonly SERVER_CORRECTION_THRESHOLD;
+    private inputFrameCounter;
+    private frameOffset;
+    private rtt;
+    private pingInterval;
+    private readonly PING_INTERVAL_MS;
+    private lastInputTime;
     constructor(context: Context);
+    /**
+     * 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 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;
     addParticle(particle: any): any;
-    addEffect(effect: {
+    /**
+     * 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
+     *
+     * @example
+     * ```ts
+     * // Add a shadow component behind all sprites
+     * engine.addSpriteComponentBehind(ShadowComponent);
+     * ```
+     */
+    addSpriteComponentBehind(component: any): 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
+     *
+     * @example
+     * ```ts
+     * // Add a health bar component in front of all sprites
+     * engine.addSpriteComponentInFront(HealthBarComponent);
+     * ```
+     */
+    addSpriteComponentInFront(component: 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;
     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 getLocalPlayerState;
+    private applyAuthoritativeState;
+    private initializePredictionController;
+    getCurrentPlayer(): import('./Game/Player').RpgClientPlayer;
+    /**
+     * 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;
+    private applyServerAck;
+    /**
+     * 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;
 }

package/dist/Sound.d.ts

@@ -0,0 +1,199 @@
+import { Howler } from 'canvasengine';
+import { RpgClientEngine } from './RpgClientEngine';
+/**
+ * Sound decorator options
+ *
+ * Defines the configuration for a sound that can be played in the game.
+ * The sound can be a single file or multiple files (for different formats).
+ *
+ * @interface SoundOptions
+ */
+export interface SoundOptions {
+    /**
+     * Sound identifier. Used to retrieve the sound later with RpgSound.get()
+     *
+     * @type {string}
+     */
+    id?: string;
+    /**
+     * Single sound file path. Use require() to wrap the path.
+     *
+     * @type {string}
+     * @example
+     * sound: require('./assets/sound.ogg')
+     */
+    sound?: string;
+    /**
+     * Multiple sounds with different IDs. The key is the sound ID and the value is the file path.
+     * Use require() to wrap each path.
+     *
+     * @type {{ [id: string]: string }}
+     * @example
+     * sounds: {
+     *   hero: require('./assets/hero.ogg'),
+     *   monster: require('./assets/monster.ogg')
+     * }
+     */
+    sounds?: {
+        [id: string]: string;
+    };
+    /**
+     * Whether the sound should loop when it finishes playing.
+     *
+     * @type {boolean}
+     * @default false
+     */
+    loop?: boolean;
+    /**
+     * Volume level (0.0 to 1.0).
+     *
+     * @type {number}
+     * @default 1.0
+     */
+    volume?: number;
+}
+/**
+ * Metadata stored on the class decorated with @Sound
+ *
+ * @interface SoundMetadata
+ */
+interface SoundMetadata {
+    id?: string;
+    sound?: string;
+    sounds?: {
+        [id: string]: string;
+    };
+    loop?: boolean;
+    volume?: number;
+}
+/**
+ * Sound decorator
+ *
+ * Decorates a class to define a sound configuration. The decorated class can be
+ * added to the RpgClient module configuration, and the sound will be automatically
+ * registered and available through RpgSound.get().
+ *
+ * ## Design
+ *
+ * The decorator stores metadata on the class that is later used by the module loader
+ * to register sounds with the engine. The sound is created using Howler.js for
+ * advanced audio features like looping, volume control, and cross-browser compatibility.
+ *
+ * @param options - Sound configuration options
+ *
+ * @example
+ * ```ts
+ * import { Sound } from '@rpgjs/client'
+ *
+ * @Sound({
+ *   id: 'town-music',
+ *   sound: require('./sound/town.ogg'),
+ *   loop: true,
+ *   volume: 0.5
+ * })
+ * export class TownMusic {}
+ *
+ * // Multiple sounds in one class
+ * @Sound({
+ *   sounds: {
+ *     hero: require('./assets/hero.ogg'),
+ *     monster: require('./assets/monster.ogg')
+ *   },
+ *   loop: true
+ * })
+ * export class CharacterSounds {}
+ * ```
+ */
+export declare function Sound(options: SoundOptions): <T extends {
+    new (...args: any[]): {};
+}>(constructor: T) => T;
+/**
+ * Get sound metadata from a decorated class
+ *
+ * @param soundClass - The class decorated with @Sound
+ * @returns The sound metadata or undefined
+ */
+export declare function getSoundMetadata(soundClass: any): SoundMetadata | undefined;
+/**
+ * RpgSound class
+ *
+ * Provides a unified API to manage sounds in the game. Uses Howler.js internally
+ * for advanced audio features. Sounds can be retrieved by ID and controlled
+ * using Howler.js methods.
+ *
+ * ## Design
+ *
+ * RpgSound acts as a facade over Howler.js, providing easy access to sounds
+ * registered in the engine. It supports both individual sound control and
+ * global sound management (volume, mute, etc.).
+ *
+ * @example
+ * ```ts
+ * import { RpgSound } from '@rpgjs/client'
+ *
+ * // Play a sound
+ * RpgSound.get('town-music').play()
+ *
+ * // Control volume
+ * RpgSound.get('town-music').volume(0.5)
+ *
+ * // Stop a sound
+ * RpgSound.get('town-music').stop()
+ *
+ * // Global volume control
+ * RpgSound.global.volume(0.2)
+ * ```
+ */
+export declare class RpgSound {
+    private static engine;
+    /**
+     * Initialize RpgSound with the engine instance
+     *
+     * This is called automatically by the engine during initialization.
+     *
+     * @param engine - The RpgClientEngine instance
+     */
+    static init(engine: RpgClientEngine): void;
+    /**
+     * Get a sound by its ID
+     *
+     * Retrieves a Howler sound instance from the engine's sound cache.
+     * The sound must be registered beforehand (via @Sound decorator or manually).
+     *
+     * @param id - The sound identifier
+     * @returns The Howler sound instance, or undefined if not found
+     *
+     * @example
+     * ```ts
+     * // Get and play a sound
+     * const sound = RpgSound.get('town-music');
+     * if (sound) {
+     *   sound.play();
+     * }
+     *
+     * // Chain methods
+     * RpgSound.get('battle-theme')?.volume(0.8).play();
+     * ```
+     */
+    static get(id: string): any;
+    /**
+     * Global Howler instance for managing all sounds
+     *
+     * Provides access to Howler.js global methods for controlling all sounds
+     * at once (volume, mute, etc.).
+     *
+     * @example
+     * ```ts
+     * // Set global volume to 20%
+     * RpgSound.global.volume(0.2)
+     *
+     * // Mute all sounds
+     * RpgSound.global.mute(true)
+     *
+     * // Unmute all sounds
+     * RpgSound.global.mute(false)
+     * ```
+     */
+    static get global(): typeof Howler;
+}
+export {};

package/dist/components/animations/index.d.ts

@@ -0,0 +1,4 @@
+export declare const PrebuiltComponentAnimations: {
+    Hit: any;
+    Animation: any;
+};

package/dist/components/dynamics/parse-value.d.ts

@@ -0,0 +1 @@
+export declare const parseDynamicValue: (value: any, object?: any) => import('canvasengine').ComputedSignal<string>;

package/dist/components/gui/index.d.ts

@@ -1,3 +1,3 @@
-export declare const PrebuiltGui: {
-    Dialogbox: any;
-};
+import { default as DialogboxComponent } from './dialogbox/index.ce';
+import { default as BoxComponent } from './box.ce';
+export { DialogboxComponent, BoxComponent };

package/dist/components/index.d.ts

@@ -1,2 +1,4 @@
 import { default as EventLayerComponent } from './scenes/event-layer.ce';
-export { EventLayerComponent };
+import { default as CharacterComponent } from './character.ce';
+export { HpBar } from './prebuilt';
+export { EventLayerComponent, CharacterComponent };

package/dist/components/prebuilt/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Prebuilt sprite components for common UI elements
+ *
+ * This module exports ready-to-use components that can be attached
+ * to sprites using componentsInFront or componentsBehind configuration.
+ *
+ * @example
+ * ```ts
+ * import { HpBar } from '@rpgjs/client/components/prebuilt';
+ *
+ * export default defineModule<RpgClient>({
+ *   sprite: {
+ *     componentsInFront: [HpBar]
+ *   }
+ * })
+ * ```
+ */
+export { default as HpBar } from './hp-bar.ce';

package/dist/index.d.ts

@@ -8,6 +8,11 @@ export * from './services/loadMap';
 export * from './module';
 export * from './Gui/Gui';
 export * from './components/gui';
-export * from './components/effects';
+export * from './components/animations';
 export * from './presets';
 export * from './components';
+export * from './components/gui';
+export * from './Sound';
+export * from './Resource';
+export { Context } from '@signe/di';
+export * from './services/keyboardControls';

package/dist/index.js

@@ -6,8 +6,15 @@ export { clearInject, context, inject, setInject } from './index6.js';
 export { LoadMapService, LoadMapToken, provideLoadMap } from './index7.js';
 export { GlobalConfigToken, provideClientGlobalConfig, provideClientModules, provideGlobalConfig } from './index8.js';
 export { RpgGui } from './index9.js';
-export { PrebuiltGui } from './index10.js';
-export { PrebuiltEffects } from './index11.js';
-export { Presets } from './index12.js';
-export { default as EventLayerComponent } from './index13.js';
+export { default as DialogboxComponent } from './index10.js';
+export { default as BoxComponent } from './index11.js';
+export { PrebuiltComponentAnimations } from './index12.js';
+export { Presets } from './index13.js';
+export { default as EventLayerComponent } from './index14.js';
+export { default as CharacterComponent } from './index15.js';
+export { default as HpBar } from './index16.js';
+export { RpgSound, Sound, getSoundMetadata } from './index17.js';
+export { RpgResource } from './index18.js';
+export { Context } from './index19.js';
+export { KeyboardControls, provideKeyboardControls } from './index20.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;"}
+{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;"}