@rpgjs/server 5.0.0-alpha.2 → 5.0.0-alpha.20

package/dist/rooms/map.d.ts

@@ -1,7 +1,22 @@
 import { MockConnection, RoomOnJoin } from '@signe/room';
-import { Hooks, RpgCommonMap, ZoneData } from '@rpgjs/common';
+import { Hooks, RpgCommonMap, RpgShape, WorldMapsManager, WorldMapConfig } from '@rpgjs/common';
 import { RpgPlayer, RpgEvent } from '../Player/Player';
 import { BehaviorSubject } from 'rxjs';
+/**
+ * Interface for input controls configuration
+ *
+ * Defines the structure for input validation and anti-cheat controls
+ */
+export interface Controls {
+    /** Maximum allowed time delta between inputs in milliseconds */
+    maxTimeDelta?: number;
+    /** Maximum allowed frame delta between inputs */
+    maxFrameDelta?: number;
+    /** Minimum time between inputs in milliseconds */
+    minTimeBetweenInputs?: number;
+    /** Whether to enable anti-cheat validation */
+    enableAntiCheat?: boolean;
+}
 /**
  * Interface representing hook methods available for map events
  *
@@ -17,11 +32,11 @@ export interface EventHooks {
     /** Called when a player touches this event */
     onPlayerTouch?: (player: RpgPlayer) => void;
     /** Called when a player enters a shape */
-    onInShape?: (zone: ZoneData, player: RpgPlayer) => void;
+    onInShape?: (zone: RpgShape, player: RpgPlayer) => void;
     /** Called when a player exits a shape */
-    onOutShape?: (zone: ZoneData, player: RpgPlayer) => void;
-    onDetectInShape?: (player: RpgPlayer, shape: ZoneData) => void;
-    onDetectOutShape?: (player: RpgPlayer, shape: ZoneData) => void;
+    onOutShape?: (zone: RpgShape, player: RpgPlayer) => void;
+    onDetectInShape?: (player: RpgPlayer, shape: RpgShape) => void;
+    onDetectOutShape?: (player: RpgPlayer, shape: RpgShape) => void;
 }
 /** Type for event class constructor */
 export type EventConstructor = new () => RpgPlayer;
@@ -48,17 +63,190 @@ export declare class RpgMap extends RpgCommonMap<RpgPlayer> implements RoomOnJoi
     dataIsReady$: BehaviorSubject<void>;
     globalConfig: any;
     damageFormulas: any;
+    /** Internal: Map of shapes by name */
+    private _shapes;
+    /** Internal: Map of shape entity UUIDs to RpgShape instances */
+    private _shapeEntities;
+    constructor();
+    /**
+     * Setup collision detection between players, events, and shapes
+     *
+     * This method listens to physics collision events and triggers hooks:
+     * - `onPlayerTouch` on events when a player collides with them
+     * - `onInShape` on players and events when they enter a shape
+     * - `onOutShape` on players and events when they exit a shape
+     *
+     * ## Architecture
+     *
+     * Uses the physics engine's collision event system to detect when entities collide.
+     * When a collision is detected:
+     * - Between a player and an event: triggers `onPlayerTouch` on the event
+     * - Between a player/event and a shape: triggers `onInShape`/`onOutShape` hooks
+     *
+     * @example
+     * ```ts
+     * // Event with onPlayerTouch hook
+     * map.createDynamicEvent({
+     *   x: 100,
+     *   y: 200,
+     *   event: {
+     *     onPlayerTouch(player) {
+     *       console.log(`Player ${player.id} touched this event!`);
+     *     }
+     *   }
+     * });
+     *
+     * // Player with onInShape hook
+     * const player: RpgPlayerHooks = {
+     *   onInShape(player: RpgPlayer, shape: RpgShape) {
+     *     console.log('in', player.name, shape.name);
+     *   },
+     *   onOutShape(player: RpgPlayer, shape: RpgShape) {
+     *     console.log('out', player.name, shape.name);
+     *   }
+     * };
+     * ```
+     */
+    private setupCollisionDetection;
+    interceptorPacket(player: RpgPlayer, packet: any, conn: MockConnection): any;
     onJoin(player: RpgPlayer, conn: MockConnection): void;
+    onLeave(player: RpgPlayer, conn: MockConnection): void;
     get hooks(): Hooks;
