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

package/src/core/ai-behavior-tree.spec.ts

@@ -0,0 +1,116 @@
+import { describe, expect, test, vi } from "vitest";
+import { AiState, AttackPattern, EnemyType } from "../ai.server";
+import {
+  action,
+  chase,
+  condition,
+  defineAiBehavior,
+  hpBelow,
+  ifHpBelow,
+  ifTargetInRange,
+  keepDistance,
+  selector,
+  sequence,
+  targetInRange,
+  useAttack,
+} from "./ai-behavior-tree";
+
+const createContext = (overrides: Record<string, any> = {}) => {
+  const event = { id: "enemy-1" };
+  const target = { id: "player-1" };
+  const distance = overrides.distance ?? 40;
+  return {
+    event,
+    target,
+    state: AiState.Combat,
+    enemyType: EnemyType.Aggressive,
+    distance,
+    hpPercent: overrides.hpPercent ?? 0.8,
+    now: 100,
+    self: {
+      event,
+      state: AiState.Combat,
+      enemyType: EnemyType.Aggressive,
+      hpPercent: overrides.hpPercent ?? 0.8,
+      attackRange: overrides.attackRange ?? 50,
+    },
+    targetInfo: overrides.targetInfo ?? {
+      entity: target,
+      distance,
+      inAttackRange: distance <= (overrides.attackRange ?? 50),
+      visible: true,
+    },
+    memory: {},
+    ...overrides,
+  } as any;
+};
+
+describe("action battle AI behavior tree", () => {
+  test("selects the first successful branch", () => {
+    const tree = selector([
+      sequence([condition(hpBelow(0.2)), action(chase())]),
+      sequence([condition(targetInRange()), action(useAttack(AttackPattern.Melee))]),
+      action(keepDistance(80)),
+    ]);
+
+    const result = tree.tick(createContext());
+
+    expect(result.status).toBe("success");
+    expect(result.intent).toEqual({
+      type: "useAttack",
+      pattern: AttackPattern.Melee,
+    });
+  });
+
+  test("compiles simplified rules to a behavior tree", () => {
+    const behavior = defineAiBehavior({
+      when: [
+        ifHpBelow(0.25, keepDistance(120)),
+        ifTargetInRange(useAttack("melee")),
+      ],
+      otherwise: chase(),
+    });
+
+    expect(behavior.tick(createContext({ hpPercent: 0.1 })).intent).toEqual({
+      type: "keepDistance",
+      distance: 120,
+      tolerance: undefined,
+    });
+    expect(behavior.tick(createContext({ distance: 30 })).intent).toEqual({
+      type: "useAttack",
+      pattern: "melee",
+    });
+    expect(behavior.tick(createContext({ distance: 90 })).intent).toEqual({
+      type: "moveToTarget",
+    });
+  });
+
+  test("supports dynamic actions with memory", () => {
+    const behavior = defineAiBehavior({
+      otherwise: ({ memory }) => {
+        memory.ticks = (memory.ticks ?? 0) + 1;
+        return useAttack(memory.ticks === 1 ? "melee" : "dashAttack");
+      },
+    });
+    const context = createContext();
+
+    expect(behavior.tick(context).intent).toEqual({
+      type: "useAttack",
+      pattern: "melee",
+    });
+    expect(behavior.tick(context).intent).toEqual({
+      type: "useAttack",
+      pattern: "dashAttack",
+    });
+  });
+
+  test("does not evaluate later selector branches after success", () => {
+    const later = vi.fn(() => ({ status: "success" as const, intent: chase() }));
+    const tree = selector([action(useAttack("melee")), later]);
+
+    const result = tree.tick(createContext());
+
+    expect(result.intent).toEqual({ type: "useAttack", pattern: "melee" });
+    expect(later).not.toHaveBeenCalled();
+  });
+});

package/src/core/ai-behavior-tree.ts

