@rpgjs/action-battle 5.0.0-beta.11 → 5.0.0-beta.12

package/src/ui.ts

@@ -0,0 +1,113 @@
+import { inject, RpgClientEngine } from "@rpgjs/client";
+// @ts-ignore CanvasEngine components are compiled by @canvasengine/compiler.
+import ActionBarComponent from "./components/action-bar.ce";
+// @ts-ignore CanvasEngine components are compiled by @canvasengine/compiler.
+import TargetingOverlayComponent from "./components/targeting-overlay.ce";
+// @ts-ignore CanvasEngine components are compiled by @canvasengine/compiler.
+import AttackPreviewComponent from "./components/attack-preview.ce";
+import type {
+  ActionBattleUiActionBarOptions,
+  ActionBattleUiAttackPreviewOptions,
+  ActionBattleUiOptions,
+  ActionBattleUiTargetingOptions,
+} from "./types";
+
+export const ActionBattleUi = {
+  ActionBar: ActionBarComponent,
+  TargetingOverlay: TargetingOverlayComponent,
+  AttackPreview: AttackPreviewComponent,
+};
+
+export interface ResolvedActionBattleUi {
+  gui: Array<{ id: string; component: any; dependencies?: Function }>;
+  sprite: {
+    componentsInFront: any[];
+    componentsBehind: any[];
+  };
+  actionBar: ActionBattleUiActionBarOptions;
+  targeting: ActionBattleUiTargetingOptions;
+  attackPreview: ActionBattleUiAttackPreviewOptions;
+}
+
+const normalizeToggle = <T extends { enabled?: boolean }>(
+  value: boolean | T | undefined,
+  defaults: T
+): T => {
+  if (value === false) {
+    return { ...defaults, enabled: false };
+  }
+  if (value === true) {
+    return { ...defaults, enabled: true };
+  }
+  if (value === undefined) {
+    return { ...defaults };
+  }
+  return {
+    ...defaults,
+    ...value,
+    enabled: value.enabled ?? defaults.enabled,
+  };
+};
+
+export function createActionBattleUi(
+  input: "classic" | ActionBattleUiOptions = "classic"
+): ActionBattleUiOptions {
+  if (input === "classic") {
+    return {};
+  }
+  return input;
+}
+
+export function resolveActionBattleUi(options: ActionBattleUiOptions = {}): ResolvedActionBattleUi {
+  const actionBar = normalizeToggle(options.actionBar, {
+    enabled: false,
+    autoOpen: false,
+    mode: "both",
+    component: ActionBattleUi.ActionBar,
+  });
+  const targeting = normalizeToggle(options.targeting, {
+    enabled: true,
+    showGrid: true,
+    component: ActionBattleUi.TargetingOverlay,
+    colors: {
+      area: 0x2f9ef7,
+      edge: 0x1b6a98,
+      cursor: 0xffd166,
+    },
+  });
+  const attackPreview = normalizeToggle(options.attackPreview, {
+    enabled: true,
+    component: ActionBattleUi.AttackPreview,
+  });
+
+  const gui = [...(options.gui ?? [])];
+  if (actionBar.enabled && actionBar.component) {
+    gui.unshift({
+      id: "action-battle-action-bar",
+      component: actionBar.component,
+      dependencies: () => {
+        const engine = inject(RpgClientEngine);
+        return [engine.scene.currentPlayer];
+      },
+    });
+  }
+
+  const configuredSpriteComponents = Array.isArray(options.spriteComponents)
+    ? { front: options.spriteComponents, back: [] }
+    : options.spriteComponents ?? {};
+
+  return {
+    gui,
+    sprite: {
+      componentsInFront: [
+        ...(targeting.enabled && targeting.component ? [targeting.component] : []),
+        ...(attackPreview.enabled && attackPreview.component ? [attackPreview.component] : []),
+        ...(configuredSpriteComponents.front ?? []),
+      ],
+      componentsBehind: configuredSpriteComponents.back ?? [],
+    },
+    actionBar,
+    targeting,
+    attackPreview,
+  };
+}

package/src/visual.spec.ts

