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

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @rpgjs/client
 
+## 5.0.0-beta.24
+
+### Patch Changes
+
+- e11f2ed: Fix main menu Escape handling, add outside-click and touch close controls for prebuilt modal GUIs, make menu layouts responsive on small screens, restore a compact desktop menu with an integrated sidebar and column-based item views, use fade-only menu transitions, improve Skills/Equipment and save slot spacing, make active menu rows less visually harsh, and improve HUD and dialog border rendering.
+- 3fb2765: Apply Studio media scale as a multiplier of the default RPGJS display scale, then combine it with event instance scale instead of overwriting it.
+- be412cf: Let Studio event-touch pressure plates overlap pushed events without physical separation, wait until ground sensors are mostly covered before firing, clean up touch tracking when collisions exit after z changes, and clamp route overshoot frames that could make pushed events jitter.
+- Updated dependencies [e11f2ed]
+- Updated dependencies [be412cf]
+  - @rpgjs/ui-css@5.0.0-beta.22
+  - @rpgjs/common@5.0.0-beta.23
+  - @rpgjs/server@5.0.0-beta.24
+
+## 5.0.0-beta.23
+
+### Patch Changes
+
+- e7d8d13: Hydrate Studio event hitboxes from the API initially, apply synchronized hitbox object payloads to client physics bodies, publish runtime Studio hitbox changes through the synced event collection instead of a separate setHitbox websocket path, and keep standalone map transfers on the restored room so transferred player positions and hitboxes are preserved in sample-dev.
+- Updated dependencies [e7d8d13]
+  - @rpgjs/common@5.0.0-beta.22
+  - @rpgjs/server@5.0.0-beta.23
+
 ## 5.0.0-beta.22
 
 ### Patch Changes

package/dist/Game/Object.d.ts

@@ -25,8 +25,11 @@ type FlashTriggerOptions = Omit<FlashOptions, "tint"> & {
 type ConfigurableTrigger<T> = Omit<Trigger<T>, "start"> & {
     start(config?: T): Promise<void>;
 };
+export declare const multiplyGraphicDisplayScale: (baseScale: unknown, instanceScale: unknown) => [number, number];
 export declare const withGraphicDisplayScale: (spritesheet: any, scale: unknown) => any;
 export declare const appendFramePayload: (current: unknown, items: unknown) => Frame[];
+export declare const getFrameTimestamp: (frame: Frame) => number;
+export declare const mergeFreshFramePayload: (current: unknown, items: unknown, lastAppliedFrameTs?: number) => Frame[];
 export declare abstract class RpgClientObject extends RpgCommonPlayer {
     abstract _type: string;
     emitParticleTrigger: Trigger<any>;
@@ -37,8 +40,10 @@ export declare abstract class RpgClientObject extends RpgCommonPlayer {
     frames: Frame[];
     graphicsSignals: import('canvasengine').WritableArraySignal<any[]>;
     flashTrigger: ConfigurableTrigger<FlashTriggerOptions>;
+    private lastAppliedFrameTs;
     private animationRestoreState?;
     constructor();
+    private getFrameTimestamp;
     /**
      * Access the shared client hook registry.
      *
@@ -51,6 +56,7 @@ export declare abstract class RpgClientObject extends RpgCommonPlayer {
      * @returns The active {@link RpgClientEngine} instance.
      */
     get engine(): RpgClientEngine<unknown>;
+    setHitbox(width: number, height: number): void;
     private animationSubscription?;
     private animationResetTimeout?;
     private animationWaitResolve?;

package/dist/Game/Object.js

@@ -4,18 +4,57 @@ import { signal, trigger } from "canvasengine";
 import { ModulesToken, RpgCommonPlayer } from "@rpgjs/common";
 import { combineLatest, from, map, of, startWith, switchMap } from "rxjs";
 //#region src/Game/Object.ts
+var toFiniteScale = (value, fallback) => {
+	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;
+};
+var normalizeGraphicScale = (value, fallback = [1, 1]) => {
+	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]);
+		return [x, toFiniteScale(value[1] ?? value[0], x)];
+	}
+	if (value && typeof value === "object") {
+		const scale = value;
+		const x = toFiniteScale(scale.x, fallback[0]);
+		return [x, toFiniteScale(scale.y ?? scale.x, x)];
+	}
+	return fallback;
+};
+var multiplyGraphicDisplayScale = (baseScale, instanceScale) => {
+	const base = normalizeGraphicScale(baseScale);
+	const instance = normalizeGraphicScale(instanceScale);
+	return [base[0] * instance[0], base[1] * instance[1]];
+};
 var withGraphicDisplayScale = (spritesheet, scale) => {
 	if (!spritesheet || typeof spritesheet !== "object") return spritesheet;
 	if (scale === void 0 || scale === null) return spritesheet;
 	return {
 		...spritesheet,
-		displayScale: scale
+		displayScale: multiplyGraphicDisplayScale(spritesheet.displayScale, scale)
 	};
 };
 var appendFramePayload = (current, items) => {
 	const nextFrames = (Array.isArray(items) ? items : items ? [items] : []).flatMap((item) => Array.isArray(item) ? item : [item]);
 	return (Array.isArray(current) ? current : []).concat(nextFrames);
 };
