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

package/src/services/AbstractSocket.ts

@@ -9,8 +9,11 @@ export type SocketUpdateProperties = {
   host?: string;
   query?: SocketQuery;
 };
+export type WebSocketMode = "standalone" | "mmorpg";
 
 export abstract class AbstractWebsocket {
+  readonly mode?: WebSocketMode;
+
   constructor(protected context: Context) {}
 
   abstract connection(listeners?: (data: any) => void): Promise<void>;

package/src/services/actionInput.spec.ts

@@ -0,0 +1,155 @@
+import { describe, expect, test } from "vitest";
+import {
+  getKeyboardControlBind,
+  keyboardEventMatchesBind,
+  normalizeActionInput,
+  resolveKeyboardActionInput,
+  resolveKeyboardDirectionInput,
+} from "./actionInput";
+
+const keyboardEvent = (values: Partial<KeyboardEvent>) =>
+  values as KeyboardEvent;
+
+describe("normalizeActionInput", () => {
+  test("keeps simple actions compatible", () => {
+    expect(normalizeActionInput("action")).toEqual({
+      action: "action",
+    });
+  });
+
+  test("adds custom data to action payloads", () => {
+    expect(normalizeActionInput("projectile:shoot", {
+      target: { x: 320, y: 180 },
+      source: "map-click",
+    })).toEqual({
+      action: "projectile:shoot",
+      data: {
+        target: { x: 320, y: 180 },
+        source: "map-click",
+      },
+    });
+  });
+
+  test("keeps object-form action payloads intact", () => {
+    const payload = {
+      action: "projectile:shoot",
+      data: { target: { x: 64, y: 96 } },
+    };
+
+    expect(normalizeActionInput(payload)).toBe(payload);
+  });
+});
+
+describe("keyboard action controls", () => {
+  test("keeps string controls compatible", () => {
+    expect(getKeyboardControlBind("space")).toBe("space");
+    expect(resolveKeyboardActionInput("space", {}, {})).toEqual({
+      action: "action",
+    });
+  });
+
+  test("resolves object controls with static data", () => {
+    const control = {
+      bind: "space",
+      action: "projectile:shoot",
+      data: {
+        source: "keyboard",
+        target: { x: 10, y: 20 },
+      },
+    };
+
+    expect(getKeyboardControlBind(control)).toBe("space");
+    expect(resolveKeyboardActionInput(control, {}, {})).toEqual({
+      action: "projectile:shoot",
+      data: {
+        source: "keyboard",
+        target: { x: 10, y: 20 },
+      },
+    });
+  });
+
+  test("resolves object controls with functional data", () => {
+    const client = {
+      pointer: {
+        world: () => ({ x: 64, y: 96 }),
+      },
+    };
+    const sprite = { id: "player-1" };
+    const control = {
+      bind: "space",
+      action: "projectile:shoot",
+      data: (resolvedClient: typeof client, resolvedSprite: typeof sprite) => ({
+        source: "keyboard",
+        target: resolvedClient.pointer.world(),
+        playerId: resolvedSprite.id,
+      }),
+    };
+
+    expect(resolveKeyboardActionInput(control, client, sprite)).toEqual({
+      action: "projectile:shoot",
+      data: {
+        source: "keyboard",
+        target: { x: 64, y: 96 },
+        playerId: "player-1",
+      },
+    });
+  });
+
+  test("omits data when object controls do not provide it", () => {
+    expect(resolveKeyboardActionInput({
+      bind: "space",
+      action: "projectile:shoot",
+    }, {}, {})).toEqual({
+      action: "projectile:shoot",
+    });
+  });
+
+  test("matches keyboard events against string, numeric, and array binds", () => {
+    expect(
+      keyboardEventMatchesBind(
+        keyboardEvent({ key: " ", code: "Space", keyCode: 32 }),
+        "space"
+      )
+    ).toBe(true);
+    expect(
+      keyboardEventMatchesBind(
+        keyboardEvent({ key: "ArrowUp", code: "ArrowUp", keyCode: 38 }),
+        "up"
+      )
+    ).toBe(true);
+    expect(
+      keyboardEventMatchesBind(
+        keyboardEvent({ key: "x", code: "KeyX", keyCode: 88 }),
+        ["space", "x"]
+      )
+    ).toBe(true);
+    expect(
+      keyboardEventMatchesBind(
+        keyboardEvent({ key: "Escape", code: "Escape", keyCode: 27 }),
+        27
+      )
+    ).toBe(true);
+    expect(
+      keyboardEventMatchesBind(
+        keyboardEvent({ key: "a", code: "KeyA", keyCode: 65 }),
+        "space"
+      )
+    ).toBe(false);
+  });
+
+  test("resolves directional keyboard controls from a native keyboard event", () => {
+    const controls = {
+      up: "up",
+      down: "down",
+      left: "left",
+      right: "right",
+    };
+
+    expect(
+      resolveKeyboardDirectionInput(
+        keyboardEvent({ key: "ArrowRight", code: "ArrowRight", keyCode: 39 }),
+        controls
+      )
+    ).toBe("right");
+  });
+});

package/src/services/actionInput.ts

@@ -0,0 +1,120 @@
+import { Direction, type RpgActionInput, type RpgActionName } from "@rpgjs/common";
+
+export type KeyboardActionDataResolver<TClient = any, TSprite = any> = (
+  client: TClient,
+  sprite: TSprite,
+) => any;
+
+export interface KeyboardActionConfig<TClient = any, TSprite = any> {
+  bind: any;
+  action?: RpgActionName;
+  data?: any | KeyboardActionDataResolver<TClient, TSprite>;
+}
+
+export function normalizeActionInput(action: RpgActionName, data?: any): RpgActionInput;
+export function normalizeActionInput(action: RpgActionInput): RpgActionInput;
+export function normalizeActionInput(action: RpgActionName | RpgActionInput, data?: any): RpgActionInput {
+  if (typeof action === "object") {
+    return action;
+  }
+  return data === undefined
+    ? { action }
+    : { action, data };
+}
+
+export function isKeyboardActionConfig(value: any): value is KeyboardActionConfig {
+  return value !== null
+    && typeof value === "object"
+    && Object.prototype.hasOwnProperty.call(value, "bind");
+}
+
+export function getKeyboardControlBind(control: any): any {
+  return isKeyboardActionConfig(control) ? control.bind : control;
+}
+
+const KEY_CODE_NAMES: Record<number, string> = {
+  32: "space",
+  27: "escape",
+  37: "left",
+  38: "up",
+  39: "right",
+  40: "down",
+};
+
+const normalizeKeyboardName = (value: unknown): string | undefined => {
+  if (typeof value !== "string") return undefined;
+  const normalized = value.toLowerCase();
+  if (
+    normalized === " " ||
+    normalized === "spacebar" ||
+    normalized === "space"
+  ) {
+    return "space";
+  }
+  if (normalized.startsWith("arrow")) {
+    return normalized.slice("arrow".length);
+  }
+  return normalized;
+};
+
+export function keyboardEventMatchesBind(
+  event: KeyboardEvent,
+  bind: any
+): boolean {
+  if (Array.isArray(bind)) {
+    return bind.some(item => keyboardEventMatchesBind(event, item));
+  }
+
+  if (typeof bind === "number") {
+    return event.keyCode === bind;
+  }
+
+  const expected = normalizeKeyboardName(bind);
+  if (!expected) return false;
+
+  return (
+    normalizeKeyboardName(event.key) === expected ||
+    normalizeKeyboardName(event.code) === expected ||
+    KEY_CODE_NAMES[event.keyCode] === expected
+  );
+}
+
+export function resolveKeyboardActionInput(
+  control: any,
+  client: any,
+  sprite: any,
+  defaultAction: RpgActionName = "action",
+): RpgActionInput {
+  if (!isKeyboardActionConfig(control)) {
+    return { action: defaultAction };
+  }
+
+  const action = control.action ?? defaultAction;
+  const data = typeof control.data === "function"
+    ? control.data(client, sprite)
+    : control.data;
+
+  return data === undefined
+    ? { action }
+    : { action, data };
+}
+
+export function resolveKeyboardDirectionInput(
+  event: KeyboardEvent,
+  keyboardControls: any
+): Direction | undefined {
+  const directions: Array<[any, Direction]> = [
+    [keyboardControls?.up, Direction.Up],
+    [keyboardControls?.down, Direction.Down],
+    [keyboardControls?.left, Direction.Left],
+    [keyboardControls?.right, Direction.Right],
+  ];
+
+  for (const [control, direction] of directions) {
+    if (keyboardEventMatchesBind(event, getKeyboardControlBind(control))) {
+      return direction;
+    }
+  }
+
+  return undefined;
+}

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