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

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

@@ -20,6 +20,8 @@ type MapData = {
   height?: number;
   /** Optional map events data (NPCs, interactive objects, etc.) */
   events?: any;
+  /** Optional named positions, for example Tiled point objects used by changeMap("map", "name") */
+  positions?: Record<string, { x: number; y: number; z?: number }>;
   /** Optional map identifier, defaults to the mapId parameter if not provided */
   id?: string;
 }
@@ -47,7 +49,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,31 @@ 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,
+        query: {
+          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 +89,70 @@ 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: {
+        ...query,
+        id: this.privateId,
+      },
     })
   }
 
-  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 +166,8 @@ export function provideMmorpg(options: MmorpgOptions) {
       provide: UpdateMapToken,
       useFactory: (context: Context) => new UpdateMapStandaloneService(context, options),
     },
+    provideKeyboardControls(),
+    provideSaveClient(),
     RpgGui,
     RpgClientEngine,
   ];

package/src/services/save.spec.ts

@@ -0,0 +1,127 @@
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import { SaveClientService, provideSaveClient } from "./save";
+
+const createSocket = () => {
+  const listeners = new Map<string, (data: any) => void>();
+  const emitted: Array<{ event: string; data: any }> = [];
+
+  return {
+    listeners,
+    emitted,
+    on: vi.fn((event: string, callback: (data: any) => void) => {
+      listeners.set(event, callback);
+    }),
+    off: vi.fn((event: string) => {
+      listeners.delete(event);
+    }),
+    emit: vi.fn((event: string, data: any) => {
+      emitted.push({ event, data });
+    }),
+  };
+};
+
+const createService = (socket = createSocket()) => {
+  const service = Object.create(SaveClientService.prototype) as SaveClientService;
+  (service as any).webSocket = socket;
+  (service as any).pending = new Map();
+  (service as any).requestCounter = 0;
+  return { service, socket };
+};
+
+describe("SaveClientService", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date("2026-01-02T03:04:05.000Z"));
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  test("registers save result listeners idempotently", () => {
+    const { service, socket } = createService();
+
+    service.initialize();
+
+    expect(socket.off).toHaveBeenCalledTimes(4);
+    expect(socket.on).toHaveBeenCalledTimes(4);
+    expect([...socket.listeners.keys()]).toEqual([
+      "save.list.result",
+      "save.save.result",
+      "save.load.result",
+      "save.error",
+    ]);
+  });
+
+  test("lists, saves and loads slots through request/response events", async () => {
+    const { service, socket } = createService();
+    service.initialize();
+
+    const listPromise = service.listSlots();
+    expect(socket.emitted[0]).toEqual({
+      event: "save.list",
+      data: { requestId: "1767323045000-1" },
+    });
+    socket.listeners.get("save.list.result")?.({
+      requestId: "1767323045000-1",
+      slots: [{ id: "slot-a" }],
+    });
+    await expect(listPromise).resolves.toEqual([{ id: "slot-a" }]);
+
+    const savePromise = service.saveSlot(2, { map: "forest" } as any);
+    expect(socket.emitted[1]).toEqual({
+      event: "save.save",
+      data: {
+        requestId: "1767323045000-2",
+        index: 2,
+        meta: { map: "forest" },
+      },
+    });
+    socket.listeners.get("save.save.result")?.({
+      requestId: "1767323045000-2",
+      index: 2,
+      slots: [null, null, { id: "slot-c" }],
+    });
+    await expect(savePromise).resolves.toEqual([null, null, { id: "slot-c" }]);
+
+    const loadPromise = service.loadSlot(2);
+    expect(socket.emitted[2]).toEqual({
+      event: "save.load",
+      data: { requestId: "1767323045000-3", index: 2 },
+    });
+    socket.listeners.get("save.load.result")?.({
+      requestId: "1767323045000-3",
+      index: 2,
+      ok: true,
+    });
+    await expect(loadPromise).resolves.toBe(true);
+  });
+
+  test("rejects matching pending requests on save errors and ignores stale responses", async () => {
+    const { service, socket } = createService();
+    service.initialize();
+
+    const listPromise = service.listSlots();
+
+    socket.listeners.get("save.list.result")?.({
+      requestId: "unknown",
+      slots: [{ id: "stale" }],
+    });
+    expect((service as any).pending.size).toBe(1);
+
+    socket.listeners.get("save.error")?.({
+      requestId: "1767323045000-1",
+      message: "Cannot save",
+    });
+
+    await expect(listPromise).rejects.toThrow("Cannot save");
+    expect((service as any).pending.size).toBe(0);
+  });
+
+  test("provides the client save service class", () => {
+    expect(provideSaveClient()).toEqual({
+      provide: SaveClientService,
+      useClass: SaveClientService,
+    });
+  });
+});

package/src/services/save.ts

