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

package/dist/Player/Player.d.ts

@@ -1,4 +1,5 @@
-import { RpgCommonPlayer, ShowAnimationParams } from '@rpgjs/common';
+import { Hooks, RpgCommonPlayer, Constructor, Direction, AttachShapeOptions, RpgShape } from '../../../common/src';
+import { Vector2 } from '../../../physic/src';
 import { IComponentManager } from './ComponentManager';
 import { RpgMap } from '../rooms/map';
 import { Context } from '@signe/di';
@@ -15,16 +16,8 @@ import { ISkillManager } from './SkillManager';
 import { IBattleManager } from './BattleManager';
 import { IClassManager } from './ClassManager';
 import { IStateManager } from './StateManager';
-interface ZoneOptions {
-    x?: number;
-    y?: number;
-    radius: number;
-    angle?: number;
-    direction?: any;
-    linkedTo?: string;
-    limitedByWalls?: boolean;
-}
-declare const RpgPlayer_base: typeof RpgCommonPlayer;
+import { SaveRequestContext, SaveSlotIndex, SaveSlotMeta } from '../services/save';
+declare const RpgPlayer_base: Constructor<RpgCommonPlayer>;
 /**
  * RPG Player class with component management capabilities
  *
@@ -48,8 +41,94 @@ export declare class RpgPlayer extends RpgPlayer_base {
     map: RpgMap | null;
     context?: Context;
     conn: MockConnection | null;
+    touchSide: boolean;
+    private _clientListeners;
+    /**
+     * Computed signal for world X position
+     *
+     * Calculates the absolute world X position from the map's world position
+     * plus the player's local X position. Returns 0 if no map is assigned.
+     *
+     * @example
+     * ```ts
+     * const worldX = player.worldX();
+     * console.log(`Player is at world X: ${worldX}`);
+     * ```
+     */
+    get worldPositionX(): any;
+    /**
+     * Computed signal for world Y position
+     *
+     * Calculates the absolute world Y position from the map's world position
+     * plus the player's local Y position. Returns 0 if no map is assigned.
+     *
+     * @example
+     * ```ts
+     * const worldY = player.worldY();
+     * console.log(`Player is at world Y: ${worldY}`);
+     * ```
+     */
+    get worldPositionY(): any;
+    private _worldPositionSignals;
+    private _getComputedWorldPosition;
+    /** Internal: Shapes attached to this player */
+    private _attachedShapes;
+    /** Internal: Shapes where this player is currently located */
+    private _inShapes;
+    /** Last processed client input timestamp for reconciliation */
+    lastProcessedInputTs: number;
+    /** Last processed client input frame for reconciliation with server tick */
+    _lastFramePositions: {
+        frame: number;
+        position: {
+            x: number;
+            y: number;
+            direction: Direction;
+        };
+        serverTick?: number;
+    } | null;
+    frames: {
+        x: number;
+        y: number;
+        ts: number;
+    }[];
     events: import('@signe/reactive').WritableArraySignal<RpgEvent[]>;
     constructor();
