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

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) => {
+            componentAnimations.forEach((componentAnimation) => {
+              engine.addComponentAnimation(componentAnimation);
+            });
+          },
+        };
+      }
+      if (module.transitions) {
+        const transitions = [...module.transitions];
+        module.transitions = {
           load: (engine: RpgClientEngine) => {
-            effects.forEach((effect) => {
-              engine.addEffect(effect);
+            const guiService = inject(engine.context, RpgGui) as RpgGui;
+            transitions.forEach((transition) => {
+              guiService.add({
+                name: transition.id,
+                component: transition.component,
+                data: transition.props || {}
+              });
             });
           },
         };
@@ -103,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/AbstractSocket.ts

@@ -2,6 +2,14 @@ import { Context } from "@signe/di";
 
 export const WebSocketToken = "websocket";
 
+export type SocketQueryValue = string | null | undefined;
+export type SocketQuery = Record<string, SocketQueryValue>;
+export type SocketUpdateProperties = {
+  room: string;
+  host?: string;
+  query?: SocketQuery;
+};
+
 export abstract class AbstractWebsocket {
   constructor(protected context: Context) {}
 
@@ -9,6 +17,6 @@ export abstract class AbstractWebsocket {
   abstract emit(event: string, data: any): void;
   abstract on(event: string, callback: (data: any) => void): void;
   abstract off(event: string, callback: (data: any) => void): void;
-  abstract updateProperties(params: { room: string, host?: string }): void;
-  abstract reconnect(listeners?: (data: any) => void): void;
+  abstract updateProperties(params: SocketUpdateProperties): void;
+  abstract reconnect(listeners?: (data: any) => void): Promise<void>;
 }

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

@@ -47,7 +47,7 @@ export class LoadMapService {
 
   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;
   }
 }

package/src/services/mmorpg.ts

@@ -2,18 +2,53 @@ import { Context } from "@signe/di";
 import { connectionRoom } from "@signe/sync/client";
 import { RpgGui } from "../Gui/Gui";
 import { RpgClientEngine } from "../RpgClientEngine";
-import { AbstractWebsocket, WebSocketToken } from "./AbstractSocket";
+import { AbstractWebsocket, SocketUpdateProperties, WebSocketToken } from "./AbstractSocket";
 import { UpdateMapService, UpdateMapToken } from "@rpgjs/common";
+import { provideKeyboardControls } from "./keyboardControls";
+import { provideSaveClient } from "./save";
 
 interface MmorpgOptions {
     host?: string;
+    connectionId?: string;
+    connectionIdScope?: "local" | "session" | "ephemeral";
 }
 
 class BridgeWebsocket extends AbstractWebsocket {
-    private socket: any;
+  private socket: any;
+  private privateId: string;
+  private pendingOn: Array<{ event: string; callback: (data: any) => void }> = [];
+  private targetRoom = "lobby-1";
 
   constructor(protected context: Context, private options: MmorpgOptions = {}) {
     super(context);
+    this.privateId = this.resolveConnectionId();
+  }
+
+  private resolveConnectionId(): string {
+    if (this.options.connectionId) {
+      return this.options.connectionId;
+    }
+
+    const scope = this.options.connectionIdScope ?? "local";
+    const key = "rpgjs-user-id";
+
+    if (scope === "ephemeral") {
+      return crypto.randomUUID();
+    }
+
+    const storage =
+      scope === "session"
+        ? window.sessionStorage
+        : window.localStorage;
+
+    const existing = storage.getItem(key);
+    if (existing) {
+      return existing;
+    }
+
+    const id = crypto.randomUUID();
+    storage.setItem(key, id);
+    return id;
   }
 
   async connection(listeners?: (data: any) => void) {
@@ -22,19 +57,28 @@ class BridgeWebsocket extends AbstractWebsocket {
         
     }
     const instance = new Room()
+    const host = this.options.host || window.location.host;
     this.socket = await connectionRoom({
-        host: this.options.host || window.location.host,
-        room: "lobby-1",
+        host,
+        room: this.targetRoom,
+        id: this.privateId
     }, instance)
 
     listeners?.(this.socket)
+    this.pendingOn.forEach(({ event, callback }) => this.socket.on(event, callback));
+    this.pendingOn = [];
   }
 
   on(key: string, callback: (data: any) => void) {
+    if (!this.socket) {
+      this.pendingOn.push({ event: key, callback });
+      return;
+    }
     this.socket.on(key, callback);
   }
 
   off(event: string, callback: (data: any) => void) {
+    if (!this.socket) return;
     this.socket.off(event, callback);
   }
 
@@ -42,25 +86,67 @@ class BridgeWebsocket extends AbstractWebsocket {
     this.socket.emit(event, data);
   }
 
-  updateProperties({ room }: { room: any }) {
+  updateProperties({ room, host, query }: SocketUpdateProperties) {
+    if (!this.socket?.conn) return;
+    this.targetRoom = room;
     this.socket.conn.updateProperties({
-      room: room,
-      host: this.options.host
+      room,
+      id: this.privateId,
+      host: host || this.options.host || window.location.host,
+      query,
     })
   }
 
-  async reconnect(listeners?: (data: any) => void) {
-   this.socket.conn.reconnect()
+  private waitForNextOpen(conn: any, timeoutMs = 10000): Promise<void> {
+    return new Promise((resolve, reject) => {
+      let timeoutId: number | undefined;
+      const onOpen = () => {
+        cleanup();
+        resolve();
+      };
+      const onError = () => {
+        cleanup();
+        reject(new Error("WebSocket reconnect failed"));
+      };
+      const cleanup = () => {
+        conn.removeEventListener("open", onOpen);
+        conn.removeEventListener("error", onError);
+        if (timeoutId !== undefined) {
+          window.clearTimeout(timeoutId);
+        }
+      };
+
+      conn.addEventListener("open", onOpen);
+      conn.addEventListener("error", onError);
+      timeoutId = window.setTimeout(() => {
+        cleanup();
+        reject(new Error("WebSocket reconnect timeout"));
+      }, timeoutMs);
+    });
+  }
+
+  async reconnect(_listeners?: (data: any) => void): Promise<void> {
+    if (!this.socket?.conn) return;
+    const conn = this.socket.conn;
+    const opened = this.waitForNextOpen(conn);
+    conn.reconnect();
+    await opened;
+  }
+
+  getCurrentRoom(): string {
+    return this.targetRoom || this.socket?.conn?.room || "lobby-1";
   }
 }
 
 class UpdateMapStandaloneService extends UpdateMapService {
-  constructor(protected context: Context, private options: MmorpgOptions) {
+  constructor(protected context: Context, private _options: MmorpgOptions) {
     super(context);
   }
 
-  async update(map: any) {
-    // nothing
+  async update(_map: any) {
+    // In MMORPG mode, clients are untrusted and must not push map definitions.
+    // Map bootstrap/update is handled server-side by @rpgjs/vite.
+    return;
   }
 }
 
@@ -74,6 +160,8 @@ export function provideMmorpg(options: MmorpgOptions) {
       provide: UpdateMapToken,
       useFactory: (context: Context) => new UpdateMapStandaloneService(context, options),
     },
+    provideKeyboardControls(),
+    provideSaveClient(),
     RpgGui,
     RpgClientEngine,
   ];