@@ -0,0 +1,166 @@
+import { describe, expect, test, vi } from "vitest";
+import {
+  ACTION_BATTLE_CLIENT_VISUAL_ID,
+  ACTION_BATTLE_HIT_FX_COMPONENT_ID,
+  createActionBattleVisual,
+  createActionBattleClientVisuals,
+  emitActionBattleClientVisual,
+  usesActionBattleFxVisual,
+} from "./visual";
+import { setActionBattleOptions } from "./config";
+
+const createEntity = () => ({
+  flash: vi.fn(),
+  showHit: vi.fn(),
+  showComponentAnimation: vi.fn(),
+  setGraphicAnimation: vi.fn(),
+});
+
+describe("action battle visual composer", () => {
+  test("classic hit uses the low-level flash and damage text primitives", () => {
+    const target = createEntity();
+    const visual = createActionBattleVisual("classic");
+
+    visual({
+      moment: "hit",
+      target,
+      damage: 12,
+    });
+
+    expect(target.flash).toHaveBeenCalledWith({
+      type: "tint",
+      tint: "red",
+      duration: 200,
+      cycles: 1,
+    });
+    expect(target.showHit).toHaveBeenCalledWith("-12");
+  });
+
+  test("classic hit falls back to component animation when client objects have no showHit helper", () => {
+    const target = {
+      flash: vi.fn(),
+      showComponentAnimation: vi.fn(),
+    };
+    const visual = createActionBattleVisual("classic");
+
+    visual({
+      moment: "hit",
+      target,
+      damage: 12,
+    });
+
+    expect(target.flash).toHaveBeenCalledWith({
+      type: "tint",
+      tint: "red",
+      duration: 200,
+      cycles: 1,
+    });
+    expect(target.showComponentAnimation).toHaveBeenCalledWith("hit", {
+      text: "-12",
+      direction: undefined,
+    });
+  });
+
+  test("fx hit keeps classic feedback and adds a CanvasEngine Fx component animation", () => {
+    const target = createEntity();
+    const visual = createActionBattleVisual("fx");
+
+    visual({
+      moment: "hit",
+      target,
+      damage: 9,
+    });
+
+    expect(target.showHit).toHaveBeenCalledWith("-9");
+    expect(target.showComponentAnimation).toHaveBeenCalledWith(
+      ACTION_BATTLE_HIT_FX_COMPONENT_ID,
+      expect.objectContaining({
+        name: "hitSpark",
+      })
+    );
+    expect(usesActionBattleFxVisual(visual)).toBe(true);
+  });
+
+  test("custom composer parts receive helpers", () => {
+    const target = createEntity();
+    const visual = createActionBattleVisual({
+      hit({ target }, fx) {
+        fx.component(target, "custom-hit", { name: "impactBurst" });
+      },
+    });
+
+    visual({
+      moment: "hit",
+      target,
+      damage: 3,
+    });
+
+    expect(target.showComponentAnimation).toHaveBeenCalledWith("custom-hit", {
+      name: "impactBurst",
+    });
+  });
+
+  test("server visual emission sends one action-battle client visual packet", () => {
+    setActionBattleOptions({ visual: "classic" } as any);
+    const clientVisual = vi.fn();
+    const attacker = {
+      id: "player-1",
+      getCurrentMap: () => ({ clientVisual }),
+    };
+    const target = {
+      id: "enemy-1",
+    };
+
+    emitActionBattleClientVisual({
+      moment: "hit",
+      entity: attacker,
+      target,
+      damage: 7,
+      result: {
+        damage: 7,
+        defeated: false,
+        attacker,
+        target,
+      },
+    });
+
+    expect(clientVisual).toHaveBeenCalledWith(
+      ACTION_BATTLE_CLIENT_VISUAL_ID,
+      expect.objectContaining({
+        moment: "hit",
+        objectId: "player-1",
+        sourceId: "player-1",
+        targetId: "enemy-1",
+        damage: 7,
+        result: expect.objectContaining({
+          damage: 7,
+          defeated: false,
+        }),
+      })
+    );
+  });
+
+  test("client visual handler replays configured action-battle visual locally", () => {
+    const target = createEntity();
+    const visuals = createActionBattleClientVisuals({
+      visual: "fx",
+      animations: {},
+    } as any);
+
+    visuals[ACTION_BATTLE_CLIENT_VISUAL_ID]({
+      target,
+      data: {
+        moment: "hit",
+        damage: 11,
+      },
+    });
+
+    expect(target.showHit).toHaveBeenCalledWith("-11");
+    expect(target.showComponentAnimation).toHaveBeenCalledWith(
+      ACTION_BATTLE_HIT_FX_COMPONENT_ID,
+      expect.objectContaining({
+        name: "hitSpark",
+      })
+    );
+  });
+});

package/src/visual.ts

