@rpgjs/client 5.0.0-alpha.3 → 5.0.0-alpha.30

package/src/module.ts

@@ -1,14 +1,69 @@
 import { findModules, provideModules } from "@rpgjs/common";
+import { FactoryProvider } from "@signe/di";
 import { RpgClientEngine } from "./RpgClientEngine";
 import { RpgClient } from "./RpgClient";
 import { inject } from "@signe/di";
 import { RpgGui } from "./Gui/Gui";
+import { getSoundMetadata } from "./Sound";
 
-export function provideClientModules(modules: RpgClient[]) {
+/**
+ * Type for client modules that can be either:
+ * - An object implementing RpgClient interface
+ * - A class decorated with @RpgModule decorator
+ */
+export type RpgClientModule = RpgClient | (new () => any);
+
+/**
+ * Provides client modules configuration to Dependency Injection
+ * 
+ * This function accepts an array of client modules that can be either:
+ * - Objects implementing the RpgClient interface
+ * - Classes decorated with the @RpgModule decorator (which will be instantiated)
+ * 
+ * @param modules - Array of client modules (objects or classes)
+ * @returns FactoryProvider configuration for DI
+ * @example
+ * ```ts
+ * // Using an object
+ * provideClientModules([
+ *   {
+ *     engine: {
+ *       onConnected(engine) {
+ *         console.log('Client connected')
+ *       }
+ *     }
+ *   }
+ * ])
+ * 
+ * // Using a decorated class
+ * @RpgModule<RpgClient>({
+ *   engine: {
+ *     onStart(engine) {
+ *       console.log('Client started')
+ *     }
+ *   }
+ * })
+ * class MyClientModule {}
+ * 
+ * provideClientModules([MyClientModule])
+ * ```
+ */
+export function provideClientModules(modules: RpgClientModule[]): FactoryProvider {
   return provideModules(modules, "client", (modules, context) => {
     const mainModuleClient = findModules(context, 'Client')
     modules = [...mainModuleClient, ...modules]
     modules = modules.map((module) => {
+      // If module is a class (constructor function), instantiate it
+      // The RpgModule decorator adds properties to the prototype, which will be accessible via the instance
+      if (typeof module === 'function') {
+        const instance = new module() as any;
+        // Copy all enumerable properties (including from prototype) to a plain object
+        const moduleObj: any = {};
+        for (const key in instance) {
+          moduleObj[key] = instance[key];
+        }
+        module = moduleObj;
+      }
       if ('client' in module) {
         module = module.client as any;
       }
@@ -22,33 +77,95 @@ export function provideClientModules(modules: RpgClient[]) {
           },
         };
       }
+      if (module.spritesheetResolver) {
+        const resolver = module.spritesheetResolver;
+        module.spritesheetResolver = {
+          load: (engine: RpgClientEngine) => {
+            engine.setSpritesheetResolver(resolver);
+          },
+        };
+      }
       if (module.sounds) {
         const sounds = [...module.sounds];
         module.sounds = {
           load: (engine: RpgClientEngine) => {
             sounds.forEach((sound) => {
-              engine.addSound(sound);
+              // Check if it's a class decorated with @Sound
+              if (typeof sound === 'function' || (sound && sound.constructor && sound.constructor !== Object)) {
+                const metadata = getSoundMetadata(sound);
+                if (metadata) {
+                  // Handle single sound
+                  if (metadata.id && metadata.sound) {
+                    engine.addSound({
+                      id: metadata.id,
+                      src: metadata.sound,
+                      loop: metadata.loop,
+                      volume: metadata.volume,
+                    });
+                  }
+                  // Handle multiple sounds
+                  if (metadata.sounds) {
+                    Object.entries(metadata.sounds).forEach(([soundId, soundSrc]) => {
+                      engine.addSound({
+                        id: soundId,
+                        src: soundSrc,
+                        loop: metadata.loop,
+                        volume: metadata.volume,
+                      });
+                    });
+                  }
+                } else {
+                  // Not a decorated class, treat as regular sound object
+                  engine.addSound(sound);
+                }
+              } else {
+                // Regular sound object
+                engine.addSound(sound);
+              }
             });
           },
         };
       }
+      if (module.soundResolver) {
+        const resolver = module.soundResolver;
+        module.soundResolver = {
+          load: (engine: RpgClientEngine) => {
+            engine.setSoundResolver(resolver);
+          },
+        };
+      }
       if (module.gui) {
         const gui = [...module.gui];
         module.gui = {
           load: (engine: RpgClientEngine) => {
-            const guiService = inject(engine.context, RpgGui);
+            const guiService = inject(engine.context, RpgGui) as RpgGui;
             gui.forEach((gui) => {
               guiService.add(gui);
             });
           },
         };
       }
-      if (module.effects) {
-        const effects = [...module.effects];
-        module.effects = {
+      if (module.componentAnimations) {
+        const componentAnimations = [...module.componentAnimations];
+        module.componentAnimations = {
           load: (engine: RpgClientEngine) => {
-            effects.forEach((effect) => {
-              engine.addEffect(effect);
+            componentAnimations.forEach((componentAnimation) => {
+              engine.addComponentAnimation(componentAnimation);
+            });
+          },
+        };
+      }
+      if (module.transitions) {
+        const transitions = [...module.transitions];
+        module.transitions = {
+          load: (engine: RpgClientEngine) => {
+            const guiService = inject(engine.context, RpgGui) as RpgGui;
+            transitions.forEach((transition) => {
+              guiService.add({
+                name: transition.id,
+                component: transition.component,
+                data: transition.props || {}
+              });
             });
           },
         };
@@ -63,6 +180,24 @@ export function provideClientModules(modules: RpgClient[]) {
           },
         };
       }
+      if (module.sprite) {
+        const sprite = {...module.sprite};
+        module.sprite = {
+          ...sprite,
+          load: (engine: RpgClientEngine) => {
+            if (sprite.componentsBehind) {
+              sprite.componentsBehind.forEach((component) => {
+                engine.addSpriteComponentBehind(component);
+              });
+            }
+            if (sprite.componentsInFront) {
+              sprite.componentsInFront.forEach((component) => {
+                engine.addSpriteComponentInFront(component);
+              });
+            }
+          },
+        };
+      }
       return module;
     });
     return modules
@@ -85,7 +220,8 @@ export function provideClientGlobalConfig(config: any = {}) {
       down: 'down',
       left: 'left',
       right: 'right',
-      action: 'space'
+      action: 'space',
+      escape: 'escape'
     }
   }
   return provideGlobalConfig(config)

package/src/presets/animation.ts

@@ -0,0 +1,46 @@
+/**
+ * Creates an animation spritesheet preset with automatic frame generation
+ * 
+ * This function generates animation frames based on the provided width and height dimensions.
+ * It creates a sequence of frames that progresses through the spritesheet from left to right,
+ * top to bottom, with each frame having a 10ms time increment.
+ * 
+ * @param {number} framesWidth - The number of frames horizontally in the spritesheet
+ * @param {number} framesHeight - The number of frames vertically in the spritesheet
+ * @returns {Object} Animation preset configuration object
+ * 
+ * @example
+ * ```javascript
+ * // For a 4x4 spritesheet
+ * const preset = AnimationSpritesheetPreset(4, 4);
+ * // This will generate 16 frames with coordinates from (0,0) to (3,3)
+ * ```
+ */
+export const AnimationSpritesheetPreset = (framesWidth: number, framesHeight: number) => {
+    
+    const animations: Array<{ time: number; frameX: number; frameY: number }> = [];
+
+    for (let y = 0; y < framesHeight; y++) {
+        for (let x = 0; x < framesWidth; x++) {
+            const frameIndex = y * framesWidth + x;
+            animations.push({ 
+                time: frameIndex * 10, 
+                frameX: x, 
+                frameY: y 
+            });
+        }
+    }
+    
+    return {
+        framesWidth,
+        framesHeight,
+        textures: {
+            default: {
+                animations: () => [
+                    animations
+                ],
+            }
+        }
+    };
+};
+  

package/src/presets/faceset.ts

@@ -0,0 +1,60 @@
+/**
+ * Creates a faceset preset for character expressions
+ * 
+ * This preset allows you to define multiple facial expressions for a character,
+ * where each expression corresponds to a specific frame position (frameX, frameY)
+ * within a single faceset texture. Each expression is defined by its position
+ * in the faceset grid.
+ * 
+ * @param options - Object containing the faceset configuration
+ * @param framesWidth - Number of frames horizontally in the faceset texture
+ * @param framesHeight - Number of frames vertically in the faceset texture
+ * @param expressions - Object mapping expression names to their frame positions as tuples [frameX, frameY]
+ * @returns Faceset configuration with animations for each expression
+ * 
+ * @example
+ * ```typescript
+ * const faceset = FacesetPreset({
+ *   id: "facesetId",
+ *   image: "faceset.png",
+ *   width: 1024,
+ *   height: 1024,
+ * }, 4, 2, {
+ *   happy: [0, 0],
+ *   sad: [1, 0],
+ *   angry: [2, 0],
+ *   surprised: [3, 0]
+ * });
+ * ```
+ */
+export const FacesetPreset = (
+    options: any,
+    framesWidth: number, 
+    framesHeight: number,
+    expressions: Record<string, [number, number]>,
+) => {
+    
+    const textures: Record<string, any> = {};
+    
+    // Create texture configuration for each expression
+    Object.keys(expressions).forEach((expressionName) => {
+        const [frameX, frameY] = expressions[expressionName];
+        textures[expressionName] = {
+            animations: () => [
+                [{ 
+                    time: 0, 
+                    frameX: frameX, 
+                    frameY: frameY 
+                }]
+            ],
+        };
+    });
+    
+    return {
+        ...options,
+        framesWidth,
+        framesHeight,
+        textures
+    };
+};
+  

package/src/presets/icon.ts

@@ -0,0 +1,17 @@
+export const IconPreset = (options: {
+    image: string;
+    framesWidth: number;
+    framesHeight: number;
+    id: string;
+}) => {
+    return {
+        textures: {
+            default: {
+                animations: () => [
+                    [{ time: 0, frameX: 0, frameY: 0 }]
+                ]
+            }
+        },
+        ...options
+    }
+}

package/src/presets/index.ts

@@ -1,5 +1,13 @@
+import { AnimationSpritesheetPreset } from "./animation";
+import { LPCSpritesheetPreset } from "./lpc";
 import { RMSpritesheet } from "./rmspritesheet";
+import { FacesetPreset } from "./faceset";
+import { IconPreset } from "./icon";
 
 export const Presets = {
-    RMSpritesheet
+    RMSpritesheet,
+    LPCSpritesheetPreset,
+    AnimationSpritesheetPreset,
+    FacesetPreset,
+    IconPreset
 }

package/src/presets/lpc.ts

@@ -0,0 +1,108 @@
+import { Animation, Direction } from "@rpgjs/common";
+
+export const LPCSpritesheetPreset = (options: {
+    id: string;
+    imageSource: string;
+    width: number;
+    height: number;
+    ratio?: number;
+  }) => {
+    const ratio = options.ratio ?? 1;
+
+    const frameY = (direction: Direction) => {
+      return {
+        [Direction.Down]: 2,
+        [Direction.Left]: 1,
+        [Direction.Right]: 3,
+        [Direction.Up]: 0,
+      }[direction];
+    };
+  
+    const stand = (direction: Direction) => [
+      { time: 0, frameX: 0, frameY: frameY(direction) },
+    ];
+    const anim = (
+      direction: Direction,
+      framesWidth: number,
+      speed: number = 5
+    ) => {
+      const array: any = [];
+      for (let i = 0; i < framesWidth; i++) {
+        array.push({ time: i * speed, frameX: i, frameY: frameY(direction) });
+      }
+      return array;
+    };
+  
+    return {
+      id: options.id,
+      image: options.imageSource,
+      width: options.width,
+      height: options.height,
+      opacity: 1,
+      rectWidth: 64 * ratio,
+      rectHeight: 64 * ratio,
+      framesWidth: 6,
+      framesHeight: 4,
+      spriteRealSize: {
+        width: 48 * ratio,
+        height: 52 * ratio,
+      },
+      textures: {
+        [Animation.Stand]: {
+          offset: {
+            x: 0,
+            y: 512 * ratio,
+          },
+          animations: ({ direction }) => [stand(direction)],
+        },
+        [Animation.Walk]: {
+          offset: {
+            x: 0,
+            y: 512 * ratio,
+          },
+          framesWidth: 9,
+          framesHeight: 4,
+          animations: ({ direction }) => [anim(direction, 9)],
+        },
+        [Animation.Attack]: {
+          offset: {
+            x: 0,
+            y: 768 * ratio,
+          },
+          framesWidth: 6,
+          framesHeight: 4,
+          animations: ({ direction }) => [anim(direction, 6, 3)],
+        },
+        [Animation.Skill]: {
+          framesWidth: 7,
+          framesHeight: 4,
+          animations: ({ direction }) => [anim(direction, 7, 3)],
+        },
+        attack2: {
+          offset: {
+            x: 0,
+            y: 256 * ratio,
+          },
+          framesWidth: 7,
+          framesHeight: 8,
+          animations: ({ direction }) => [anim(direction, 7, 3)],
+        },
+        ...(options.height > 3000
+          ? {
+              attack3: {
+                offset: {
+                  x: 0,
+                  y: 5568 - 288 * 4,
+                },
+                rectWidth: 288,
+                rectHeight: 288,
+                framesWidth: 6,
+                framesHeight: 4,
+                animations: ({ direction }) => [anim(direction, 6, 3)],
+              },
+            }
+          : {}),
+      },
+    };
+  };
+  

package/src/services/keyboardControls.ts

@@ -0,0 +1,20 @@
+import { KeyboardControls  } from "canvasengine";
+
+export enum Control {
+  Action = 'action',
+  Attack = 'attack',
+  Defense = 'defense',
+  Skill = 'skill',
+  Back = 'back',
+  Up = 1,
+  Down = 3,
+  Right = 2,
+  Left = 4
+}
+
+export function provideKeyboardControls() {
+  return {
+    provide: 'KeyboardControls',
+    useValue: null,
+  };
+}

package/src/services/loadMap.ts

@@ -3,27 +3,156 @@ import { UpdateMapToken, UpdateMapService } from "@rpgjs/common";
 
 export 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 class LoadMapService {
   private updateMapService: UpdateMapService;
 
   constructor(private context: Context, private options: LoadMapOptions) {
+    if (context['side'] === 'server') {
+      return
+    }
     this.updateMapService = inject(context, UpdateMapToken);
   }
 
   async load(mapId: string) {
     const map = await this.options(mapId.replace('map-', ''))
-    await this.updateMapService.update(mapId, map);
+    await this.updateMapService.update(map);
     return map;
   }
 }
 
+/**
+ * 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 function provideLoadMap(options: LoadMapOptions) {
   return [
     {
       provide: UpdateMapToken,
-      useFactory: (context: Context) => console.warn('UpdateMapToken is not overridden'),
+      useFactory: (context: Context) => {
+        if (context['side'] === 'client') {
+          console.warn('UpdateMapToken is not overridden')
+        }
+        return
+      },
     },
     {
       provide: LoadMapToken,