@rpgjs/client 5.0.0-beta.22 → 5.0.0-beta.24

package/dist/services/standalone.js.map

@@ -1 +1 @@
-{"version":3,"file":"standalone.js","names":[],"sources":["../../src/services/standalone.ts"],"sourcesContent":["import { AbstractWebsocket, SocketUpdateProperties, WebSocketToken } from \"./AbstractSocket\";\nimport { ClientIo, ServerIo } from \"@signe/room\";\nimport { Context } from \"@signe/di\";\nimport { RpgClientEngine } from \"../RpgClientEngine\";\nimport { UpdateMapService, UpdateMapToken } from \"@rpgjs/common\";\nimport { LoadMapToken } from \"./loadMap\";\nimport { RpgGui } from \"../Gui/Gui\";\nimport { provideKeyboardControls } from \"./keyboardControls\";\nimport { provideSaveClient } from \"./save\";\nimport { normalizeStandaloneMessage } from \"./standalone-message\";\n\ntype ServerIo = any;\ntype ClientIo = any;\n\ninterface StandaloneOptions {\n  env?: Record<string, any>;\n}\n\nclass BridgeWebsocket extends AbstractWebsocket {\n  readonly mode = \"standalone\" as const;\n\n  private room: ServerIo;\n  private socket: ClientIo;\n  private socketRoom?: ServerIo;\n  private listeners: Array<{\n    event: string;\n    callback: (data: any) => void;\n    handler: (event: any) => void;\n  }> = [];\n  private rooms = {\n    partyFn: async (roomId: string) => {\n      this.room = new ServerIo(roomId, this.rooms);\n      const server = new this.server(this.room)\n      await server.onStart();\n      await server.subRoom.onStart()\n      this.context.set('server', server)\n      return server\n    },\n    env: {}\n  }\n  private serverInstance: any;\n\n  constructor(protected context: Context, private server: any, options: StandaloneOptions = {}) {\n    super(context);\n    // fake room\n    this.rooms.env = options.env || {};\n    this.room = new ServerIo(\"lobby-1\", this.rooms);\n  }\n\n  async connection(listeners?: (data: any) => void) {\n    this.serverInstance = new this.server(this.room);\n    await this.serverInstance.onStart();\n    await this.serverInstance.subRoom.onStart()\n    this.context.set('server', this.serverInstance)\n    return this._connection(listeners)\n  }\n\n  private async _connection(listeners?: (data: any) => void) {\n    this.detachCurrentSocket();\n    this.serverInstance = this.context.get('server')\n    this.socket = new ClientIo(this.serverInstance, 'player-client-id');\n    const url = new URL('http://localhost')\n    const request = new Request(url.toString(), {\n      method: 'GET',\n      headers: {\n        'Content-Type': 'application/json'\n      }\n    })\n    listeners?.(this.socket)\n    this.room.clients.set(this.socket.id, this.socket);\n    this.socketRoom = this.room;\n    this.listeners.forEach(({ handler }) => {\n      this.socket.addEventListener(\"message\", handler);\n    });\n    await this.serverInstance.onConnect(this.socket.conn as any, { request } as any);\n    return this.socket\n  }\n\n  on(key: string, callback: (data: any) => void) {\n    if (\n      this.listeners.some(\n        (listener) => listener.event === key && listener.callback === callback\n      )\n    ) {\n      return;\n    }\n    const handler = (event) => {\n      const object = normalizeStandaloneMessage(event);\n      if (object.type === key) {\n        callback(object.value);\n      }\n    };\n    this.listeners.push({ event: key, callback, handler });\n    this.socket?.addEventListener(\"message\", handler);\n  }\n\n  off(event: string, callback: (data: any) => void) {\n    const remaining: typeof this.listeners = [];\n    for (const listener of this.listeners) {\n      if (listener.event === event && listener.callback === callback) {\n        this.socket?.removeEventListener(\"message\", listener.handler);\n        continue;\n      }\n      remaining.push(listener);\n    }\n    this.listeners = remaining;\n  }\n\n  emit(event: string, data: any) {\n    this.socket.send({\n      action: event,\n      value: data,\n    });\n  }\n\n  /**\n   * Update underlying connection properties before a reconnect\n   *\n   * Design\n   * - Dynamically register a factory for the requested room to ensure a fresh server instance\n   * - Swap the internal ServerIo to target the new room\n   *\n   * @param params - Properties to update\n   * @param params.room - The target room id (e.g. `map-simplemap2`)\n   *\n   * @example\n   * ```ts\n   * websocket.updateProperties({ room: 'map-simplemap2' })\n   * await websocket.reconnect()\n   * ```\n   */\n  updateProperties(_params: SocketUpdateProperties) {\n    // empty\n  }\n\n  /**\n   * Reconnect the client to the current Party room\n   *\n   * Design\n   * - Must be called after `updateProperties()` when switching rooms\n   * - Rebuilds the client <-> server bridge and re-triggers connection listeners\n   *\n   * @param listeners - Optional callback to re-bind event handlers on the new socket\n   *\n   * @example\n   * ```ts\n   * websocket.updateProperties({ room: 'map-dungeon' })\n   * await websocket.reconnect((socket) => {\n   *   // re-bind events here\n   * })\n   * ```\n   */\n  async reconnect(listeners?: (data: any) => void): Promise<void> {\n    await this._connection((socket) => {\n      listeners?.(socket)\n    })\n  }\n\n  private detachCurrentSocket() {\n    if (!this.socket) return;\n    this.listeners.forEach(({ handler }) => {\n      this.socket.removeEventListener(\"message\", handler);\n    });\n    this.socketRoom?.clients?.delete?.(this.socket.id);\n    this.socket = undefined as any;\n    this.socketRoom = undefined;\n  }\n\n  getServer() {\n    return this.serverInstance\n  }\n\n  getSocket() {\n    return this.socket\n  }\n}\n\nclass UpdateMapStandaloneService extends UpdateMapService {\n  private server: any;\n\n  /**\n   * Update the current room map data on the server side\n   *\n   * Design\n   * - Uses the in-memory server instance stored in context (standalone mode)\n   * - Builds a local HTTP-like request to the current Party room endpoint\n   *\n   * @param map - The map payload to apply on the server\n   *\n   * @example\n   * ```ts\n   * await updateMapService.update({ width: 1024, height: 768, events: [] })\n   * ```\n   */\n  async update(map: any) {\n    this.server = this.context.get('server')\n    const roomId = this.server?.room?.id ?? 'lobby-1'\n    const req = {\n      url: `http://localhost/parties/main/${roomId}/map/update`,\n      method: 'POST',\n      headers: new Headers({}),\n      json: async () => {\n        return map;\n      }\n    };\n    await this.server.onRequest(req)\n  }\n}\n\nexport function provideRpg(server: any, options: StandaloneOptions = {}) {\n  return [\n    {\n      provide: WebSocketToken,\n      useFactory: (context: Context) => new BridgeWebsocket(context, server, options),\n    },\n    {\n      provide: UpdateMapToken,\n      useClass: UpdateMapStandaloneService,\n    },\n    provideKeyboardControls(),\n    provideSaveClient(),\n    RpgGui,\n    RpgClientEngine,\n  ];\n}\n"],"mappings":"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"}
+{"version":3,"file":"standalone.js","names":[],"sources":["../../src/services/standalone.ts"],"sourcesContent":["import { AbstractWebsocket, SocketUpdateProperties, WebSocketToken } from \"./AbstractSocket\";\nimport { ClientIo, ServerIo } from \"@signe/room\";\nimport { Context } from \"@signe/di\";\nimport { RpgClientEngine } from \"../RpgClientEngine\";\nimport { UpdateMapService, UpdateMapToken } from \"@rpgjs/common\";\nimport { LoadMapToken } from \"./loadMap\";\nimport { RpgGui } from \"../Gui/Gui\";\nimport { provideKeyboardControls } from \"./keyboardControls\";\nimport { provideSaveClient } from \"./save\";\nimport { normalizeStandaloneMessage } from \"./standalone-message\";\nimport type { SocketQuery } from \"./AbstractSocket\";\n\ntype ServerIo = any;\ntype ClientIo = any;\n\ninterface StandaloneOptions {\n  env?: Record<string, any>;\n}\n\nclass BridgeWebsocket extends AbstractWebsocket {\n  readonly mode = \"standalone\" as const;\n\n  private room: ServerIo;\n  private socket: ClientIo;\n  private socketRoom?: ServerIo;\n  private roomId = \"lobby-1\";\n  private query?: SocketQuery;\n  private readonly privateId = \"player-client-id\";\n  private listeners: Array<{\n    event: string;\n    callback: (data: any) => void;\n    handler: (event: any) => void;\n  }> = [];\n  private rooms = {\n    partyFn: async (roomId: string) => {\n      const room = new ServerIo(roomId, this.rooms);\n      const server = new this.server(room)\n      await server.onStart();\n      await server.subRoom.onStart()\n      return server\n    },\n    env: {}\n  }\n  private serverInstance: any;\n\n  constructor(protected context: Context, private server: any, options: StandaloneOptions = {}) {\n    super(context);\n    // fake room\n    this.rooms.env = options.env || {};\n    this.room = new ServerIo(\"lobby-1\", this.rooms);\n  }\n\n  async connection(listeners?: (data: any) => void) {\n    this.serverInstance = new this.server(this.room);\n    await this.serverInstance.onStart();\n    await this.serverInstance.subRoom.onStart()\n    this.context.set('server', this.serverInstance)\n    return this._connection(listeners)\n  }\n\n  private async _connection(listeners?: (data: any) => void) {\n    this.detachCurrentSocket();\n    await this.connectToRoom();\n    listeners?.(this.socket)\n    return this.socket\n  }\n\n  on(key: string, callback: (data: any) => void) {\n    if (\n      this.listeners.some(\n        (listener) => listener.event === key && listener.callback === callback\n      )\n    ) {\n      return;\n    }\n    const handler = (event) => {\n      const object = normalizeStandaloneMessage(event);\n      if (object.type === key) {\n        callback(object.value);\n      }\n    };\n    this.listeners.push({ event: key, callback, handler });\n    this.socket?.addEventListener(\"message\", handler);\n  }\n\n  off(event: string, callback: (data: any) => void) {\n    const remaining: typeof this.listeners = [];\n    for (const listener of this.listeners) {\n      if (listener.event === event && listener.callback === callback) {\n        this.socket?.removeEventListener(\"message\", listener.handler);\n        continue;\n      }\n      remaining.push(listener);\n    }\n    this.listeners = remaining;\n  }\n\n  emit(event: string, data: any) {\n    this.socket.send({\n      action: event,\n      value: data,\n    });\n  }\n\n  /**\n   * Update underlying connection properties before a reconnect\n   *\n   * Design\n   * - Dynamically register a factory for the requested room to ensure a fresh server instance\n   * - Swap the internal ServerIo to target the new room\n   *\n   * @param params - Properties to update\n   * @param params.room - The target room id (e.g. `map-simplemap2`)\n   *\n   * @example\n   * ```ts\n   * websocket.updateProperties({ room: 'map-simplemap2' })\n   * await websocket.reconnect()\n   * ```\n   */\n  updateProperties({ room, query }: SocketUpdateProperties) {\n    this.roomId = room;\n    this.query = query;\n  }\n\n  /**\n   * Reconnect the client to the current Party room\n   *\n   * Design\n   * - Must be called after `updateProperties()` when switching rooms\n   * - Rebuilds the client <-> server bridge and re-triggers connection listeners\n   *\n   * @param listeners - Optional callback to re-bind event handlers on the new socket\n   *\n   * @example\n   * ```ts\n   * websocket.updateProperties({ room: 'map-dungeon' })\n   * await websocket.reconnect((socket) => {\n   *   // re-bind events here\n   * })\n   * ```\n   */\n  async reconnect(listeners?: (data: any) => void): Promise<void> {\n    await this._connection((socket) => {\n      listeners?.(socket)\n    })\n  }\n\n  private async connectToRoom() {\n    if (this.serverInstance?.room?.id !== this.roomId) {\n      const party = await this.room.context.parties.main.get(this.roomId);\n      this.serverInstance = party.server;\n      this.context.set('server', this.serverInstance);\n      this.room = this.serverInstance.room;\n    }\n    else {\n      this.serverInstance = this.context.get('server');\n    }\n\n    this.socket = new ClientIo(this.serverInstance, this.privateId);\n    const url = new URL('http://localhost');\n    const query = this.normalizeQuery(this.query);\n    if (query) {\n      for (const [key, value] of Object.entries(query)) {\n        url.searchParams.set(key, value);\n      }\n    }\n    const request = new Request(url.toString(), {\n      method: 'GET',\n      headers: {\n        'Content-Type': 'application/json'\n      }\n    });\n    this.room.clients.set(this.socket.id, this.socket);\n    this.socketRoom = this.room;\n    this.listeners.forEach(({ handler }) => {\n      this.socket.addEventListener(\"message\", handler);\n    });\n    await this.serverInstance.onConnect(this.socket.conn as any, { request } as any);\n  }\n\n  private normalizeQuery(query?: SocketQuery): Record<string, string> | undefined {\n    if (!query) {\n      return undefined;\n    }\n    return Object.fromEntries(\n      Object.entries(query)\n        .filter((entry): entry is [string, string] => typeof entry[1] === \"string\")\n    );\n  }\n\n  private detachCurrentSocket() {\n    if (!this.socket) return;\n    this.listeners.forEach(({ handler }) => {\n      this.socket.removeEventListener(\"message\", handler);\n    });\n    this.socketRoom?.clients?.delete?.(this.socket.id);\n    this.socket = undefined as any;\n    this.socketRoom = undefined;\n  }\n\n  getServer() {\n    return this.serverInstance\n  }\n\n  getSocket() {\n    return this.socket\n  }\n}\n\nclass UpdateMapStandaloneService extends UpdateMapService {\n  private server: any;\n\n  /**\n   * Update the current room map data on the server side\n   *\n   * Design\n   * - Uses the in-memory server instance stored in context (standalone mode)\n   * - Builds a local HTTP-like request to the current Party room endpoint\n   *\n   * @param map - The map payload to apply on the server\n   *\n   * @example\n   * ```ts\n   * await updateMapService.update({ width: 1024, height: 768, events: [] })\n   * ```\n   */\n  async update(map: any) {\n    this.server = this.context.get('server')\n    const roomId = this.server?.room?.id ?? 'lobby-1'\n    const req = {\n      url: `http://localhost/parties/main/${roomId}/map/update`,\n      method: 'POST',\n      headers: new Headers({}),\n      json: async () => {\n        return map;\n      }\n    };\n    await this.server.onRequest(req)\n  }\n}\n\nexport function provideRpg(server: any, options: StandaloneOptions = {}) {\n  return [\n    {\n      provide: WebSocketToken,\n      useFactory: (context: Context) => new BridgeWebsocket(context, server, options),\n    },\n    {\n      provide: UpdateMapToken,\n      useClass: UpdateMapStandaloneService,\n    },\n    provideKeyboardControls(),\n    provideSaveClient(),\n    RpgGui,\n    RpgClientEngine,\n  ];\n}\n"],"mappings":"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"}

