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

package/src/RpgClientEngine.ts

@@ -39,8 +39,15 @@ 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";
+export type {
+  CameraFollowEase,
+  CameraFollowSmoothMove,
+  CameraFollowSmoothMoveOptions,
+} from "./services/cameraFollow";
 
 interface MovementTrajectoryPoint {
   frame: number;
@@ -183,10 +190,14 @@ export class RpgClientEngine<T = any> {
   private eventComponentResolvers = new EventComponentResolverRegistry();
   /** ID of the sprite that the camera should follow. null means follow the current player */
   cameraFollowTargetId = signal<string | null>(null);
+  /** Camera follow transition options used by character components when the target changes */
+  cameraFollowSmoothMove: CameraFollowSmoothMove = false;
+  /** Incremented for each camera follow command so repeated commands on the same target are applied */
+  cameraFollowRevision = signal(0);
   /** Trigger for map shake animation */
   mapShakeTrigger: ConfigurableTrigger<MapShakeOptions> = trigger<MapShakeOptions>();
 
-  controlsReady = signal(undefined); 
+  controlsReady = signal<boolean | undefined>(undefined); 
   gamePause = signal(false);
 
   private predictionEnabled = false;
@@ -363,7 +374,7 @@ export class RpgClientEngine<T = any> {
       ...currentValues,
       values: new Map([['__default__', controlInstance]])
     }
-    this.controlsReady.set(undefined);
+    this.controlsReady.set(true);
   }
 
   async start() {
@@ -606,6 +617,12 @@ export class RpgClientEngine<T = any> {
     return find((this.canvasApp as any)?.stage);
   }
 
+  private clearCameraFollowViewportPlugins(): void {
+    const viewport = this.findViewportInstance();
+    viewport?.plugins?.remove?.("animate");
+    viewport?.plugins?.remove?.("follow");
+  }
+
   private prepareSyncPayload(data: any): any {
     const payload = { ...(data ?? {}) };
     delete payload.ack;
@@ -881,7 +898,7 @@ export class RpgClientEngine<T = any> {
     this.sceneMap.clearLightSpots();
     this.clearComponentAnimations();
     this.projectiles.setMapId(nextMapId);
-    this.cameraFollowTargetId.set(null);
+    this.resetCameraFollow(false);
     this.sceneMap.reset();
     this.sceneMap.loadPhysic();
   }
@@ -951,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);
@@ -1476,19 +1494,22 @@ export class RpgClientEngine<T = any> {
    * Set the camera to follow a specific sprite
    * 
    * This method changes which sprite the camera viewport should follow.
-   * The camera will smoothly animate to the target sprite if smoothMove options are provided.
+   * The camera can smoothly animate to the target sprite before continuous follow starts.
    * 
    * ## Design
    * 
    * The camera follow target is stored in a signal that is read by sprite components.
    * Each sprite checks if it should be followed by comparing its ID with the target ID.
-   * When smoothMove options are provided, the viewport animation is handled by CanvasEngine's
-   * viewport system.
+   * When smoothMove options are provided, the transition is handled by pixi-viewport's
+   * animation plugin, then continuous follow is handled by CanvasEngine's viewport system.
    * 
    * @param targetId - The ID of the sprite to follow. Set to null to follow the current player
    * @param smoothMove - Animation options. Can be a boolean (default: true) or an object with time and ease
    * @param smoothMove.time - Duration of the animation in milliseconds (optional)
    * @param smoothMove.ease - Easing function name from https://easings.net (optional)
+   * @param smoothMove.speed - Continuous follow speed after the transition (optional)
+   * @param smoothMove.acceleration - Continuous follow acceleration after the transition (optional)
+   * @param smoothMove.radius - Center radius where the target can move without moving the viewport (optional)
    * 
    * @example
    * ```ts
@@ -1510,19 +1531,19 @@ export class RpgClientEngine<T = any> {
    */
   setCameraFollow(
     targetId: string | null,
-    smoothMove?: boolean | { time?: number; ease?: string }
+    smoothMove?: CameraFollowSmoothMove
   ): void {
-    // Store smoothMove options for potential future use with viewport animation
-    // For now, we just set the target ID and let CanvasEngine handle the viewport follow
-    // The smoothMove options could be used to configure viewport animation if CanvasEngine supports it
+    this.clearCameraFollowViewportPlugins();
+    this.cameraFollowSmoothMove = smoothMove ?? true;
     this.cameraFollowTargetId.set(targetId);
-    
-    // If smoothMove is an object, we could store it for viewport configuration
-    // This would require integration with CanvasEngine's viewport animation system
-    if (typeof smoothMove === "object" && smoothMove !== null) {
-      // Future: Apply smoothMove.time and smoothMove.ease to viewport animation
-      // For now, CanvasEngine handles viewport following automatically
-    }
+    this.cameraFollowRevision.set(this.cameraFollowRevision() + 1);
+  }
+
+  private resetCameraFollow(smoothMove: CameraFollowSmoothMove = false): void {
+    this.clearCameraFollowViewportPlugins();
+    this.cameraFollowSmoothMove = smoothMove;
+    this.cameraFollowTargetId.set(null);
+    this.cameraFollowRevision.set(this.cameraFollowRevision() + 1);
   }
 
   addParticle(particle: any) {
@@ -2153,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");
@@ -2387,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");
@@ -2611,7 +2643,7 @@ export class RpgClientEngine<T = any> {
 
       // Reset signals
       this.playerIdSignal.set(null);
-      this.cameraFollowTargetId.set(null);
+      this.resetCameraFollow(false);
       this.spriteComponentsBehind.set([]);
       this.spriteComponentsInFront.set([]);
       this.eventComponentResolvers.clear();

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),
+  );
+};