@rpgjs/client 5.0.0-beta.2 → 5.0.0-beta.20

package/src/services/keyboardControls.ts

@@ -5,6 +5,7 @@ export enum Control {
   Attack = 'attack',
   Defense = 'defense',
   Skill = 'skill',
+  Dash = 'dash',
   Back = 'back',
   Up = 1,
   Down = 3,
@@ -17,4 +18,4 @@ export function provideKeyboardControls() {
     provide: 'KeyboardControls',
     useValue: null,
   };
-}
+}

package/src/services/loadMap.ts

@@ -1,5 +1,5 @@
 import { Context, inject } from "@signe/di";
-import { UpdateMapToken, UpdateMapService } from "@rpgjs/common";
+import { UpdateMapToken, UpdateMapService, type LightingState } from "@rpgjs/common";
 
 export const LoadMapToken = 'LoadMapToken'
 
@@ -20,8 +20,12 @@ 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;
+  /** Optional initial lighting state for the loaded map */
+  lighting?: LightingState | null;
 }
 
 /**

package/src/services/mmorpg-connection.spec.ts

@@ -0,0 +1,99 @@
+import { describe, expect, test } from "vitest";
+import { isNativeSocketEvent, parseSocketMessage, waitForRpgjsConnected } from "./mmorpg-connection";
+
+function wait(ms = 0): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+class FakeConnection extends EventTarget {
+  serverMessage(data: any) {
+    this.dispatchEvent(new MessageEvent("message", {
+      data: typeof data === "string" ? data : JSON.stringify(data),
+    }));
+  }
+
+  close(reason = "", code = 1008) {
+    this.dispatchEvent(new CloseEvent("close", {
+      code,
+      reason,
+    }));
+  }
+
+  fail(message = "WebSocket connection failed") {
+    this.dispatchEvent(new ErrorEvent("error", {
+      message,
+    }));
+  }
+}
+
+describe("MMORPG connection gate", () => {
+  test("resolves only after the RPGJS connected packet", async () => {
+    const conn = new FakeConnection();
+    let resolved = false;
+    const promise = waitForRpgjsConnected(conn).then(() => {
+      resolved = true;
+    });
+
+    conn.serverMessage({ type: "sync", value: { pId: "player-1" } });
+    await wait();
+
+    expect(resolved).toBe(false);
+
+    conn.serverMessage({ type: "connected", value: { id: "conn-1" } });
+    await promise;
+
+    expect(resolved).toBe(true);
+  });
+
+  test("rejects when the socket closes before the RPGJS connected packet", async () => {
+    const conn = new FakeConnection();
+    const promise = waitForRpgjsConnected(conn);
+
+    conn.close("Authentication failed");
+
+    await expect(promise).rejects.toThrow("Authentication failed");
+  });
+
+  test("can ignore the clean close emitted by PartySocket during manual reconnect", async () => {
+    const conn = new FakeConnection();
+    const promise = waitForRpgjsConnected(conn, 10000, { ignoreCleanClose: true });
+
+    conn.close("", 1000);
+    await wait();
+
+    conn.serverMessage({ type: "connected", value: { id: "conn-2" } });
+
+    await expect(promise).resolves.toBeUndefined();
+  });
+
+  test("can ignore PartySocket reconnect close events with non-string reasons", async () => {
+    const conn = new FakeConnection();
+    const promise = waitForRpgjsConnected(conn, 10000, { ignoreCleanClose: true });
+
+    conn.dispatchEvent(new CloseEvent("close", {
+      code: 1000,
+      reason: new Event("close") as any,
+    }));
+    await wait();
+
+    conn.serverMessage({ type: "connected", value: { id: "conn-3" } });
+
+    await expect(promise).resolves.toBeUndefined();
+  });
+
+  test("rejects when the socket errors before the RPGJS connected packet", async () => {
+    const conn = new FakeConnection();
+    const promise = waitForRpgjsConnected(conn);
+
+    conn.fail("Unauthorized");
+
+    await expect(promise).rejects.toThrow("Unauthorized");
+  });
+
+  test("parses connection messages and detects native socket events", () => {
+    expect(parseSocketMessage(JSON.stringify({ type: "connected" }))).toEqual({ type: "connected" });
+    expect(parseSocketMessage("not-json")).toBeUndefined();
+    expect(isNativeSocketEvent("open")).toBe(true);
+    expect(isNativeSocketEvent("sync")).toBe(false);
+  });
+});

package/src/services/mmorpg-connection.ts

@@ -0,0 +1,69 @@
+export function parseSocketMessage(data: any) {
+  if (typeof data !== "string") {
+    return data;
+  }
+  try {
+    return JSON.parse(data);
+  }
+  catch {
+    return undefined;
+  }
+}
+
+export function isNativeSocketEvent(event: string) {
+  return event === "open" || event === "close" || event === "error";
+}
+
+export function waitForRpgjsConnected(
+  conn: any,
+  timeoutMs = 10000,
+  options: { ignoreCleanClose?: boolean } = {},
+): Promise<void> {
+  return new Promise((resolve, reject) => {
+    let timeoutId: number | undefined;
+
+    const cleanup = () => {
+      conn.removeEventListener("message", onMessage);
+      conn.removeEventListener("close", onClose);
+      conn.removeEventListener("error", onError);
+      if (timeoutId !== undefined) {
+        window.clearTimeout(timeoutId);
+      }
+    };
+    const rejectWith = (error: Error) => {
+      cleanup();
+      reject(error);
+    };
+    const onMessage = (event: MessageEvent) => {
+      const data = parseSocketMessage(event.data);
+      if (data?.type !== "connected") {
+        return;
+      }
+      cleanup();
+      resolve();
+    };
+    const onClose = (event: CloseEvent) => {
+      const rawReason: unknown = (event as any).reason;
+      if (
+        options.ignoreCleanClose
+        && (event.code === 1000 || rawReason instanceof Event || typeof rawReason !== "string")
+      ) {
+        return;
+      }
+      const reason = typeof rawReason === "string" && rawReason
+        ? rawReason
+        : "WebSocket closed before RPGJS connection was accepted";
+      rejectWith(new Error(reason));
+    };
+    const onError = (event: ErrorEvent) => {
+      rejectWith(new Error(event.message || "WebSocket connection failed"));
+    };
+
+    conn.addEventListener("message", onMessage);
+    conn.addEventListener("close", onClose);
+    conn.addEventListener("error", onError);
+    timeoutId = window.setTimeout(() => {
+      rejectWith(new Error("RPGJS connection timeout"));
+    }, timeoutMs);
+  });
+}

package/src/services/mmorpg.ts

@@ -2,21 +2,27 @@ import { Context } from "@signe/di";
 import { connectionRoom } from "@signe/sync/client";
 import { RpgGui } from "../Gui/Gui";
 import { RpgClientEngine } from "../RpgClientEngine";
-import { AbstractWebsocket, SocketUpdateProperties, WebSocketToken } from "./AbstractSocket";
+import { AbstractWebsocket, SocketQuery, SocketUpdateProperties, WebSocketToken } from "./AbstractSocket";
 import { UpdateMapService, UpdateMapToken } from "@rpgjs/common";
 import { provideKeyboardControls } from "./keyboardControls";
 import { provideSaveClient } from "./save";
+import { isNativeSocketEvent, waitForRpgjsConnected } from "./mmorpg-connection";
 
-interface MmorpgOptions {
+export interface MmorpgOptions {
     host?: string;
     connectionId?: string;
     connectionIdScope?: "local" | "session" | "ephemeral";
+    query?: SocketQuery | (() => SocketQuery | undefined);
+    socketOptions?: Record<string, any>;
 }
 
-class BridgeWebsocket extends AbstractWebsocket {
+export class BridgeWebsocket extends AbstractWebsocket {
+  readonly mode = "mmorpg" as const;
+
   private socket: any;
   private privateId: string;
   private pendingOn: Array<{ event: string; callback: (data: any) => void }> = [];
+  private acceptedOpenListeners = new Set<(data: any) => void>();
   private targetRoom = "lobby-1";
 
   constructor(protected context: Context, private options: MmorpgOptions = {}) {
@@ -51,6 +57,14 @@ class BridgeWebsocket extends AbstractWebsocket {
     return id;
   }
 
+  private resolveQuery(): SocketQuery {
+    const query = typeof this.options.query === "function"
+      ? this.options.query()
+      : this.options.query;
+
+    return query ?? {};
+  }
+
   async connection(listeners?: (data: any) => void) {
     // tmp
     class Room {
@@ -59,14 +73,28 @@ class BridgeWebsocket extends AbstractWebsocket {
     const instance = new Room()
     const host = this.options.host || window.location.host;
     this.socket = await connectionRoom({
+        maxRetries: 0,
+        ...this.options.socketOptions,
         host,
         room: this.targetRoom,
-        id: this.privateId
+        id: this.privateId,
+        query: {
+          ...this.resolveQuery(),
+          id: this.privateId,
+        },
     }, instance)
 
-    listeners?.(this.socket)
-    this.pendingOn.forEach(({ event, callback }) => this.socket.on(event, callback));
+    const pendingOn = this.pendingOn;
     this.pendingOn = [];
+    pendingOn
+      .filter(({ event }) => !this.isNativeSocketEvent(event))
+      .forEach(({ event, callback }) => this.attachEvent(event, callback));
+    await waitForRpgjsConnected(this.socket.conn);
+    pendingOn
+      .filter(({ event }) => this.isNativeSocketEvent(event))
+      .forEach(({ event, callback }) => this.attachEvent(event, callback));
+    this.emitAcceptedOpen();
+    listeners?.(this.socket)
   }
 
   on(key: string, callback: (data: any) => void) {
@@ -74,11 +102,19 @@ class BridgeWebsocket extends AbstractWebsocket {
       this.pendingOn.push({ event: key, callback });
       return;
     }
-    this.socket.on(key, callback);
+    this.attachEvent(key, callback);
   }
 
   off(event: string, callback: (data: any) => void) {
     if (!this.socket) return;
+    if (event === "open") {
+      this.acceptedOpenListeners.delete(callback);
+      return;
+    }
+    if (this.isNativeSocketEvent(event)) {
+      this.socket.conn.removeEventListener(event, callback);
+      return;
+    }
     this.socket.off(event, callback);
   }
 
@@ -86,6 +122,23 @@ class BridgeWebsocket extends AbstractWebsocket {
     this.socket.emit(event, data);
   }
 
+  private attachEvent(event: string, callback: (data: any) => void) {
+    if (event === "open") {
+      this.acceptedOpenListeners.add(callback);
+      return;
+    }
+    if (this.isNativeSocketEvent(event)) {
+      this.socket.conn.addEventListener(event, callback);
+      return;
+    }
+    this.socket.on(event, callback);
+  }
+
+  private emitAcceptedOpen() {
+    const event = new Event("open");
+    this.acceptedOpenListeners.forEach((callback) => callback(event));
+  }
+
   updateProperties({ room, host, query }: SocketUpdateProperties) {
     if (!this.socket?.conn) return;
     this.targetRoom = room;
@@ -93,44 +146,25 @@ class BridgeWebsocket extends AbstractWebsocket {
       room,
       id: this.privateId,
       host: host || this.options.host || window.location.host,
-      query,
+      query: {
+        ...this.resolveQuery(),
+        ...query,
+        id: this.privateId,
+      },
     })
   }
 
-  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);
-    });
+  private isNativeSocketEvent(event: string) {
+    return isNativeSocketEvent(event);
   }
 
   async reconnect(_listeners?: (data: any) => void): Promise<void> {
     if (!this.socket?.conn) return;
     const conn = this.socket.conn;
-    const opened = this.waitForNextOpen(conn);
+    const connected = waitForRpgjsConnected(conn, 10000, { ignoreCleanClose: true });
     conn.reconnect();
-    await opened;
+    await connected;
+    this.emitAcceptedOpen();
   }
 
   getCurrentRoom(): string {

package/src/services/pointerContext.spec.ts

@@ -0,0 +1,36 @@
+import { describe, expect, test } from "vitest";
+import { createClientPointerContext } from "./pointerContext";
+
+describe("createClientPointerContext", () => {
+  test("returns null before any pointer event", () => {
+    const pointer = createClientPointerContext();
+
+    expect(pointer.screen()).toBeNull();
+    expect(pointer.world()).toBeNull();
+  });
+
+  test("stores screen and world coordinates from pointer events", () => {
+    const pointer = createClientPointerContext();
+
+    const world = pointer.updateFromEvent({
+      global: { x: 120, y: 80 },
+      currentTarget: {
+        toLocal(point: { x: number; y: number }) {
+          return { x: point.x + 10, y: point.y + 20 };
+        },
+      },
+    });
+
+    expect(world).toEqual({ x: 130, y: 100 });
+    expect(pointer.screen()).toEqual({ x: 120, y: 80 });
+    expect(pointer.world()).toEqual({ x: 130, y: 100 });
+  });
+
+  test("ignores pointer events without usable coordinates", () => {
+    const pointer = createClientPointerContext();
+
+    expect(pointer.updateFromEvent({ global: { x: Number.NaN, y: 80 } })).toBeNull();
+    expect(pointer.screen()).toBeNull();
+    expect(pointer.world()).toBeNull();
+  });
+});

package/src/services/pointerContext.ts

@@ -0,0 +1,84 @@
+export interface ClientPointerPosition {
+  x: number;
+  y: number;
+}
+
+export interface ClientPointerContext {
+  screen(): ClientPointerPosition | null;
+  world(): ClientPointerPosition | null;
+  update(screen: ClientPointerPosition | null, world?: ClientPointerPosition | null): ClientPointerPosition | null;
+  updateFromEvent(event: any): ClientPointerPosition | null;
+}
+
+function toPosition(point: any): ClientPointerPosition | null {
+  const x = Number(point?.x);
+  const y = Number(point?.y);
+
+  if (!Number.isFinite(x) || !Number.isFinite(y)) {
+    return null;
+  }
+
+  return { x, y };
+}
+
+function extractGlobalPoint(event: any): ClientPointerPosition | null {
+  return toPosition(event?.global)
+    ?? toPosition(event?.data?.global)
+    ?? toPosition(event);
+}
+
+function extractWorldPoint(event: any, global: ClientPointerPosition | null): ClientPointerPosition | null {
+  const target = event?.currentTarget ?? event?.target;
+
+  if (target && global && typeof target.toLocal === "function") {
+    return toPosition(target.toLocal(global));
+  }
+
+  if (typeof event?.getLocalPosition === "function") {
+    return toPosition(event.getLocalPosition(target));
+  }
+
+  if (typeof event?.data?.getLocalPosition === "function") {
+    return toPosition(event.data.getLocalPosition(target));
+  }
+
+  return global;
+}
+
+export function createClientPointerContext(): ClientPointerContext {
+  let lastScreen: ClientPointerPosition | null = null;
+  let lastWorld: ClientPointerPosition | null = null;
+
+  const update = (screen: ClientPointerPosition | null, world?: ClientPointerPosition | null) => {
+    const nextScreen = toPosition(screen);
+    const nextWorld = toPosition(world) ?? nextScreen;
+
+    if (nextScreen) {
+      lastScreen = nextScreen;
+    }
+
+    if (nextWorld) {
+      lastWorld = nextWorld;
+    }
+
+    return lastWorld ? { ...lastWorld } : null;
+  };
+
+  return {
+    screen() {
+      return lastScreen ? { ...lastScreen } : null;
+    },
+
+    world() {
+      return lastWorld ? { ...lastWorld } : null;
+    },
+
+    update,
+
+    updateFromEvent(event: any) {
+      const global = extractGlobalPoint(event);
+      const world = extractWorldPoint(event, global);
+      return update(global, world);
+    },
+  };
+}

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/standalone-message.ts

@@ -0,0 +1,7 @@
+export function normalizeStandaloneMessage(event: unknown): any {
+  const raw = event && typeof event === "object" && "data" in event
+    ? (event as MessageEvent).data
+    : event;
+
+  return typeof raw === "string" ? JSON.parse(raw) : raw;
+}

package/src/services/standalone.spec.ts

@@ -0,0 +1,54 @@
+// @vitest-environment jsdom
+
+import { describe, expect, test, vi } from "vitest";
+import { Context } from "@signe/di";
+import { WebSocketToken } from "./AbstractSocket";
+import { provideMmorpg } from "./mmorpg";
+import { provideRpg } from "./standalone";
+import { normalizeStandaloneMessage } from "./standalone-message";
+
+describe("standalone websocket bridge", () => {
+  test("dispatches mock room object broadcasts to named listeners", () => {
+    const onSpawn = vi.fn();
+    const object = normalizeStandaloneMessage({
+      type: "projectile:spawnBatch",
+      value: {
+        projectiles: [{ id: "p1", type: "bolt" }],
+      },
+    });
+
+    if (object.type === "projectile:spawnBatch") {
+      onSpawn(object.value);
+    }
+
+    expect(onSpawn).toHaveBeenCalledWith({
+      projectiles: [{ id: "p1", type: "bolt" }],
+    });
+  });
+
+  test("still accepts browser-style string messages", () => {
+    expect(normalizeStandaloneMessage({
+      data: JSON.stringify({
+        type: "projectile:spawnBatch",
+        value: { projectiles: [] },
+      }),
+    })).toEqual({
+      type: "projectile:spawnBatch",
+      value: { projectiles: [] },
+    });
+  });
+
+  test("marks standalone and MMORPG websocket providers with their runtime mode", () => {
+    class Server {}
+    const context = new Context();
+    const standaloneProvider = provideRpg(Server).find(
+      (provider: any) => provider.provide === WebSocketToken,
+    ) as any;
+    const mmorpgProvider = provideMmorpg({ connectionId: "test-client" }).find(
+      (provider: any) => provider.provide === WebSocketToken,
+    ) as any;
+
+    expect(standaloneProvider.useFactory(context).mode).toBe("standalone");
+    expect(mmorpgProvider.useFactory(context).mode).toBe("mmorpg");
+  });
+});