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

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

package/src/services/interactions.spec.ts

@@ -0,0 +1,175 @@
+import { describe, expect, test, vi } from "vitest";
+import {
+  dragToTile,
+  hoverPopover,
+  RpgClientInteractions,
+  selectable,
+} from "./interactions";
+import { createClientPointerContext } from "./pointerContext";
+
+function createClient() {
+  const client = {
+    pointer: createClientPointerContext(),
+    processAction: vi.fn(),
+    sceneMap: {
+      tileWidth: 16,
+      tileHeight: 16,
+    },
+  } as any;
+  client.interactions = new RpgClientInteractions(client);
+  return client;
+}
+
+describe("RpgClientInteractions", () => {
+  test("renders registered components with sprite state and bounds", () => {
+    const client = createClient();
+    const Popover = () => null;
+    const sprite = { id: "event-1", name: "Guard" };
+
+    client.interactions.use("Guard", hoverPopover(Popover, { label: "Talk" }));
+    client.interactions.handle(sprite, "pointerover", {
+      bounds: {
+        graphic: { left: 1, top: 2, right: 11, bottom: 22, width: 10, height: 20, centerX: 6, centerY: 12 } as any,
+      },
+    });
+
+    const entries = client.interactions.getRenderedComponents(sprite, {
+      graphic: { left: 1, top: 2, right: 11, bottom: 22, width: 10, height: 20, centerX: 6, centerY: 12 } as any,
+    });
+
+    expect(entries).toHaveLength(1);
+    expect(entries[0].component).toBe(Popover);
+    expect(entries[0].props.label).toBe("Talk");
+    expect(entries[0].props.state.hovered).toBe(true);
+    expect(entries[0].props.bounds.centerX).toBe(6);
+  });
+
+  test("keeps clicks client-only unless a behavior sends an action", () => {
+    const client = createClient();
+    const sprite = { id: "event-1", name: "Guard" };
+
+    client.interactions.use("Guard", selectable());
+    client.interactions.handle(sprite, "click");
+
+    expect(client.interactions.getState(sprite).selected).toBe(true);
+    expect(client.processAction).not.toHaveBeenCalled();
+
+    client.interactions.use("Guard", {
+      click(ctx) {
+        ctx.action("guard:talk", { eventId: ctx.target.id });
+      },
+    });
+    client.interactions.handle(sprite, "click");
+
+    expect(client.processAction).toHaveBeenCalledWith("guard:talk", { eventId: "event-1" });
+  });
+
+  test("uses behavior hit tests before changing hover state", () => {
+    const client = createClient();
+    const sprite = { id: "event-1", name: "Tree" };
+
+    client.pointer.update({ x: 0, y: 0 }, { x: 40, y: 40 });
+    client.interactions.use("Tree", {
+      cursor: "pointer",
+      hitTest(ctx) {
+        return ctx.bounds("hitbox").contains(ctx.pointer.world());
+      },
+    });
+
+    client.interactions.handle(sprite, "pointerover", {
+      bounds: {
+        hitbox: { left: 0, top: 0, right: 16, bottom: 16, width: 16, height: 16, centerX: 8, centerY: 8 } as any,
+      },
+    });
+
+    expect(client.interactions.getState(sprite).hovered).toBe(false);
+    expect(client.interactions.cursorFor(sprite, {
+      hitbox: { left: 0, top: 0, right: 16, bottom: 16, width: 16, height: 16, centerX: 8, centerY: 8 } as any,
+    })).toBeUndefined();
+  });
+
+  test("exposes handler bounds in world coordinates", () => {
+    const client = createClient();
+    const sprite = { id: "crate-1", name: "Crate", x: () => 100, y: () => 80 };
+
+    client.pointer.update({ x: 0, y: 0 }, { x: 112, y: 92 });
+    client.interactions.use("Crate", {
+      component: () => null,
+      cursor: "grab",
+      hitTest(ctx) {
+        return ctx.bounds("hitbox").contains(ctx.pointer.world());
+      },
+    });
+
+    client.interactions.handle(sprite, "pointerover", {
+      bounds: {
+        hitbox: { left: 0, top: 0, right: 16, bottom: 16, width: 16, height: 16, centerX: 8, centerY: 8 } as any,
+      },
+    });
+
+    expect(client.interactions.getState(sprite).hovered).toBe(true);
+    expect(client.interactions.cursorFor(sprite, {
+      hitbox: { left: 0, top: 0, right: 16, bottom: 16, width: 16, height: 16, centerX: 8, centerY: 8 } as any,
+    })).toBe("grab");
+
+    const [entry] = client.interactions.getRenderedComponents(sprite, {
+      hitbox: { left: 0, top: 0, right: 16, bottom: 16, width: 16, height: 16, centerX: 8, centerY: 8 } as any,
+    });
+    expect(entry?.props.bounds.centerX).toBe(8);
+  });
+
+  test("updates hit-tested hover while moving inside an already hovered sprite", () => {
+    const client = createClient();
+    const sprite = { id: "crate-1", name: "Crate", x: () => 100, y: () => 80 };
+
+    client.interactions.use("Crate", {
+      hitTest(ctx) {
+        return ctx.bounds("hitbox").contains(ctx.pointer.world());
+      },
+    });
+
+    client.pointer.update({ x: 0, y: 0 }, { x: 140, y: 120 });
+    client.interactions.handle(sprite, "pointerover", {
+      bounds: {
+        hitbox: { left: 0, top: 0, right: 16, bottom: 16, width: 16, height: 16, centerX: 8, centerY: 8 } as any,
+      },
+    });
+    expect(client.interactions.getState(sprite).hovered).toBe(false);
+
+    client.pointer.update({ x: 0, y: 0 }, { x: 112, y: 92 });
+    client.interactions.handle(sprite, "pointermove", {
+      bounds: {
+        hitbox: { left: 0, top: 0, right: 16, bottom: 16, width: 16, height: 16, centerX: 8, centerY: 8 } as any,
+      },
+    });
+
+    expect(client.interactions.getState(sprite).hovered).toBe(true);
+  });
+
+  test("runs drag lifecycle and resolves pointer tile on drop", () => {
+    const client = createClient();
+    const sprite = { id: "crate-1", name: "Crate" };
+
+    client.interactions.use("Crate", dragToTile({ action: "crate:move" }));
+    client.pointer.update({ x: 0, y: 0 }, { x: 18, y: 35 });
+    client.interactions.handle(sprite, "pointerdown");
+
+    expect(client.interactions.getState(sprite).dragging).toBe(true);
+
+    client.pointer.update({ x: 0, y: 0 }, { x: 33, y: 47 });
+    client.interactions.handlePointerUp();
+
+    expect(client.interactions.getState(sprite).dragging).toBe(false);
+    expect(client.processAction).toHaveBeenCalledWith("crate:move", {
+      eventId: "crate-1",
+      position: {
+        x: 2,
+        y: 2,
+        worldX: 32,
+        worldY: 32,
+        width: 16,
+        height: 16,
+      },
+    });
+  });
+});