package/dist/utils/syncHitbox.d.ts

@@ -0,0 +1 @@
+export declare const applySyncedHitboxPayload: (sceneMap: any, payload: any) => void;

package/dist/utils/syncHitbox.js

@@ -0,0 +1,69 @@
+//#region src/utils/syncHitbox.ts
+var toPositiveNumber = (value) => {
+	const numberValue = typeof value === "string" ? Number(value) : value;
+	return typeof numberValue === "number" && Number.isFinite(numberValue) && numberValue > 0 ? Math.round(numberValue) : null;
+};
+var readSignalValue = (value) => {
+	if (typeof value === "function") try {
+		return value();
+	} catch {
+		return;
+	}
+	return value;
+};
+var normalizeHitbox = (source) => {
+	if (!source || typeof source !== "object") return null;
+	const hitbox = source;
+	const width = toPositiveNumber(hitbox.w ?? hitbox.width);
+	const height = toPositiveNumber(hitbox.h ?? hitbox.height);
+	return width && height ? {
+		width,
+		height
+	} : null;
+};
+var readObjectHitbox = (object) => {
+	return normalizeHitbox(readSignalValue(object?.hitbox));
+};
+var readCoordinate = (object, key) => {
+	const value = readSignalValue(object?.[key]);
+	const numberValue = typeof value === "string" ? Number(value) : value;
+	return typeof numberValue === "number" && Number.isFinite(numberValue) ? numberValue : null;
+};
+var getObjectById = (sceneMap, id) => {
+	return sceneMap?.getObjectById?.(id) ?? sceneMap?.players?.()?.[id] ?? sceneMap?.events?.()?.[id];
+};
+var applyHitboxToObject = (sceneMap, id, object, hitbox) => {
+	if (!object) return;
+	const current = readObjectHitbox(object);
+	if (current?.width !== hitbox.width || current?.height !== hitbox.height) {
+		if (typeof object.hitbox?.set === "function") object.hitbox.set({
+			w: hitbox.width,
+			h: hitbox.height
+		});
+		else if (typeof object.setHitbox === "function") {
+			object.setHitbox(hitbox.width, hitbox.height);
+			return;
+		}
+	}
+	const objectId = typeof object.id === "string" && object.id ? object.id : id;
+	const x = readCoordinate(object, "x");
+	const y = readCoordinate(object, "y");
+	if (objectId && x !== null && y !== null) sceneMap?.updateHitbox?.(objectId, x, y, hitbox.width, hitbox.height);
+};
+var applyHitboxCollection = (sceneMap, collection) => {
+	if (!collection || typeof collection !== "object") return;
+	for (const [id, patch] of Object.entries(collection)) {
+		if (!patch || typeof patch !== "object") continue;
+		const hitbox = normalizeHitbox(patch.hitbox);
+		if (!hitbox) continue;
+		applyHitboxToObject(sceneMap, id, getObjectById(sceneMap, id), hitbox);
+	}
+};
+var applySyncedHitboxPayload = (sceneMap, payload) => {
+	applyHitboxCollection(sceneMap, payload?.players);
+	applyHitboxCollection(sceneMap, payload?.events);
+};
+//#endregion
+export { applySyncedHitboxPayload };
+
+//# sourceMappingURL=syncHitbox.js.map