+    get widthPx(): number;
+    get heightPx(): number;
+    get id(): string;
+    get worldX(): number;
+    get worldY(): number;
     guiInteraction(player: RpgPlayer, value: any): void;
     guiExit(player: RpgPlayer, { guiId, data }: {
         guiId: any;
         data: any;
     }): void;
     onAction(player: RpgPlayer, action: any): void;
-    onInput(player: RpgPlayer, input: any): void;
+    onInput(player: RpgPlayer, input: any): Promise<void>;
     updateMap(request: Request): Promise<void>;
-    addInDatabase(id: string, data: any): void;
+    /**
+     * Update (or create) a world configuration and propagate to all maps in that world
+     *
+     * Body must contain the world config as defined by Tiled world import or an array of maps.
+     * If the world does not exist yet for this scene, it is created (auto-create).
+     *
+     * Expected payload examples:
+     * - { id: string, maps: WorldMapConfig[] }
+     * - WorldMapConfig[]
+     */
+    updateWorld(request: Request): Promise<any>;
+    /**
+     * Process pending inputs for a player with anti-cheat validation
+     *
+     * This method processes all pending inputs for a player while performing
+     * anti-cheat validation to prevent time manipulation and frame skipping.
+     * It validates the time deltas between inputs and ensures they are within
+     * acceptable ranges.
+     *
+     * ## Architecture
+     *
+     * **Important**: This method only updates entity velocities - it does NOT step
+     * the physics engine. Physics simulation is handled centrally by the game loop
+     * (`tick$` -> `runFixedTicks`). This ensures:
+     * - Consistent physics timing (60fps fixed timestep)
+     * - No double-stepping when multiple inputs are processed
+     * - Deterministic physics regardless of input frequency
+     *
+     * @param playerId - The ID of the player to process inputs for
+     * @param controls - Optional anti-cheat configuration
+     * @returns Promise containing the player and processed input strings
+     *
+     * @example
+     * ```ts
+     * // Process inputs with default anti-cheat settings
+     * const result = await map.processInput('player1');
+     * console.log('Processed inputs:', result.inputs);
+     *
+     * // Process inputs with custom anti-cheat configuration
+     * const result = await map.processInput('player1', {
+     *   maxTimeDelta: 100,
+     *   maxFrameDelta: 5,
+     *   minTimeBetweenInputs: 16,
+     *   enableAntiCheat: true
+     * });
+     * ```
+     */
+    processInput(playerId: string, controls?: Controls): Promise<{
+        player: RpgPlayer;
+        inputs: string[];
+    }>;
+    private loop;
+    /**
+     * Get a world manager by id (if multiple supported in future)
+     */
+    getWorldMaps(id: string): WorldMapsManager | null;
+    /**
+     * Delete a world manager by id
+     */
+    deleteWorldMaps(id: string): boolean;
+    /**
+     * Create a world manager dynamically
+     */
+    createDynamicWorldMaps(world: {
+        id?: string;
+        maps: WorldMapConfig[];
+    }): WorldMapsManager;
+    /**
+     * Update world maps by id. Auto-create when missing.
+     */
+    updateWorldMaps(id: string, maps: WorldMapConfig[]): Promise<void>;
+    /**
+     * Add data to the map's database
+     *
+     * This method allows you to dynamically add items, classes, or any data to the map's database.
+     * By default, if an ID already exists, the operation is ignored to prevent overwriting existing data.
+     *
+     * @param id - Unique identifier for the data
+     * @param data - The data to store (can be a class, object, or any value)
+     * @param options - Optional configuration
+     * @param options.force - If true, overwrites existing data even if ID already exists (default: false)
+     * @returns true if data was added, false if ignored (ID already exists)
+     *
+     * @example
+     * ```ts
+     * // Add an item class to the database
+     * map.addInDatabase('Potion', PotionClass);
+     *
+     * // Add an item object to the database
+     * map.addInDatabase('custom-item', {
+     *   name: 'Custom Item',
+     *   price: 100
+     * });
+     *
+     * // Force overwrite existing data
+     * map.addInDatabase('Potion', UpdatedPotionClass, { force: true });
+     * ```
+     */
+    addInDatabase(id: string, data: any, options?: {
+        force?: boolean;
+    }): boolean;
+    /**
+     * Remove data from the map's database
+     *
+     * This method allows you to remove items or data from the map's database.
+     *
+     * @param id - Unique identifier of the data to remove
+     * @returns true if data was removed, false if ID didn't exist
+     *
+     * @example
+     * ```ts
+     * // Remove an item from the database
+     * map.removeInDatabase('Potion');
+     *
+     * // Check if removal was successful
+     * const removed = map.removeInDatabase('custom-item');
+     * if (removed) {
+     *   console.log('Item removed successfully');
+     * }
+     * ```
+     */
+    removeInDatabase(id: string): boolean;
     /**
      * Creates a dynamic event on the map
      *
@@ -100,11 +288,301 @@ export declare class RpgMap extends RpgCommonMap<RpgPlayer> implements RoomOnJoi
     createDynamicEvent(eventObj: EventPosOption): Promise<void>;
     getEvent<T extends RpgPlayer>(eventId: string): T | undefined;
     getPlayer(playerId: string): RpgPlayer | undefined;
+    getPlayers(): RpgPlayer[];
     getEvents(): RpgEvent[];
+    getEventBy(cb: (event: RpgEvent) => boolean): RpgEvent | undefined;
+    getEventsBy(cb: (event: RpgEvent) => boolean): RpgEvent[];
     removeEvent(eventId: string): void;
-    showAnimation(animationName: string, object: RpgPlayer): void;
+    /**
+     * Display a component animation at a specific position on the map
+     *
+     * This method broadcasts a component animation to all clients connected to the map,
+     * allowing temporary visual effects to be displayed at any location on the map.
+     * Component animations are custom Canvas Engine components that can display
+     * complex effects with custom logic and parameters.
+     *
+     * @param id - The ID of the component animation to display
+     * @param position - The x, y coordinates where to display the animation
+     * @param params - Parameters to pass to the component animation
+     *
+     * @example
+     * ```ts
+     * // Show explosion at specific coordinates
+     * map.showComponentAnimation("explosion", { x: 300, y: 400 }, {
+     *   intensity: 2.5,
+     *   duration: 1500
+     * });
+     *
+     * // Show area damage effect
+     * map.showComponentAnimation("area-damage", { x: player.x, y: player.y }, {
+     *   radius: 100,
+     *   color: "red",
+     *   damage: 50
+     * });
+     *
+     * // Show treasure spawn effect
+     * map.showComponentAnimation("treasure-spawn", { x: 150, y: 200 }, {
+     *   sparkle: true,
+     *   sound: "treasure-appear"
+     * });
+     * ```
+     */
+    showComponentAnimation(id: string, position: {
+        x: number;
+        y: number;
+    }, params: any): void;
+    /**
+     * Display a spritesheet animation at a specific position on the map
+     *
+     * This method displays a temporary visual animation using a spritesheet at any
+     * location on the map. It's a convenience method that internally uses showComponentAnimation
+     * with the built-in 'animation' component. This is useful for spell effects, environmental
+     * animations, or any visual feedback that uses predefined spritesheets.
+     *
+     * @param position - The x, y coordinates where to display the animation
+     * @param graphic - The ID of the spritesheet to use for the animation
+     * @param animationName - The name of the animation within the spritesheet (default: 'default')
+     *
+     * @example
+     * ```ts
+     * // Show explosion at specific coordinates
+     * map.showAnimation({ x: 100, y: 200 }, "explosion");
+     *
+     * // Show spell effect at player position
+     * const playerPos = { x: player.x, y: player.y };
+     * map.showAnimation(playerPos, "spell-effects", "lightning");
+     *
+     * // Show environmental effect
+     * map.showAnimation({ x: 300, y: 150 }, "nature-effects", "wind-gust");
+     *
+     * // Show portal opening animation
+     * map.showAnimation({ x: 500, y: 400 }, "portals", "opening");
+     * ```
+     */
+    showAnimation(position: {
+        x: number;
+        y: number;
+    }, graphic: string, animationName?: string): void;
+    /**
+     * Set the sync schema for the map
+     * @param schema - The schema to set
+     */
+    /**
+     * Configure runtime synchronized properties on the map
+     *
+     * Design
+     * - Reads a schema object shaped like module props
+     * - Creates typed sync signals with @signe/sync
+     */
+    setSync(schema: Record<string, any>): void;
+    /**
+     * Create a shape dynamically on the map
+     *
+     * This method creates a static hitbox on the map that can be used for
+     * collision detection, area triggers, or visual boundaries. The shape is
+     * backed by the physics engine's static entity system for accurate collision detection.
+     *
+     * ## Architecture
+     *
+     * Creates a static entity (hitbox) in the physics engine at the specified position and size.
+     * The shape is stored internally and can be retrieved by name. When players or events
+     * collide with this hitbox, the `onInShape` and `onOutShape` hooks are automatically
+     * triggered on both the player and the event.
+     *
+     * @param obj - Shape configuration object
+     * @param obj.x - X position of the shape (top-left corner) (required)
+     * @param obj.y - Y position of the shape (top-left corner) (required)
+     * @param obj.width - Width of the shape in pixels (required)
+     * @param obj.height - Height of the shape in pixels (required)
+     * @param obj.name - Name of the shape (optional, auto-generated if not provided)
+     * @param obj.z - Z position/depth for rendering (optional)
+     * @param obj.color - Color in hexadecimal format, shared with client (optional)
+     * @param obj.collision - Whether the shape has collision (optional)
+     * @param obj.properties - Additional custom properties (optional)
+     * @returns The created RpgShape instance
+     *
+     * @example
+     * ```ts
+     * // Create a simple rectangular shape
+     * const shape = map.createShape({
+     *   x: 100,
+     *   y: 200,
+     *   width: 50,
+     *   height: 50,
+     *   name: "spawn-zone"
+     * });
+     *
+     * // Create a shape with visual properties
+     * const triggerZone = map.createShape({
+     *   x: 300,
+     *   y: 400,
+     *   width: 100,
+     *   height: 100,
+     *   name: "treasure-area",
+     *   color: "#FFD700",
+     *   z: 1,
+     *   collision: false,
+     *   properties: {
+     *     type: "treasure",
+     *     value: 100
+     *   }
+     * });
+     *
+     * // Player hooks will be triggered automatically
+     * const player: RpgPlayerHooks = {
+     *   onInShape(player: RpgPlayer, shape: RpgShape) {
+     *     console.log('in', player.name, shape.name);
+     *   },
+     *   onOutShape(player: RpgPlayer, shape: RpgShape) {
+     *     console.log('out', player.name, shape.name);
+     *   }
+     * };
+     * ```
+     */
+    createShape(obj: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        name?: string;
+        z?: number;
+        color?: string;
+        collision?: boolean;
+        properties?: Record<string, any>;
+    }): RpgShape;
+    /**
+     * Delete a shape from the map
+     *
+     * Removes a shape by its name and cleans up the associated static hitbox entity.
+     * If the shape doesn't exist, the method does nothing.
+     *
+     * @param name - Name of the shape to remove
+     * @returns void
+     *
+     * @example
+     * ```ts
+     * // Create and then remove a shape
+     * const shape = map.createShape({
+     *   x: 100,
+     *   y: 200,
+     *   width: 50,
+     *   height: 50,
+     *   name: "temp-zone"
+     * });
+     *
+     * // Later, remove it
+     * map.removeShape("temp-zone");
+     * ```
+     */
+    removeShape(name: string): void;
+    /**
+     * Get all shapes on the map
+     *
+     * Returns an array of all shapes that have been created on this map,
+     * regardless of whether they are static shapes or player-attached shapes.
+     *
+     * @returns Array of RpgShape instances
+     *
+     * @example
+     * ```ts
+     * // Create multiple shapes
+     * map.createShape({ x: 0, y: 0, width: 50, height: 50, name: "zone1" });
+     * map.createShape({ x: 100, y: 100, width: 50, height: 50, name: "zone2" });
+     *
+     * // Get all shapes
+     * const allShapes = map.getShapes();
+     * console.log(allShapes.length); // 2
+     * ```
+     */
+    getShapes(): RpgShape[];
+    /**
+     * Get a shape by its name
+     *
+     * Returns a shape with the specified name, or undefined if no shape
+     * with that name exists on the map.
+     *
+     * @param name - Name of the shape to retrieve
+     * @returns The RpgShape instance, or undefined if not found
+     *
+     * @example
+     * ```ts
+     * // Create a shape with a specific name
+     * map.createShape({
+     *   x: 100,
+     *   y: 200,
+     *   width: 50,
+     *   height: 50,
+     *   name: "spawn-point"
+     * });
+     *
+     * // Retrieve it later
+     * const spawnZone = map.getShape("spawn-point");
+     * if (spawnZone) {
+     *   console.log(`Spawn zone at (${spawnZone.x}, ${spawnZone.y})`);
+     * }
+     * ```
+     */
+    getShape(name: string): RpgShape | undefined;
+    /**
+     * Play a sound for all players on the map
+     *
+     * This method plays a sound for all players currently on the map by iterating
+     * over each player and calling `player.playSound()`. The sound must be defined
+     * on the client side (in the client module configuration).
+     * This is ideal for environmental sounds, battle music, or map-wide events that
+     * all players should hear simultaneously.
+     *
+     * ## Design
+     *
+     * Iterates over all players on the map and calls `player.playSound()` for each one.
+     * This avoids code duplication and reuses the existing player sound logic.
+     * For player-specific sounds, use `player.playSound()` directly.
+     *
+     * @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 all players on the map
+     * map.playSound("explosion");
+     *
+     * // Play background music for everyone with volume and loop
+     * map.playSound("battle-theme", {
+     *   volume: 0.7,
+     *   loop: true
+     * });
+     *
+     * // Play a door opening sound at low volume
+     * map.playSound("door-open", { volume: 0.4 });
+     * ```
+     */
+    playSound(soundId: string, options?: {
+        volume?: number;
+        loop?: boolean;
+    }): void;
+    /**
+     * Stop a sound for all players on the map
+     *
+     * This method stops a sound that was previously started with `map.playSound()`
+     * for all players on the map by iterating over each player and calling `player.stopSound()`.
+     *
+     * @param soundId - Sound identifier to stop
+     *
+     * @example
+     * ```ts
+     * // Start background music for everyone
+     * map.playSound("battle-theme", { loop: true });
+     *
+     * // Later, stop it for everyone
+     * map.stopSound("battle-theme");
+     * ```
+     */
+    stopSound(soundId: string): void;
 }
 export interface RpgMap {
     $send: (conn: MockConnection, data: any) => void;
     $broadcast: (data: any) => void;
+    $sessionTransfer: (userOrPublicId: any | string, targetRoomId: string) => void;
 }