@@ -0,0 +1,272 @@
+import type { RpgEvent, RpgPlayer } from "@rpgjs/server";
+import type { AiState, AttackPattern, EnemyType } from "../ai.server";
+import type {
+  ActionBattleAiContext,
+  ActionBattleAiDecision,
+} from "./contracts";
+
+export type ActionBattleAiTreeStatus = "success" | "failure" | "running";
+
+export type ActionBattleAiMemory = Record<string, any>;
+
+export interface ActionBattleAiIntentBase {
+  consume?: boolean;
+  metadata?: Record<string, any>;
+}
+
+export type ActionBattleAiIntent =
+  | (ActionBattleAiIntentBase & { type: "idle" })
+  | (ActionBattleAiIntentBase & { type: "patrol" })
+  | (ActionBattleAiIntentBase & { type: "faceTarget" })
+  | (ActionBattleAiIntentBase & { type: "moveToTarget" })
+  | (ActionBattleAiIntentBase & { type: "fleeFromTarget" })
+  | (ActionBattleAiIntentBase & {
+      type: "keepDistance";
+      distance: number;
+      tolerance?: number;
+    })
+  | (ActionBattleAiIntentBase & {
+      type: "useAttack";
+      pattern?: AttackPattern | string;
+    })
+  | (ActionBattleAiIntentBase & {
+      type: "useSkill";
+      skill: any;
+    })
+  | (ActionBattleAiIntentBase & {
+      type: "setMode";
+      mode: NonNullable<ActionBattleAiDecision["mode"]>;
+    });
+
+export interface ActionBattleAiSnapshotSelf {
+  event: RpgEvent;
+  state: AiState;
+  enemyType: EnemyType;
+  hpPercent: number | null;
+  attackRange: number;
+}
+
+export interface ActionBattleAiSnapshotTarget {
+  entity: RpgPlayer;
+  distance: number;
+  inAttackRange: boolean;
+  visible: boolean;
+}
+
+export interface ActionBattleAiTreeContext extends ActionBattleAiContext {
+  self: ActionBattleAiSnapshotSelf;
+  targetInfo: ActionBattleAiSnapshotTarget | null;
+  memory: ActionBattleAiMemory;
+}
+
+export interface ActionBattleAiTreeResult {
+  status: ActionBattleAiTreeStatus;
+  decision?: ActionBattleAiDecision;
+  intent?: ActionBattleAiIntent | ActionBattleAiIntent[];
+}
+
+export interface ActionBattleAiTreeNode {
+  tick(context: ActionBattleAiTreeContext): ActionBattleAiTreeResult;
+}
+
+export type ActionBattleAiTreeInput =
+  | ActionBattleAiTreeNode
+  | ((context: ActionBattleAiTreeContext) => ActionBattleAiTreeResult | void);
+
+export type ActionBattleAiCondition = (
+  context: ActionBattleAiTreeContext
+) => boolean;
+
+export type ActionBattleAiIntentInput =
+  | ActionBattleAiIntent
+  | ActionBattleAiIntent[]
+  | ActionBattleAiTreeNode
+  | ((context: ActionBattleAiTreeContext) => ActionBattleAiIntent | ActionBattleAiIntent[]);
+
+export interface ActionBattleAiRule {
+  condition: ActionBattleAiCondition;
+  then: ActionBattleAiIntentInput;
+}
+
+export interface ActionBattleAiSimpleBehavior {
+  when?: ActionBattleAiRule[];
+  otherwise?: ActionBattleAiIntentInput;
+}
+
+const isTreeNode = (input: unknown): input is ActionBattleAiTreeNode =>
+  Boolean(input && typeof (input as ActionBattleAiTreeNode).tick === "function");
+
+const normalizeTreeResult = (
+  result: ActionBattleAiTreeResult | void
+): ActionBattleAiTreeResult => result ?? { status: "failure" };
+
+const runIntentInput = (
+  input: ActionBattleAiIntentInput,
+  context: ActionBattleAiTreeContext
+): ActionBattleAiTreeResult => {
+  if (isTreeNode(input)) return input.tick(context);
+  const intent = typeof input === "function" ? input(context) : input;
+  return { status: "success", intent };
+};
+
+export const defineAiTree = (
+  input: ActionBattleAiTreeInput
+): ActionBattleAiTreeNode => {
+  if (isTreeNode(input)) return input;
+  return {
+    tick(context) {
+      return normalizeTreeResult(input(context));
+    },
+  };
+};
+
+export const selector = (
+  children: ActionBattleAiTreeInput[]
+): ActionBattleAiTreeNode => ({
+  tick(context) {
+    for (const child of children) {
+      const result = defineAiTree(child).tick(context);
+      if (result.status !== "failure") return result;
+    }
+    return { status: "failure" };
+  },
+});
+
+export const sequence = (
+  children: ActionBattleAiTreeInput[]
+): ActionBattleAiTreeNode => ({
+  tick(context) {
+    let last: ActionBattleAiTreeResult = { status: "success" };
+    for (const child of children) {
+      last = defineAiTree(child).tick(context);
+      if (last.status !== "success") return last;
+    }
+    return last;
+  },
+});
+
+export const condition = (
+  predicate: ActionBattleAiCondition
+): ActionBattleAiTreeNode => ({
+  tick(context) {
+    return { status: predicate(context) ? "success" : "failure" };
+  },
+});
+
+export const action = (
+  input: ActionBattleAiIntentInput,
+  status: ActionBattleAiTreeStatus = "success"
+): ActionBattleAiTreeNode => ({
+  tick(context) {
+    const result = runIntentInput(input, context);
+    return { ...result, status };
+  },
+});
+
+export const decision = (
+  resolve: ActionBattleAiDecision | ((context: ActionBattleAiTreeContext) => ActionBattleAiDecision)
+): ActionBattleAiTreeNode => ({
+  tick(context) {
+    return {
+      status: "success",
+      decision: typeof resolve === "function" ? resolve(context) : resolve,
+    };
+  },
+});
+
+export const rule = (
+  predicate: ActionBattleAiCondition,
+  then: ActionBattleAiIntentInput
+): ActionBattleAiRule => ({
+  condition: predicate,
+  then,
+});
+
+export const defineAiBehavior = (
+  behavior: ActionBattleAiSimpleBehavior
+): ActionBattleAiTreeNode => {
+  const branches = [
+    ...(behavior.when ?? []).map((entry) =>
+      sequence([condition(entry.condition), action(entry.then)])
+    ),
+  ];
+  if (behavior.otherwise) {
+    branches.push(action(behavior.otherwise));
+  }
+  return selector(branches);
+};
+
+export const hpBelow = (ratio: number): ActionBattleAiCondition => {
+  return ({ self }) => self.hpPercent !== null && self.hpPercent < ratio;
+};
+
+export const targetVisible = (): ActionBattleAiCondition => {
+  return ({ targetInfo }) => Boolean(targetInfo?.visible);
+};
+
+export const targetInRange = (
+  range?: number
+): ActionBattleAiCondition => {
+  return ({ self, targetInfo }) => {
+    if (!targetInfo) return false;
+    return targetInfo.distance <= (range ?? self.attackRange);
+  };
+};
+
+export const distanceLessThan = (
+  distance: number
+): ActionBattleAiCondition => {
+  return ({ targetInfo }) =>
+    targetInfo !== null && targetInfo.distance < distance;
+};
+
+export const inState = (state: AiState): ActionBattleAiCondition => {
+  return ({ self }) => self.state === state;
+};
+
+export const isEnemyType = (
+  enemyType: EnemyType
+): ActionBattleAiCondition => {
+  return ({ self }) => self.enemyType === enemyType;
+};
+
+export const idle = (): ActionBattleAiIntent => ({ type: "idle" });
+export const patrol = (): ActionBattleAiIntent => ({ type: "patrol" });
+export const faceTarget = (): ActionBattleAiIntent => ({ type: "faceTarget" });
+export const chase = (): ActionBattleAiIntent => ({ type: "moveToTarget" });
+export const moveToTarget = chase;
+export const flee = (): ActionBattleAiIntent => ({ type: "fleeFromTarget" });
+export const fleeFromTarget = flee;
+export const keepDistance = (
+  distance: number,
+  tolerance?: number
+): ActionBattleAiIntent => ({ type: "keepDistance", distance, tolerance });
+export const useAttack = (
+  pattern?: AttackPattern | string
+): ActionBattleAiIntent => ({ type: "useAttack", pattern });
+export const useSkill = (skill: any): ActionBattleAiIntent => ({
+  type: "useSkill",
+  skill,
+});
+export const setMode = (
+  mode: NonNullable<ActionBattleAiDecision["mode"]>
+): ActionBattleAiIntent => ({ type: "setMode", mode, consume: false });
+
+export const ifHpBelow = (
+  ratio: number,
+  then: ActionBattleAiIntentInput
+): ActionBattleAiRule => rule(hpBelow(ratio), then);
+
+export const ifTargetVisible = (
+  then: ActionBattleAiIntentInput
+): ActionBattleAiRule => rule(targetVisible(), then);
+
+export const ifTargetInRange = (
+  then: ActionBattleAiIntentInput,
+  range?: number
+): ActionBattleAiRule => rule(targetInRange(range), then);
+
+export const ifDistanceLessThan = (
+  distance: number,
+  then: ActionBattleAiIntentInput
+): ActionBattleAiRule => rule(distanceLessThan(distance), then);