+    private _getClientListenerBucket;
+    _dispatchClientEvent(key: string, data: any): Promise<void>;
+    _onInit(): void;
+    /**
+     * Apply the built-in default parameter curves to this player.
+     *
+     * Use this when you want RPGJS to provide the initial parameter setup
+     * instead of restoring values from your own database or a saved snapshot.
+     *
+     * This method only defines the parameter curves and related defaults.
+     * It does not restore custom persisted data for you.
+     *
+     * @method player.applyDefaultParameters()
+     * @returns {void}
+     */
+    applyDefaultParameters(): void;
+    /**
+     * Initialize the built-in default player stats.
+     *
+     * This applies the default parameter curves and then restores HP/SP to their
+     * current maximum values so the client receives coherent bars on first load.
+     *
+     * Call this manually in `onConnected()` or `onStart()` when your game relies
+     * on the built-in defaults. Do not call it after loading a snapshot or
+     * hydrating player data from your own database unless you explicitly want to
+     * overwrite those values.
+     *
+     * @method player.initializeDefaultStats()
+     * @returns {void}
+     */
+    initializeDefaultStats(): void;
+    get hooks(): Hooks;
+    get server(): RpgMap | null;
+    setMap(map: RpgMap): void;
+    applyFrames(): void;
     execMethod(method: string, methodData?: any[], target?: any): Promise<any>;
     /**
      * Change the map for this player
@@ -72,13 +151,180 @@ export declare class RpgPlayer extends RpgPlayer_base {
         y: number;
         z?: number;
     } | string): Promise<any | null | boolean>;
+    autoChangeMap(nextPosition: Vector2): Promise<boolean>;
     teleport(positions: {
         x: number;
         y: number;
     }): Promise<false | undefined>;
     getCurrentMap<T extends RpgMap = RpgMap>(): T | null;
+    /**
+     * Send a custom event to the current player's client.
+     *
+     * Use this to push arbitrary websocket payloads to one client only.
+     * On the client side, receive the event by injecting `WebSocketToken`
+     * and subscribing with `socket.on(...)`.
+     *
+     * @method player.emit(type, value)
+     * @param type - Custom event name sent to the client
+     * @param value - Payload sent with the event
+     * @returns {void}
+     *
+     * @example
+     * ```ts
+     * player.emit("inventory:updated", {
+     *   slots: player.items().length,
+     * });
+     * ```
+     *
+     * @example
+     * ```ts
+     * import { inject } from "@rpgjs/client";
+     * import { WebSocketToken, type AbstractWebsocket } from "@rpgjs/client";
+     *
+     * const socket = inject<AbstractWebsocket>(WebSocketToken);
+     *
+     * socket.on("inventory:updated", (payload) => {
+     *   console.log(payload.slots);
+     * });
+     * ```
+     */
     emit(type: string, value?: any): void;