@@ -0,0 +1,103 @@
+import type { SaveSlotList, SaveSlotMeta } from "@rpgjs/common";
+import { inject } from "../core/inject";
+import { AbstractWebsocket, WebSocketToken } from "./AbstractSocket";
+
+export const SaveClientToken = "SaveClientToken";
+
+type SaveListResult = {
+  requestId: string;
+  slots: SaveSlotList;
+};
+
+type SaveSaveResult = {
+  requestId: string;
+  index: number;
+  slots: SaveSlotList;
+};
+
+type SaveLoadResult = {
+  requestId: string;
+  index: number;
+  ok: boolean;
+  slot?: SaveSlotMeta;
+};
+
+type SaveErrorResult = {
+  requestId: string;
+  message: string;
+};
+
+type PendingRequest = {
+  resolve: (value: any) => void;
+  reject: (error: Error) => void;
+};
+
+export class SaveClientService {
+  private webSocket: AbstractWebsocket = inject(WebSocketToken);
+  private pending: Map<string, PendingRequest> = new Map();
+  private requestCounter = 0;
+
+  initialize() {
+    const saveListResult = (data: SaveListResult) => this.resolveRequest(data.requestId, data);
+    const saveSaveResult = (data: SaveSaveResult) => this.resolveRequest(data.requestId, data);
+    const saveLoadResult = (data: SaveLoadResult) => this.resolveRequest(data.requestId, data);
+    const saveErrorResult = (data: SaveErrorResult) => this.rejectRequest(data.requestId, data.message);
+    this.webSocket.off("save.list.result", saveListResult);
+    this.webSocket.off("save.save.result", saveSaveResult);
+    this.webSocket.off("save.load.result", saveLoadResult);
+    this.webSocket.off("save.error", saveErrorResult);
+    this.webSocket.on("save.list.result", saveListResult);
+    this.webSocket.on("save.save.result", saveSaveResult);
+    this.webSocket.on("save.load.result", saveLoadResult);
+    this.webSocket.on("save.error", saveErrorResult);
+  }
+
+  listSlots(): Promise<SaveSlotList> {
+    return this.request<SaveListResult>("save.list", {}).then((result) => result.slots);
+  }
+
+  saveSlot(index: number, meta: SaveSlotMeta = {}): Promise<SaveSlotList> {
+    return this.request<SaveSaveResult>("save.save", { index, meta }).then((result) => result.slots);
+  }
+
+  loadSlot(index: number): Promise<boolean> {
+    return this.request<SaveLoadResult>("save.load", { index }).then((result) => result.ok);
+  }
+
+  private request<T>(event: string, payload: Record<string, any>): Promise<T> {
+    return new Promise((resolve, reject) => {
+      if (!this.webSocket) {
+        this.initialize();
+      }
+      const requestId = this.nextRequestId();
+      this.pending.set(requestId, { resolve, reject });
+      this.webSocket?.emit(event, { requestId, ...payload });
+    });
+  }
+
+  private resolveRequest(requestId: string, result: any) {
+    const pending = this.pending.get(requestId);
+    if (!pending) return;
+    this.pending.delete(requestId);
+    pending.resolve(result);
+  }
+
+  private rejectRequest(requestId: string, message: string) {
+    const pending = this.pending.get(requestId);
+    if (!pending) return;
+    this.pending.delete(requestId);
+    pending.reject(new Error(message));
+  }
+
+  private nextRequestId(): string {
+    this.requestCounter += 1;
+    return `${Date.now()}-${this.requestCounter}`;
+  }
+}
+
+export function provideSaveClient() {
+  return {
+    provide: SaveClientService,
+    useClass: SaveClientService,
+  };
+}

package/src/services/standalone.ts

@@ -1,29 +1,55 @@
-import { AbstractWebsocket, WebSocketToken } from "./AbstractSocket";
+import { AbstractWebsocket, SocketUpdateProperties, WebSocketToken } from "./AbstractSocket";
 import { ClientIo, ServerIo } from "@signe/room";
 import { Context } from "@signe/di";
 import { RpgClientEngine } from "../RpgClientEngine";
 import { UpdateMapService, UpdateMapToken } from "@rpgjs/common";
 import { LoadMapToken } from "./loadMap";
 import { RpgGui } from "../Gui/Gui";
+import { provideKeyboardControls } from "./keyboardControls";
+import { provideSaveClient } from "./save";
 
 type ServerIo = any;
 type ClientIo = any;
 