+var getFrameTimestamp = (frame) => {
+	const timestamp = Number(frame.ts);
+	return Number.isFinite(timestamp) ? timestamp : 0;
+};
+var mergeFreshFramePayload = (current, items, lastAppliedFrameTs = 0) => {
+	return appendFramePayload(current, items).filter((frame) => {
+		const timestamp = getFrameTimestamp(frame);
+		return timestamp === 0 || timestamp > lastAppliedFrameTs;
+	}).sort((a, b) => getFrameTimestamp(a) - getFrameTimestamp(b));
+};
 var RpgClientObject = class extends RpgCommonPlayer {
 	constructor() {
 		super();
@@ -27,11 +66,12 @@ var RpgClientObject = class extends RpgCommonPlayer {
 		this.frames = [];
 		this.graphicsSignals = signal([]);
 		this.flashTrigger = trigger();
+		this.lastAppliedFrameTs = 0;
 		const engine = this.engine;
 		this.hooks.callHooks("client-sprite-onInit", this).subscribe();
 		this._frames.observable.subscribe(({ items }) => {
 			if (!this.id) return;
-			this.frames = appendFramePayload(this.frames, items);
+			this.frames = mergeFreshFramePayload(this.frames, items, this.lastAppliedFrameTs);
 		});
 		combineLatest([this.graphics.observable.pipe(map(({ items }) => items)), this._graphicScale.observable.pipe(startWith({ value: this._graphicScale() }), map((payload) => payload?.value ?? payload))]).pipe(switchMap(([graphics, scale]) => {
 			const graphicRefs = Array.isArray(graphics) ? graphics : [];
@@ -46,10 +86,16 @@ var RpgClientObject = class 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;
 			}
 		});
 	}
+	getFrameTimestamp(frame) {
+		return getFrameTimestamp(frame);
+	}
 	/**
 	* Access the shared client hook registry.
 	*
@@ -66,6 +112,16 @@ var RpgClientObject = class extends RpgCommonPlayer {
 	get engine() {
 		return inject(RpgClientEngine);
 	}
+	setHitbox(width, height) {
+		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?.sceneMap;
+		if (sceneMap && this.id) sceneMap.updateHitbox?.(this.id, this.x(), this.y(), width, height);
+	}
 	clearAnimationControls() {
 		if (this.animationSubscription) {
 			this.animationSubscription.unsubscribe();

package/dist/Game/Object.js.map

@@ -1 +1 @@
-{"version":3,"file":"Object.js","names":[],"sources":["../../src/Game/Object.ts"],"sourcesContent":["import { Hooks, ModulesToken, RpgCommonPlayer } from \"@rpgjs/common\";\nimport { trigger, signal, type Trigger } from \"canvasengine\";\nimport { combineLatest, from, map, of, startWith, Subscription, switchMap } from \"rxjs\";\nimport { inject } from \"../core/inject\";\nimport { RpgClientEngine } from \"../RpgClientEngine\";\ntype Frame = { x: number; y: number; ts: number };\n\ntype AnimationRestoreOptions = {\n  restoreAnimationName?: string;\n  restoreGraphics?: any[];\n  timeoutMs?: number;\n};\n\ntype FlashType = 'alpha' | 'tint' | 'both';\n\ntype FlashOptions = {\n  type?: FlashType;\n  duration?: number;\n  cycles?: number;\n  alpha?: number;\n  tint?: number | string;\n};\n\ntype FlashTriggerOptions = Omit<FlashOptions, \"tint\"> & {\n  tint: number;\n};\n\ntype ConfigurableTrigger<T> = Omit<Trigger<T>, \"start\"> & {\n  start(config?: T): Promise<void>;\n};\n\nexport const withGraphicDisplayScale = (spritesheet: any, scale: unknown): any => {\n  if (!spritesheet || typeof spritesheet !== \"object\") return spritesheet;\n  if (scale === undefined || scale === null) return spritesheet;\n  return {\n    ...spritesheet,\n    displayScale: scale,\n  };\n};\n\nexport const appendFramePayload = (current: unknown, items: unknown): Frame[] => {\n  const frameItems = Array.isArray(items) ? items : items ? [items] : [];\n  const nextFrames = frameItems.flatMap((item): Frame[] =>\n    Array.isArray(item) ? item : [item as Frame]\n  );\n  const currentFrames = Array.isArray(current) ? current as Frame[] : [];\n  return currentFrames.concat(nextFrames);\n};\n\nexport abstract class RpgClientObject extends RpgCommonPlayer {\n  abstract _type: string;\n  emitParticleTrigger = trigger();\n  particleName = signal(\"\");\n  animationCurrentIndex = signal(0);\n  animationIsPlaying = signal(false);\n  _param = signal({});\n  frames: Frame[] = [];\n  graphicsSignals = signal<any[]>([]);\n  flashTrigger: ConfigurableTrigger<FlashTriggerOptions> = trigger<FlashTriggerOptions>();\n  private animationRestoreState?: {\n    animationName: string;\n    graphics: any[];\n  };\n\n  constructor() {\n    super();\n    const engine = this.engine;\n    this.hooks.callHooks(\"client-sprite-onInit\", this).subscribe();\n\n    this._frames.observable.subscribe(({ items }) => {\n      if (!this.id) return;\n      //if (this.id == this.engine.playerIdSignal()!) return;\n      this.frames = appendFramePayload(this.frames, items);\n    });\n\n    const graphics$ = this.graphics.observable.pipe(map(({ items }) => items));\n    const graphicScale$ = this._graphicScale.observable.pipe(\n      startWith({ value: this._graphicScale() }),\n      map((payload: any) => payload?.value ?? payload),\n    );\n\n    combineLatest([graphics$, graphicScale$])\n    .pipe(\n      switchMap(([graphics, scale]) => {\n        const graphicRefs = Array.isArray(graphics) ? graphics : [];\n        if (graphicRefs.length === 0) return of([]);\n        return from(Promise.all(graphicRefs.map(async (graphic) => {\n          const spritesheet = await engine.getSpriteSheet(graphic);\n          return withGraphicDisplayScale(spritesheet, scale);\n        })));\n      })\n    )\n    .subscribe((sheets) => {  \n      this.graphicsSignals.set(sheets);\n    });\n\n    engine.tick\n      .pipe\n      //throttleTime(10)\n      ()\n      .subscribe(() => {\n        const frame = this.frames.shift();\n        if (frame) {\n          if (typeof frame.x !== \"number\" || typeof frame.y !== \"number\") return;\n          engine.scene.setBodyPosition(\n            this.id,\n            frame.x,\n            frame.y,\n            \"top-left\"\n          );\n        }\n      });\n  }\n\n  /**\n   * Access the shared client hook registry.\n   *\n   * @returns The hook service used to register and trigger client-side hooks.\n   */\n  get hooks() {\n    return inject<Hooks>(ModulesToken);\n  }\n\n  /**\n   * Access the current client engine instance.\n   *\n   * @returns The active {@link RpgClientEngine} instance.\n   */\n  get engine() {\n    return inject(RpgClientEngine);\n  }\n\n  private animationSubscription?: Subscription;\n  private animationResetTimeout?: ReturnType<typeof setTimeout>;\n  private animationWaitResolve?: () => void;\n\n  private clearAnimationControls() {\n    if (this.animationSubscription) {\n      this.animationSubscription.unsubscribe();\n      this.animationSubscription = undefined;\n    }\n    if (this.animationResetTimeout) {\n      clearTimeout(this.animationResetTimeout);\n      this.animationResetTimeout = undefined;\n    }\n  }\n\n  private resolveAnimationWait() {\n    const resolve = this.animationWaitResolve;\n    this.animationWaitResolve = undefined;\n    resolve?.();\n  }\n\n  private finishTemporaryAnimation() {\n    const restoreState = this.animationRestoreState;\n    this.clearAnimationControls();\n    this.animationCurrentIndex.set(0);\n    this.animationRestoreState = undefined;\n    this.animationIsPlaying.set(false);\n    if (restoreState) {\n      this.animationName.set(restoreState.animationName);\n      this.graphics.set([...restoreState.graphics]);\n    }\n    this.resolveAnimationWait();\n  }\n\n  /**\n   * Trigger a flash animation on this sprite\n   * \n   * This method triggers a flash effect using CanvasEngine's flash directive.\n   * The flash can be configured with various options including type (alpha, tint, or both),\n   * duration, cycles, and color.\n   * \n   * ## Design\n   * \n   * The flash uses a trigger system that is connected to the flash directive in the\n   * character component. This allows for flexible configuration and can be triggered\n   * from both server events and client-side code.\n   * \n   * @param options - Flash configuration options\n   * @param options.type - Type of flash effect: 'alpha' (opacity), 'tint' (color), or 'both' (default: 'alpha')\n   * @param options.duration - Duration of the flash animation in milliseconds (default: 300)\n   * @param options.cycles - Number of flash cycles (flash on/off) (default: 1)\n   * @param options.alpha - Alpha value when flashing, from 0 to 1 (default: 0.3)\n   * @param options.tint - Tint color when flashing as hex value or color name (default: 0xffffff - white)\n   * \n   * @example\n   * ```ts\n   * // Simple flash with default settings (alpha flash)\n   * player.flash();\n   * \n   * // Flash with red tint\n   * player.flash({ type: 'tint', tint: 0xff0000 });\n   * \n   * // Flash with both alpha and tint\n   * player.flash({ \n   *   type: 'both', \n   *   alpha: 0.5, \n   *   tint: 0xff0000,\n   *   duration: 200,\n   *   cycles: 2\n   * });\n   * \n   * // Quick damage flash\n   * player.flash({ \n   *   type: 'tint', \n   *   tint: 0xff0000, \n   *   duration: 150,\n   *   cycles: 1\n   * });\n   * ```\n   */\n  flash(options?: FlashOptions): void {\n    const flashOptions = {\n      type: options?.type || 'alpha',\n      duration: options?.duration ?? 300,\n      cycles: options?.cycles ?? 1,\n      alpha: options?.alpha ?? 0.3,\n      tint: options?.tint ?? 0xffffff,\n    };\n    \n    // Convert color name to hex if needed\n    let tintValue = flashOptions.tint;\n    if (typeof tintValue === 'string') {\n      // Common color name to hex mapping\n      const colorMap: Record<string, number> = {\n        'white': 0xffffff,\n        'red': 0xff0000,\n        'green': 0x00ff00,\n        'blue': 0x0000ff,\n        'yellow': 0xffff00,\n        'cyan': 0x00ffff,\n        'magenta': 0xff00ff,\n        'black': 0x000000,\n      };\n      tintValue = colorMap[tintValue.toLowerCase()] ?? 0xffffff;\n    }\n    \n    this.flashTrigger.start({\n      ...flashOptions,\n      tint: tintValue,\n    });\n  }\n\n  /**\n   * Reset animation state when animation changes externally\n   *\n   * This method should be called when the animation changes due to movement\n   * or other external factors to ensure the animation system doesn't get stuck\n   *\n   * @example\n   * ```ts\n   * // Reset when player starts moving\n   * player.resetAnimationState();\n   * ```\n   */\n  resetAnimationState() {\n    if (this.animationRestoreState) {\n      this.finishTemporaryAnimation();\n      return;\n    }\n    this.animationIsPlaying.set(false);\n    this.animationCurrentIndex.set(0);\n    this.clearAnimationControls();\n    this.resolveAnimationWait();\n  }\n\n  /**\n   * Set a custom animation for a specific number of times\n   *\n   * Plays a custom animation for the specified number of repetitions.\n   * The animation system prevents overlapping animations and automatically\n   * returns to the previous animation when complete.\n   *\n   * @param animationName - Name of the animation to play\n   * @param nbTimes - Number of times to repeat the animation (default: Infinity for continuous)\n   * @param options - Restore and timeout options\n   * @returns A promise resolved when a finite animation finishes, is interrupted, or times out\n   *\n   * @example\n   * ```ts\n   * // Play attack animation 3 times\n   * await player.setAnimation('attack', 3);\n   *\n   * // Play continuous spell animation\n   * player.setAnimation('spell');\n   * ```\n   */\n  setAnimation(animationName: string, nbTimes?: number, options?: AnimationRestoreOptions): Promise<void>;\n  /**\n   * Set a custom animation with temporary graphic change\n   *\n   * Plays a custom animation for the specified number of repetitions and temporarily\n   * changes the player's graphic (sprite sheet) during the animation. The graphic\n   * is automatically reset when the animation finishes.\n   *\n   * @param animationName - Name of the animation to play\n   * @param graphic - The graphic(s) to temporarily use during the animation\n   * @param nbTimes - Number of times to repeat the animation (default: Infinity for continuous)\n   * @param options - Restore and timeout options\n   * @returns A promise resolved when a finite animation finishes, is interrupted, or times out\n   *\n   * @example\n   * ```ts\n   * // Play attack animation with temporary graphic change\n   * await player.setAnimation('attack', 'hero_attack', 3);\n   * ```\n   */\n  setAnimation(animationName: string, graphic?: string | string[], nbTimes?: number, options?: AnimationRestoreOptions): Promise<void>;\n  setAnimation(\n    animationName: string,\n    graphicOrNbTimes?: string | string[] | number,\n    nbTimesOrOptions?: number | AnimationRestoreOptions,\n    options?: AnimationRestoreOptions\n  ): Promise<void> {\n    let graphic: string | string[] | undefined;\n    let finalNbTimes: number = Infinity;\n    let restoreOptions: AnimationRestoreOptions | undefined = options;\n\n    // Handle overloads\n    if (typeof graphicOrNbTimes === 'number') {\n      // setAnimation(animationName, nbTimes)\n      finalNbTimes = graphicOrNbTimes;\n      restoreOptions = typeof nbTimesOrOptions === 'object' ? nbTimesOrOptions : options;\n    } else if (graphicOrNbTimes !== undefined) {\n      // setAnimation(animationName, graphic, nbTimes)\n      graphic = graphicOrNbTimes;\n      if (typeof nbTimesOrOptions === 'number') {\n        finalNbTimes = nbTimesOrOptions;\n      } else {\n        finalNbTimes = Infinity;\n        restoreOptions = nbTimesOrOptions ?? options;\n      }\n    } else {\n      // setAnimation(animationName) - nbTimes remains Infinity\n      finalNbTimes = Infinity;\n    }\n\n    if (this.animationIsPlaying()) {\n      this.finishTemporaryAnimation();\n    }\n\n    const waitPromise =\n      finalNbTimes === Infinity\n        ? Promise.resolve()\n        : new Promise<void>((resolve) => {\n            this.animationWaitResolve = resolve;\n          });\n\n    this.animationIsPlaying.set(true);\n    const previousAnimationName =\n      restoreOptions?.restoreAnimationName ?? this.animationName();\n    const previousGraphics = restoreOptions?.restoreGraphics\n      ? [...restoreOptions.restoreGraphics]\n      : [...this.graphics()];\n    this.animationRestoreState = {\n      animationName: previousAnimationName,\n      graphics: previousGraphics,\n    };\n    this.animationCurrentIndex.set(0);\n\n    // Temporarily change graphic if provided\n    if (graphic !== undefined) {\n      if (Array.isArray(graphic)) {\n        this.graphics.set(graphic);\n      } else {\n        this.graphics.set([graphic]);\n      }\n    }\n\n    this.clearAnimationControls();\n\n    this.animationSubscription =\n      this.animationCurrentIndex.observable.subscribe((index) => {\n        if (index >= finalNbTimes) {\n          this.finishTemporaryAnimation();\n        }\n      });\n\n    if (finalNbTimes !== Infinity) {\n      this.animationResetTimeout = setTimeout(() => {\n        if (this.animationIsPlaying()) {\n          this.finishTemporaryAnimation();\n        }\n      }, restoreOptions?.timeoutMs ?? Math.max(1000, finalNbTimes * 1000));\n    }\n\n    this.animationName.set(animationName);\n\n    return waitPromise;\n  }\n\n  /**\n   * Display a registered component animation effect on this object.\n   *\n   * @param id - Identifier of the component animation to play.\n   * @param params - Parameters forwarded to the animation effect.\n   * @returns A promise resolved when the animation component calls `onFinish`.\n   */\n  showComponentAnimation(id: string, params: any): Promise<void> {\n    const engine = inject(RpgClientEngine);\n    return engine.getComponentAnimation(id).displayEffect(params, this);\n  }\n\n  /**\n   * Display a registered spritesheet animation effect on this object.\n   *\n   * @param graphic - Identifier of the spritesheet to use.\n   * @param animationName - Name of the animation inside the spritesheet.\n   * @returns A promise resolved when the animation component calls `onFinish`.\n   */\n  showAnimation(graphic: string, animationName: string = 'default'): Promise<void> {\n    return this.showComponentAnimation('animation', {\n      graphic,\n      animationName,\n    });\n  }\n  \n  /**\n   * Check whether this client object represents an event.\n   *\n   * @returns `true` if the object type is `event`, otherwise `false`.\n   */\n  isEvent(): boolean {\n    return this._type === 'event';\n  }\n\n  /**\n   * Check whether this client object represents a player.\n   *\n   * @returns `true` if the object type is `player`, otherwise `false`.\n   */\n  isPlayer(): boolean {\n    return this._type === 'player';\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"Object.js","names":[],"sources":["../../src/Game/Object.ts"],"sourcesContent":["import { Hooks, ModulesToken, RpgCommonPlayer } from \"@rpgjs/common\";\nimport { trigger, signal, type Trigger } from \"canvasengine\";\nimport { combineLatest, from, map, of, startWith, Subscription, switchMap } from \"rxjs\";\nimport { inject } from \"../core/inject\";\nimport { RpgClientEngine } from \"../RpgClientEngine\";\ntype Frame = { x: number; y: number; ts: number };\n\ntype AnimationRestoreOptions = {\n  restoreAnimationName?: string;\n  restoreGraphics?: any[];\n  timeoutMs?: number;\n};\n\ntype FlashType = 'alpha' | 'tint' | 'both';\n\ntype FlashOptions = {\n  type?: FlashType;\n  duration?: number;\n  cycles?: number;\n  alpha?: number;\n  tint?: number | string;\n};\n\ntype FlashTriggerOptions = Omit<FlashOptions, \"tint\"> & {\n  tint: number;\n};\n\ntype ConfigurableTrigger<T> = Omit<Trigger<T>, \"start\"> & {\n  start(config?: T): Promise<void>;\n};\n\nconst toFiniteScale = (value: unknown, fallback: number): number => {\n  if (typeof value === \"number\" && Number.isFinite(value)) return value;\n  if (typeof value === \"string\" && value.trim()) {\n    const parsed = Number(value);\n    return Number.isFinite(parsed) ? parsed : fallback;\n  }\n  return fallback;\n};\n\nconst normalizeGraphicScale = (value: unknown, fallback: [number, number] = [1, 1]): [number, number] => {\n  if (typeof value === \"number\" || typeof value === \"string\") {\n    const scale = toFiniteScale(value, fallback[0]);\n    return [scale, scale];\n  }\n  if (Array.isArray(value)) {\n    const x = toFiniteScale(value[0], fallback[0]);\n    const y = toFiniteScale(value[1] ?? value[0], x);\n    return [x, y];\n  }\n  if (value && typeof value === \"object\") {\n    const scale = value as { x?: unknown; y?: unknown };\n    const x = toFiniteScale(scale.x, fallback[0]);\n    const y = toFiniteScale(scale.y ?? scale.x, x);\n    return [x, y];\n  }\n  return fallback;\n};\n\nexport const multiplyGraphicDisplayScale = (\n  baseScale: unknown,\n  instanceScale: unknown,\n): [number, number] => {\n  const base = normalizeGraphicScale(baseScale);\n  const instance = normalizeGraphicScale(instanceScale);\n  return [base[0] * instance[0], base[1] * instance[1]];\n};\n\nexport const withGraphicDisplayScale = (spritesheet: any, scale: unknown): any => {\n  if (!spritesheet || typeof spritesheet !== \"object\") return spritesheet;\n  if (scale === undefined || scale === null) return spritesheet;\n  return {\n    ...spritesheet,\n    displayScale: multiplyGraphicDisplayScale(spritesheet.displayScale, scale),\n  };\n};\n\nexport const appendFramePayload = (current: unknown, items: unknown): Frame[] => {\n  const frameItems = Array.isArray(items) ? items : items ? [items] : [];\n  const nextFrames = frameItems.flatMap((item): Frame[] =>\n    Array.isArray(item) ? item : [item as Frame]\n  );\n  const currentFrames = Array.isArray(current) ? current as Frame[] : [];\n  return currentFrames.concat(nextFrames);\n};\n\nexport const getFrameTimestamp = (frame: Frame): number => {\n  const timestamp = Number(frame.ts);\n  return Number.isFinite(timestamp) ? timestamp : 0;\n};\n\nexport const mergeFreshFramePayload = (\n  current: unknown,\n  items: unknown,\n  lastAppliedFrameTs = 0,\n): Frame[] => {\n  return appendFramePayload(current, items)\n    .filter((frame) => {\n      const timestamp = getFrameTimestamp(frame);\n      return timestamp === 0 || timestamp > lastAppliedFrameTs;\n    })\n    .sort((a, b) => getFrameTimestamp(a) - getFrameTimestamp(b));\n};\n\nexport abstract class RpgClientObject extends RpgCommonPlayer {\n  abstract _type: string;\n  emitParticleTrigger = trigger();\n  particleName = signal(\"\");\n  animationCurrentIndex = signal(0);\n  animationIsPlaying = signal(false);\n  _param = signal({});\n  frames: Frame[] = [];\n  graphicsSignals = signal<any[]>([]);\n  flashTrigger: ConfigurableTrigger<FlashTriggerOptions> = trigger<FlashTriggerOptions>();\n  private lastAppliedFrameTs = 0;\n  private animationRestoreState?: {\n    animationName: string;\n    graphics: any[];\n  };\n\n  constructor() {\n    super();\n    const engine = this.engine;\n    this.hooks.callHooks(\"client-sprite-onInit\", this).subscribe();\n\n    this._frames.observable.subscribe(({ items }) => {\n      if (!this.id) return;\n      //if (this.id == this.engine.playerIdSignal()!) return;\n      this.frames = mergeFreshFramePayload(\n        this.frames,\n        items,\n        this.lastAppliedFrameTs,\n      );\n    });\n\n    const graphics$ = this.graphics.observable.pipe(map(({ items }) => items));\n    const graphicScale$ = this._graphicScale.observable.pipe(\n      startWith({ value: this._graphicScale() }),\n      map((payload: any) => payload?.value ?? payload),\n    );\n\n    combineLatest([graphics$, graphicScale$])\n    .pipe(\n      switchMap(([graphics, scale]) => {\n        const graphicRefs = Array.isArray(graphics) ? graphics : [];\n        if (graphicRefs.length === 0) return of([]);\n        return from(Promise.all(graphicRefs.map(async (graphic) => {\n          const spritesheet = await engine.getSpriteSheet(graphic);\n          return withGraphicDisplayScale(spritesheet, scale);\n        })));\n      })\n    )\n    .subscribe((sheets) => {  \n      this.graphicsSignals.set(sheets);\n    });\n\n    engine.tick\n      .pipe\n      //throttleTime(10)\n      ()\n      .subscribe(() => {\n        const frame = this.frames.shift();\n        if (frame) {\n          if (typeof frame.x !== \"number\" || typeof frame.y !== \"number\") return;\n          const frameTs = this.getFrameTimestamp(frame);\n          if (frameTs > 0 && frameTs <= this.lastAppliedFrameTs) return;\n          engine.scene.setBodyPosition(\n            this.id,\n            frame.x,\n            frame.y,\n            \"top-left\"\n          );\n          if (frameTs > this.lastAppliedFrameTs) {\n            this.lastAppliedFrameTs = frameTs;\n          }\n        }\n      });\n  }\n\n  private getFrameTimestamp(frame: Frame): number {\n    return getFrameTimestamp(frame);\n  }\n\n  /**\n   * Access the shared client hook registry.\n   *\n   * @returns The hook service used to register and trigger client-side hooks.\n   */\n  get hooks() {\n    return inject<Hooks>(ModulesToken);\n  }\n\n  /**\n   * Access the current client engine instance.\n   *\n   * @returns The active {@link RpgClientEngine} instance.\n   */\n  get engine() {\n    return inject(RpgClientEngine);\n  }\n\n  setHitbox(width: number, height: number): void {\n    if (typeof width !== \"number\" || width <= 0) {\n      throw new Error(\"setHitbox: width must be a positive number\");\n    }\n    if (typeof height !== \"number\" || height <= 0) {\n      throw new Error(\"setHitbox: height must be a positive number\");\n    }\n\n    this.hitbox.set({\n      w: width,\n      h: height,\n    });\n\n    const sceneMap = (this.engine as any)?.sceneMap;\n    if (sceneMap && this.id) {\n      sceneMap.updateHitbox?.(this.id, this.x(), this.y(), width, height);\n    }\n  }\n\n  private animationSubscription?: Subscription;\n  private animationResetTimeout?: ReturnType<typeof setTimeout>;\n  private animationWaitResolve?: () => void;\n\n  private clearAnimationControls() {\n    if (this.animationSubscription) {\n      this.animationSubscription.unsubscribe();\n      this.animationSubscription = undefined;\n    }\n    if (this.animationResetTimeout) {\n      clearTimeout(this.animationResetTimeout);\n      this.animationResetTimeout = undefined;\n    }\n  }\n\n  private resolveAnimationWait() {\n    const resolve = this.animationWaitResolve;\n    this.animationWaitResolve = undefined;\n    resolve?.();\n  }\n\n  private finishTemporaryAnimation() {\n    const restoreState = this.animationRestoreState;\n    this.clearAnimationControls();\n    this.animationCurrentIndex.set(0);\n    this.animationRestoreState = undefined;\n    this.animationIsPlaying.set(false);\n    if (restoreState) {\n      this.animationName.set(restoreState.animationName);\n      this.graphics.set([...restoreState.graphics]);\n    }\n    this.resolveAnimationWait();\n  }\n\n  /**\n   * Trigger a flash animation on this sprite\n   * \n   * This method triggers a flash effect using CanvasEngine's flash directive.\n   * The flash can be configured with various options including type (alpha, tint, or both),\n   * duration, cycles, and color.\n   * \n   * ## Design\n   * \n   * The flash uses a trigger system that is connected to the flash directive in the\n   * character component. This allows for flexible configuration and can be triggered\n   * from both server events and client-side code.\n   * \n   * @param options - Flash configuration options\n   * @param options.type - Type of flash effect: 'alpha' (opacity), 'tint' (color), or 'both' (default: 'alpha')\n   * @param options.duration - Duration of the flash animation in milliseconds (default: 300)\n   * @param options.cycles - Number of flash cycles (flash on/off) (default: 1)\n   * @param options.alpha - Alpha value when flashing, from 0 to 1 (default: 0.3)\n   * @param options.tint - Tint color when flashing as hex value or color name (default: 0xffffff - white)\n   * \n   * @example\n   * ```ts\n   * // Simple flash with default settings (alpha flash)\n   * player.flash();\n   * \n   * // Flash with red tint\n   * player.flash({ type: 'tint', tint: 0xff0000 });\n   * \n   * // Flash with both alpha and tint\n   * player.flash({ \n   *   type: 'both', \n   *   alpha: 0.5, \n   *   tint: 0xff0000,\n   *   duration: 200,\n   *   cycles: 2\n   * });\n   * \n   * // Quick damage flash\n   * player.flash({ \n   *   type: 'tint', \n   *   tint: 0xff0000, \n   *   duration: 150,\n   *   cycles: 1\n   * });\n   * ```\n   */\n  flash(options?: FlashOptions): void {\n    const flashOptions = {\n      type: options?.type || 'alpha',\n      duration: options?.duration ?? 300,\n      cycles: options?.cycles ?? 1,\n      alpha: options?.alpha ?? 0.3,\n      tint: options?.tint ?? 0xffffff,\n    };\n    \n    // Convert color name to hex if needed\n    let tintValue = flashOptions.tint;\n    if (typeof tintValue === 'string') {\n      // Common color name to hex mapping\n      const colorMap: Record<string, number> = {\n        'white': 0xffffff,\n        'red': 0xff0000,\n        'green': 0x00ff00,\n        'blue': 0x0000ff,\n        'yellow': 0xffff00,\n        'cyan': 0x00ffff,\n        'magenta': 0xff00ff,\n        'black': 0x000000,\n      };\n      tintValue = colorMap[tintValue.toLowerCase()] ?? 0xffffff;\n    }\n    \n    this.flashTrigger.start({\n      ...flashOptions,\n      tint: tintValue,\n    });\n  }\n\n  /**\n   * Reset animation state when animation changes externally\n   *\n   * This method should be called when the animation changes due to movement\n   * or other external factors to ensure the animation system doesn't get stuck\n   *\n   * @example\n   * ```ts\n   * // Reset when player starts moving\n   * player.resetAnimationState();\n   * ```\n   */\n  resetAnimationState() {\n    if (this.animationRestoreState) {\n      this.finishTemporaryAnimation();\n      return;\n    }\n    this.animationIsPlaying.set(false);\n    this.animationCurrentIndex.set(0);\n    this.clearAnimationControls();\n    this.resolveAnimationWait();\n  }\n\n  /**\n   * Set a custom animation for a specific number of times\n   *\n   * Plays a custom animation for the specified number of repetitions.\n   * The animation system prevents overlapping animations and automatically\n   * returns to the previous animation when complete.\n   *\n   * @param animationName - Name of the animation to play\n   * @param nbTimes - Number of times to repeat the animation (default: Infinity for continuous)\n   * @param options - Restore and timeout options\n   * @returns A promise resolved when a finite animation finishes, is interrupted, or times out\n   *\n   * @example\n   * ```ts\n   * // Play attack animation 3 times\n   * await player.setAnimation('attack', 3);\n   *\n   * // Play continuous spell animation\n   * player.setAnimation('spell');\n   * ```\n   */\n  setAnimation(animationName: string, nbTimes?: number, options?: AnimationRestoreOptions): Promise<void>;\n  /**\n   * Set a custom animation with temporary graphic change\n   *\n   * Plays a custom animation for the specified number of repetitions and temporarily\n   * changes the player's graphic (sprite sheet) during the animation. The graphic\n   * is automatically reset when the animation finishes.\n   *\n   * @param animationName - Name of the animation to play\n   * @param graphic - The graphic(s) to temporarily use during the animation\n   * @param nbTimes - Number of times to repeat the animation (default: Infinity for continuous)\n   * @param options - Restore and timeout options\n   * @returns A promise resolved when a finite animation finishes, is interrupted, or times out\n   *\n   * @example\n   * ```ts\n   * // Play attack animation with temporary graphic change\n   * await player.setAnimation('attack', 'hero_attack', 3);\n   * ```\n   */\n  setAnimation(animationName: string, graphic?: string | string[], nbTimes?: number, options?: AnimationRestoreOptions): Promise<void>;\n  setAnimation(\n    animationName: string,\n    graphicOrNbTimes?: string | string[] | number,\n    nbTimesOrOptions?: number | AnimationRestoreOptions,\n    options?: AnimationRestoreOptions\n  ): Promise<void> {\n    let graphic: string | string[] | undefined;\n    let finalNbTimes: number = Infinity;\n    let restoreOptions: AnimationRestoreOptions | undefined = options;\n\n    // Handle overloads\n    if (typeof graphicOrNbTimes === 'number') {\n      // setAnimation(animationName, nbTimes)\n      finalNbTimes = graphicOrNbTimes;\n      restoreOptions = typeof nbTimesOrOptions === 'object' ? nbTimesOrOptions : options;\n    } else if (graphicOrNbTimes !== undefined) {\n      // setAnimation(animationName, graphic, nbTimes)\n      graphic = graphicOrNbTimes;\n      if (typeof nbTimesOrOptions === 'number') {\n        finalNbTimes = nbTimesOrOptions;\n      } else {\n        finalNbTimes = Infinity;\n        restoreOptions = nbTimesOrOptions ?? options;\n      }\n    } else {\n      // setAnimation(animationName) - nbTimes remains Infinity\n      finalNbTimes = Infinity;\n    }\n\n    if (this.animationIsPlaying()) {\n      this.finishTemporaryAnimation();\n    }\n\n    const waitPromise =\n      finalNbTimes === Infinity\n        ? Promise.resolve()\n        : new Promise<void>((resolve) => {\n            this.animationWaitResolve = resolve;\n          });\n\n    this.animationIsPlaying.set(true);\n    const previousAnimationName =\n      restoreOptions?.restoreAnimationName ?? this.animationName();\n    const previousGraphics = restoreOptions?.restoreGraphics\n      ? [...restoreOptions.restoreGraphics]\n      : [...this.graphics()];\n    this.animationRestoreState = {\n      animationName: previousAnimationName,\n      graphics: previousGraphics,\n    };\n    this.animationCurrentIndex.set(0);\n\n    // Temporarily change graphic if provided\n    if (graphic !== undefined) {\n      if (Array.isArray(graphic)) {\n        this.graphics.set(graphic);\n      } else {\n        this.graphics.set([graphic]);\n      }\n    }\n\n    this.clearAnimationControls();\n\n    this.animationSubscription =\n      this.animationCurrentIndex.observable.subscribe((index) => {\n        if (index >= finalNbTimes) {\n          this.finishTemporaryAnimation();\n        }\n      });\n\n    if (finalNbTimes !== Infinity) {\n      this.animationResetTimeout = setTimeout(() => {\n        if (this.animationIsPlaying()) {\n          this.finishTemporaryAnimation();\n        }\n      }, restoreOptions?.timeoutMs ?? Math.max(1000, finalNbTimes * 1000));\n    }\n\n    this.animationName.set(animationName);\n\n    return waitPromise;\n  }\n\n  /**\n   * Display a registered component animation effect on this object.\n   *\n   * @param id - Identifier of the component animation to play.\n   * @param params - Parameters forwarded to the animation effect.\n   * @returns A promise resolved when the animation component calls `onFinish`.\n   */\n  showComponentAnimation(id: string, params: any): Promise<void> {\n    const engine = inject(RpgClientEngine);\n    return engine.getComponentAnimation(id).displayEffect(params, this);\n  }\n\n  /**\n   * Display a registered spritesheet animation effect on this object.\n   *\n   * @param graphic - Identifier of the spritesheet to use.\n   * @param animationName - Name of the animation inside the spritesheet.\n   * @returns A promise resolved when the animation component calls `onFinish`.\n   */\n  showAnimation(graphic: string, animationName: string = 'default'): Promise<void> {\n    return this.showComponentAnimation('animation', {\n      graphic,\n      animationName,\n    });\n  }\n  \n  /**\n   * Check whether this client object represents an event.\n   *\n   * @returns `true` if the object type is `event`, otherwise `false`.\n   */\n  isEvent(): boolean {\n    return this._type === 'event';\n  }\n\n  /**\n   * Check whether this client object represents a player.\n   *\n   * @returns `true` if the object type is `player`, otherwise `false`.\n   */\n  isPlayer(): boolean {\n    return this._type === 'player';\n  }\n}\n"],"mappings":"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"}

package/dist/RpgClientEngine.d.ts

@@ -697,6 +697,8 @@ export declare class RpgClientEngine<T = any> {
     private flushPendingMovePath;
     private applyPredictedMovementInput;
     private getLocalPlayerState;
+    private resolveHitboxDimension;
+    private resolveObjectHitboxSize;
     private applyAuthoritativeState;
     private initializePredictionController;
     getCurrentPlayer(): import('.').RpgClientPlayer;

package/dist/RpgClientEngine.js

@@ -24,6 +24,7 @@ import { ProjectileManager } from "./Game/ProjectileManager.js";
 import { ClientVisualRegistry } from "./Game/ClientVisuals.js";
 import { createClientPointerContext } from "./services/pointerContext.js";
 import { RpgClientInteractions } from "./services/interactions.js";
+import { applySyncedHitboxPayload } from "./utils/syncHitbox.js";
 import { EventComponentResolverRegistry } from "./Game/EventComponentResolver.js";
 import { RpgClientBuiltinI18n } from "./i18n.js";
 import { Howl, bootstrapCanvas, signal, trigger } from "canvasengine";
@@ -686,6 +687,7 @@ var RpgClientEngine = class {
 		const normalizedAck = ack && typeof ack.frame === "number" ? this.normalizeAckWithSyncState(ack, data) : void 0;
 		const payload = this.prepareSyncPayload(data);
 		load(this.sceneMap, payload, true);
+		applySyncedHitboxPayload(this.sceneMap, payload);
 		if (normalizedAck) this.applyServerAck(normalizedAck);
 		for (const playerId in payload.players ?? {}) {
 			const player = payload.players[playerId];
@@ -1603,12 +1605,21 @@ var RpgClientEngine = class {
 			direction: currentPlayer.direction()
 		};
 	}
+	resolveHitboxDimension(source, fallback) {
+		const value = typeof source === "string" ? Number(source) : source;
+		return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : fallback;
+	}
+	resolveObjectHitboxSize(object) {
+		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)
+		};
+	}
 	applyAuthoritativeState(state) {
 		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);
 		if (!this.sceneMap.updateHitbox(player.id, state.x, state.y, width, height)) this.sceneMap.setBodyPosition(player.id, state.x, state.y, "top-left");
 		player.x.set(Math.round(state.x));
 		player.y.set(Math.round(state.y));
@@ -1795,9 +1806,7 @@ var RpgClientEngine = class {
 		const player = this.getCurrentPlayer();
 		const myId = this.playerIdSignal();
 		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);
 		if (!this.sceneMap.updateHitbox(myId, ack.x, ack.y, width, height)) this.sceneMap.setBodyPosition(myId, ack.x, ack.y, "top-left");
 		player.x.set(Math.round(ack.x));
 		player.y.set(Math.round(ack.y));