@rpgjs/client 5.0.0-alpha.0 → 5.0.0-alpha.10

package/dist/services/loadMap.d.ts

@@ -1,14 +1,135 @@
 import { Context } from '@signe/di';
 export declare const LoadMapToken = "LoadMapToken";
-export type LoadMapOptions = (mapId: string) => Promise<void>;
+/**
+ * Represents the structure of map data that should be returned by the load map callback.
+ * This interface defines all the properties that can be provided when loading a custom map.
+ *
+ * @interface MapData
+ */
+type MapData = {
+    /** Raw map data that will be passed to the map component */
+    data: any;
+    /** CanvasEngine component that will render the map */
+    component: any;
+    /** Optional map width in pixels, used for viewport calculations */
+    width?: number;
+    /** Optional map height in pixels, used for viewport calculations */
+    height?: number;
+    /** Optional map events data (NPCs, interactive objects, etc.) */
+    events?: any;
+    /** Optional map identifier, defaults to the mapId parameter if not provided */
+    id?: string;
+};
+/**
+ * Callback function type for loading map data.
+ * This function receives a map ID and should return either a MapData object directly
+ * or a Promise that resolves to a MapData object.
+ *
+ * @callback LoadMapOptions
+ * @param {string} mapId - The identifier of the map to load
+ * @returns {Promise<MapData> | MapData} The map data object or a promise resolving to it
+ */
+export type LoadMapOptions = (mapId: string) => Promise<MapData> | MapData;
 export declare class LoadMapService {
     private context;
     private options;
     private updateMapService;
     constructor(context: Context, options: LoadMapOptions);
-    load(mapId: string): Promise<void>;
+    load(mapId: string): Promise<MapData>;
 }
+/**
+ * Creates a dependency injection configuration for custom map loading on the client side.
+ *
+ * This function allows you to customize how maps are loaded and displayed by providing
+ * a callback that defines custom map data and rendering components. It's designed to work
+ * with the RPG-JS dependency injection system and enables integration of custom map formats
+ * like Tiled TMX files or any other map data structure.
+ *
+ * The function sets up the necessary service providers for map loading, including:
+ * - UpdateMapToken: Handles map updates in the client context
+ * - LoadMapToken: Provides the LoadMapService with your custom loading logic
+ *
+ * **Design Concept:**
+ * The function follows the provider pattern, creating a modular way to inject custom
+ * map loading behavior into the RPG-JS client engine. It separates the concern of
+ * map data fetching from map rendering, allowing developers to focus on their specific
+ * map format while leveraging the engine's rendering capabilities.
+ *
+ * @param {LoadMapOptions} options - Callback function that handles map loading logic
+ * @returns {Array<Object>} Array of dependency injection provider configurations
+ *
+ * @example
+ * ```typescript
+ * import { provideLoadMap } from '@rpgjs/client'
+ * import { createModule } from '@rpgjs/common'
+ * import MyTiledMapComponent from './MyTiledMapComponent.ce'
+ *
+ * // Basic usage with JSON map data
+ * export function provideCustomMap() {
+ *   return createModule("CustomMap", [
+ *     provideLoadMap(async (mapId) => {
+ *       const response = await fetch(`/maps/${mapId}.json`)
+ *       const mapData = await response.json()
+ *
+ *       return {
+ *         data: mapData,
+ *         component: MyTiledMapComponent,
+ *         width: mapData.width,
+ *         height: mapData.height,
+ *         events: mapData.events
+ *       }
+ *     })
+ *   ])
+ * }
+ *
+ * // Advanced usage with Tiled TMX files
+ * export function provideTiledMap() {
+ *   return createModule("TiledMap", [
+ *     provideLoadMap(async (mapId) => {
+ *       // Load TMX file
+ *       const tmxResponse = await fetch(`/tiled/${mapId}.tmx`)
+ *       const tmxData = await tmxResponse.text()
+ *
+ *       // Parse TMX data (using a TMX parser)
+ *       const parsedMap = parseTMX(tmxData)
+ *
+ *       return {
+ *         data: parsedMap,
+ *         component: TiledMapRenderer,
+ *         width: parsedMap.width * parsedMap.tilewidth,
+ *         height: parsedMap.height * parsedMap.tileheight,
+ *         events: parsedMap.objectGroups?.find(g => g.name === 'events')?.objects
+ *       }
+ *     })
+ *   ])
+ * }
+ *
+ * // Synchronous usage for static maps
+ * export function provideStaticMap() {
+ *   return createModule("StaticMap", [
+ *     provideLoadMap((mapId) => {
+ *       const staticMaps = {
+ *         'town': { tiles: [...], npcs: [...] },
+ *         'dungeon': { tiles: [...], monsters: [...] }
+ *       }
+ *
+ *       return {
+ *         data: staticMaps[mapId],
+ *         component: StaticMapComponent,
+ *         width: 800,
+ *         height: 600
+ *       }
+ *     })
+ *   ])
+ * }
+ * ```
+ *
+ * @since 4.0.0
+ * @see {@link LoadMapOptions} for callback function signature
+ * @see {@link MapData} for return data structure
+ */
 export declare function provideLoadMap(options: LoadMapOptions): {
     provide: string;
     useFactory: (context: Context) => void;
 }[];
