hrbattle 0.1.0

package/dist/cocos-adapter/BattleFacade.js

@@ -0,0 +1,22 @@
+import { BattleCore } from "../battle/battleCore";
+export class BattleFacade {
+    core;
+    start(units, config, initialize) {
+        const normalizedUnits = units.map((unit) => ({
+            ...unit,
+            id: this.toInstanceId(unit)
+        }));
+        this.core = new BattleCore(normalizedUnits, config);
+        initialize?.(this.core);
+        return this.core.run();
+    }
+    stop() {
+        this.core = undefined;
+    }
+    toInstanceId(unit) {
+        if (/^t[12]_p\d+_.+/.test(unit.id)) {
+            return unit.id;
+        }
+        return `t${unit.teamId}_p${unit.position}_${unit.id}`;
+    }
+}

package/dist/cocos-adapter/clientBattleResult.d.ts

@@ -0,0 +1,127 @@
+import type { BattleResult } from "../battle/battleCore";
+import type { BuffConfig } from "../battle/types";
+export interface ClientPositionChange {
+    unitId: string;
+    from: number;
+    to: number;
+    reason: "position_shift";
+}
+export interface ClientActionStateRef {
+    snapshotIndex: number | null;
+}
+export interface ClientBuffChange {
+    unitId: string;
+    buffId: string;
+    name: string;
+    changeType: "added" | "removed" | "updated";
+    fromStacks: number;
+    toStacks: number;
+    fromRemainingRounds: number;
+    toRemainingRounds: number;
+    sourceId: string;
+}
+export interface ClientStatChange {
+    unitId: string;
+    stat: "Att" | "Def" | "Spd" | "pCTR" | "pCTD" | "pHE" | "pEHR" | "pERes" | "pIM" | "pITM" | "pVulnerability";
+    from: number;
+    to: number;
+}
+export interface ClientPanelBuffDelta {
+    unitId: string;
+    buffId: string;
+    name: string;
+    stat: ClientStatChange["stat"];
+    delta: number;
+    mode: "on_first_gain";
+}
+export interface ClientStateSettlementDelta {
+    unitId: string;
+    stat: "Hp" | "AP" | "Energy" | "Shield" | "Imbalance";
+    delta: number;
+    source: "buff_settlement" | "other_runtime_change" | "imbalance_turn_clear" | "imbalance_skill_effect";
+    sourceBuffId: string | null;
+    element: string | null;
+    sourceActorId: string | null;
+    sourceSkillId: string | null;
+}
+export interface ClientImbalanceBreak {
+    targetId: string;
+    attackerId: string;
+    element: string;
+}
+export interface ClientImbalanceChange {
+    targetId: string;
+    delta: number;
+    reason: "turn_start_clear" | "skill_effect";
+    sourceActorId: string | null;
+    sourceSkillId: string | null;
+}
+export interface ClientTurnSettlement {
+    turn: number;
+    snapshotIndex: number;
+    positionChanges: ClientPositionChange[];
+    stateSettlementDeltas: ClientStateSettlementDelta[];
+    imbalanceChanges: ClientImbalanceChange[];
+    dotDamages: Array<{
+        targetId: string;
+        value: number;
+        buffId: string;
+        element: string | null;
+    }>;
+}
+type ClientSnapshot = Omit<BattleResult["logs"]["snapshots"][number], "dotDamages" | "imbalanceBreaks" | "imbalanceChanges"> & {
+    dotDamages: Array<{
+        targetId: string;
+        value: number;
+        buffId: string;
+        element: string | null;
+    }>;
+    imbalanceBreaks: Array<{
+        targetId: string;
+        attackerId: string;
+        element: string;
+    }>;
+    imbalanceChanges: ClientImbalanceChange[];
+};
+export type ClientAction = BattleResult["logs"]["actionLogs"][number] & {
+    actionIndex: number;
+    stateRef: ClientActionStateRef;
+    buffChanges: ClientBuffChange[];
+    panelBuffDeltas: ClientPanelBuffDelta[];
+    stateRuntimeDeltas: ClientStateSettlementDelta[];
+    imbalanceBreaks: ClientImbalanceBreak[];
+    imbalanceChanges: ClientImbalanceChange[];
+};
+export interface ClientBattleResult {
+    meta: {
+        seed: number;
+        maxTurns: number;
+        generatedAt: string;
+    };
+    lineup: {
+        team1: string[];
+        team2: string[];
+    };
+    summary: {
+        winner: 1 | 2 | 0;
+        totalTurns: number;
+        actionCount: number;
+        snapshotCount: number;
+        errorCount: number;
+    };
+    actions: ClientAction[];
+    turnSettlements: ClientTurnSettlement[];
+    snapshots: ClientSnapshot[];
+    errors: BattleResult["logs"]["errors"];
+    finalUnits: BattleResult["logs"]["snapshots"][number]["units"];
+}
+export interface BuildClientBattleResultInput {
+    battleResult: BattleResult;
+    seed: number;
+    maxTurns: number;
+    team1HeroIds: string[];
+    team2HeroIds: string[];
+    buffConfigs?: BuffConfig[];
+}
+export declare function buildClientBattleResult(input: BuildClientBattleResultInput): ClientBattleResult;
+export {};