-    showAnimation(params: ShowAnimationParams): void;
+    snapshot(): Record<string, any>;
+    applySnapshot(snapshot: string | object): Promise<any>;
+    save(slot?: SaveSlotIndex, meta?: SaveSlotMeta, context?: SaveRequestContext): Promise<{
+        index: number;
+        meta: import('../../../common/src').SaveSlotMeta;
+    } | null>;
+    load(slot?: SaveSlotIndex, context?: SaveRequestContext, options?: {
+        changeMap?: boolean;
+    }): Promise<{
+        ok: boolean;
+        slot?: undefined;
+        index?: undefined;
+    } | {
+        ok: boolean;
+        slot: {
+            [key: string]: any;
+            level?: number;
+            exp?: number;
+            map?: string;
+            date?: string;
+        };
+        index: number;
+    }>;
+    /**
+     * @deprecated Use setGraphicAnimation instead.
+     * @param animationName - The name of the animation to play (e.g., 'attack', 'skill', 'walk')
+     * @param nbTimes - Number of times to repeat the animation (default: Infinity for continuous)
+     */
+    setAnimation(animationName: string, nbTimes?: number): void;
+    /**
+     * @deprecated Use setGraphicAnimation instead.
+     * @param graphic - The graphic to use for the animation (e.g., 'attack', 'skill', 'walk')
+     * @param animationName - The name of the animation to play (e.g., 'attack', 'skill', 'walk')
+     * @param replaceGraphic - Whether to replace the player's graphic (default: false)
+     */
+    showAnimation(graphic: string, animationName: string, replaceGraphic?: boolean): void;
+    /**
+     * Listen to custom data sent by the current player's client.
+     *
+     * This listens to websocket actions emitted from the client with
+     * `socket.emit(key, data)`. It is intended for custom client events
+     * that are not already handled by built-in server actions such as
+     * `move`, `action`, or GUI interactions.
+     *
+     * @title Listen to data from the client
+     * @method player.on(key, cb)
+     * @param key - Event name emitted by the client
+     * @param cb - Callback invoked with the payload sent by the client
+     * @returns {void}
+     * @since 3.0.0-beta.5
+     *
+     * @example
+     * ```ts
+     * player.on("chat:message", ({ text }) => {
+     *   console.log("Client says:", text);
+     * });
+     * ```
+     *
+     * @example
+     * ```ts
+     * import { inject } from "@rpgjs/client";
+     * import { WebSocketToken, type AbstractWebsocket } from "@rpgjs/client";
+     *
+     * const socket = inject<AbstractWebsocket>(WebSocketToken);
+     * socket.emit("chat:message", { text: "Hello server" });
+     * ```
+     */
+    on(key: string, cb: (data: any) => void | Promise<void>): void;
+    /**
+     * Listen one time to custom data sent by the current player's client.
+     *
+     * After the first matching event is received, the listener is removed
+     * automatically.
+     *
+     * @title Listen one-time to data from the client
+     * @method player.once(key, cb)
+     * @param key - Event name emitted by the client
+     * @param cb - Callback invoked only once with the payload sent by the client
+     * @returns {void}
+     * @since 3.0.0-beta.5
+     *
+     * @example
+     * ```ts
+     * player.once("tutorial:ready", (payload) => {
+     *   console.log("Ready once:", payload.step);
+     * });
+     * ```
+     */
+    once(key: string, cb: (data: any) => void | Promise<void>): void;
+    /**
+     * Remove all listeners for a custom client event on this player.
+     *
+     * @title Remove listeners of the client event
+     * @method player.off(key)
+     * @param key - Event name to clear
+     * @returns {void}
+     * @since 3.0.0-beta.5
+     *
+     * @example
+     * ```ts
+     * player.off("chat:message");
+     * ```
+     */
+    off(key: string): void;
+    /**
+    * Set the current animation of the player's sprite
+    *
+    * This method changes the animation state of the player's current sprite.
+    * It's used to trigger character animations like attack, skill, or custom movements.
+    * When `nbTimes` is set to a finite number, the animation will play that many times
+    * before returning to the previous animation state.
+    *
+    * If `animationFixed` is true, this method will not change the animation.
+    *
+    * @param animationName - The name of the animation to play (e.g., 'attack', 'skill', 'walk')
+    * @param nbTimes - Number of times to repeat the animation (default: Infinity for continuous)
+    */
+    setGraphicAnimation(animationName: string, nbTimes: number): void;
+    /**
+     * Set the current animation of the player's sprite with a temporary graphic change
+     *
+     * This method changes the animation state of the player's current sprite and temporarily
+     * changes the player's graphic (sprite sheet) during the animation. The graphic is
+     * automatically reset when the animation finishes.
+     *
+     * When `nbTimes` is set to a finite number, the animation will play that many times
+     * before returning to the previous animation state and graphic.
+     *
+     * If `animationFixed` is true, this method will not change the animation.
+     *
+     * @param animationName - The name of the animation to play (e.g., 'attack', 'skill', 'walk')
+     * @param graphic - The graphic(s) to temporarily use during the animation
+     * @param nbTimes - Number of times to repeat the animation (default: Infinity for continuous)
+     */
+    setGraphicAnimation(animationName: string, graphic: string | string[], nbTimes: number): void;
+    setGraphicAnimation(animationName: string, graphic: string | string[]): void;
     /**
      * Run the change detection cycle. Normally, as soon as a hook is called in a class, the cycle is started. But you can start it manually
      * The method calls the `onChanges` method on events and synchronizes all map data with the client.
@@ -91,13 +337,311 @@ export declare class RpgPlayer extends RpgPlayer_base {
     syncChanges(): void;
     databaseById(id: string): any;
     private _eventChanges;
-    attachShape(id: string, options: ZoneOptions): void;
-    broadcastEffect(id: string, params: any): void;
+    /**
+     * Attach a zone shape to this player using the physic zone system
+     *
+     * This method creates a zone attached to the player's entity in the physics engine.
+     * The zone can be circular or cone-shaped and will detect other entities (players/events)
+     * entering or exiting the zone.
+     *
+     * @param id - Optional zone identifier. If not provided, a unique ID will be generated
+     * @param options - Zone configuration options
+     *
+     * @example
+     * ```ts
+     * // Create a circular detection zone
+     * player.attachShape("vision", {
+     *   radius: 150,
+     *   angle: 360,
+     * });
+     *
+     * // Create a cone-shaped vision zone
+     * player.attachShape("vision", {
+     *   radius: 200,
+     *   angle: 120,
+     *   direction: Direction.Right,
+     *   limitedByWalls: true,
+     * });
+     *
+     * // Create a zone with width/height (radius calculated automatically)
+     * player.attachShape({
+     *   width: 100,
+     *   height: 100,
+     *   positioning: "center",
+     * });
+     * ```
+     */
+    attachShape(idOrOptions: string | AttachShapeOptions, options?: AttachShapeOptions): RpgShape | undefined;
+    /**
+     * Get all shapes attached to this player
+     *
+     * Returns all shapes that were created using `attachShape()` on this player.
+     *
+     * @returns Array of RpgShape instances attached to this player
+     *
+     * @example
+     * ```ts
+     * player.attachShape("vision", { radius: 150 });
+     * player.attachShape("detection", { radius: 100 });
+     *
+     * const shapes = player.getShapes();
+     * console.log(shapes.length); // 2
+     * ```
+     */
+    getShapes(): RpgShape[];
+    /**
+     * Get all shapes where this player is currently located
+     *
+     * Returns all shapes (from any player/event) where this player is currently inside.
+     * This is updated automatically when the player enters or exits shapes.
+     *
+     * @returns Array of RpgShape instances where this player is located
+     *
+     * @example
+     * ```ts
+     * // Another player has a detection zone
+     * otherPlayer.attachShape("detection", { radius: 200 });
+     *
+     * // Check if this player is in any shape
+     * const inShapes = player.getInShapes();
+     * if (inShapes.length > 0) {
+     *   console.log("Player is being detected!");
+     * }
+     * ```
+     */
+    getInShapes(): RpgShape[];
+    /**
+     * Show a temporary component animation on this player
+     *
+     * This method broadcasts a component animation to all clients, allowing
+     * temporary visual effects like hit indicators, spell effects, or status animations
+     * to be displayed on the player.
+     *
+     * @param id - The ID of the component animation to display
+     * @param params - Parameters to pass to the component animation
+     *
+     * @example
+     * ```ts
+     * // Show a hit animation with damage text
+     * player.showComponentAnimation("hit", {
+     *   text: "150",
+     *   color: "red"
+     * });
+     *
+     * // Show a heal animation
+     * player.showComponentAnimation("heal", {
+     *   amount: 50
+     * });
+     * ```
+     */
+    showComponentAnimation(id: string, params?: any): void;
     showHit(text: string): void;