+export {};

package/dist/services/mmorpg.d.ts

@@ -4,17 +4,21 @@ import { RpgClientEngine } from '../RpgClientEngine';
 import { AbstractWebsocket } from './AbstractSocket';
 import { UpdateMapService } from '@rpgjs/common';
 interface MmorpgOptions {
-    host: string;
+    host?: string;
 }
 declare class BridgeWebsocket extends AbstractWebsocket {
     protected context: Context;
     private options;
     private socket;
-    constructor(context: Context, options: MmorpgOptions);
-    connection(): Promise<void>;
+    constructor(context: Context, options?: MmorpgOptions);
+    connection(listeners?: (data: any) => void): Promise<void>;
     on(key: string, callback: (data: any) => void): void;
     off(event: string, callback: (data: any) => void): void;
     emit(event: string, data: any): void;
+    updateProperties({ room }: {
+        room: any;
+    }): void;
+    reconnect(listeners?: (data: any) => void): Promise<void>;
 }
 declare class UpdateMapStandaloneService extends UpdateMapService {
     protected context: Context;

package/package.json

@@ -1,16 +1,12 @@
 {
   "name": "@rpgjs/client",
-  "version": "5.0.0-alpha.0",
+  "version": "5.0.0-alpha.10",
   "description": "RPGJS is a framework for creating RPG/MMORPG games",
   "main": "dist/index.js",
   "types": "./dist/index.d.ts",
   "publishConfig": {
     "access": "public"
   },
-  "scripts": {
-    "dev": "vite build --watch",
-    "build": "vite build"
-  },
   "keywords": [
     "rpg",
     "game",
@@ -20,21 +16,27 @@
   ],
   "author": "Samuel Ronce",
   "license": "MIT",
+  "peerDependencies": {
+    "@canvasengine/presets": "*",
+    "canvasengine": "*",
+    "pixi.js": "^8.9.2"
+  },
   "dependencies": {
-    "@canvasengine/presets": "2.0.0-beta.22",
-    "@rpgjs/common": "workspace:*",
+    "@rpgjs/common": "5.0.0-alpha.10",
     "@signe/di": "^2.3.3",
     "@signe/room": "^2.3.3",
     "@signe/sync": "^2.3.3",
-    "canvasengine": "2.0.0-beta.22",
-    "pixi.js": "^8.10.1",
     "rxjs": "^7.8.2"
   },
   "devDependencies": {
-    "@canvasengine/compiler": "2.0.0-beta.21",
+    "@canvasengine/compiler": "2.0.0-beta.22",
     "vite": "^6.2.5",
     "vite-plugin-dts": "^4.5.3",
     "vitest": "^3.1.1"
   },
-  "type": "module"
-}
+  "type": "module",
+  "scripts": {
+    "dev": "vite build --watch",
+    "build": "vite build"
+  }
+}

package/src/Game/{EffectManager.ts → AnimationManager.ts}

@@ -1,10 +1,10 @@
 import { generateUID, RpgCommonPlayer } from "@rpgjs/common";
 import { signal } from "canvasengine";
 
