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

package/src/services/cameraFollow.spec.ts

@@ -0,0 +1,220 @@
+import { describe, expect, it, vi } from "vitest";
+import {
+  applyCameraFollow,
+  cameraFollowAnimationOptions,
+  cameraFollowOptions,
+  ownsCameraFollowRevision,
+} from "./cameraFollow";
+
+const createViewport = () => ({
+  animate: vi.fn(),
+  follow: vi.fn(),
+  plugins: {
+    remove: vi.fn(),
+  },
+});
+
+describe("camera follow", () => {
+  it("normalizes transition options from smoothMove", () => {
+    expect(cameraFollowAnimationOptions(true)).toEqual({
+      time: 1000,
+      ease: "easeInOutSine",
+    });
+    expect(cameraFollowAnimationOptions({ time: 450, ease: "easeInOutQuad" })).toEqual({
+      time: 450,
+      ease: "easeInOutQuad",
+    });
+    expect(cameraFollowAnimationOptions({ time: 450, ease: "easeInOutQuadd" } as any)).toEqual({
+      time: 450,
+      ease: "easeInOutSine",
+    });
+    expect(cameraFollowAnimationOptions(false)).toBeNull();
+  });
+
+  it("normalizes continuous follow options", () => {
+    expect(cameraFollowOptions({ speed: 12, acceleration: 0.2, radius: 80 })).toEqual({
+      speed: 12,
+      acceleration: 0.2,
+      radius: 80,
+    });
+    expect(cameraFollowOptions({ speed: -4, acceleration: null, radius: null })).toEqual({
+      speed: 0,
+      acceleration: null,
+      radius: null,
+    });
+    expect(cameraFollowOptions(true)).toBeUndefined();
+  });
+
+  it("animates to the target then follows it", () => {
+    const viewport = createViewport();
+    const target = { x: 120, y: 240 };
+
+    applyCameraFollow({
+      viewport,
+      target,
+      smoothMove: { time: 800, ease: "easeInOutQuad", speed: 10, radius: 32 },
+      followRevision: 2,
+      isCurrentRevision: (revision) => revision === 2,
+      shouldFollowCamera: () => true,
+    });
+
+    expect(viewport.plugins.remove).toHaveBeenCalledWith("animate");
+    expect(viewport.plugins.remove).toHaveBeenCalledWith("follow");
+    expect(viewport.animate).toHaveBeenCalledWith(
+      expect.objectContaining({
+        position: { x: 120, y: 240 },
+        time: 800,
+        ease: "easeInOutQuad",
+      })
+    );
+    expect(viewport.follow).not.toHaveBeenCalled();
+
+    const animateOptions = viewport.animate.mock.calls[0][0];
+    animateOptions.callbackOnComplete();
+
+    const [followTarget, followOptions] = viewport.follow.mock.calls[0];
+    expect(followTarget).not.toBe(target);
+    expect(followTarget.x).toBe(120);
+    expect(followTarget.y).toBe(240);
+    expect(followOptions).toEqual({
+      speed: 10,
+      radius: 32,
+    });
+  });
+
+  it("follows instantly when smoothMove is disabled", () => {
+    const viewport = createViewport();
+    const target = { x: 120, y: 240 };
+
+    applyCameraFollow({
+      viewport,
+      target,
+      smoothMove: false,
+      followRevision: 1,
+      isCurrentRevision: () => true,
+      shouldFollowCamera: () => true,
+    });
+
+    expect(viewport.animate).not.toHaveBeenCalled();
+    const [followTarget] = viewport.follow.mock.calls[0];
+    expect(followTarget).not.toBe(target);
+    expect(followTarget.x).toBe(120);
+    expect(followTarget.y).toBe(240);
+  });
+
+  it("does not follow after animation if another camera command superseded it", () => {
+    const viewport = createViewport();
+
+    applyCameraFollow({
+      viewport,
+      target: { x: 120, y: 240 },
+      smoothMove: { time: 800, ease: "easeInOutQuad" },
+      followRevision: 2,
+      isCurrentRevision: (revision) => revision === 3,
+      shouldFollowCamera: () => true,
+    });
+
+    const animateOptions = viewport.animate.mock.calls[0][0];
+    animateOptions.callbackOnComplete();
+
+    expect(viewport.follow).not.toHaveBeenCalled();
+  });
+
+  it("does not follow a target whose position cannot be read", () => {
+    const viewport = createViewport();
+    const target = {
+      get x(): number {
+        throw new Error("target destroyed");
+      },
+      get y() {
+        return 240;
+      },
+    };
+
+    applyCameraFollow({
+      viewport,
+      target,
+      smoothMove: false,
+      followRevision: 1,
+      isCurrentRevision: () => true,
+      shouldFollowCamera: () => true,
+    });
+
+    expect(viewport.plugins.remove).toHaveBeenCalledWith("animate");
+    expect(viewport.plugins.remove).toHaveBeenCalledWith("follow");
+    expect(viewport.animate).not.toHaveBeenCalled();
+    expect(viewport.follow).not.toHaveBeenCalled();
+  });
+
+  it("keeps the follow target readable when the source target is destroyed", () => {
+    const viewport = createViewport();
+    let position: { x: number; y: number } | null = { x: 120, y: 240 };
+    const target = {
+      get destroyed() {
+        return position === null;
+      },
+      get x() {
+        if (!position) throw new Error("target destroyed");
+        return position.x;
+      },
+      get y() {
+        if (!position) throw new Error("target destroyed");
+        return position.y;
+      },
+    };
+
+    applyCameraFollow({
+      viewport,
+      target,
+      smoothMove: false,
+      followRevision: 1,
+      isCurrentRevision: () => true,
+      shouldFollowCamera: () => true,
+    });
+
+    const [followTarget] = viewport.follow.mock.calls[0];
+    expect(followTarget.x).toBe(120);
+    expect(followTarget.y).toBe(240);
+
+    position = { x: 160, y: 280 };
+    expect(followTarget.x).toBe(160);
+    expect(followTarget.y).toBe(280);
+
+    position = null;
+    expect(followTarget.x).toBe(160);
+    expect(followTarget.y).toBe(280);
+  });
+
+  it("does not follow after animation if the target was destroyed", () => {
+    const viewport = createViewport();
+    let destroyed = false;
+    const target = {
+      get destroyed() {
+        return destroyed;
+      },
+      x: 120,
+      y: 240,
+    };
+
+    applyCameraFollow({
+      viewport,
+      target,
+      smoothMove: { time: 800, ease: "easeInOutQuad" },
+      followRevision: 2,
+      isCurrentRevision: (revision) => revision === 2,
+      shouldFollowCamera: () => true,
+    });
+
+    destroyed = true;
+    const animateOptions = viewport.animate.mock.calls[0][0];
+    animateOptions.callbackOnComplete();
+
+    expect(viewport.follow).not.toHaveBeenCalled();
+  });
+
+  it("only lets the sprite that owns the active follow revision clear plugins", () => {
+    expect(ownsCameraFollowRevision(2, 2)).toBe(true);
+    expect(ownsCameraFollowRevision(2, 3)).toBe(false);
+    expect(ownsCameraFollowRevision(null, 2)).toBe(false);
+  });
+});