+    /**
+     * Play a sound on the client side for this player only
+     *
+     * This method emits an event to play a sound only for this specific player.
+     * The sound must be defined on the client side (in the client module configuration).
+     *
+     * ## Design
+     *
+     * The sound is sent only to this player's client connection, making it ideal
+     * for personal feedback sounds like UI interactions, notifications, or personal
+     * achievements. For map-wide sounds that all players should hear, use `map.playSound()` instead.
+     *
+     * @param soundId - Sound identifier, defined on the client side
+     * @param options - Optional sound configuration
+     * @param options.volume - Volume level (0.0 to 1.0, default: 1.0)
+     * @param options.loop - Whether the sound should loop (default: false)
+     *
+     * @example
+     * ```ts
+     * // Play a sound for this player only (default behavior)
+     * player.playSound("item-pickup");
+     *
+     * // Play a sound with volume and loop
+     * player.playSound("background-music", {
+     *   volume: 0.5,
+     *   loop: true
+     * });
+     *
+     * // Play a notification sound at low volume
+     * player.playSound("notification", { volume: 0.3 });
+     * ```
+     */
+    playSound(soundId: string, options?: {
+        volume?: number;
+        loop?: boolean;
+    }): void;
+    /**
+     * Stop a sound that is currently playing for this player
+     *
+     * This method stops a sound that was previously started with `playSound()`.
+     * The sound must be defined on the client side.
+     *
+     * @param soundId - Sound identifier to stop
+     *
+     * @example
+     * ```ts
+     * // Start a looping background music
+     * player.playSound("background-music", { loop: true });
+     *
+     * // Later, stop it
+     * player.stopSound("background-music");
+     * ```
+     */
+    stopSound(soundId: string): void;
+    /**
+     * Stop all currently playing sounds for this player
+     *
+     * This method stops all sounds that are currently playing for the player.
+     * Useful when changing maps to prevent sound overlap.
+     *
+     * @example
+     * ```ts
+     * // Stop all sounds before changing map
+     * player.stopAllSounds();
+     * await player.changeMap("new-map");
+     * ```
+     */
+    stopAllSounds(): void;
+    /**
+     * Make the camera follow another player or event
+     *
+     * This method sends an instruction to the client to fix the viewport on another sprite.
+     * The camera will follow the specified player or event, with optional smooth animation.
+     *
+     * ## Design
+     *
+     * The camera follow instruction is sent only to this player's client connection.
+     * This allows each player to have their own camera target, useful for cutscenes,
+     * following NPCs, or focusing on specific events.
+     *
+     * @param otherPlayer - The player or event that the camera should follow
+     * @param options - Camera follow options
+     * @param options.smoothMove - Enable smooth animation. Can be a boolean (default: true) or an object with animation parameters
+     * @param options.smoothMove.time - Time duration for the animation in milliseconds (optional)
+     * @param options.smoothMove.ease - Easing function name. Visit https://easings.net for available functions (optional)
+     *
+     * @example
+     * ```ts
+     * // Follow another player with default smooth animation
+     * player.cameraFollow(otherPlayer, { smoothMove: true });
+     *
+     * // Follow an event with custom smooth animation
+     * player.cameraFollow(npcEvent, {
+     *   smoothMove: {
+     *     time: 1000,
+     *     ease: "easeInOutQuad"
+     *   }
+     * });
+     *
+     * // Follow without animation (instant)
+     * player.cameraFollow(targetPlayer, { smoothMove: false });
+     * ```
+     */
+    cameraFollow(otherPlayer: RpgPlayer | RpgEvent, options?: {
+        smoothMove?: boolean | {
+            time?: number;
+            ease?: string;
+        };
+    }): void;
+    /**
+     * Trigger a flash animation on this player
+     *
+     * This method sends a flash animation event to the client, creating a visual
+     * feedback effect on the player's sprite. The flash can be configured with
+     * various options including type (alpha, tint, or both), duration, cycles, and color.
+     *
+     * ## Design
+     *
+     * The flash is sent as a broadcast event to all clients viewing this player.
+     * This is useful for visual feedback when the player takes damage, receives
+     * a buff, or when an important event occurs.
+     *
+     * @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
+     * // Simple flash with default settings (alpha flash)
+     * player.flash();
+     *
+     * // Flash with red tint when taking damage
+     * player.flash({ type: 'tint', tint: 0xff0000 });
+     *
+     * // Flash with both alpha and tint for dramatic effect
+     * player.flash({
+     *   type: 'both',
+     *   alpha: 0.5,
+     *   tint: 0xff0000,
+     *   duration: 200,
+     *   cycles: 2
+     * });
+     *
+     * // Quick damage flash
+     * player.flash({
+     *   type: 'tint',
+     *   tint: 'red',
+     *   duration: 150,
+     *   cycles: 1
+     * });
+     * ```
+     */
+    flash(options?: {
+        type?: 'alpha' | 'tint' | 'both';
+        duration?: number;
+        cycles?: number;
+        alpha?: number;
+        tint?: number | string;
+    }): void;
+    /**
+     * Set the hitbox of the player for collision detection
+     *
+     * This method defines the hitbox used for collision detection in the physics engine.
+     * The hitbox can be smaller or larger than the visual representation of the player,
+     * allowing for precise collision detection.
+     *
+     * ## Design
+     *
+     * The hitbox is used by the physics engine to detect collisions with other entities,
+     * static obstacles, and shapes. Changing the hitbox will immediately update the
+     * collision detection without affecting the visual appearance of the player.
+     *
+     * @param width - Width of the hitbox in pixels
+     * @param height - Height of the hitbox in pixels
+     *
+     * @example
+     * ```ts
+     * // Set a 20x20 hitbox for precise collision detection
+     * player.setHitbox(20, 20);
+     *
+     * // Set a larger hitbox for easier collision detection
+     * player.setHitbox(40, 40);
+     * ```
+     */
+    setHitbox(width: number, height: number): void;
+    /**
+     * Set the sync schema for the map
+     * @param schema - The schema to set
+     */
+    setSync(schema: any): void;
+    isEvent(): boolean;
 }
 export declare class RpgEvent extends RpgPlayer {
+    constructor();
     execMethod(methodName: string, methodData?: any[], instance?: this): Promise<any>;
+    /**
+     * Remove this event from the map
+     *
+     * Stops all movements before removing to prevent "unable to resolve entity" errors
+     * from the MovementManager when the entity is destroyed while moving.
+     */
     remove(): void;
+    isEvent(): boolean;
 }
 /**
  * Interface extension for RpgPlayer