package/package.json

@@ -1,31 +1,33 @@
 {
   "name": "@rpgjs/server",
-  "version": "5.0.0-alpha.2",
+  "version": "5.0.0-alpha.20",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "publishConfig": {
     "access": "public"
   },
-  "scripts": {
-    "dev": "vite build --watch",
-    "build": "vite build"
-  },
   "keywords": [],
   "author": "",
   "license": "MIT",
   "description": "",
   "dependencies": {
-    "@rpgjs/common": "workspace:*",
+    "@rpgjs/common": "5.0.0-alpha.20",
+    "@rpgjs/physic": "5.0.0-alpha.20",
     "@rpgjs/database": "^4.3.0",
-    "@signe/di": "^2.3.2",
-    "@signe/reactive": "^2.3.2",
-    "@signe/room": "^2.3.2",
-    "@signe/sync": "^2.3.2",
-    "rxjs": "^7.8.2"
+    "@signe/di": "^2.5.1",
+    "@signe/reactive": "^2.5.1",
+    "@signe/room": "^2.5.1",
+    "@signe/sync": "^2.5.1",
+    "rxjs": "^7.8.2",
+    "zod": "^4.1.13"
   },
   "devDependencies": {
-    "vite": "^6.2.5",
-    "vite-plugin-dts": "^4.5.3"
+    "vite": "^7.2.4",
+    "vite-plugin-dts": "^4.5.4"
   },
-  "type": "module"
-}
+  "type": "module",
+  "scripts": {
+    "dev": "vite build --watch",
+    "build": "vite build"
+  }
+}

package/src/Gui/DialogGui.ts

@@ -18,7 +18,11 @@ export interface DialogOptions {
     autoClose?: boolean,
     tranparent?: boolean,
     typewriterEffect?: boolean,
-    talkWith?: RpgPlayer
+    talkWith?: RpgPlayer,
+    face?: {
+        id: string,
+        expression: string
+    },
 }
 
 export class DialogGui extends Gui {
@@ -47,7 +51,8 @@ export class DialogGui extends Gui {
             // remove value property. It is not useful to know this on the client side.
             choices: options.choices.map(choice => ({
                 text: choice.text
-            }))
+            })),
+            face: options.face
         }
         return super.open({
             message,

package/src/Gui/index.ts

@@ -10,4 +10,6 @@ export {
     MenuGui,
     ShopGui,
     NotificationGui
-}
+}
+
+export { DialogPosition } from './DialogGui'