@rpgjs/client 5.0.0-beta.2 → 5.0.0-beta.22

package/dist/RpgClientEngine.d.ts

@@ -1,9 +1,28 @@
+import { Trigger } from 'canvasengine';
 import { AbstractWebsocket } from './services/AbstractSocket';
-import { Direction } from '@rpgjs/common';
+import { I18nParams, RpgActionInput, RpgActionName, RpgDashInput, RpgMovementInput } from '@rpgjs/common';
+import { EventComponentConfig } from './RpgClient';
+import { RpgClientEvent } from './Game/Event';
 import { RpgClientMap } from './Game/Map';
 import { AnimationManager } from './Game/AnimationManager';
 import { Observable } from 'rxjs';
+import { ProjectileManager } from './Game/ProjectileManager';
+import { ClientVisualRegistry, ClientVisualHandler, ClientVisualMap, ClientVisualPacket } from './Game/ClientVisuals';
+import { ClientPointerContext } from './services/pointerContext';
+import { RpgClientInteractions } from './services/interactions';
+import { EventComponentResolver } from './Game/EventComponentResolver';
+import { CameraFollowSmoothMove } from './services/cameraFollow';
 import * as PIXI from "pixi.js";
+export type { CameraFollowEase, CameraFollowSmoothMove, CameraFollowSmoothMoveOptions, } from './services/cameraFollow';
+type ConfigurableTrigger<T> = Omit<Trigger<T>, "start"> & {
+    start(config?: T): Promise<void>;
+};
+type MapShakeOptions = {
+    intensity?: number;
+    duration?: number;
+    frequency?: number;
+    direction?: string;
+};
 export declare class RpgClientEngine<T = any> {
     context: any;
     private guiService;
@@ -14,12 +33,18 @@ export declare class RpgClientEngine<T = any> {
     private selector;
     globalConfig: T;
     sceneComponent: any;
+    sceneMapComponent: any;
     stopProcessingInput: boolean;
     width: import('canvasengine').WritableSignal<string>;
     height: import('canvasengine').WritableSignal<string>;
-    spritesheets: Map<string, any>;
+    spritesheets: Map<string | number, any>;
+    private spritesheetPromises;
     sounds: Map<string, any>;
     componentAnimations: any[];
+    clientVisuals: ClientVisualRegistry;
+    projectiles: ProjectileManager;
+    pointer: ClientPointerContext;
+    interactions: RpgClientInteractions;
     private spritesheetResolver?;
     private soundResolver?;
     particleSettings: {
@@ -32,19 +57,31 @@ export declare class RpgClientEngine<T = any> {
     playerIdSignal: import('canvasengine').WritableSignal<string | null>;
     spriteComponentsBehind: import('canvasengine').WritableArraySignal<any[]>;
     spriteComponentsInFront: import('canvasengine').WritableArraySignal<any[]>;
+    spriteComponents: Map<string, any>;
+    private eventComponentResolvers;
     /** ID of the sprite that the camera should follow. null means follow the current player */
     cameraFollowTargetId: import('canvasengine').WritableSignal<string | null>;
+    /** Camera follow transition options used by character components when the target changes */
+    cameraFollowSmoothMove: CameraFollowSmoothMove;
+    /** Incremented for each camera follow command so repeated commands on the same target are applied */
+    cameraFollowRevision: import('canvasengine').WritableSignal<number>;
     /** Trigger for map shake animation */
-    mapShakeTrigger: import('canvasengine').Trigger<any>;
-    controlsReady: import('canvasengine').WritableSignal<undefined>;
+    mapShakeTrigger: ConfigurableTrigger<MapShakeOptions>;
+    controlsReady: import('canvasengine').WritableSignal<boolean | undefined>;
     gamePause: import('canvasengine').WritableSignal<boolean>;
     private predictionEnabled;
     private prediction?;
     private readonly SERVER_CORRECTION_THRESHOLD;
+    private localMovementAuthority;
+    private lastLocalMovementInputAt;
+    private readonly LOCAL_MOVEMENT_AUTHORITY_ACK_GRACE_MS;
     private inputFrameCounter;
     private pendingPredictionFrames;
     private lastClientPhysicsStepAt;
     private frameOffset;
+    private latestServerTick?;
+    private latestServerTickAt;
+    private dashLockedUntil;
     private rtt;
     private pingInterval;
     private readonly PING_INTERVAL_MS;
@@ -59,10 +96,30 @@ export declare class RpgClientEngine<T = any> {
     private eventsReceived$;
     private onAfterLoadingSubscription?;
     private sceneResetQueued;
+    private mapTransitionInProgress;
+    private currentMapRoomId?;
+    private socketListenersInitialized;
+    private clientReadyForMapChanges;
+    private pendingMapChanges;
     private tickSubscriptions;
     private resizeHandler?;
+    private pointerMoveHandler?;
+    private pointerUpHandler?;
+    private pointerCancelHandler?;
+    private pointerCanvas?;
+    private pendingSyncPackets;
     private notificationManager;
+    private i18nService;
+    private locale?;
     constructor(context: any);
+    private resolveLocalMovementAuthority;
+    setLocale(locale: string): void;
+    getLocale(): string;
+    t(key: string, params?: I18nParams): string;
+    i18n(): {
+        locale: string;
+        t: (key: string, params?: I18nParams) => string;
+    };
     /**
      * Assigns a CanvasEngine KeyboardControls instance to the dependency injection context
      *
@@ -98,9 +155,28 @@ export declare class RpgClientEngine<T = any> {
      */
     setKeyboardControls(controlInstance: any): void;
     start(): Promise<void>;
+    private installCanvasResizeGuard;
+    private readCanvasResizeTargetSize;
+    private readCanvasRendererSize;
+    private cancelCanvasResizeFrame;
+    private resolveSceneMapComponent;
+    private setupPointerTracking;
+    updatePointerFromInteractionEvent(event: any): void;
+    private findViewportInstance;
+    private clearCameraFollowViewportPlugins;
     private prepareSyncPayload;
+    private shouldPreserveLocalPlayerPosition;
+    private shouldKeepLocalPlayerMovement;
     private normalizeAckWithSyncState;
     private initListeners;
+    private beginMapTransfer;
+    private clearComponentAnimations;
+    private shouldProcessProjectilePacket;
+    private callConnectError;
+    private flushPendingSyncPackets;
+    private flushPendingMapChanges;
+    private handleChangeMap;
+    private applySyncPacket;
     /**
      * Start periodic ping/pong for client-server synchronization
      *
@@ -175,7 +251,7 @@ export declare class RpgClientEngine<T = any> {
      * });
      * ```
      */
-    setSpritesheetResolver(resolver: (id: string) => any | Promise<any>): void;
+    setSpritesheetResolver(resolver: (id: string | number) => any | Promise<any>): void;
     /**
      * Get a spritesheet by ID, using resolver if not found in cache
      *
@@ -183,7 +259,7 @@ export declare class RpgClientEngine<T = any> {
      * 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
+     * @param id - The spritesheet ID or legacy tile 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
      *
@@ -196,7 +272,7 @@ export declare class RpgClientEngine<T = any> {
      * const spritesheet = await engine.getSpriteSheet('dynamic-sprite');
      * ```
      */
-    getSpriteSheet(id: string): any | Promise<any>;
+    getSpriteSheet(id: string | number): any | Promise<any>;
     /**
      * Add a sound to the engine
      *
@@ -332,19 +408,22 @@ export declare class RpgClientEngine<T = any> {
      * 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.
+     * The camera can smoothly animate to the target sprite before continuous follow starts.
      *
      * ## 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.
+     * When smoothMove options are provided, the transition is handled by pixi-viewport's
+     * animation plugin, then continuous follow 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)
+     * @param smoothMove.speed - Continuous follow speed after the transition (optional)
+     * @param smoothMove.acceleration - Continuous follow acceleration after the transition (optional)
+     * @param smoothMove.radius - Center radius where the target can move without moving the viewport (optional)
      *
      * @example
      * ```ts
@@ -364,10 +443,8 @@ export declare class RpgClientEngine<T = any> {
      * engine.setCameraFollow(null);
      * ```
      */
-    setCameraFollow(targetId: string | null, smoothMove?: boolean | {
-        time?: number;
-        ease?: string;
-    }): void;
+    setCameraFollow(targetId: string | null, smoothMove?: CameraFollowSmoothMove): void;
+    private resetCameraFollow;
     addParticle(particle: any): any;
     /**
      * Add a component to render behind sprites
@@ -451,6 +528,76 @@ export declare class RpgClientEngine<T = any> {
         props: (object: any) => any;
         dependencies?: (object: any) => any[];
     }): any;
+    /**
+     * Register a reusable sprite component that can be addressed by the server.
+     *
+     * Server-side component definitions only carry the component id and
+     * serializable props. The client registry maps that id to the CanvasEngine
+     * component that performs the actual rendering.
+     *
+     * @param id - Stable component id used by server component definitions
+     * @param component - CanvasEngine component to render for this id
+     * @returns The registered component
+     *
+     * @example
+     * ```ts
+     * engine.registerSpriteComponent('guildBadge', GuildBadgeComponent);
+     * ```
+     */
+    registerSpriteComponent(id: string, component: any): any;
+    /**
+     * Get a reusable sprite component by id.
+     *
+     * @param id - Component id registered on the client
+     * @returns The CanvasEngine component, or undefined when missing
+     */
+    getSpriteComponent(id: string): any;
+    /**
+     * Register a custom event component resolver.
+     *
+     * The last resolver returning a component wins. This lets later modules
+     * override earlier defaults without replacing the whole map scene.
+     *
+     * @param resolver - Function receiving the synced event object
+     * @returns The registered resolver
+     */
+    addEventComponentResolver(resolver: EventComponentResolver): EventComponentResolver;
+    /**
+     * Resolve the custom CanvasEngine component for an event, if any.
+     *
+     * @param event - Synced client event object
+     * @returns The component/config returned by the last matching resolver
+     */
+    resolveEventComponent(event: RpgClientEvent): EventComponentConfig | null;
+    registerProjectileComponent(type: string, component: any): any;
+    getProjectileComponent(type: string): any;
+    /**
+     * Register a named client visual macro.
+     *
+     * Client visuals are small client-side functions that group existing visual
+     * primitives such as flash, sound, component animations, sprite animation, or
+     * map shake. The server sends only the visual name and a serializable payload.
+     *
+     * @param name - Stable visual name sent by the server
+     * @param handler - Client-side visual handler
+     * @returns The registered handler
+     */
+    registerClientVisual(name: string, handler: ClientVisualHandler): ClientVisualHandler;
+    /**
+     * Register several named client visual macros.
+     *
+     * @param visuals - Map of visual names to client-side handlers
+     */
+    registerClientVisuals(visuals: ClientVisualMap): void;
+    /**
+     * Play a registered client visual locally.
+     *
+     * This is also used by the websocket listener when the server calls
+     * `player.clientVisual()` or `map.clientVisual()`.
+     *
+     * @param packet - Visual name and serializable payload
+     */
+    playClientVisual(packet: ClientVisualPacket): Promise<void>;
     /**
      * Add a component animation to the engine
      *
@@ -520,26 +667,35 @@ export declare class RpgClientEngine<T = any> {
      *   duration: 1000,
      *   onFinish: () => console.log('Fade complete')
      * });
+     *
+     * // Wait until the transition component calls onFinish
+     * await engine.startTransition('fade', { duration: 1000 });
      * ```
      */
-    startTransition(id: string, props?: any): void;
+    startTransition(id: string, props?: any): Promise<void>;
     processInput({ input }: {
-        input: Direction;
+        input: RpgMovementInput;
     }): Promise<void>;
-    processAction({ action }: {
-        action: number;
-    }): void;
+    processDash(input?: Partial<RpgDashInput>): Promise<void>;
+    processAction(action: RpgActionName, data?: any): void;
+    processAction(action: RpgActionInput): void;
     get PIXI(): typeof PIXI;
     get socket(): AbstractWebsocket;
     get playerId(): string | null;
     get scene(): RpgClientMap;
+    getObjectById(id: string): any;
     private getPhysicsTick;
+    private getPhysicsTickDurationMs;
+    private updateServerTickEstimate;
+    private estimateServerTick;
+    private predictProjectileImpact;
     private ensureCurrentPlayerBody;
     private stepClientPhysicsTick;
     private flushPendingPredictedStates;
     private buildPendingMoveTrajectory;
     private emitMovePacket;
     private flushPendingMovePath;
+    private applyPredictedMovementInput;
     private getLocalPlayerState;
     private applyAuthoritativeState;
     private initializePredictionController;
@@ -584,6 +740,22 @@ export declare class RpgClientEngine<T = any> {
      * ```
      */
     clearClientPredictionStates(): void;
+    /**
+     * Stop local movement immediately and discard pending predicted movement.
+     *
+     * Use this before a blocking action such as an A-RPG attack, dialog, dash
+     * startup, or any client-side state where already buffered movement inputs
+     * must not be replayed after server reconciliation.
+     *
+     * @param player - Player object to stop. Defaults to the current player.
+     * @returns `true` when a player was found and interrupted.
+     *
+     * @example
+     * ```ts
+     * engine.interruptCurrentPlayerMovement();
+     * ```
+     */
+    interruptCurrentPlayerMovement(player?: any): boolean;
     /**
      * Trigger a flash animation on a sprite
      *