package/dist/utils/syncHitbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"syncHitbox.js","names":[],"sources":["../../src/utils/syncHitbox.ts"],"sourcesContent":["interface HitboxSize {\n  width: number;\n  height: number;\n}\n\nconst toPositiveNumber = (value: unknown): number | null => {\n  const numberValue = typeof value === \"string\" ? Number(value) : value;\n  return typeof numberValue === \"number\" && Number.isFinite(numberValue) && numberValue > 0\n    ? Math.round(numberValue)\n    : null;\n};\n\nconst readSignalValue = (value: any): any => {\n  if (typeof value === \"function\") {\n    try {\n      return value();\n    }\n    catch {\n      return undefined;\n    }\n  }\n  return value;\n};\n\nconst normalizeHitbox = (source: unknown): HitboxSize | null => {\n  if (!source || typeof source !== \"object\") {\n    return null;\n  }\n\n  const hitbox = source as any;\n  const width = toPositiveNumber(hitbox.w ?? hitbox.width);\n  const height = toPositiveNumber(hitbox.h ?? hitbox.height);\n\n  return width && height ? { width, height } : null;\n};\n\nconst readObjectHitbox = (object: any): HitboxSize | null => {\n  return normalizeHitbox(readSignalValue(object?.hitbox));\n};\n\nconst readCoordinate = (object: any, key: \"x\" | \"y\"): number | null => {\n  const value = readSignalValue(object?.[key]);\n  const numberValue = typeof value === \"string\" ? Number(value) : value;\n  return typeof numberValue === \"number\" && Number.isFinite(numberValue)\n    ? numberValue\n    : null;\n};\n\nconst getObjectById = (sceneMap: any, id: string): any => {\n  return sceneMap?.getObjectById?.(id)\n    ?? sceneMap?.players?.()?.[id]\n    ?? sceneMap?.events?.()?.[id];\n};\n\nconst applyHitboxToObject = (\n  sceneMap: any,\n  id: string,\n  object: any,\n  hitbox: HitboxSize,\n): void => {\n  if (!object) {\n    return;\n  }\n\n  const current = readObjectHitbox(object);\n  if (current?.width !== hitbox.width || current?.height !== hitbox.height) {\n    if (typeof object.hitbox?.set === \"function\") {\n      object.hitbox.set({ w: hitbox.width, h: hitbox.height });\n    }\n    else if (typeof object.setHitbox === \"function\") {\n      object.setHitbox(hitbox.width, hitbox.height);\n      return;\n    }\n  }\n\n  const objectId = typeof object.id === \"string\" && object.id ? object.id : id;\n  const x = readCoordinate(object, \"x\");\n  const y = readCoordinate(object, \"y\");\n  if (objectId && x !== null && y !== null) {\n    sceneMap?.updateHitbox?.(objectId, x, y, hitbox.width, hitbox.height);\n  }\n};\n\nconst applyHitboxCollection = (sceneMap: any, collection: unknown): void => {\n  if (!collection || typeof collection !== \"object\") {\n    return;\n  }\n\n  for (const [id, patch] of Object.entries(collection)) {\n    if (!patch || typeof patch !== \"object\") {\n      continue;\n    }\n    const hitbox = normalizeHitbox((patch as any).hitbox);\n    if (!hitbox) {\n      continue;\n    }\n    applyHitboxToObject(sceneMap, id, getObjectById(sceneMap, id), hitbox);\n  }\n};\n\nexport const applySyncedHitboxPayload = (sceneMap: any, payload: any): void => {\n  applyHitboxCollection(sceneMap, payload?.players);\n  applyHitboxCollection(sceneMap, payload?.events);\n};\n"],"mappings":";AAKA,IAAM,oBAAoB,UAAkC;CAC1D,MAAM,cAAc,OAAO,UAAU,WAAW,OAAO,KAAK,IAAI;CAChE,OAAO,OAAO,gBAAgB,YAAY,OAAO,SAAS,WAAW,KAAK,cAAc,IACpF,KAAK,MAAM,WAAW,IACtB;AACN;AAEA,IAAM,mBAAmB,UAAoB;CAC3C,IAAI,OAAO,UAAU,YACnB,IAAI;EACF,OAAO,MAAM;CACf,QACM;EACJ;CACF;CAEF,OAAO;AACT;AAEA,IAAM,mBAAmB,WAAuC;CAC9D,IAAI,CAAC,UAAU,OAAO,WAAW,UAC/B,OAAO;CAGT,MAAM,SAAS;CACf,MAAM,QAAQ,iBAAiB,OAAO,KAAK,OAAO,KAAK;CACvD,MAAM,SAAS,iBAAiB,OAAO,KAAK,OAAO,MAAM;CAEzD,OAAO,SAAS,SAAS;EAAE;EAAO;CAAO,IAAI;AAC/C;AAEA,IAAM,oBAAoB,WAAmC;CAC3D,OAAO,gBAAgB,gBAAgB,QAAQ,MAAM,CAAC;AACxD;AAEA,IAAM,kBAAkB,QAAa,QAAkC;CACrE,MAAM,QAAQ,gBAAgB,SAAS,IAAI;CAC3C,MAAM,cAAc,OAAO,UAAU,WAAW,OAAO,KAAK,IAAI;CAChE,OAAO,OAAO,gBAAgB,YAAY,OAAO,SAAS,WAAW,IACjE,cACA;AACN;AAEA,IAAM,iBAAiB,UAAe,OAAoB;CACxD,OAAO,UAAU,gBAAgB,EAAE,KAC9B,UAAU,UAAU,IAAI,OACxB,UAAU,SAAS,IAAI;AAC9B;AAEA,IAAM,uBACJ,UACA,IACA,QACA,WACS;CACT,IAAI,CAAC,QACH;CAGF,MAAM,UAAU,iBAAiB,MAAM;CACvC,IAAI,SAAS,UAAU,OAAO,SAAS,SAAS,WAAW,OAAO;MAC5D,OAAO,OAAO,QAAQ,QAAQ,YAChC,OAAO,OAAO,IAAI;GAAE,GAAG,OAAO;GAAO,GAAG,OAAO;EAAO,CAAC;OAEpD,IAAI,OAAO,OAAO,cAAc,YAAY;GAC/C,OAAO,UAAU,OAAO,OAAO,OAAO,MAAM;GAC5C;EACF;;CAGF,MAAM,WAAW,OAAO,OAAO,OAAO,YAAY,OAAO,KAAK,OAAO,KAAK;CAC1E,MAAM,IAAI,eAAe,QAAQ,GAAG;CACpC,MAAM,IAAI,eAAe,QAAQ,GAAG;CACpC,IAAI,YAAY,MAAM,QAAQ,MAAM,MAClC,UAAU,eAAe,UAAU,GAAG,GAAG,OAAO,OAAO,OAAO,MAAM;AAExE;AAEA,IAAM,yBAAyB,UAAe,eAA8B;CAC1E,IAAI,CAAC,cAAc,OAAO,eAAe,UACvC;CAGF,KAAK,MAAM,CAAC,IAAI,UAAU,OAAO,QAAQ,UAAU,GAAG;EACpD,IAAI,CAAC,SAAS,OAAO,UAAU,UAC7B;EAEF,MAAM,SAAS,gBAAiB,MAAc,MAAM;EACpD,IAAI,CAAC,QACH;EAEF,oBAAoB,UAAU,IAAI,cAAc,UAAU,EAAE,GAAG,MAAM;CACvE;AACF;AAEA,IAAa,4BAA4B,UAAe,YAAuB;CAC7E,sBAAsB,UAAU,SAAS,OAAO;CAChD,sBAAsB,UAAU,SAAS,MAAM;AACjD"}