package/dist/cocos-adapter/clientBattleResult.js

@@ -0,0 +1,413 @@
+function toPositionMap(snapshot) {
+    return new Map((snapshot?.units ?? []).map((u) => [u.id, u.position]));
+}
+function diffPositions(prev, next) {
+    const changes = [];
+    for (const [unitId, from] of prev.entries()) {
+        const to = next.get(unitId);
+        if (to === undefined || to === from) {
+            continue;
+        }
+        changes.push({
+            unitId,
+            from,
+            to,
+            reason: "position_shift"
+        });
+    }
+    return changes;
+}
+function buildAfterSkillSnapshotIndices(snapshots) {
+    const indices = [];
+    for (let i = 0; i < snapshots.length; i++) {
+        if (snapshots[i].phase === "afterSkill") {
+            indices.push(i);
+        }
+    }
+    return indices;
+}
+function buildTurnEndSnapshotIndexByTurn(snapshots) {
+    const map = new Map();
+    for (let i = 0; i < snapshots.length; i++) {
+        if (snapshots[i].phase === "turnEnd") {
+            map.set(snapshots[i].turn, i);
+        }
+    }
+    return map;
+}
+function unitMap(snapshot) {
+    return new Map((snapshot?.units ?? []).map((u) => [u.id, u]));
+}
+function diffBuffs(prevSnapshot, nextSnapshot) {
+    const changes = [];
+    const prevUnits = unitMap(prevSnapshot);
+    const nextUnits = unitMap(nextSnapshot);
+    for (const [unitId, nextUnit] of nextUnits.entries()) {
+        const prevUnit = prevUnits.get(unitId);
+        const prevBuffs = new Map((prevUnit?.buffs ?? []).map((b) => [b.id, b]));
+        const nextBuffs = new Map((nextUnit.buffs ?? []).map((b) => [b.id, b]));
+        for (const [buffId, nextBuff] of nextBuffs.entries()) {
+            const prevBuff = prevBuffs.get(buffId);
+            if (!prevBuff) {
+                changes.push({
+                    unitId,
+                    buffId,
+                    name: nextBuff.name,
+                    changeType: "added",
+                    fromStacks: 0,
+                    toStacks: nextBuff.stacks,
+                    fromRemainingRounds: 0,
+                    toRemainingRounds: nextBuff.remainingRounds,
+                    sourceId: nextBuff.sourceId
+                });
+                continue;
+            }
+            if (prevBuff.stacks !== nextBuff.stacks || prevBuff.remainingRounds !== nextBuff.remainingRounds) {
+                changes.push({
+                    unitId,
+                    buffId,
+                    name: nextBuff.name,
+                    changeType: "updated",
+                    fromStacks: prevBuff.stacks,
+                    toStacks: nextBuff.stacks,
+                    fromRemainingRounds: prevBuff.remainingRounds,
+                    toRemainingRounds: nextBuff.remainingRounds,
+                    sourceId: nextBuff.sourceId
+                });
+            }
+        }
+        for (const [buffId, prevBuff] of prevBuffs.entries()) {
+            if (nextBuffs.has(buffId)) {
+                continue;
+            }
+            changes.push({
+                unitId,
+                buffId,
+                name: prevBuff.name,
+                changeType: "removed",
+                fromStacks: prevBuff.stacks,
+                toStacks: 0,
+                fromRemainingRounds: prevBuff.remainingRounds,
+                toRemainingRounds: 0,
+                sourceId: prevBuff.sourceId
+            });
+        }
+    }
+    return changes;
+}
+function diffStats(prevSnapshot, nextSnapshot) {
+    const changes = [];
+    const prevUnits = unitMap(prevSnapshot);
+    const nextUnits = unitMap(nextSnapshot);
+    const stats = ["Att", "Def", "Spd", "pCTR", "pCTD", "pHE", "pEHR", "pERes", "pIM", "pITM", "pVulnerability"];
+    for (const [unitId, nextUnit] of nextUnits.entries()) {
+        const prevUnit = prevUnits.get(unitId);
+        for (const stat of stats) {
+            const from = prevUnit?.effectiveAllStats?.[stat] ?? 0;
+            const to = nextUnit.effectiveAllStats[stat];
+            if (from !== to) {
+                changes.push({ unitId, stat, from, to });
+            }
+        }
+    }
+    return changes;
+}
+function buildTurnSettlements(snapshots) {
+    const settlements = [];
+    for (let i = 0; i < snapshots.length; i++) {
+        const current = snapshots[i];
+        if (current.phase !== "turnEnd") {
+            continue;
+        }
+        const prev = i > 0 ? snapshots[i - 1] : undefined;
+        settlements.push({
+            turn: current.turn,
+            snapshotIndex: i,
+            positionChanges: diffPositions(toPositionMap(prev), toPositionMap(current)),
+            stateSettlementDeltas: diffRuntimeStates(prev, current, undefined, current.dotDamages, current.imbalanceChanges),
+            imbalanceChanges: (current.imbalanceChanges ?? []).map((change) => ({
+                targetId: change.targetId,
+                delta: change.delta,
+                reason: change.reason,
+                sourceActorId: change.sourceActorId ?? null,
+                sourceSkillId: change.sourceSkillId ?? null
+            })),
+            dotDamages: (current.dotDamages ?? []).map((dot) => ({
+                targetId: dot.targetId,
+                value: dot.value,
+                buffId: dot.buffId,
+                element: dot.element ?? null
+            }))
+        });
+    }
+    return settlements;
+}
+function impactedRuntimeStatsByHits(hits) {
+    const map = new Map();
+    for (const hit of hits ?? []) {
+        const stats = map.get(hit.targetId) ?? new Set();
+        if (hit.effectType === "damage" || hit.effectType === "heal") {
+            stats.add("Hp");
+        }
+        else if (hit.effectType === "shield") {
+            stats.add("Shield");
+        }
+        map.set(hit.targetId, stats);
+    }
+    return map;
+}
+function diffRuntimeStates(prevSnapshot, nextSnapshot, hits, dotDamages, imbalanceChanges) {
+    if (!nextSnapshot) {
+        return [];
+    }
+    const deltas = [];
+    const prevUnits = unitMap(prevSnapshot);
+    const hitImpacts = impactedRuntimeStatsByHits(hits);
+    const dotDamageMap = new Map();
+    for (const dot of dotDamages ?? []) {
+        const buffMap = dotDamageMap.get(dot.targetId) ?? new Map();
+        buffMap.set(dot.buffId, { value: dot.value, element: dot.element });
+        dotDamageMap.set(dot.targetId, buffMap);
+    }
+    const imbalanceChangeMap = new Map();
+    for (const change of imbalanceChanges ?? []) {
+        const list = imbalanceChangeMap.get(change.targetId) ?? [];
+        list.push(change);
+        imbalanceChangeMap.set(change.targetId, list);
+    }
+    for (const nextUnit of nextSnapshot.units) {
+        const prevUnit = prevUnits.get(nextUnit.id);
+        const relatedBuffIds = [...new Set([...(prevUnit?.buffs ?? []), ...(nextUnit.buffs ?? [])].map((b) => b.id))];
+        const fields = [
+            ["Hp", prevUnit?.hp ?? nextUnit.hp, nextUnit.hp],
+            ["AP", prevUnit?.ap ?? nextUnit.ap, nextUnit.ap],
+            ["Energy", prevUnit?.energy ?? nextUnit.energy, nextUnit.energy],
+            ["Shield", prevUnit?.shield ?? nextUnit.shield, nextUnit.shield],
+            ["Imbalance", prevUnit?.imbalance ?? nextUnit.imbalance, nextUnit.imbalance]
+        ];
+        for (const [stat, from, to] of fields) {
+            const delta = to - from;
+            if (delta === 0) {
+                continue;
+            }
+            const impactedByHit = hitImpacts.get(nextUnit.id)?.has(stat) ?? false;
+            const unitDotMap = dotDamageMap.get(nextUnit.id);
+            let sourceBuffId = null;
+            let element = null;
+            let sourceActorId = null;
+            let sourceSkillId = null;
+            let source = "other_runtime_change";
+            if (!impactedByHit && unitDotMap && relatedBuffIds.length > 0 && stat === "Hp" && delta < 0) {
+                for (const buffId of relatedBuffIds) {
+                    if (unitDotMap.has(buffId)) {
+                        const dotInfo = unitDotMap.get(buffId);
+                        if (dotInfo.value === -delta) {
+                            sourceBuffId = buffId;
+                            element = dotInfo.element ?? null;
+                            source = "buff_settlement";
+                            break;
+                        }
+                    }
+                }
+            }
+            if (stat === "Imbalance") {
+                const exactMatchedChange = (imbalanceChangeMap.get(nextUnit.id) ?? []).find((change) => change.delta === delta);
+                if (exactMatchedChange?.reason === "turn_start_clear") {
+                    source = "imbalance_turn_clear";
+                    sourceActorId = exactMatchedChange.sourceActorId ?? null;
+                    sourceSkillId = exactMatchedChange.sourceSkillId ?? null;
+                }
+                else if (exactMatchedChange?.reason === "skill_effect") {
+                    source = "imbalance_skill_effect";
+                    sourceActorId = exactMatchedChange.sourceActorId ?? null;
+                    sourceSkillId = exactMatchedChange.sourceSkillId ?? null;
+                }
+            }
+            deltas.push({
+                unitId: nextUnit.id,
+                stat,
+                delta,
+                source,
+                sourceBuffId,
+                element,
+                sourceActorId,
+                sourceSkillId
+            });
+        }
+    }
+    return deltas;
+}
+function statFromBuffConfig(config) {
+    const stats = new Set();
+    if (config.attackRateDelta) {
+        stats.add("Att");
+    }
+    if (config.defenseRateDelta) {
+        stats.add("Def");
+    }
+    if (config.speedRateDelta) {
+        stats.add("Spd");
+    }
+    if (config.critRateDelta) {
+        stats.add("pCTR");
+    }
+    if (config.critDamageDelta) {
+        stats.add("pCTD");
+    }
+    if (config.healEffectDelta) {
+        stats.add("pHE");
+    }
+    if (config.effectHitDelta) {
+        stats.add("pEHR");
+    }
+    if (config.effectResDelta) {
+        stats.add("pERes");
+    }
+    if (config.vulnerabilityDelta) {
+        stats.add("pVulnerability");
+    }
+    return stats;
+}
+function buildBuffAffectStatsMap(buffConfigs) {
+    const map = new Map();
+    for (const config of buffConfigs) {
+        map.set(config.id, statFromBuffConfig(config));
+    }
+    return map;
+}
+function toPanelBuffDeltas(buffChanges, statChanges, buffAffectStatsMap) {
+    const added = buffChanges.filter((b) => b.changeType === "added");
+    if (added.length === 0) {
+        return [];
+    }
+    const addedByUnit = new Map();
+    for (const buff of added) {
+        const list = addedByUnit.get(buff.unitId) ?? [];
+        list.push(buff);
+        addedByUnit.set(buff.unitId, list);
+    }
+    const result = [];
+    for (const stat of statChanges) {
+        const delta = stat.to - stat.from;
+        if (delta === 0) {
+            continue;
+        }
+        const candidates = addedByUnit.get(stat.unitId) ?? [];
+        if (candidates.length === 0) {
+            continue;
+        }
+        const preferred = candidates.find((item) => buffAffectStatsMap.get(item.buffId)?.has(stat.stat)) ??
+            (stat.stat === "pVulnerability" ? candidates.find((item) => item.buffId.includes("vulnerability")) : undefined) ??
+            candidates[0];
+        result.push({
+            unitId: stat.unitId,
+            buffId: preferred.buffId,
+            name: preferred.name,
+            stat: stat.stat,
+            delta,
+            mode: "on_first_gain"
+        });
+    }
+    return result;
+}
+function buildClientActions(battleResult, buffAffectStatsMap) {
+    const snapshots = battleResult.logs.snapshots;
+    const afterSkillIndices = buildAfterSkillSnapshotIndices(snapshots);
+    const turnEndIndexByTurn = buildTurnEndSnapshotIndexByTurn(snapshots);
+    const firstSnapshot = snapshots[0];
+    let currentSnapshotIndex = 0;
+    let afterSkillCursor = 0;
+    let currentTurn = firstSnapshot?.turn ?? 0;
+    const actions = [];
+    for (let actionIndex = 0; actionIndex < battleResult.logs.actionLogs.length; actionIndex++) {
+        const action = battleResult.logs.actionLogs[actionIndex];
+        if (action.turn > currentTurn) {
+            const prevTurnEndIndex = turnEndIndexByTurn.get(action.turn - 1);
+            if (prevTurnEndIndex !== undefined) {
+                currentSnapshotIndex = prevTurnEndIndex;
+            }
+            currentTurn = action.turn;
+        }
+        const snapshotIndex = afterSkillIndices[afterSkillCursor] ?? null;
+        const snapshot = snapshotIndex === null ? undefined : snapshots[snapshotIndex];
+        afterSkillCursor += 1;
+        const buffChanges = diffBuffs(snapshots[currentSnapshotIndex], snapshot);
+        const statChanges = diffStats(snapshots[currentSnapshotIndex], snapshot);
+        actions.push({
+            ...action,
+            actionIndex,
+            buffChanges,
+            panelBuffDeltas: toPanelBuffDeltas(buffChanges, statChanges, buffAffectStatsMap),
+            stateRuntimeDeltas: diffRuntimeStates(snapshots[currentSnapshotIndex], snapshot, action.result.hits, snapshot?.dotDamages, snapshot?.imbalanceChanges),
+            imbalanceBreaks: (snapshot?.imbalanceBreaks ?? []).map((ib) => ({
+                targetId: ib.targetId,
+                attackerId: ib.attackerId,
+                element: ib.element
+            })),
+            imbalanceChanges: (snapshot?.imbalanceChanges ?? []).map((change) => ({
+                targetId: change.targetId,
+                delta: change.delta,
+                reason: change.reason,
+                sourceActorId: change.sourceActorId ?? null,
+                sourceSkillId: change.sourceSkillId ?? null
+            })),
+            stateRef: {
+                snapshotIndex
+            }
+        });
+        if (snapshotIndex !== null) {
+            currentSnapshotIndex = snapshotIndex;
+        }
+    }
+    return actions;
+}
+export function buildClientBattleResult(input) {
+    const finalSnapshot = [...input.battleResult.logs.snapshots].reverse().find((item) => item.phase === "turnEnd");
+    const buffAffectStatsMap = buildBuffAffectStatsMap(input.buffConfigs ?? []);
+    const actions = buildClientActions(input.battleResult, buffAffectStatsMap);
+    const turnSettlements = buildTurnSettlements(input.battleResult.logs.snapshots);
+    const snapshots = input.battleResult.logs.snapshots.map((snapshot) => ({
+        ...snapshot,
+        dotDamages: (snapshot.dotDamages ?? []).map((dot) => ({
+            targetId: dot.targetId,
+            value: dot.value,
+            buffId: dot.buffId,
+            element: dot.element ?? null
+        })),
+        imbalanceBreaks: (snapshot.imbalanceBreaks ?? []).map((ib) => ({
+            targetId: ib.targetId,
+            attackerId: ib.attackerId,
+            element: ib.element
+        })),
+        imbalanceChanges: (snapshot.imbalanceChanges ?? []).map((change) => ({
+            targetId: change.targetId,
+            delta: change.delta,
+            reason: change.reason,
+            sourceActorId: change.sourceActorId ?? null,
+            sourceSkillId: change.sourceSkillId ?? null
+        }))
+    }));
+    return {
+        meta: {
+            seed: input.seed,
+            maxTurns: input.maxTurns,
+            generatedAt: new Date().toISOString()
+        },
+        lineup: {
+            team1: input.team1HeroIds,
+            team2: input.team2HeroIds
+        },
+        summary: {
+            winner: input.battleResult.winner,
+            totalTurns: input.battleResult.totalTurns,
+            actionCount: actions.length,
+            snapshotCount: input.battleResult.logs.snapshots.length,
+            errorCount: input.battleResult.logs.errors.length
+        },
+        actions,
+        turnSettlements,
+        snapshots,
+        errors: input.battleResult.logs.errors,
+        finalUnits: finalSnapshot?.units ?? []
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export { BattleCore } from "./battle/battleCore";
+export { BattleFacade } from "./cocos-adapter/BattleFacade";
+export { buildClientBattleResult } from "./cocos-adapter/clientBattleResult";
+export type { BuildClientBattleResultInput, ClientAction, ClientActionStateRef, ClientBattleResult, ClientImbalanceChange, ClientPanelBuffDelta, ClientPositionChange, ClientStateSettlementDelta, ClientStatChange, ClientTurnSettlement } from "./cocos-adapter/clientBattleResult";
+export { BattleEventBus } from "./battle/eventBus";
+export { EffectSystem } from "./battle/effectSystem";
+export { calcDamage, calcEffectProbability, calcHealOrShield } from "./battle/formula";
+export { ConfigSkillEngine, ScriptSkillEngine, SkillExecutor } from "./battle/skillEngine";
+export { designedScripts } from "./battle/script/designedScripts";
+export type { BattleScriptApi, BattleConfig, BattleInitUnit, BuffConfig, ISkillScript, SkillDefinition, SkillExecMode, SkillTemplate, UnitModel, UnitStats } from "./battle/types";

package/dist/index.js

@@ -0,0 +1,8 @@
+export { BattleCore } from "./battle/battleCore";
+export { BattleFacade } from "./cocos-adapter/BattleFacade";
+export { buildClientBattleResult } from "./cocos-adapter/clientBattleResult";
+export { BattleEventBus } from "./battle/eventBus";
+export { EffectSystem } from "./battle/effectSystem";
+export { calcDamage, calcEffectProbability, calcHealOrShield } from "./battle/formula";
+export { ConfigSkillEngine, ScriptSkillEngine, SkillExecutor } from "./battle/skillEngine";
+export { designedScripts } from "./battle/script/designedScripts";

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "hrbattle",
+  "version": "0.1.0",
+  "description": "一个基于回合制战斗引擎，支持技能脚本、buff系统和效果解析。",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "battle:result": "vitest run tests/battleResultOutput.test.ts"
+  },
+  "keywords": [
+    "battle",
+    "turn-based",
+    "game",
+    "rpg",
+    "skill",
+    "buff"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^22.15.3",
+    "tsx": "^4.19.4",
+    "typescript": "^5.8.3",
+    "vitest": "^3.1.2",
+    "xlsx": "^0.18.5"
+  }
+}