package/src/services/cameraFollow.ts

@@ -0,0 +1,222 @@
+export const DEFAULT_CAMERA_FOLLOW_TIME = 1000;
+export const DEFAULT_CAMERA_FOLLOW_EASE = "easeInOutSine";
+
+export const CAMERA_FOLLOW_EASES = [
+  "linear",
+  "easeInQuad",
+  "easeOutQuad",
+  "easeInOutQuad",
+  "easeInCubic",
+  "easeOutCubic",
+  "easeInOutCubic",
+  "easeInQuart",
+  "easeOutQuart",
+  "easeInOutQuart",
+  "easeInQuint",
+  "easeOutQuint",
+  "easeInOutQuint",
+  "easeInSine",
+  "easeOutSine",
+  "easeInOutSine",
+  "easeInExpo",
+  "easeOutExpo",
+  "easeInOutExpo",
+  "easeInCirc",
+  "easeOutCirc",
+  "easeInOutCirc",
+  "easeInElastic",
+  "easeOutElastic",
+  "easeInOutElastic",
+  "easeInBack",
+  "easeOutBack",
+  "easeInOutBack",
+  "easeInBounce",
+  "easeOutBounce",
+  "easeInOutBounce",
+] as const;
+
+export type CameraFollowEase = typeof CAMERA_FOLLOW_EASES[number];
+
+export type CameraFollowSmoothMoveOptions = {
+  /** Enable or disable the smooth transition when options are sent as an object. */
+  enabled?: boolean;
+  /** Duration of the transition to the new camera target, in milliseconds. */
+  time?: number;
+  /** pixi-viewport easing name, for example "easeInOutQuad". */
+  ease?: CameraFollowEase;
+  /** Continuous follow speed after the transition. 0 keeps the target centered instantly. */
+  speed?: number;
+  /** Continuous follow acceleration after the transition. */
+  acceleration?: number | null;
+  /** Center radius where the followed target can move without moving the viewport. */
+  radius?: number | null;
+};
+
+export type CameraFollowSmoothMove = boolean | CameraFollowSmoothMoveOptions;
+
+export type CameraFollowTarget = {
+  x: number;
+  y: number;
+  destroyed?: boolean;
+} | null | undefined;
+
+export type CameraFollowPosition = {
+  x: number;
+  y: number;
+};
+
+export interface CameraFollowApplyContext {
+  viewport: any;
+  target: CameraFollowTarget;
+  smoothMove: CameraFollowSmoothMove;
+  followRevision: number;
+  isCurrentRevision: (revision: number) => boolean;
+  shouldFollowCamera: () => boolean;
+}
+
+const finiteNumber = (value: unknown, fallback: number) => {
+  return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+};
+
+const isCameraFollowEase = (value: unknown): value is CameraFollowEase => {
+  return typeof value === "string" && (CAMERA_FOLLOW_EASES as readonly string[]).includes(value);
+};
+
+export const smoothMoveEnabled = (smoothMove: CameraFollowSmoothMove) => {
+  if (smoothMove === false) return false;
+  if (typeof smoothMove === "object" && smoothMove !== null && smoothMove.enabled === false) {
+    return false;
+  }
+  return true;
+};
+
+export const cameraFollowAnimationOptions = (
+  smoothMove: CameraFollowSmoothMove
+) => {
+  if (!smoothMoveEnabled(smoothMove)) return null;
+  const options = typeof smoothMove === "object" && smoothMove !== null ? smoothMove : {};
+  return {
+    time: Math.max(0, finiteNumber(options.time, DEFAULT_CAMERA_FOLLOW_TIME)),
+    ease: isCameraFollowEase(options.ease) ? options.ease : DEFAULT_CAMERA_FOLLOW_EASE,
+  };
+};
+
+export const cameraFollowOptions = (smoothMove: CameraFollowSmoothMove) => {
+  if (typeof smoothMove !== "object" || smoothMove === null) return undefined;
+  const options: { speed?: number; acceleration?: number | null; radius?: number | null } = {};
+  if (typeof smoothMove.speed === "number" && Number.isFinite(smoothMove.speed)) {
+    options.speed = Math.max(0, smoothMove.speed);
+  }
+  if (typeof smoothMove.acceleration === "number" && Number.isFinite(smoothMove.acceleration)) {
+    options.acceleration = Math.max(0, smoothMove.acceleration);
+  } else if (smoothMove.acceleration === null) {
+    options.acceleration = null;
+  }
+  if (typeof smoothMove.radius === "number" && Number.isFinite(smoothMove.radius)) {
+    options.radius = Math.max(0, smoothMove.radius);
+  } else if (smoothMove.radius === null) {
+    options.radius = null;
+  }
+  return Object.keys(options).length > 0 ? options : undefined;
+};
+
+export const clearCameraFollowPlugins = (viewport: any) => {
+  viewport?.plugins?.remove?.("animate");
+  viewport?.plugins?.remove?.("follow");
+};
+
+export const ownsCameraFollowRevision = (
+  appliedRevision: number | null,
+  currentRevision: number
+) => {
+  return appliedRevision !== null && appliedRevision === currentRevision;
+};
+
+export const readCameraFollowPosition = (
+  target: CameraFollowTarget
+): CameraFollowPosition | null => {
+  if (!target) return null;
+
+  try {
+    if (target.destroyed) return null;
+    const x = target.x;
+    const y = target.y;
+    if (!Number.isFinite(x) || !Number.isFinite(y)) return null;
+    return { x, y };
+  } catch {
+    return null;
+  }
+};
+
+const createCameraFollowTarget = (
+  target: CameraFollowTarget,
+  initialPosition: CameraFollowPosition
+) => {
+  let lastPosition = initialPosition;
+
+  const readPosition = () => {
+    const nextPosition = readCameraFollowPosition(target);
+    if (nextPosition) {
+      lastPosition = nextPosition;
+    }
+    return lastPosition;
+  };
+
+  return {
+    get x() {
+      return readPosition().x;
+    },
+    get y() {
+      return readPosition().y;
+    },
+  };
+};
+
+export const followCameraInstantly = (
+  viewport: any,
+  target: CameraFollowTarget,
+  smoothMove: CameraFollowSmoothMove
+) => {
+  const position = readCameraFollowPosition(target);
+  if (!position) return false;
+
+  const followTarget = createCameraFollowTarget(target, position);
+  const followOptions = cameraFollowOptions(smoothMove);
+  if (followOptions) {
+    viewport.follow(followTarget, followOptions);
+  } else {
+    viewport.follow(followTarget);
+  }
+  return true;
+};
+
+export const applyCameraFollow = ({
+  viewport,
+  target,
+  smoothMove,
+  followRevision,
+  isCurrentRevision,
+  shouldFollowCamera,
+}: CameraFollowApplyContext) => {
+  clearCameraFollowPlugins(viewport);
+
+  const position = readCameraFollowPosition(target);
+  if (!position) return false;
+
+  const animationOptions = cameraFollowAnimationOptions(smoothMove);
+  if (!animationOptions || animationOptions.time <= 0) {
+    return followCameraInstantly(viewport, target, smoothMove);
+  }
+
+  viewport.animate({
+    position,
+    time: animationOptions.time,
+    ease: animationOptions.ease,
+    callbackOnComplete: () => {
+      if (!isCurrentRevision(followRevision) || !shouldFollowCamera()) return;
+      if (!readCameraFollowPosition(target)) return;
+      followCameraInstantly(viewport, target, smoothMove);
+    },
+  });
+  return true;
+};