package/src/core/attack-profile.spec.ts

@@ -115,4 +115,50 @@ describe("normalizeActionBattleAttackProfile", () => {
     expect(profile.recoveryMs).toBe(380);
     expect(profile.cooldownMs).toBe(500);
   });
+
+  test("normalizes the new combat, ai, skills, and ui option shape", () => {
+    const damage = () => ({ damage: 1, defeated: false });
+    const behavior = () => ({ mode: "assault" as const });
+    const targeting = () => ({ range: 4, aoeMask: ["#"] });
+    const options = normalizeActionBattleOptions({
+      attack: {
+        lockDurationMs: 500,
+      },
+      systems: {
+        combat: {
+          damage: () => ({ damage: 0, defeated: false }),
+        },
+      },
+      combat: {
+        attack: {
+          lockDurationMs: 260,
+        },
+        damage,
+      },
+      ai: {
+        behaviors: {
+          slime: behavior,
+        },
+      },
+      skills: {
+        targeting,
+      },
+      ui: {
+        actionBar: true,
+        targeting: false,
+        attackPreview: false,
+      },
+    });
+
+    expect(options.attack?.lockDurationMs).toBe(260);
+    expect(options.systems?.combat?.damage).toBe(damage);
+    expect(options.combat?.damage).toBe(damage);
+    expect(options.systems?.ai?.behaviors?.slime).toBe(behavior);
+    expect(options.ai?.behaviors?.slime).toBe(behavior);
+    expect(options.skills?.getTargeting).toBe(targeting);
+    expect(options.skills?.targeting).toBe(targeting);
+    expect((options.ui?.actionBar as any).enabled).toBe(true);
+    expect((options.ui?.targeting as any).enabled).toBe(false);
+    expect((options.ui?.attackPreview as any).enabled).toBe(false);
+  });
 });