-export class EffectManager {
+export class AnimationManager {
   current = signal<any[]>([]);
 
-  displayEffect(params: any, player: RpgCommonPlayer) {
+  displayEffect(params: any, player: RpgCommonPlayer | { x: number, y: number }) {
     const id = generateUID();
     this.current().push({
       ...params,

package/src/Game/Object.ts

@@ -1,10 +1,14 @@
 import { RpgCommonPlayer } from "@rpgjs/common";
 import { trigger, signal } from "canvasengine";
+import { Subscription } from "rxjs";
 
 export abstract class RpgClientObject extends RpgCommonPlayer {
   abstract type: string;
   emitParticleTrigger = trigger()
   particleName = signal('')
+  animationCurrentIndex = signal(0)
+  animationIsPlaying = signal(false)
+  private animationSubscription?: Subscription
 
   flash(color: string, duration: number = 100) {
     const lastTint = this.tint()
@@ -13,4 +17,69 @@ export abstract class RpgClientObject extends RpgCommonPlayer {
       this.tint.set(lastTint)
     }, duration)
   }
+
+  /**
+   * Reset animation state when animation changes externally
+   * 
+   * This method should be called when the animation changes due to movement
+   * or other external factors to ensure the animation system doesn't get stuck
+   * 
+   * @example
+   * ```ts
+   * // Reset when player starts moving
+   * player.resetAnimationState();
+   * ```
+   */
+  resetAnimationState() {
+    this.animationIsPlaying.set(false);
+    this.animationCurrentIndex.set(0);
+    if (this.animationSubscription) {
+      this.animationSubscription.unsubscribe();
+      this.animationSubscription = undefined;
+    }
+  }
+
+  /**
+   * Set a custom animation for a specific number of times
+   * 
+   * Plays a custom animation for the specified number of repetitions.
+   * The animation system prevents overlapping animations and automatically
+   * returns to the previous animation when complete.
+   * 
+   * @param animationName - Name of the animation to play
+   * @param nbTimes - Number of times to repeat the animation (default: Infinity for continuous)
+   * 
+   * @example
+   * ```ts
+   * // Play attack animation 3 times
+   * player.setAnimation('attack', 3);
+   * 
+   * // Play continuous spell animation
+   * player.setAnimation('spell');
+   * ```
+   */
+  setAnimation(animationName: string, nbTimes: number = Infinity) {
+    if (this.animationIsPlaying()) return;
+    this.animationIsPlaying.set(true);
+    const previousAnimationName = this.animationName();
+    this.animationCurrentIndex.set(0);
+    
+    // Clean up any existing subscription
+    if (this.animationSubscription) {
+      this.animationSubscription.unsubscribe();
+    }
+    
+    this.animationSubscription = this.animationCurrentIndex.observable.subscribe(index => {
+      if (index >= nbTimes) {
+        this.animationCurrentIndex.set(0);
+        this.animationName.set(previousAnimationName);
+        this.animationIsPlaying.set(false);
+        if (this.animationSubscription) {
+          this.animationSubscription.unsubscribe();
+          this.animationSubscription = undefined;
+        }
+      }
+    })
+    this.animationName.set(animationName);
+  }
 }   

package/src/RpgClient.ts

@@ -1,9 +1,10 @@
+import { ComponentFunction } from 'canvasengine'
 import { RpgClientEngine } from './RpgClientEngine'
-import { Loader } from 'pixi.js'
+import { Loader, Container } from 'pixi.js'
 
 type RpgClass<T = any> = new (...args: any[]) => T
-type RpgComponent = any
-type SceneMap = any
+type RpgComponent = Container
+type SceneMap = Container
 
 export interface RpgClientEngineHooks {
     /**
@@ -12,7 +13,7 @@ export interface RpgClientEngineHooks {
      * @prop { (engine: RpgClientEngine) => boolean | any } [onStart]
      * @memberof RpgEngineHooks
      */
-    onStart?: (engine: RpgClientEngine) => boolean | void
+    onStart?: (engine: RpgClientEngine) => boolean | void | Promise<boolean | void>
 
     /**
      * Each frame
@@ -65,6 +66,36 @@ export interface RpgClientEngineHooks {
 }
 
 export interface RpgSpriteHooks {
+    /**
+     * Array of components to render behind the sprite
+     * These components will be displayed with a lower z-index than the sprite itself
+     * 
+     * @prop { ComponentFunction[] } [componentsBehind]
+     * @memberof RpgSpriteHooks
+     * @example
+     * ```ts
+     * const sprite: RpgSpriteHooks = {
+     *   componentsBehind: [ShadowComponent, AuraComponent]
+     * }
+     * ```
+     */
+    componentsBehind?: ComponentFunction[]
+    
+    /**
+     * Array of components to render in front of the sprite
+     * These components will be displayed with a higher z-index than the sprite itself
+     * 
+     * @prop { ComponentFunction[] } [componentsInFront]
+     * @memberof RpgSpriteHooks
+     * @example
+     * ```ts
+     * const sprite: RpgSpriteHooks = {
+     *   componentsInFront: [HealthBarComponent, StatusEffectComponent]
+     * }
+     * ```
+     */
+    componentsInFront?: ComponentFunction[]
+    
     /**
      * As soon as the sprite is initialized
      * 
@@ -178,14 +209,13 @@ export interface RpgClient {
      * @example
      * 
      * ```ts
-     * import { RpgClient, RpgModule } from '@rpgjs/client'
+     * import { RpgClient, defineModule } from '@rpgjs/client'
      * 
-     * @RpgModule<RpgClient>({
+     * defineModule<RpgClient>({
      *     hooks: {
      *        player: ['onAuth']
      *    }
      * })
-     * class RpgClientEngine { }
      * ```
      * 
      * Emit the hook:
@@ -224,7 +254,7 @@ export interface RpgClient {
      * Object containing the hooks concerning the engine
      * 
      * ```ts
-     * import { RpgClientEngine, RpgClientEngineHooks, RpgModule, RpgClient } from '@rpgjs/client'
+     * import { RpgClientEngine, RpgClientEngineHooks, defineModule, RpgClient } from '@rpgjs/client'
      * 
      * const engine: RpgClientEngineHooks = {
      *      onConnected(engine: RpgClientEngine) {
@@ -232,10 +262,9 @@ export interface RpgClient {
      *      }
      * }
      * 
-     * @RpgModule<RpgClient>({
+     * defineModule<RpgClient>({
      *      engine
      * })
-     * class RpgClientModule {}
      * ```
      * 
      * @prop {RpgClientEngineHooks} [engine]
@@ -245,29 +274,32 @@ export interface RpgClient {
 
     /** 
      * Array containing the list of spritesheets
-     * An element contains a class with the `@Spritesheet` decorator
+     * Each element is a simple object containing spritesheet definitions
      * 
      * ```ts
-     * import { Spritesheet, Animation, Direction, RpgClient, RpgModule } from '@rpgjs/client'
-     * 
-     * @Spritesheet({
-     *      id: 'chest',
-     *      image: require('./assets/chest.png'),
-     *      // other options
-     * })
-     * class Chest  { }
+     * import { defineModule, RpgClient } from '@rpgjs/client'
      * 
-     * @RpgModule<RpgClient>({
+     * defineModule<RpgClient>({
      *      spritesheets: [
-     *          Chest
+     *          {
+     *              id: 'chest',
+     *              image: require('./assets/chest.png'),
+     *              framesWidth: 32,
+     *              framesHeight: 32,
+     *              animations: {
+     *                  default: {
+     *                      frames: [0, 1, 2],
+     *                      duration: 1000
+     *                  }
+     *              }
+     *          }
      *      ]
      * })
-     * class RpgClientEngine {}
      * ```
      * 
      * [Guide: Create Sprite](/guide/create-sprite.html)
      * 
-     * @prop {Array<Class>} [spritesheets]
+     * @prop {Array<Object>} [spritesheets]
      * @memberof RpgClient
      * */
     spritesheets?: any[],
@@ -275,72 +307,49 @@ export interface RpgClient {
     /** 
      * Array containing the list of VueJS components
      * 
-     * ```ts
-     * import { RpgClient, RpgModule } from '@rpgjs/client'
-     * 
-     * const component = {
-     *      name: 'my-gui',
-     *      template: `
-     *          <div>
-     *              Component
-     *          </div>
-     *      `
-     * }
-     * 
-     * @RpgModule<RpgClient>({
-     *      gui: [
-     *          component
-     *      ]
-     * })
-     * class RpgClientEngine {}
-     * ```
      * 
      * [Guide: Create GUI](/guide/create-gui.html)
      * 
-     * @prop {Array<Component of VueJS>} [gui]
+     * @prop {Array<Component of CanvasEngine>} [gui]
      * @memberof RpgClient
      * */
-    gui?: any[],
+    gui?: ComponentFunction[],
 
     /** 
      * Array containing the list of sounds
-     * An element contains a class with the `@Sound` decorator
+     * Each element is a simple object containing sound definitions
      * 
      * ```ts
-     * import { Sound, RpgModule, RpgClient } from '@rpgjs/client'
-     * 
-     * @Sound({
-     *      sounds: {
-     *          town: require('./assets/Town_Theme.ogg')
-     *      }
-     * })
-     * class Sounds {}
-     * 
-     * @RpgModule<RpgClient>({
-     *      sounds: [ Sounds ]
+     * import { defineModule, RpgClient } from '@rpgjs/client'
+     * 
+     * defineModule<RpgClient>({
+     *      sounds: [
+     *          {
+     *              town: require('./assets/Town_Theme.ogg'),
+     *              battle: require('./assets/Battle_Theme.ogg')
+     *          }
+     *      ]
      * })
-     * class RpgClientEngine {}
      * ```
      * 
-     * @prop {Array<Class>} [sounds]
+     * @prop {Array<Object>} [sounds]
      * @memberof RpgClient
      * */
-    sounds?: RpgClass[],
+    sounds?: any[],
 
     /** 
      * Give the `RpgSprite` class. A Sprite represents a player or an event
      * 
      * ```ts
-     * import { RpgSprite, RpgSpriteHooks, RpgClient, RpgModule } from '@rpgjs/client'
+     * import { RpgSprite, RpgSpriteHooks, RpgClient, defineModule } from '@rpgjs/client'
      * 
      * export const sprite: RpgSpriteHooks = {
      *    onInit(sprite: RpgSprite) {}
      * }
      * 
-     * @RpgModule<RpgClient>({
+     * defineModule<RpgClient>({
      *      sprite
      * })
-     * class RpgClientEngine {}
      * ``` 
      * 
      * @prop {RpgSpriteHooks} [sprite]
@@ -352,19 +361,18 @@ export interface RpgClient {
      * Reference the scenes of the game. Here you can put your own class that inherits RpgSceneMap
      * 
      * ```ts
-     * import { RpgSceneMapHooks, RpgClient, RpgModule } from '@rpgjs/client'
+     * import { RpgSceneMapHooks, RpgClient, defineModule } from '@rpgjs/client'
      * 
      * export const sceneMap: RpgSceneMapHooks = {
      *     
      * }
      * 
-     * @RpgModule<RpgClient>({
+     * defineModule<RpgClient>({
      *      scenes: {
      *          // If you put the RpgSceneMap scene, Thhe key is called mandatory `map`
      *          map: sceneMap
      *      }
      * })
-     * class RpgClientEngine {}
      * ``` 
      * 
      * @prop { [sceneName: string]: RpgSceneMapHooks } [scenes]
@@ -374,8 +382,34 @@ export interface RpgClient {
         map: RpgSceneMapHooks
     }
 
-    effects?: {
+    /** 
+     * Array containing the list of component animations
+     * Each element defines a temporary component to display for animations like hits, effects, etc.
+     * 
+     * ```ts
+     * import { defineModule, RpgClient } from '@rpgjs/client'
+     * import HitComponent from './hit.ce'
+     * import ExplosionComponent from './explosion.ce'
+     * 
+     * defineModule<RpgClient>({
+     *      componentAnimations: [
+     *          {
+     *              id: 'hit',
+     *              component: HitComponent
+     *          },
+     *          {
+     *              id: 'explosion',
+     *              component: ExplosionComponent
+     *          }
+     *      ]
+     * })
+     * ```
+     * 
+     * @prop {Array<{id: string, component: ComponentFunction}>} [componentAnimations]
+     * @memberof RpgClient
+     * */
+    componentAnimations?: {
         id: string,
-        component: any
+        component: ComponentFunction
     }[]
 }