package/dist/utils/syncHitbox.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rpgjs/client",
-  "version": "5.0.0-beta.22",
+  "version": "5.0.0-beta.24",
   "description": "RPGJS is a framework for creating RPG/MMORPG games",
   "main": "dist/index.js",
   "types": "./dist/index.d.ts",
@@ -22,9 +22,9 @@
     "pixi.js": "^8.9.2"
   },
   "dependencies": {
-    "@rpgjs/common": "5.0.0-beta.21",
-    "@rpgjs/server": "5.0.0-beta.22",
-    "@rpgjs/ui-css": "5.0.0-beta.21",
+    "@rpgjs/common": "5.0.0-beta.23",
+    "@rpgjs/server": "5.0.0-beta.24",
+    "@rpgjs/ui-css": "5.0.0-beta.22",
     "@signe/di": "3.1.0",
     "@signe/room": "3.1.0",
     "@signe/sync": "3.1.0",

package/src/Game/Object.spec.ts

@@ -1,38 +1,102 @@
-import { describe, expect, test, vi } from "vitest";
+import { beforeEach, describe, expect, test, vi } from "vitest";
 import { signal } from "canvasengine";
-import { appendFramePayload, RpgClientObject, withGraphicDisplayScale } from "./Object";
+import {
+  appendFramePayload,
+  mergeFreshFramePayload,
+  multiplyGraphicDisplayScale,
+  RpgClientObject,
+  withGraphicDisplayScale,
+} from "./Object";
+import { RpgClientEvent } from "./Event";
+import { RpgClientPlayer } from "./Player";
+
+const injected = vi.hoisted(() => ({
+  engine: {} as any,
+}));
 
 vi.mock("../RpgClientEngine", () => ({
   RpgClientEngine: class RpgClientEngine {},
 }));
 
 vi.mock("../core/inject", () => ({
-  inject: () => ({}),
+  inject: () => injected.engine,
 }));
 
-function createObject() {
-  const object = Object.create(RpgClientObject.prototype) as RpgClientObject;
+function createObject(prototype: object = RpgClientObject.prototype) {
+  const object = Object.create(prototype) as RpgClientObject;
+  object.id = "object-1";
+  object.x = signal(10) as any;
+  object.y = signal(20) as any;
   object.animationName = signal("stand");
   object.graphics = signal(["hero"]) as any;
   object.animationCurrentIndex = signal(0);
   object.animationIsPlaying = signal(false);
+  object.hitbox = signal({ w: 32, h: 32 }) as any;
   return object;
 }
 
 describe("RpgClientObject animations", () => {
+  beforeEach(() => {
+    injected.engine = {};
+  });
+
   test("accepts a single frame payload without requiring iterable spread", () => {
     expect(
       appendFramePayload({ stale: true }, { x: 10, y: 20, ts: 1 }),
     ).toEqual([{ x: 10, y: 20, ts: 1 }]);
   });
 
+  test("drops stale movement frames that arrive after a newer frame was applied", () => {
+    expect(
+      mergeFreshFramePayload(
+        [],
+        [{ x: 733, y: 551, ts: 200 }],
+        300,
+      ),
+    ).toEqual([]);
+  });
+
   test("keeps instance scale outside the spritesheet transform scale", () => {
     expect(withGraphicDisplayScale({ id: "hero" }, 0.5)).toEqual({
       id: "hero",
-      displayScale: 0.5,
+      displayScale: [0.5, 0.5],
+    });
+  });
+
+  test("combines media and instance display scales", () => {
+    expect(multiplyGraphicDisplayScale(0.5, 2)).toEqual([1, 1]);
+    expect(withGraphicDisplayScale({ id: "hero", displayScale: 0.5 }, { x: 2, y: 3 })).toEqual({
+      id: "hero",
+      displayScale: [1, 1.5],
     });
   });
 
+  test("updates the client-side hitbox signal", () => {
+    const object = createObject();
+
+    object.setHitbox(56, 50);
+
+    expect(object.hitbox()).toEqual({ w: 56, h: 50 });
+  });
+
+  test.each([
+    ["player", RpgClientPlayer.prototype],
+    ["event", RpgClientEvent.prototype],
+  ])("updates the client-side %s physics body", (_kind, prototype) => {
+    const updateHitbox = vi.fn();
+    injected.engine = {
+      sceneMap: {
+        updateHitbox,
+      },
+    };
+    const object = createObject(prototype);
+
+    object.setHitbox(56, 50);
+
+    expect(object.hitbox()).toEqual({ w: 56, h: 50 });
+    expect(updateHitbox).toHaveBeenCalledWith("object-1", 10, 20, 56, 50);
+  });
+
   test("marks temporary animation as finished before restoring locomotion animation", async () => {
     const object = createObject();
     const animationChanges: Array<{ name: string; isPlaying: boolean }> = [];

package/src/Game/Object.ts

@@ -29,12 +29,49 @@ type ConfigurableTrigger<T> = Omit<Trigger<T>, "start"> & {
   start(config?: T): Promise<void>;
 };
 
+const toFiniteScale = (value: unknown, fallback: number): number => {
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (typeof value === "string" && value.trim()) {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : fallback;
+  }
+  return fallback;
+};
+
+const normalizeGraphicScale = (value: unknown, fallback: [number, number] = [1, 1]): [number, number] => {
+  if (typeof value === "number" || typeof value === "string") {
+    const scale = toFiniteScale(value, fallback[0]);
+    return [scale, scale];
+  }
+  if (Array.isArray(value)) {
+    const x = toFiniteScale(value[0], fallback[0]);
+    const y = toFiniteScale(value[1] ?? value[0], x);
+    return [x, y];
+  }
+  if (value && typeof value === "object") {
+    const scale = value as { x?: unknown; y?: unknown };
+    const x = toFiniteScale(scale.x, fallback[0]);
+    const y = toFiniteScale(scale.y ?? scale.x, x);
+    return [x, y];
+  }
+  return fallback;
+};
+
+export const multiplyGraphicDisplayScale = (
+  baseScale: unknown,
+  instanceScale: unknown,
+): [number, number] => {
+  const base = normalizeGraphicScale(baseScale);
+  const instance = normalizeGraphicScale(instanceScale);
+  return [base[0] * instance[0], base[1] * instance[1]];
+};
+
 export const withGraphicDisplayScale = (spritesheet: any, scale: unknown): any => {
   if (!spritesheet || typeof spritesheet !== "object") return spritesheet;
   if (scale === undefined || scale === null) return spritesheet;
   return {
     ...spritesheet,
-    displayScale: scale,
+    displayScale: multiplyGraphicDisplayScale(spritesheet.displayScale, scale),
   };
 };
 
@@ -47,6 +84,24 @@ export const appendFramePayload = (current: unknown, items: unknown): Frame[] =>
   return currentFrames.concat(nextFrames);
 };
 
+export const getFrameTimestamp = (frame: Frame): number => {
+  const timestamp = Number(frame.ts);
+  return Number.isFinite(timestamp) ? timestamp : 0;
+};
+
+export const mergeFreshFramePayload = (
+  current: unknown,
+  items: unknown,
+  lastAppliedFrameTs = 0,
+): Frame[] => {
+  return appendFramePayload(current, items)
+    .filter((frame) => {
+      const timestamp = getFrameTimestamp(frame);
+      return timestamp === 0 || timestamp > lastAppliedFrameTs;
+    })
+    .sort((a, b) => getFrameTimestamp(a) - getFrameTimestamp(b));
+};
+
 export abstract class RpgClientObject extends RpgCommonPlayer {
   abstract _type: string;
   emitParticleTrigger = trigger();
@@ -57,6 +112,7 @@ export abstract class RpgClientObject extends RpgCommonPlayer {
   frames: Frame[] = [];
   graphicsSignals = signal<any[]>([]);
   flashTrigger: ConfigurableTrigger<FlashTriggerOptions> = trigger<FlashTriggerOptions>();
+  private lastAppliedFrameTs = 0;
   private animationRestoreState?: {
     animationName: string;
     graphics: any[];
@@ -70,7 +126,11 @@ export abstract class RpgClientObject extends RpgCommonPlayer {
     this._frames.observable.subscribe(({ items }) => {
       if (!this.id) return;
       //if (this.id == this.engine.playerIdSignal()!) return;
-      this.frames = appendFramePayload(this.frames, items);
+      this.frames = mergeFreshFramePayload(
+        this.frames,
+        items,
+        this.lastAppliedFrameTs,
+      );
     });
 
     const graphics$ = this.graphics.observable.pipe(map(({ items }) => items));
@@ -102,16 +162,25 @@ export abstract class RpgClientObject extends RpgCommonPlayer {
         const frame = this.frames.shift();
         if (frame) {
           if (typeof frame.x !== "number" || typeof frame.y !== "number") return;
+          const frameTs = this.getFrameTimestamp(frame);
+          if (frameTs > 0 && frameTs <= this.lastAppliedFrameTs) return;
           engine.scene.setBodyPosition(
             this.id,
             frame.x,
             frame.y,
             "top-left"
           );
+          if (frameTs > this.lastAppliedFrameTs) {
+            this.lastAppliedFrameTs = frameTs;
+          }
         }
       });
   }
 
+  private getFrameTimestamp(frame: Frame): number {
+    return getFrameTimestamp(frame);
+  }
+
   /**
    * Access the shared client hook registry.
    *
@@ -130,6 +199,25 @@ export abstract class RpgClientObject extends RpgCommonPlayer {
     return inject(RpgClientEngine);
   }
 
+  setHitbox(width: number, height: number): void {
+    if (typeof width !== "number" || width <= 0) {
+      throw new Error("setHitbox: width must be a positive number");
+    }
+    if (typeof height !== "number" || height <= 0) {
+      throw new Error("setHitbox: height must be a positive number");
+    }
+
+    this.hitbox.set({
+      w: width,
+      h: height,
+    });
+
+    const sceneMap = (this.engine as any)?.sceneMap;
+    if (sceneMap && this.id) {
+      sceneMap.updateHitbox?.(this.id, this.x(), this.y(), width, height);
+    }
+  }
+
   private animationSubscription?: Subscription;
   private animationResetTimeout?: ReturnType<typeof setTimeout>;
   private animationWaitResolve?: () => void;

package/src/RpgClientEngine.ts

@@ -39,6 +39,7 @@ import { normalizeActionInput } from "./services/actionInput";
 import { createClientPointerContext, type ClientPointerContext } from "./services/pointerContext";
 import { RpgClientInteractions } from "./services/interactions";
 import { normalizeRoomMapId } from "./utils/mapId";
+import { applySyncedHitboxPayload } from "./utils/syncHitbox";
 import { EventComponentResolverRegistry, type EventComponentResolver } from "./Game/EventComponentResolver";
 import { RpgClientBuiltinI18n } from "./i18n";
 import type { CameraFollowSmoothMove } from "./services/cameraFollow";
@@ -967,6 +968,7 @@ export class RpgClientEngine<T = any> {
         : undefined;
     const payload = this.prepareSyncPayload(data);
     load(this.sceneMap, payload, true);
+    applySyncedHitboxPayload(this.sceneMap, payload);
 
     if (normalizedAck) {
       this.applyServerAck(normalizedAck);
@@ -2172,12 +2174,25 @@ export class RpgClientEngine<T = any> {
     return { x, y, direction };
   }
 
+  private resolveHitboxDimension(source: unknown, fallback: number): number {
+    const value = typeof source === "string" ? Number(source) : source;
+    return typeof value === "number" && Number.isFinite(value) && value > 0
+      ? value
+      : fallback;
+  }
+
+  private resolveObjectHitboxSize(object: any): { width: number; height: number } {
+    const hitbox = typeof object?.hitbox === "function" ? object.hitbox() : object?.hitbox;
+    return {
+      width: this.resolveHitboxDimension(hitbox?.w ?? hitbox?.width, 0),
+      height: this.resolveHitboxDimension(hitbox?.h ?? hitbox?.height, 0),
+    };
+  }
+
   private applyAuthoritativeState(state: PredictionState<Direction>): void {
     const player = this.sceneMap?.getCurrentPlayer();
     if (!player) return;
-    const hitbox = typeof player.hitbox === "function" ? player.hitbox() : player.hitbox;
-    const width = hitbox?.w ?? 0;
-    const height = hitbox?.h ?? 0;
+    const { width, height } = this.resolveObjectHitboxSize(player);
     const updated = this.sceneMap.updateHitbox(player.id, state.x, state.y, width, height);
     if (!updated) {
       this.sceneMap.setBodyPosition(player.id, state.x, state.y, "top-left");
@@ -2406,9 +2421,7 @@ export class RpgClientEngine<T = any> {
     if (!player || !myId) {
       return;
     }
-    const hitbox = typeof player.hitbox === "function" ? player.hitbox() : player.hitbox;
-    const width = hitbox?.w ?? 0;
-    const height = hitbox?.h ?? 0;
+    const { width, height } = this.resolveObjectHitboxSize(player);
     const updated = this.sceneMap.updateHitbox(myId, ack.x, ack.y, width, height);
     if (!updated) {
       this.sceneMap.setBodyPosition(myId, ack.x, ack.y, "top-left");

package/src/components/character-hitbox.spec.ts

@@ -0,0 +1,33 @@
+import { describe, expect, test } from "vitest";
+import {
+  resolveHitboxAnchor,
+  resolveScaledHitboxAnchor,
+  scaleHitboxForGraphicDisplay,
+} from "./character-hitbox";
+
+describe("character hitbox display helpers", () => {
+  test("keeps the rendered hitbox dimensions stable when graphic display scale changes", () => {
+    const hitbox = { w: 32, h: 32 };
+    const scaled = scaleHitboxForGraphicDisplay(hitbox, [0.5, 0.5]);
+
+    expect(scaled).toEqual({ w: 64, h: 64 });
+    expect(scaled!.w * 0.5).toBe(32);
+    expect(scaled!.h * 0.5).toBe(32);
+  });
+
+  test("anchors the graphic from the display-adjusted hitbox", () => {
+    const unscaledAnchor = resolveHitboxAnchor(96, 96, undefined, { w: 32, h: 32 });
+    const scaledAnchor = resolveHitboxAnchor(96, 96, undefined, { w: 64, h: 64 });
+
+    expect(unscaledAnchor).toEqual([1 / 3, 2 / 3]);
+    expect(scaledAnchor).toEqual([1 / 6, 1 / 3]);
+  });
+
+  test("keeps the graphic foot aligned with the hitbox foot after sprite scale", () => {
+    const anchor = resolveScaledHitboxAnchor(256, 256, undefined, { w: 56, h: 50 }, [0.5, 0.5]);
+
+    const renderedBottom = (1 - anchor[1]) * 256 * 0.5;
+
+    expect(renderedBottom).toBe(50);
+  });
+});

package/src/components/character-hitbox.ts

@@ -0,0 +1,72 @@
+export type CharacterHitbox = {
+  w: number;
+  h: number;
+  anchorMode?: "top-left" | "center" | "foot";
+};
+
+export const toPositiveNumber = (value: unknown): number | undefined => {
+  const number = typeof value === "number" ? value : parseFloat(String(value));
+  return Number.isFinite(number) && number > 0 ? number : undefined;
+};
+
+const clampRatio = (value: number): number => Math.min(1, Math.max(0, value));
+
+export const scaleHitboxForGraphicDisplay = (
+  box: CharacterHitbox | null | undefined,
+  scale: [number, number],
+): CharacterHitbox | null => {
+  if (!box) return null;
+  const scaleX = Math.abs(toPositiveNumber(scale[0]) ?? 1);
+  const scaleY = Math.abs(toPositiveNumber(scale[1]) ?? scaleX);
+
+  return {
+    ...box,
+    w: box.w / scaleX,
+    h: box.h / scaleY,
+  };
+};
+
+export const resolveHitboxAnchor = (
+  spriteWidth: number | undefined,
+  spriteHeight: number | undefined,
+  realSize: number | { height?: number } | undefined,
+  box: CharacterHitbox | null | undefined,
+): [number, number] => {
+  if (!spriteWidth || !spriteHeight || !box) {
+    return [0, 0];
+  }
+
+  const heightOfSprite = typeof realSize === "number" ? realSize : realSize?.height;
+  const resolvedHeight = toPositiveNumber(heightOfSprite) ?? spriteHeight;
+  const gap = Math.max(0, (spriteHeight - resolvedHeight) / 2);
+  const hitboxTopLeftX = clampRatio((spriteWidth - box.w) / 2 / spriteWidth);
+  const hitboxTopLeftY = clampRatio((spriteHeight - box.h - gap) / spriteHeight);
+  const hitboxCenterX = clampRatio(hitboxTopLeftX + box.w / 2 / spriteWidth);
+  const hitboxCenterY = clampRatio(hitboxTopLeftY + box.h / 2 / spriteHeight);
+  const footY = clampRatio((spriteHeight - gap) / spriteHeight);
+
+  switch (box.anchorMode ?? "top-left") {
+    case "center":
+      return [hitboxCenterX, hitboxCenterY];
+    case "foot":
+      return [hitboxCenterX, footY];
+    case "top-left":
+    default:
+      return [hitboxTopLeftX, hitboxTopLeftY];
+  }
+};
+
+export const resolveScaledHitboxAnchor = (
+  spriteWidth: number | undefined,
+  spriteHeight: number | undefined,
+  realSize: number | { height?: number } | undefined,
+  box: CharacterHitbox | null | undefined,
+  scale: [number, number],
+): [number, number] => {
+  return resolveHitboxAnchor(
+    spriteWidth,
+    spriteHeight,
+    realSize,
+    scaleHitboxForGraphicDisplay(box, scale),
+  );
+};