@@ -0,0 +1,285 @@
+import type {
+  ActionBattleAnimationKey,
+  ActionBattleVisualComposer,
+  ActionBattleVisualContext,
+  ActionBattleVisualHelpers,
+  ActionBattleVisualInput,
+  ActionBattleVisualPart,
+} from "./types";
+import { getActionBattleOptions } from "./config";
+import { playActionBattleAnimation } from "./animations";
+
+export const ACTION_BATTLE_CLIENT_VISUAL_ID = "action-battle.visual";
+export const ACTION_BATTLE_HIT_FX_COMPONENT_ID = "action-battle-hit-fx";
+
+type PreviewStarter = (
+  entity: any,
+  options?: Record<string, any>
+) => void;
+
+let previewStarter: PreviewStarter | undefined;
+
+export function setActionBattlePreviewStarter(starter?: PreviewStarter) {
+  previewStarter = starter;
+}
+
+const entityId = (entity: any): string | undefined =>
+  typeof entity?.id === "string" ? entity.id : undefined;
+
+const serializeSkill = (skill: any) => {
+  const id = skill?.id;
+  if (typeof id === "string") return { id };
+  if (typeof id === "function") {
+    const value = id.call(skill);
+    if (typeof value === "string") return { id: value };
+  }
+  return undefined;
+};
+
+const serializeResult = (result: any) => {
+  if (!result) return undefined;
+  return {
+    damage: result.damage,
+    knockbackForce: result.knockbackForce,
+    knockbackDuration: result.knockbackDuration,
+    defeated: result.defeated,
+    attackerId: entityId(result.attacker),
+    targetId: entityId(result.target),
+    rawDamage: result.rawDamage,
+    reaction: result.reaction,
+    cancelled: result.cancelled,
+    metadata: result.metadata,
+  };
+};
+
+const serializeActionBattleVisualContext = (
+  context: ActionBattleVisualContext
+) => ({
+  moment: context.moment,
+  objectId: entityId(context.entity),
+  sourceId: entityId(context.attacker ?? context.entity),
+  targetId: entityId(context.target),
+  damage: context.damage,
+  defeated: context.defeated,
+  result: serializeResult(context.result),
+  skill: serializeSkill(context.skill),
+  pattern: context.pattern,
+  animations: context.animations,
+  animationDefaults: context.animationDefaults,
+});
+
+export function emitActionBattleClientVisual(
+  context: ActionBattleVisualContext
+) {
+  if (getActionBattleOptions().visual === "none") return;
+  const anchor = context.entity ?? context.target ?? context.attacker;
+  const map = anchor?.getCurrentMap?.();
+  if (!map?.clientVisual) return;
+  map.clientVisual(
+    ACTION_BATTLE_CLIENT_VISUAL_ID,
+    serializeActionBattleVisualContext(context)
+  );
+}
+
+export function createActionBattleClientVisuals(
+  options = getActionBattleOptions()
+) {
+  return {
+    [ACTION_BATTLE_CLIENT_VISUAL_ID]: (context: any) => {
+      const data = context.data ?? {};
+      playActionBattleVisual(options.visual, {
+        moment: data.moment,
+        entity: context.object ?? context.source ?? context.target,
+        target: context.target,
+        attacker: context.source,
+        damage: data.damage,
+        defeated: data.defeated,
+        result: data.result,
+        skill: data.skill,
+        pattern: data.pattern,
+        animations: data.animations ?? options.animations,
+        animationDefaults: data.animationDefaults,
+      });
+    },
+  };
+}
+
+const callGraphic = (
+  entity: any,
+  keyOrOptions: ActionBattleAnimationKey | any,
+  context?: ActionBattleVisualContext
+) => {
+  if (!entity || keyOrOptions == null) return;
+
+  if (typeof keyOrOptions === "string") {
+    playActionBattleAnimation(
+      keyOrOptions as ActionBattleAnimationKey,
+      entity,
+      context?.animations ?? getActionBattleOptions().animations,
+      {
+        attacker: context?.attacker,
+        target: context?.target,
+        skill: context?.skill,
+      },
+      context?.animationDefaults
+    );
+    return;
+  }
+
+  const animationName = keyOrOptions.animationName;
+  if (!animationName) return;
+  const repeat = keyOrOptions.repeat ?? 1;
+  const graphic = keyOrOptions.graphic;
+  if (typeof entity.setGraphicAnimation === "function") {
+    if (graphic !== undefined) {
+      entity.setGraphicAnimation(animationName, graphic, repeat);
+    } else {
+      entity.setGraphicAnimation(animationName, repeat);
+    }
+    return;
+  }
+  if (typeof entity.setAnimation === "function") {
+    if (graphic !== undefined) {
+      entity.setAnimation(animationName, graphic, repeat);
+    } else {
+      entity.setAnimation(animationName, repeat);
+    }
+  }
+};
+
+const createHelpers = (context: ActionBattleVisualContext): ActionBattleVisualHelpers => ({
+  graphic(entity, keyOrOptions) {
+    callGraphic(entity, keyOrOptions, context);
+  },
+  flash(entity, options = {}) {
+    entity?.flash?.({
+      type: "tint",
+      tint: "red",
+      duration: 200,
+      cycles: 1,
+      ...options,
+    });
+  },
+  damageText(entity, damageOrText) {
+    if (typeof damageOrText === "string") {
+      if (entity?.showHit) {
+        entity.showHit(damageOrText);
+        return;
+      }
+      entity?.showComponentAnimation?.("hit", {
+        text: damageOrText,
+        direction: entity?.direction?.() ?? entity?.direction,
+      });
+      return;
+    }
+    const damage = damageOrText ?? context.damage ?? context.result?.damage;
+    if (damage === undefined) return;
+    const text = `-${damage}`;
+    if (entity?.showHit) {
+      entity.showHit(text);
+      return;
+    }
+    entity?.showComponentAnimation?.("hit", {
+      text,
+      direction: entity?.direction?.() ?? entity?.direction,
+    });
+  },
+  component(entity, id, params = {}) {
+    entity?.showComponentAnimation?.(id, params);
+  },
+  preview(entity, options = {}) {
+    previewStarter?.(entity, options);
+  },
+});
+
+const classicParts: Partial<Record<ActionBattleVisualContext["moment"], ActionBattleVisualPart>> = {
+  attack({ entity }, fx) {
+    fx.graphic(entity, "attack");
+  },
+  castSkill({ entity }, fx) {
+    fx.graphic(entity, "castSkill");
+  },
+  preview({ entity }, fx) {
+    fx.preview(entity);
+  },
+  hit({ target, damage }, fx) {
+    fx.flash(target);
+    fx.damageText(target, damage);
+  },
+  hurt({ entity, target }, fx) {
+    const hurtTarget = target ?? entity;
+    fx.flash(hurtTarget);
+    fx.damageText(hurtTarget);
+    fx.graphic(hurtTarget, "hurt");
+  },
+  defeat({ entity, target }, fx) {
+    fx.graphic(target ?? entity, "die");
+  },
+};
+
+const fxParts: Partial<Record<ActionBattleVisualContext["moment"], ActionBattleVisualPart>> = {
+  ...classicParts,
+  hit(context, fx) {
+    classicParts.hit?.(context, fx);
+    fx.component(context.target, ACTION_BATTLE_HIT_FX_COMPONENT_ID, {
+      name: "hitSpark",
+      scale: 0.8,
+      zIndex: 1000,
+    });
+  },
+  hurt(context, fx) {
+    classicParts.hurt?.(context, fx);
+    fx.component(context.target ?? context.entity, ACTION_BATTLE_HIT_FX_COMPONENT_ID, {
+      name: "hitSpark",
+      scale: 0.8,
+      zIndex: 1000,
+    });
+  },
+};
+
+const resolveParts = (
+  input: ActionBattleVisualInput | undefined
+): Partial<Record<ActionBattleVisualContext["moment"], ActionBattleVisualPart>> | null => {
+  const visual = input ?? "classic";
+  if (visual === "none") return null;
+  if (visual === "classic") return classicParts;
+  if (visual === "fx") return fxParts;
+  if (typeof visual === "function") return null;
+  return visual;
+};
+
+export function createActionBattleVisual(
+  input: ActionBattleVisualInput = "classic"
+): ActionBattleVisualComposer {
+  if (typeof input === "function") {
+    return input;
+  }
+  const parts = resolveParts(input);
+  const composer: ActionBattleVisualComposer = (context) => {
+    if (!parts) return;
+    const part = parts[context.moment];
+    if (!part) return;
+    part(context, createHelpers(context));
+  };
+  (composer as any).__actionBattleUsesFx = input === "fx";
+  return composer;
+}
+
+export const createClassicActionBattleVisual = () =>
+  createActionBattleVisual("classic");
+
+export const createFxActionBattleVisual = () =>
+  createActionBattleVisual("fx");
+
+export function playActionBattleVisual(
+  visual: ActionBattleVisualInput | ActionBattleVisualComposer | undefined,
+  context: ActionBattleVisualContext
+) {
+  const composer =
+    typeof visual === "function" ? visual : createActionBattleVisual(visual);
+  composer(context);
+}
+
+export function usesActionBattleFxVisual(visual: ActionBattleVisualInput | undefined): boolean {
+  return visual === "fx" || Boolean((visual as any)?.__actionBattleUsesFx);
+}