+interface StandaloneOptions {
+  env?: Record<string, any>;
+}
+
 class BridgeWebsocket extends AbstractWebsocket {
   private room: ServerIo;
   private socket: ClientIo;
+  private pendingOn: Array<{ event: string; callback: (data: any) => void }> = [];
+  private rooms = {
+    partyFn: async (roomId: string) => {
+      this.room = new ServerIo(roomId, this.rooms);
+      const server = new this.server(this.room)
+      await server.onStart();
+      await server.subRoom.onStart()
+      this.context.set('server', server)
+      return server
+    },
+    env: {}
+  }
+  private serverInstance: any;
 
-  constructor(protected context: Context, private server: any) {
+  constructor(protected context: Context, private server: any, options: StandaloneOptions = {}) {
     super(context);
     // fake room
-    this.room = new ServerIo("lobby-1");
+    this.rooms.env = options.env || {};
+    this.room = new ServerIo("lobby-1", this.rooms);
   }
 
   async connection(listeners?: (data: any) => void) {
-    const server = new this.server(this.room);
-    await server.onStart();
-    this.context.set('server', server)
-    this.socket = new ClientIo(server);
+    this.serverInstance = new this.server(this.room);
+    await this.serverInstance.onStart();
+    await this.serverInstance.subRoom.onStart()
+    this.context.set('server', this.serverInstance)
+    return this._connection(listeners)
+  }
+
+  private async _connection(listeners?: (data: any) => void) {
+    this.serverInstance = this.context.get('server')
+    this.socket = new ClientIo(this.serverInstance, 'player-client-id');
     const url = new URL('http://localhost')
     const request = new Request(url.toString(), {
       method: 'GET',
@@ -32,21 +58,29 @@ class BridgeWebsocket extends AbstractWebsocket {
       }
     })
     listeners?.(this.socket)
-    await server.onConnect(this.socket.conn as any, { request } as any);
+    await this.serverInstance.onConnect(this.socket.conn as any, { request } as any);
     this.room.clients.set(this.socket.id, this.socket);
+    this.pendingOn.forEach(({ event, callback }) => this.socket.addEventListener(event, callback));
+    this.pendingOn = [];
     return this.socket
   }
 
   on(key: string, callback: (data: any) => void) {
-    this.socket.addEventListener("message", (event) => {
+    const handler = (event) => {
       const object = JSON.parse(event);
       if (object.type === key) {
         callback(object.value);
       }
-    });
+    };
+    if (!this.socket) {
+      this.pendingOn.push({ event: "message", callback: handler });
+      return;
+    }
+    this.socket.addEventListener("message", handler);
   }
 
   off(event: string, callback: (data: any) => void) {
+    if (!this.socket) return;
     this.socket.removeEventListener(event, callback);
   }
 
@@ -57,24 +91,80 @@ class BridgeWebsocket extends AbstractWebsocket {
     });
   }
 
-  updateProperties({ room }: { room: any }) {
-    this.room = new ServerIo(room);
+  /**
+   * Update underlying connection properties before a reconnect
+   *
+   * Design
+   * - Dynamically register a factory for the requested room to ensure a fresh server instance
+   * - Swap the internal ServerIo to target the new room
+   *
+   * @param params - Properties to update
+   * @param params.room - The target room id (e.g. `map-simplemap2`)
+   *
+   * @example
+   * ```ts
+   * websocket.updateProperties({ room: 'map-simplemap2' })
+   * await websocket.reconnect()
+   * ```
+   */
+  updateProperties(_params: SocketUpdateProperties) {
+    // empty
   }
 
-  async reconnect(listeners?: (data: any) => void) {
-    await this.connection((socket) => {
+  /**
+   * Reconnect the client to the current Party room
+   *
+   * Design
+   * - Must be called after `updateProperties()` when switching rooms
+   * - Rebuilds the client <-> server bridge and re-triggers connection listeners
+   *
+   * @param listeners - Optional callback to re-bind event handlers on the new socket
+   *
+   * @example
+   * ```ts
+   * websocket.updateProperties({ room: 'map-dungeon' })
+   * await websocket.reconnect((socket) => {
+   *   // re-bind events here
+   * })
+   * ```
+   */
+  async reconnect(listeners?: (data: any) => void): Promise<void> {
+    await this._connection((socket) => {
       listeners?.(socket)
     })
   }
+
+  getServer() {
+    return this.serverInstance
+  }
+
+  getSocket() {
+    return this.socket
+  }
 }
 
 class UpdateMapStandaloneService extends UpdateMapService {
   private server: any;
 
-  async update(mapId: string, map: any) {
+  /**
+   * Update the current room map data on the server side
+   *
+   * Design
+   * - Uses the in-memory server instance stored in context (standalone mode)
+   * - Builds a local HTTP-like request to the current Party room endpoint
+   *
+   * @param map - The map payload to apply on the server
+   *
+   * @example
+   * ```ts
+   * await updateMapService.update({ width: 1024, height: 768, events: [] })
+   * ```
+   */
+  async update(map: any) {
     this.server = this.context.get('server')
+    const roomId = this.server?.room?.id ?? 'lobby-1'
     const req = {
-      url: `http://localhost/parties/main/${mapId}/map/update`,
+      url: `http://localhost/parties/main/${roomId}/map/update`,
       method: 'POST',
       headers: new Headers({}),
       json: async () => {
@@ -85,16 +175,18 @@ class UpdateMapStandaloneService extends UpdateMapService {
   }
 }
 
-export function provideRpg(server: any) {
+export function provideRpg(server: any, options: StandaloneOptions = {}) {
   return [
     {
       provide: WebSocketToken,
-      useFactory: (context: Context) => new BridgeWebsocket(context, server),
+      useFactory: (context: Context) => new BridgeWebsocket(context, server, options),
     },
     {
       provide: UpdateMapToken,
       useClass: UpdateMapStandaloneService,
     },
+    provideKeyboardControls(),
+    provideSaveClient(),
     RpgGui,
     RpgClientEngine,
   ];