package/src/core/attack-runtime.spec.ts

@@ -4,6 +4,7 @@ import {
   createActionBattleAttackId,
   getNormalizedActionBattleAttackProfile,
   resolveActionBattleHitboxSpeed,
+  runActionBattleActiveHitbox,
   scheduleActionBattleStartup,
 } from "./attack-runtime";
 
@@ -76,6 +77,40 @@ describe("attack runtime helpers", () => {
     expect(scheduler).toHaveBeenCalledWith(callback, 120);
   });
 
+  test("runs hitbox queries across the active window", () => {
+    const callbacks: Array<() => void> = [];
+    const scheduler = vi.fn((callback: () => void) => {
+      callbacks.push(callback);
+      return callbacks.length;
+    });
+    const onHitboxes = vi.fn();
+    const profile = getNormalizedActionBattleAttackProfile({
+      attack: {
+        profile: {
+          startupMs: 20,
+          activeMs: 32,
+        },
+      },
+    });
+
+    runActionBattleActiveHitbox(
+      profile,
+      () => [{ x: 0, y: 0, width: 10, height: 10 }],
+      onHitboxes,
+      scheduler
+    );
+
+    expect(onHitboxes).not.toHaveBeenCalled();
+    expect(scheduler).toHaveBeenCalledWith(expect.any(Function), 20);
+
+    callbacks.shift()?.();
+    expect(onHitboxes).toHaveBeenCalledTimes(1);
+    expect(scheduler).toHaveBeenLastCalledWith(expect.any(Function), 16);
+
+    callbacks.shift()?.();
+    expect(onHitboxes).toHaveBeenCalledTimes(2);
+  });
+
   test("creates stable unique attack ids", () => {
     const first = createActionBattleAttackId("player-1", "sword");
     const second = createActionBattleAttackId("player-1", "sword");

package/src/core/attack-runtime.ts

@@ -3,6 +3,7 @@ import type {
   ActionBattleOptions,
   NormalizedActionBattleAttackProfile,
 } from "../types";
+import type { ActionBattleHitbox } from "./contracts";
 import { normalizeActionBattleAttackProfile } from "./attack-profile";
 
 export const ACTION_BATTLE_HITBOX_FRAME_MS = 16;
@@ -42,6 +43,37 @@ export function scheduleActionBattleStartup(
   return scheduler(callback, profile.startupMs);
 }
 
+export function runActionBattleActiveHitbox(
+  profile: NormalizedActionBattleAttackProfile,
+  resolveHitboxes: () => ActionBattleHitbox[],
+  onHitboxes: (hitboxes: ActionBattleHitbox[]) => void,
+  scheduler: (callback: () => void, delayMs: number) => unknown = setTimeout
+) {
+  const frames = Math.max(
+    1,
+    Math.ceil(profile.activeMs / ACTION_BATTLE_HITBOX_FRAME_MS)
+  );
+  let frame = 0;
+
+  const step = () => {
+    const hitboxes = resolveHitboxes();
+    if (hitboxes.length > 0) {
+      onHitboxes(hitboxes);
+    }
+    frame++;
+    if (frame < frames) {
+      scheduler(step, ACTION_BATTLE_HITBOX_FRAME_MS);
+    }
+  };
+
+  if (profile.startupMs <= 0) {
+    step();
+    return null;
+  }
+
+  return scheduler(step, profile.startupMs);
+}
+
 let attackIdCounter = 0;
 
 export function createActionBattleAttackId(

package/src/core/context.ts

@@ -6,20 +6,29 @@ const mergeSystems = (options: ActionBattleOptions = {}): ActionBattleSystems =>
   combat: {
     ...defaultActionBattleSystems.combat,
     resolveDamage:
+      options.combat?.damage ??
       options.systems?.combat?.damage ??
       defaultActionBattleSystems.combat.resolveDamage,
     resolveKnockback:
+      options.combat?.knockback ??
       options.systems?.combat?.knockback ??
       defaultActionBattleSystems.combat.resolveKnockback,
     hooks: {
       ...defaultActionBattleSystems.combat.hooks,
       ...options.systems?.combat?.hooks,
+      ...options.combat?.hooks,
     },
   },
   ai: {
     behaviors: {
       ...defaultActionBattleSystems.ai.behaviors,
       ...options.systems?.ai?.behaviors,
+      ...options.ai?.behaviors,
+    },
+    presets: {
+      ...defaultActionBattleSystems.ai.presets,
+      ...options.systems?.ai?.presets,
+      ...options.ai?.presets,
     },
   },
 });