hrbattle 1.0.2 → 1.0.3

package/dist/battle/battleCore.js

@@ -395,7 +395,10 @@ export class BattleCore {
                     applyBuff: (sourceId, targetId, buffId) => this.applyBuff(sourceId, targetId, buffId),
                     getEffectiveStats: (unit) => this.effectSystem.getEffectiveStats(unit),
                     createScriptApi: (skillElement) => ({
-                        damage: (sourceId, targetId, value) => this.applyDamage(sourceId, targetId, value, skillElement),
+                        damage: (sourceId, targetId, value) => {
+                            const r = this.applyDamage(sourceId, targetId, value, skillElement);
+                            return { damage: r.damage, imbalanceDelta: r.imbalanceDelta, triggeredImbalanceBreak: r.triggeredImbalanceBreak };
+                        },
                         heal: (targetId, value) => this.applyHeal(targetId, value),
                         shield: (targetId, value) => this.applyShield(targetId, value),
                         adjustImbalance: (targetId, delta) => {
@@ -575,10 +578,14 @@ export class BattleCore {
             this.eventBus.emit({ name: "OnKill", payload: { killerId: source.id, targetId: target.id } });
         }
         this.eventBus.emit({ name: "OnAfterDamage", payload: { sourceId, targetId, value: damage } });
+        let imbalanceDelta = 0;
+        let triggeredImbalanceBreak = false;
         if (staggerElement && sourceId !== targetId && target.runtime.alive) {
-            this.accumulateStagger(source, target, staggerElement);
+            const staggerResult = this.accumulateStagger(source, target, staggerElement);
+            imbalanceDelta = staggerResult.applied;
+            triggeredImbalanceBreak = staggerResult.broke;
         }
-        return damage;
+        return { damage, imbalanceDelta, triggeredImbalanceBreak };
     }
     applyHeal(targetId, value) {
         const target = this.mustUnit(targetId);
@@ -623,7 +630,7 @@ export class BattleCore {
     }
     accumulateStagger(source, target, skillElement) {
         if (this.pendingImbalanceClear.has(target.id)) {
-            return;
+            return { applied: 0, broke: false };
         }
         const effectiveSource = this.effectSystem.getEffectiveStats(source);
         const baseStagger = effectiveSource.Att;
@@ -642,9 +649,12 @@ export class BattleCore {
         if (applied !== 0) {
             this.logger.logImbalanceChange(target.id, applied, "skill_effect", this.activeSkillContext?.actorId ?? source.id, this.activeSkillContext?.skillId);
         }
+        let broke = false;
         if (target.runtime.Imbalance >= max) {
+            broke = true;
             this.onImbalanceBreak(source, target, skillElement);
         }
+        return { applied, broke };
     }
     onImbalanceBreak(source, target, element) {
         const max = this.computeImbalanceMax(target);

package/dist/battle/config/sampleData.d.ts

@@ -0,0 +1,3 @@
+import type { BuffConfig, SkillTemplate } from "../types";
+export declare const sampleBuffs: BuffConfig[];
+export declare const sampleTemplates: SkillTemplate[];

package/dist/battle/config/sampleData.js

@@ -0,0 +1,82 @@
+export const sampleBuffs = [
+    {
+        id: "slow",
+        name: "迟缓",
+        maxStacks: 5,
+        durationPerStack: 1,
+        expireRounds: 1,
+        onRoundEndDelta: -1,
+        speedRateDelta: -1000
+    },
+    {
+        id: "stun",
+        name: "眩晕",
+        maxStacks: 1,
+        durationPerStack: 1,
+        onRoundEndDelta: -999,
+        stun: true
+    },
+    {
+        id: "taunt",
+        name: "嘲讽",
+        maxStacks: 1,
+        durationPerStack: 2,
+        expireRounds: 2,
+        onRoundEndDelta: -1,
+        taunt: true
+    },
+    {
+        id: "burn",
+        name: "点燃",
+        maxStacks: 99,
+        durationPerStack: 1,
+        expireRounds: 1,
+        onRoundEndDelta: -1,
+        dotRatio: 0.18
+    },
+    {
+        id: "share-damage",
+        name: "分摊伤害",
+        maxStacks: 1,
+        durationPerStack: 3,
+        expireRounds: 3,
+        onRoundEndDelta: -1
+    },
+    {
+        id: "imbalance-vulnerability",
+        name: "失衡易伤",
+        maxStacks: 1,
+        durationPerStack: 1,
+        expireRounds: 1,
+        onRoundEndDelta: -1,
+        vulnerabilityDelta: 2000
+    }
+];
+export const sampleTemplates = [
+    {
+        id: "basic-single",
+        steps: [
+            { kind: "damage", ratio: 0.5 },
+            { kind: "buff", ratio: 0, buffId: "burn", fixedProb: 2500 }
+        ]
+    },
+    {
+        id: "core-stun",
+        steps: [
+            { kind: "damage", ratio: 0.8 },
+            { kind: "buff", ratio: 0, buffId: "stun", fixedProb: 6500 }
+        ]
+    },
+    {
+        id: "ultimate-aoe",
+        steps: [{ kind: "damage", ratio: 1.8 }]
+    },
+    {
+        id: "taunt-skill",
+        steps: [{ kind: "buff", ratio: 0, buffId: "taunt", fixedProb: 8000 }]
+    },
+    {
+        id: "shield-team",
+        steps: [{ kind: "shield", ratio: 0.6 }]
+    }
+];

package/dist/battle/script/designedScripts.js

@@ -14,17 +14,19 @@ function buildEmptyResult(ctx, targets = ctx.targets) {
         triggeredBy: ctx.trigger
     };
 }
-function buildDamageHit(ctx, targetId, finalValue) {
+function buildDamageHit(ctx, targetId, finalValue, imbalanceDelta, triggeredImbalanceBreak) {
     return {
         targetId,
         effectType: "damage",
         element: ctx.api.getUnit(ctx.caster)?.element ?? "fire",
-        skillType: "basic",
+        skillType: ctx.skillType,
         isCritical: false,
         baseValue: finalValue,
         criticalValue: finalValue,
         finalValue,
         isRepression: 0,
+        imbalanceDelta,
+        triggeredImbalanceBreak,
         damageBreakdown: {
             preMitigation: finalValue,
             postMitigation: finalValue,
@@ -38,7 +40,7 @@ function buildBuffHit(ctx, targetId, buffId, resisted = false) {
         targetId,
         effectType: "buff",
         element: ctx.api.getUnit(ctx.caster)?.element ?? "fire",
-        skillType: "basic",
+        skillType: ctx.skillType,
         isCritical: false,
         baseValue: 0,
         criticalValue: 0,
@@ -53,7 +55,7 @@ function buildShieldHit(ctx, targetId, finalValue) {
         targetId,
         effectType: "shield",
         element: ctx.api.getUnit(ctx.caster)?.element ?? "fire",
-        skillType: "basic",
+        skillType: ctx.skillType,
         isCritical: false,
         baseValue: finalValue,
         criticalValue: finalValue,
@@ -66,7 +68,7 @@ function buildHealHit(ctx, targetId, finalValue) {
         targetId,
         effectType: "heal",
         element: ctx.api.getUnit(ctx.caster)?.element ?? "fire",
-        skillType: "basic",
+        skillType: ctx.skillType,
         isCritical: false,
         baseValue: finalValue,
         criticalValue: finalValue,
@@ -86,9 +88,9 @@ const bladeUltimateScript = {
         const hits = [];
         if (target && target.runtime.Hp * 100 < target.stats.Mhp * 50) {
             // 策划：对生命值低于50%的敌人额外造成20%伤害
-            const damage = ctx.api.damage(ctx.caster, targetId, Math.floor(self.stats.Att * 0.2));
-            totalDamage += damage;
-            hits.push(buildDamageHit(ctx, targetId, damage));
+            const r = ctx.api.damage(ctx.caster, targetId, Math.floor(self.stats.Att * 0.2));
+            totalDamage += r.damage;
+            hits.push(buildDamageHit(ctx, targetId, r.damage, r.imbalanceDelta));
         }
         return {
             ...buildEmptyResult(ctx, [targetId]),
@@ -110,9 +112,9 @@ const bladeBasicScript = {
         const hits = [];
         if (target && target.runtime.Hp * 100 > target.stats.Mhp * 70) {
             // 策划：对生命值高于70%的敌人造成额外20%伤害
-            const damage = ctx.api.damage(ctx.caster, targetId, Math.floor(self.stats.Att * 0.2));
-            totalDamage += damage;
-            hits.push(buildDamageHit(ctx, targetId, damage));
+            const r = ctx.api.damage(ctx.caster, targetId, Math.floor(self.stats.Att * 0.2));
+            totalDamage += r.damage;
+            hits.push(buildDamageHit(ctx, targetId, r.damage, r.imbalanceDelta));
         }
         return {
             ...buildEmptyResult(ctx, [targetId]),
@@ -137,9 +139,9 @@ const bladeCoreScript = {
         for (let i = 0; i < 3; i++) {
             const target = enemies[ctx.api.randomInt(enemies.length)];
             hitTargets.push(target.id);
-            const damage = ctx.api.damage(ctx.caster, target.id, Math.floor(self.stats.Att * 0.3));
-            totalDamage += damage;
-            hits.push(buildDamageHit(ctx, target.id, damage));
+            const r = ctx.api.damage(ctx.caster, target.id, Math.floor(self.stats.Att * 0.3));
+            totalDamage += r.damage;
+            hits.push(buildDamageHit(ctx, target.id, r.damage, r.imbalanceDelta));
             if (ctx.api.randomInt(10000) < 2000) {
                 ctx.api.gainEnergy(ctx.caster, 10);
             }
@@ -168,24 +170,8 @@ const luoluoBasicScript = {
 // 洛洛核心技：获得10%生命值的护盾，每层【惩戒/意志】使护盾强度增加10%
 const luoluoCoreScript = {
     onCast(ctx) {
-        const self = ctx.api.getUnit(ctx.caster);
-        let totalShield = 0;
-        const hits = [];
-        if (self) {
-            // 策划：10%Mhp护盾，每层意志增加10%
-            const willBuffs = ctx.api.getBuffs(ctx.caster).filter(b => b.id === "will");
-            const willStacks = willBuffs.reduce((sum, b) => sum + b.stacks, 0);
-            const shieldMultiplier = 1 + willStacks * 0.1;
-            const shield = Math.floor(self.stats.Mhp * 0.1 * shieldMultiplier);
-            ctx.api.shield(ctx.caster, shield);
-            totalShield += shield;
-            hits.push(buildShieldHit(ctx, ctx.caster, shield));
-        }
-        return {
-            ...buildEmptyResult(ctx, ctx.targets),
-            totalShield: totalShield,
-            hits
-        };
+        // 护盾交由config模板结算，script层不再重复加盾
+        return buildEmptyResult(ctx, ctx.targets);
     }
 };
 const miaoluoUltimateScript = {
@@ -206,14 +192,14 @@ const miaoluoUltimateScript = {
             ctx.api.addBuff(ctx.caster, ctx.caster, "miaoluo-ultimate-focus");
             hits.push(buildBuffHit(ctx, ctx.caster, "miaoluo-ultimate-focus"));
             for (let i = 0; i < 3; i += 1) {
-                const damage = ctx.api.damage(ctx.caster, target.id, Math.floor(self.stats.Att * 0.6));
-                totalDamage += damage;
-                hits.push(buildDamageHit(ctx, target.id, damage));
+                const r = ctx.api.damage(ctx.caster, target.id, Math.floor(self.stats.Att * 0.6));
+                totalDamage += r.damage;
+                hits.push(buildDamageHit(ctx, target.id, r.damage, r.imbalanceDelta));
             }
             if (ctx.api.hasBuff(target.id, "imbalance-vulnerability")) {
-                const damage = ctx.api.damage(ctx.caster, target.id, Math.floor(self.stats.Att * 0.3));
-                totalDamage += damage;
-                hits.push(buildDamageHit(ctx, target.id, damage));
+                const r2 = ctx.api.damage(ctx.caster, target.id, Math.floor(self.stats.Att * 0.3));
+                totalDamage += r2.damage;
+                hits.push(buildDamageHit(ctx, target.id, r2.damage, r2.imbalanceDelta));
             }
         }
         return {
@@ -238,9 +224,9 @@ const miaoluoBasicScript = {
         let totalDamage = 0;
         const hits = [];
         if (self && target) {
-            const damage = ctx.api.damage(ctx.caster, target.id, Math.floor(self.stats.Att * 0.5));
-            totalDamage += damage;
-            hits.push(buildDamageHit(ctx, target.id, damage));
+            const r = ctx.api.damage(ctx.caster, target.id, Math.floor(self.stats.Att * 0.5));
+            totalDamage += r.damage;
+            hits.push(buildDamageHit(ctx, target.id, r.damage, r.imbalanceDelta));
         }
         return {
             ...buildEmptyResult(ctx, target ? [target.id] : []),
@@ -264,9 +250,9 @@ const miaoluoCoreScript = {
         let totalDamage = 0;
         const hits = [];
         if (self && target) {
-            const damage = ctx.api.damage(ctx.caster, target.id, Math.floor(self.stats.Att * 0.8));
-            totalDamage += damage;
-            hits.push(buildDamageHit(ctx, target.id, damage));
+            const r = ctx.api.damage(ctx.caster, target.id, Math.floor(self.stats.Att * 0.8));
+            totalDamage += r.damage;
+            hits.push(buildDamageHit(ctx, target.id, r.damage, r.imbalanceDelta));
             ctx.api.addBuff(ctx.caster, target.id, "static");
             hits.push(buildBuffHit(ctx, target.id, "static"));
             ctx.api.addBuff(ctx.caster, ctx.caster, "flash");
@@ -288,13 +274,13 @@ const cookBasicScript = {
         if (self) {
             const selfCost = Math.floor(self.runtime.Hp * 0.1);
             if (selfCost > 0) {
-                const damage = ctx.api.damage(ctx.caster, ctx.caster, selfCost);
-                totalDamage += damage;
-                hits.push(buildDamageHit(ctx, ctx.caster, damage));
+                const r1 = ctx.api.damage(ctx.caster, ctx.caster, selfCost);
+                totalDamage += r1.damage;
+                hits.push(buildDamageHit(ctx, ctx.caster, r1.damage, r1.imbalanceDelta));
                 if (targetId) {
-                    const damage2 = ctx.api.damage(ctx.caster, targetId, Math.floor(selfCost * 0.5));
-                    totalDamage += damage2;
-                    hits.push(buildDamageHit(ctx, targetId, damage2));
+                    const r2 = ctx.api.damage(ctx.caster, targetId, Math.floor(selfCost * 0.5));
+                    totalDamage += r2.damage;
+                    hits.push(buildDamageHit(ctx, targetId, r2.damage, r2.imbalanceDelta));
                 }
             }
         }
@@ -324,9 +310,9 @@ const cookCoreScript = {
             const lostHp = Math.max(0, self.stats.Mhp - self.runtime.Hp);
             const lostStepCount = Math.floor((lostHp * 10) / Math.max(1, self.stats.Mhp));
             const multiplier = 1 + lostStepCount * 0.05;
-            const damage = ctx.api.damage(ctx.caster, target.id, Math.floor(self.stats.Att * multiplier));
-            totalDamage += damage;
-            hits.push(buildDamageHit(ctx, target.id, damage));
+            const r = ctx.api.damage(ctx.caster, target.id, Math.floor(self.stats.Att * multiplier));
+            totalDamage += r.damage;
+            hits.push(buildDamageHit(ctx, target.id, r.damage, r.imbalanceDelta));
         }
         return {
             ...buildEmptyResult(ctx, target ? [target.id] : []),
@@ -372,9 +358,9 @@ const kesiCoreScript = {
             const index = ctx.api.randomInt(pool.length);
             const [target] = pool.splice(index, 1);
             hitTargets.push(target.id);
-            const damage = ctx.api.damage(ctx.caster, target.id, Math.floor(self.stats.Att * 0.5));
-            totalDamage += damage;
-            hits.push(buildDamageHit(ctx, target.id, damage));
+            const r = ctx.api.damage(ctx.caster, target.id, Math.floor(self.stats.Att * 0.5));
+            totalDamage += r.damage;
+            hits.push(buildDamageHit(ctx, target.id, r.damage, r.imbalanceDelta));
             if (target.teamId === self.teamId) {
                 ctx.api.gainEnergy(ctx.caster, 10);
             }
@@ -404,9 +390,9 @@ const kesiUltimateScript = {
             const target = enemies[ctx.api.randomInt(enemies.length)];
             hitTargets.push(target.id);
             attacked.add(target.id);
-            const damage = ctx.api.damage(ctx.caster, target.id, Math.floor(self.stats.Att * 0.8));
-            totalDamage += damage;
-            hits.push(buildDamageHit(ctx, target.id, damage));
+            const r = ctx.api.damage(ctx.caster, target.id, Math.floor(self.stats.Att * 0.8));
+            totalDamage += r.damage;
+            hits.push(buildDamageHit(ctx, target.id, r.damage, r.imbalanceDelta));
         }
         for (const targetId of attacked) {
             const target = ctx.api.getUnit(targetId);
@@ -418,9 +404,9 @@ const kesiUltimateScript = {
                 .filter((buff) => buff.stacks > 0 && buff.config.dotRatio)
                 .reduce((sum, buff) => sum + Math.floor(target.stats.Att * (buff.config.dotRatio ?? 0) * buff.stacks), 0);
             if (dotValue > 0) {
-                const damage = ctx.api.damage(ctx.caster, targetId, Math.floor(dotValue * 0.6));
-                totalDamage += damage;
-                hits.push(buildDamageHit(ctx, target.id, damage));
+                const r2 = ctx.api.damage(ctx.caster, targetId, Math.floor(dotValue * 0.6));
+                totalDamage += r2.damage;
+                hits.push(buildDamageHit(ctx, target.id, r2.damage, r2.imbalanceDelta));
             }
         }
         return {
@@ -636,11 +622,11 @@ const luolaiBasicScript = {
         let totalDamage = 0;
         let totalHeal = 0;
         const hits = [];
-        const damage = ctx.api.damage(ctx.caster, target.id, Math.floor(self.stats.Att * 0.5));
-        totalDamage += damage;
-        hits.push(buildDamageHit(ctx, target.id, damage));
+        const r = ctx.api.damage(ctx.caster, target.id, Math.floor(self.stats.Att * 0.5));
+        totalDamage += r.damage;
+        hits.push(buildDamageHit(ctx, target.id, r.damage, r.imbalanceDelta));
         if (frontAlly) {
-            const heal = ctx.api.heal(frontAlly.id, Math.floor(damage * 0.5));
+            const heal = ctx.api.heal(frontAlly.id, Math.floor(r.damage * 0.5));
             totalHeal += heal;
             hits.push(buildHealHit(ctx, frontAlly.id, heal));
         }
@@ -938,9 +924,9 @@ const esCoreScript = {
         let totalDamage = 0;
         const hits = [];
         for (const enemy of enemies) {
-            const damage = ctx.api.damage(ctx.caster, enemy.id, Math.floor(self.stats.Att * 0.35));
-            totalDamage += damage;
-            hits.push(buildDamageHit(ctx, enemy.id, damage));
+            const r = ctx.api.damage(ctx.caster, enemy.id, Math.floor(self.stats.Att * 0.35));
+            totalDamage += r.damage;
+            hits.push(buildDamageHit(ctx, enemy.id, r.damage, r.imbalanceDelta));
             const resisted = ctx.api.randomInt(10000) >= 5000;
             if (!resisted) {
                 ctx.api.addBuff(ctx.caster, enemy.id, "dazzle");

package/dist/battle/script/monsterScripts.js

@@ -9,17 +9,19 @@ function buildEmptyResult(ctx, targets = ctx.targets) {
         triggeredBy: ctx.trigger
     };
 }
-function buildDamageHit(ctx, targetId, finalValue) {
+function buildDamageHit(ctx, targetId, finalValue, imbalanceDelta, triggeredImbalanceBreak) {
     return {
         targetId,
         effectType: "damage",
         element: ctx.api.getUnit(ctx.caster)?.element ?? "fire",
-        skillType: "basic",
+        skillType: ctx.skillType,
         isCritical: false,
         baseValue: finalValue,
         criticalValue: finalValue,
         finalValue,
         isRepression: 0,
+        imbalanceDelta,
+        triggeredImbalanceBreak,
         damageBreakdown: { preMitigation: finalValue, postMitigation: finalValue, shieldAbsorbed: 0, hpDamage: finalValue }
     };
 }
@@ -28,7 +30,7 @@ function buildBuffHit(ctx, targetId, buffId, resisted = false) {
         targetId,
         effectType: "buff",
         element: ctx.api.getUnit(ctx.caster)?.element ?? "fire",
-        skillType: "basic",
+        skillType: ctx.skillType,
         isCritical: false,
         baseValue: 0,
         criticalValue: 0,
@@ -43,7 +45,7 @@ function buildHealHit(ctx, targetId, finalValue) {
         targetId,
         effectType: "heal",
         element: ctx.api.getUnit(ctx.caster)?.element ?? "fire",
-        skillType: "basic",
+        skillType: ctx.skillType,
         isCritical: false,
         baseValue: finalValue,
         criticalValue: finalValue,
@@ -56,7 +58,7 @@ function buildShieldHit(ctx, targetId, finalValue) {
         targetId,
         effectType: "shield",
         element: ctx.api.getUnit(ctx.caster)?.element ?? "fire",
-        skillType: "basic",
+        skillType: ctx.skillType,
         isCritical: false,
         baseValue: finalValue,
         criticalValue: finalValue,
@@ -207,9 +209,9 @@ const m16122Script = {
             const target = pool.splice(idx, 1)[0];
             hitTargets.push(target.id);
             const ratio = (ctx.levelParams.ratio ?? 6000) / 10000;
-            const dmg = ctx.api.damage(ctx.caster, target.id, Math.floor(self.stats.Att * ratio));
-            totalDamage += dmg;
-            hits.push(buildDamageHit(ctx, target.id, dmg));
+            const r = ctx.api.damage(ctx.caster, target.id, Math.floor(self.stats.Att * ratio));
+            totalDamage += r.damage;
+            hits.push(buildDamageHit(ctx, target.id, r.damage, r.imbalanceDelta));
             if (ctx.api.randomInt(10000) < 5000) {
                 ctx.api.addBuff(ctx.caster, target.id, "dazzle");
                 hits.push(buildBuffHit(ctx, target.id, "dazzle"));

package/dist/battle/script/monsterScripts18xx.js

@@ -1,14 +1,14 @@
 function buildEmptyResult(ctx, targets = ctx.targets) {
     return { skillId: ctx.skillId, casterId: ctx.caster, targets, totalDamage: 0, totalHeal: 0, totalShield: 0, triggeredBy: ctx.trigger };
 }
-function buildDamageHit(ctx, targetId, v) {
-    return { targetId, effectType: "damage", element: ctx.api.getUnit(ctx.caster)?.element ?? "fire", skillType: "basic", isCritical: false, baseValue: v, criticalValue: v, finalValue: v, isRepression: 0, damageBreakdown: { preMitigation: v, postMitigation: v, shieldAbsorbed: 0, hpDamage: v } };
+function buildDamageHit(ctx, targetId, v, imbalanceDelta, triggeredImbalanceBreak) {
+    return { targetId, effectType: "damage", element: ctx.api.getUnit(ctx.caster)?.element ?? "fire", skillType: ctx.skillType, isCritical: false, baseValue: v, criticalValue: v, finalValue: v, isRepression: 0, imbalanceDelta, triggeredImbalanceBreak, damageBreakdown: { preMitigation: v, postMitigation: v, shieldAbsorbed: 0, hpDamage: v } };
 }
 function buildBuffHit(ctx, targetId, buffId, resisted = false) {
-    return { targetId, effectType: "buff", element: ctx.api.getUnit(ctx.caster)?.element ?? "fire", skillType: "basic", isCritical: false, baseValue: 0, criticalValue: 0, finalValue: 0, isRepression: 0, appliedBuffId: resisted ? undefined : buffId, resisted };
+    return { targetId, effectType: "buff", element: ctx.api.getUnit(ctx.caster)?.element ?? "fire", skillType: ctx.skillType, isCritical: false, baseValue: 0, criticalValue: 0, finalValue: 0, isRepression: 0, appliedBuffId: resisted ? undefined : buffId, resisted };
 }
 function buildHealHit(ctx, targetId, v) {
-    return { targetId, effectType: "heal", element: ctx.api.getUnit(ctx.caster)?.element ?? "fire", skillType: "basic", isCritical: false, baseValue: v, criticalValue: v, finalValue: v, isRepression: 0 };
+    return { targetId, effectType: "heal", element: ctx.api.getUnit(ctx.caster)?.element ?? "fire", skillType: ctx.skillType, isCritical: false, baseValue: v, criticalValue: v, finalValue: v, isRepression: 0 };
 }
 // ============================================================
 // 18011 光波比比 普攻：对距离最近的一名敌人造成50%光属性伤害，使自身获得3层【光能】
@@ -56,9 +56,9 @@ const m18013Script = {
                 if (!enemy.runtime.alive)
                     continue;
                 const perHitRatio = (ctx.levelParams.ratio ?? 2000) / 10000;
-                const dmg = ctx.api.damage(ctx.caster, enemy.id, Math.floor(self.stats.Att * perHitRatio));
-                totalDamage += dmg;
-                hits.push(buildDamageHit(ctx, enemy.id, dmg));
+                const r = ctx.api.damage(ctx.caster, enemy.id, Math.floor(self.stats.Att * perHitRatio));
+                totalDamage += r.damage;
+                hits.push(buildDamageHit(ctx, enemy.id, r.damage, r.imbalanceDelta));
                 if (!hitTargets.includes(enemy.id))
                     hitTargets.push(enemy.id);
             }
@@ -87,9 +87,9 @@ const m18022Script = {
         const hits = [];
         for (const t of targets) {
             const ratio18022 = (ctx.levelParams.ratio ?? 4000) / 10000;
-            const dmg = ctx.api.damage(ctx.caster, t.id, Math.floor(self.stats.Att * ratio18022));
-            totalDamage += dmg;
-            hits.push(buildDamageHit(ctx, t.id, dmg));
+            const r = ctx.api.damage(ctx.caster, t.id, Math.floor(self.stats.Att * ratio18022));
+            totalDamage += r.damage;
+            hits.push(buildDamageHit(ctx, t.id, r.damage, r.imbalanceDelta));
             ctx.api.addBuff(ctx.caster, t.id, "erosion");
             hits.push(buildBuffHit(ctx, t.id, "erosion"));
         }
@@ -120,9 +120,9 @@ const m18023Script = {
         // 若有侵蚀则额外伤害
         if (ctx.api.hasBuff(target.id, "erosion")) {
             const extraRatio = (ctx.levelParams.extraRatio ?? 15000) / 10000;
-            const dmg = ctx.api.damage(ctx.caster, target.id, Math.floor(self.stats.Att * extraRatio));
-            totalDamage += dmg;
-            hits.push(buildDamageHit(ctx, target.id, dmg));
+            const r = ctx.api.damage(ctx.caster, target.id, Math.floor(self.stats.Att * extraRatio));
+            totalDamage += r.damage;
+            hits.push(buildDamageHit(ctx, target.id, r.damage, r.imbalanceDelta));
         }
         return { ...buildEmptyResult(ctx, [target.id]), totalDamage, hits };
     }
@@ -141,11 +141,11 @@ const m18033Script = {
         const target = enemies[0];
         const hits = [];
         const ratio18033 = (ctx.levelParams.ratio ?? 3000) / 10000;
-        const dmg = ctx.api.damage(ctx.caster, target.id, Math.floor(self.stats.Att * ratio18033));
-        hits.push(buildDamageHit(ctx, target.id, dmg));
+        const r = ctx.api.damage(ctx.caster, target.id, Math.floor(self.stats.Att * ratio18033));
+        hits.push(buildDamageHit(ctx, target.id, r.damage, r.imbalanceDelta));
         ctx.api.addBuff(ctx.caster, target.id, "stun");
         hits.push(buildBuffHit(ctx, target.id, "stun"));
-        return { ...buildEmptyResult(ctx, [target.id]), totalDamage: dmg, hits };
+        return { ...buildEmptyResult(ctx, [target.id]), totalDamage: r.damage, hits };
     }
 };
 // ============================================================
@@ -159,13 +159,13 @@ const m18041Script = {
             return buildEmptyResult(ctx);
         const hits = [];
         let totalDamage = 0;
-        const dmg = ctx.api.damage(ctx.caster, targetId, Math.floor(self.stats.Att * 0.5));
-        totalDamage += dmg;
-        hits.push(buildDamageHit(ctx, targetId, dmg));
+        const r1 = ctx.api.damage(ctx.caster, targetId, Math.floor(self.stats.Att * 0.5));
+        totalDamage += r1.damage;
+        hits.push(buildDamageHit(ctx, targetId, r1.damage, r1.imbalanceDelta));
         if (ctx.api.hasBuff(targetId, "slow")) {
-            const extra = ctx.api.damage(ctx.caster, targetId, Math.floor(self.stats.Att * 0.5));
-            totalDamage += extra;
-            hits.push(buildDamageHit(ctx, targetId, extra));
+            const r2 = ctx.api.damage(ctx.caster, targetId, Math.floor(self.stats.Att * 0.5));
+            totalDamage += r2.damage;
+            hits.push(buildDamageHit(ctx, targetId, r2.damage, r2.imbalanceDelta));
         }
         return { ...buildEmptyResult(ctx, [targetId]), totalDamage, hits };
     }
@@ -205,9 +205,9 @@ const m18043Script = {
         let totalDamage = 0;
         const hits = [];
         for (const enemy of enemies) {
-            const dmg = ctx.api.damage(ctx.caster, enemy.id, Math.floor(self.stats.Att * 0.5));
-            totalDamage += dmg;
-            hits.push(buildDamageHit(ctx, enemy.id, dmg));
+            const r = ctx.api.damage(ctx.caster, enemy.id, Math.floor(self.stats.Att * 0.5));
+            totalDamage += r.damage;
+            hits.push(buildDamageHit(ctx, enemy.id, r.damage, r.imbalanceDelta));
             ctx.api.addBuff(ctx.caster, enemy.id, "slow");
             hits.push(buildBuffHit(ctx, enemy.id, "slow"));
         }
@@ -253,13 +253,13 @@ const m18062Script = {
         const target = enemies[0];
         let totalDamage = 0;
         const hits = [];
-        const dmg = ctx.api.damage(ctx.caster, target.id, Math.floor(self.stats.Att * 1.3));
-        totalDamage += dmg;
-        hits.push(buildDamageHit(ctx, target.id, dmg));
+        const r1 = ctx.api.damage(ctx.caster, target.id, Math.floor(self.stats.Att * 1.3));
+        totalDamage += r1.damage;
+        hits.push(buildDamageHit(ctx, target.id, r1.damage, r1.imbalanceDelta));
         if (ctx.api.hasBuff(target.id, "static")) {
-            const extra = ctx.api.damage(ctx.caster, target.id, Math.floor(self.stats.Att * 0.5));
-            totalDamage += extra;
-            hits.push(buildDamageHit(ctx, target.id, extra));
+            const r2 = ctx.api.damage(ctx.caster, target.id, Math.floor(self.stats.Att * 0.5));
+            totalDamage += r2.damage;
+            hits.push(buildDamageHit(ctx, target.id, r2.damage, r2.imbalanceDelta));
         }
         return { ...buildEmptyResult(ctx, [target.id]), totalDamage, hits };
     }
@@ -304,9 +304,9 @@ const m18072Script = {
                 // 引爆：立即结算1次风化DOT伤害
                 const dotDmg = Math.floor(enemy.stats.Att * 0.18 * stacks);
                 if (dotDmg > 0) {
-                    const dmg = ctx.api.damage(ctx.caster, enemy.id, dotDmg);
-                    totalDamage += dmg;
-                    hits.push(buildDamageHit(ctx, enemy.id, dmg));
+                    const r = ctx.api.damage(ctx.caster, enemy.id, dotDmg);
+                    totalDamage += r.damage;
+                    hits.push(buildDamageHit(ctx, enemy.id, r.damage, r.imbalanceDelta));
                 }
             }
         }

package/dist/battle/script/monsterScripts19xx.js

@@ -1,17 +1,17 @@
 function empty(ctx, targets = ctx.targets) {
     return { skillId: ctx.skillId, casterId: ctx.caster, targets, totalDamage: 0, totalHeal: 0, totalShield: 0, triggeredBy: ctx.trigger };
 }
-function dmgHit(ctx, tid, v) {
-    return { targetId: tid, effectType: "damage", element: ctx.api.getUnit(ctx.caster)?.element ?? "fire", skillType: "basic", isCritical: false, baseValue: v, criticalValue: v, finalValue: v, isRepression: 0, damageBreakdown: { preMitigation: v, postMitigation: v, shieldAbsorbed: 0, hpDamage: v } };
+function dmgHit(ctx, tid, v, ib, tib) {
+    return { targetId: tid, effectType: "damage", element: ctx.api.getUnit(ctx.caster)?.element ?? "fire", skillType: ctx.skillType, isCritical: false, baseValue: v, criticalValue: v, finalValue: v, isRepression: 0, imbalanceDelta: ib, triggeredImbalanceBreak: tib, damageBreakdown: { preMitigation: v, postMitigation: v, shieldAbsorbed: 0, hpDamage: v } };
 }
 function buffHit(ctx, tid, bid, r = false) {
-    return { targetId: tid, effectType: "buff", element: ctx.api.getUnit(ctx.caster)?.element ?? "fire", skillType: "basic", isCritical: false, baseValue: 0, criticalValue: 0, finalValue: 0, isRepression: 0, appliedBuffId: r ? undefined : bid, resisted: r };
+    return { targetId: tid, effectType: "buff", element: ctx.api.getUnit(ctx.caster)?.element ?? "fire", skillType: ctx.skillType, isCritical: false, baseValue: 0, criticalValue: 0, finalValue: 0, isRepression: 0, appliedBuffId: r ? undefined : bid, resisted: r };
 }
 function healHit(ctx, tid, v) {
-    return { targetId: tid, effectType: "heal", element: ctx.api.getUnit(ctx.caster)?.element ?? "fire", skillType: "basic", isCritical: false, baseValue: v, criticalValue: v, finalValue: v, isRepression: 0 };
+    return { targetId: tid, effectType: "heal", element: ctx.api.getUnit(ctx.caster)?.element ?? "fire", skillType: ctx.skillType, isCritical: false, baseValue: v, criticalValue: v, finalValue: v, isRepression: 0 };
 }
 function shieldHit(ctx, tid, v) {
-    return { targetId: tid, effectType: "shield", element: ctx.api.getUnit(ctx.caster)?.element ?? "fire", skillType: "basic", isCritical: false, baseValue: v, criticalValue: v, finalValue: v, isRepression: 0 };
+    return { targetId: tid, effectType: "shield", element: ctx.api.getUnit(ctx.caster)?.element ?? "fire", skillType: ctx.skillType, isCritical: false, baseValue: v, criticalValue: v, finalValue: v, isRepression: 0 };
 }
 // 19011 骨墩墩 普攻：80%火属性伤害+赋予自身【反击】(反击触发的普攻不赋予反击)
 const m19011Script = {
@@ -23,13 +23,13 @@ const m19011Script = {
         if (!tid)
             return empty(ctx);
         const hits = [];
-        const d = ctx.api.damage(ctx.caster, tid, Math.floor(self.stats.Att * 0.8));
-        hits.push(dmgHit(ctx, tid, d));
+        const r = ctx.api.damage(ctx.caster, tid, Math.floor(self.stats.Att * 0.8));
+        hits.push(dmgHit(ctx, tid, r.damage, r.imbalanceDelta));
         if (ctx.trigger !== "counter") {
             ctx.api.addBuff(ctx.caster, ctx.caster, "monster-counter-boss");
             hits.push(buffHit(ctx, ctx.caster, "monster-counter-boss"));
         }
-        return { ...empty(ctx, [tid]), totalDamage: d, hits };
+        return { ...empty(ctx, [tid]), totalDamage: r.damage, hits };
     }
 };
 // 19012 骨墩墩 技能1：召唤2只骨骨
@@ -144,9 +144,9 @@ const m19023Script = {
         let totalDamage = 0;
         const hits = [];
         for (const enemy of enemies) {
-            const d = ctx.api.damage(ctx.caster, enemy.id, Math.floor(self.stats.Att * (1.5 + bonusRatio)));
-            totalDamage += d;
-            hits.push(dmgHit(ctx, enemy.id, d));
+            const r = ctx.api.damage(ctx.caster, enemy.id, Math.floor(self.stats.Att * (1.5 + bonusRatio)));
+            totalDamage += r.damage;
+            hits.push(dmgHit(ctx, enemy.id, r.damage, r.imbalanceDelta));
             if (ctx.api.hasBuff(enemy.id, "slow")) {
                 ctx.api.adjustActionProgress(enemy.id, -0.3);
             }
@@ -199,9 +199,9 @@ const m19033Script = {
         const target = enemies[0];
         const hits = [];
         let totalDamage = 0;
-        const d = ctx.api.damage(ctx.caster, target.id, Math.floor(self.stats.Att * 2.2));
-        totalDamage += d;
-        hits.push(dmgHit(ctx, target.id, d));
+        const r = ctx.api.damage(ctx.caster, target.id, Math.floor(self.stats.Att * 2.2));
+        totalDamage += r.damage;
+        hits.push(dmgHit(ctx, target.id, r.damage, r.imbalanceDelta));
         // 检查5层静电 -> 直接死亡
         const staticBuffs = ctx.api.getBuffs(target.id).filter(b => b.id === "static");
         const staticStacks = staticBuffs.reduce((s, b) => s + b.stacks, 0);

package/dist/battle/script/monsterScripts19xxPart2.js

@@ -1,17 +1,17 @@
 function empty(ctx, targets = ctx.targets) {
     return { skillId: ctx.skillId, casterId: ctx.caster, targets, totalDamage: 0, totalHeal: 0, totalShield: 0, triggeredBy: ctx.trigger };
 }
-function dmgHit(ctx, tid, v) {
-    return { targetId: tid, effectType: "damage", element: ctx.api.getUnit(ctx.caster)?.element ?? "fire", skillType: "basic", isCritical: false, baseValue: v, criticalValue: v, finalValue: v, isRepression: 0, damageBreakdown: { preMitigation: v, postMitigation: v, shieldAbsorbed: 0, hpDamage: v } };
+function dmgHit(ctx, tid, v, ib, tib) {
+    return { targetId: tid, effectType: "damage", element: ctx.api.getUnit(ctx.caster)?.element ?? "fire", skillType: ctx.skillType, isCritical: false, baseValue: v, criticalValue: v, finalValue: v, isRepression: 0, imbalanceDelta: ib, triggeredImbalanceBreak: tib, damageBreakdown: { preMitigation: v, postMitigation: v, shieldAbsorbed: 0, hpDamage: v } };
 }
 function buffHit(ctx, tid, bid, r = false) {
-    return { targetId: tid, effectType: "buff", element: ctx.api.getUnit(ctx.caster)?.element ?? "fire", skillType: "basic", isCritical: false, baseValue: 0, criticalValue: 0, finalValue: 0, isRepression: 0, appliedBuffId: r ? undefined : bid, resisted: r };
+    return { targetId: tid, effectType: "buff", element: ctx.api.getUnit(ctx.caster)?.element ?? "fire", skillType: ctx.skillType, isCritical: false, baseValue: 0, criticalValue: 0, finalValue: 0, isRepression: 0, appliedBuffId: r ? undefined : bid, resisted: r };
 }
 function healHit(ctx, tid, v) {
-    return { targetId: tid, effectType: "heal", element: ctx.api.getUnit(ctx.caster)?.element ?? "fire", skillType: "basic", isCritical: false, baseValue: v, criticalValue: v, finalValue: v, isRepression: 0 };
+    return { targetId: tid, effectType: "heal", element: ctx.api.getUnit(ctx.caster)?.element ?? "fire", skillType: ctx.skillType, isCritical: false, baseValue: v, criticalValue: v, finalValue: v, isRepression: 0 };
 }
 function shieldHit(ctx, tid, v) {
-    return { targetId: tid, effectType: "shield", element: ctx.api.getUnit(ctx.caster)?.element ?? "fire", skillType: "basic", isCritical: false, baseValue: v, criticalValue: v, finalValue: v, isRepression: 0 };
+    return { targetId: tid, effectType: "shield", element: ctx.api.getUnit(ctx.caster)?.element ?? "fire", skillType: ctx.skillType, isCritical: false, baseValue: v, criticalValue: v, finalValue: v, isRepression: 0 };
 }
 // 19042 大风 技能1：对全体敌人造成50%风属性伤害，并消除敌人20%行动值持续2回合
 // (伤害由模板处理，这里处理行动值削减)
@@ -245,13 +245,13 @@ const m19071Script = {
             return empty(ctx);
         const hits = [];
         let totalDamage = 0;
-        const d1 = ctx.api.damage(ctx.caster, tid, Math.floor(self.stats.Att * 0.8));
-        totalDamage += d1;
-        hits.push(dmgHit(ctx, tid, d1));
+        const r1 = ctx.api.damage(ctx.caster, tid, Math.floor(self.stats.Att * 0.8));
+        totalDamage += r1.damage;
+        hits.push(dmgHit(ctx, tid, r1.damage, r1.imbalanceDelta));
         // 附加防御力50%额外伤害
-        const d2 = ctx.api.damage(ctx.caster, tid, Math.floor(self.stats.Def * 0.5));
-        totalDamage += d2;
-        hits.push(dmgHit(ctx, tid, d2));
+        const r2 = ctx.api.damage(ctx.caster, tid, Math.floor(self.stats.Def * 0.5));
+        totalDamage += r2.damage;
+        hits.push(dmgHit(ctx, tid, r2.damage, r2.imbalanceDelta));
         return { ...empty(ctx, [tid]), totalDamage, hits };
     }
 };
@@ -287,9 +287,9 @@ const m19073Script = {
             const enemies = ctx.api.getAliveUnits().filter(u => u.teamId !== self.teamId);
             for (const enemy of enemies) {
                 // 额外200%伤害(模板已有150%，这里补充额外的300%总计)
-                const d = ctx.api.damage(ctx.caster, enemy.id, Math.floor(self.stats.Att * 3.0));
-                totalDamage += d;
-                hits.push(dmgHit(ctx, enemy.id, d));
+                const r = ctx.api.damage(ctx.caster, enemy.id, Math.floor(self.stats.Att * 3.0));
+                totalDamage += r.damage;
+                hits.push(dmgHit(ctx, enemy.id, r.damage, r.imbalanceDelta));
                 ctx.api.addBuff(ctx.caster, enemy.id, "stun");
                 hits.push(buffHit(ctx, enemy.id, "stun"));
             }

package/dist/battle/script/sampleScripts.d.ts

@@ -0,0 +1,28 @@
+import type { ISkillScript } from "../types";
+/**
+ * 导出所有示例脚本
+ */
+export declare const sampleUpgradeScripts: Record<string, ISkillScript>;
+/**
+ * 使用示例：
+ *
+ * // 在初始化战斗单位时，配置技能等级和参数
+ * const skill: SkillDefinition = {
+ *   id: "hero.skill.1",
+ *   mode: "script",
+ *   type: "core",
+ *   scriptId: "sample.upgradable.damage",
+ *   energyCost: 30,
+ *   energyGain: 0,
+ *   cooldown: 2,
+ *   targetRule: "nearest",
+ *   element: "fire",
+ *   level: 3 as const, // 技能等级 3
+ *   levelParams: {
+ *     baseRatio: 0.5,      // 基础系数 50%
+ *     ratioPerLevel: 0.08  // 每级+8%
+ *   }
+ * };
+ *
+ * // 等级3的实际系数 = 0.5 + (3-1) * 0.08 = 0.66 = 66%
+ */

package/dist/battle/script/sampleScripts.js

@@ -0,0 +1,223 @@
+/**
+ * 示例：支持技能升级的手写技能脚本
+ *
+ * 升级方案：
+ * - 基础伤害系数随等级提升
+ * - levelParams 中可配置额外参数
+ */
+const upgradableDamageSkill = {
+    onCast(ctx) {
+        const { level, levelParams } = ctx;
+        const self = ctx.api.getUnit(ctx.caster);
+        if (!self || ctx.targets.length === 0) {
+            return {
+                skillId: ctx.skillId,
+                casterId: ctx.caster,
+                targets: [],
+                totalDamage: 0,
+                totalHeal: 0,
+                totalShield: 0,
+                triggeredBy: ctx.trigger
+            };
+        }
+        // 基础系数 + 每级成长
+        const baseRatio = levelParams.baseRatio ?? 0.5;
+        const ratioPerLevel = levelParams.ratioPerLevel ?? 0.05;
+        const currentRatio = baseRatio + (level - 1) * ratioPerLevel;
+        // 计算伤害
+        const damage = Math.floor(self.stats.Att * currentRatio);
+        let totalDamage = 0;
+        for (const targetId of ctx.targets) {
+            const r = ctx.api.damage(ctx.caster, targetId, damage);
+            totalDamage += r.damage;
+        }
+        return {
+            skillId: ctx.skillId,
+            casterId: ctx.caster,
+            targets: ctx.targets,
+            totalDamage,
+            totalHeal: 0,
+            totalShield: 0,
+            triggeredBy: ctx.trigger
+        };
+    }
+};
+/**
+ * 示例：护盾技能，护盾值随等级提升
+ */
+const upgradableShieldSkill = {
+    onCast(ctx) {
+        const { level, levelParams } = ctx;
+        const self = ctx.api.getUnit(ctx.caster);
+        if (!self) {
+            return {
+                skillId: ctx.skillId,
+                casterId: ctx.caster,
+                targets: [],
+                totalDamage: 0,
+                totalHeal: 0,
+                totalShield: 0,
+                triggeredBy: ctx.trigger
+            };
+        }
+        // 护盾基础值 + 等级加成
+        const baseShield = levelParams.baseShield ?? 100;
+        const shieldPerLevel = levelParams.shieldPerLevel ?? 20;
+        const shieldValue = baseShield + (level - 1) * shieldPerLevel;
+        // 可以基于防御力缩放
+        const defRatio = levelParams.defRatio ?? 0.3;
+        const finalShield = Math.floor(self.stats.Def * defRatio + shieldValue);
+        const totalShield = ctx.api.shield(ctx.caster, finalShield);
+        return {
+            skillId: ctx.skillId,
+            casterId: ctx.caster,
+            targets: [ctx.caster],
+            totalDamage: 0,
+            totalHeal: 0,
+            totalShield,
+            triggeredBy: ctx.trigger
+        };
+    }
+};
+/**
+ * 示例：治疗技能，治疗量随等级提升
+ */
+const upgradableHealSkill = {
+    onCast(ctx) {
+        const { level, levelParams } = ctx;
+        const self = ctx.api.getUnit(ctx.caster);
+        if (!self || ctx.targets.length === 0) {
+            return {
+                skillId: ctx.skillId,
+                casterId: ctx.caster,
+                targets: [],
+                totalDamage: 0,
+                totalHeal: 0,
+                totalShield: 0,
+                triggeredBy: ctx.trigger
+            };
+        }
+        // 治疗基础值 + 等级加成
+        const baseHeal = levelParams.baseHeal ?? 50;
+        const healPerLevel = levelParams.healPerLevel ?? 10;
+        const healValue = baseHeal + (level - 1) * healPerLevel;
+        // 基于攻击力缩放
+        const attRatio = levelParams.attRatio ?? 0.2;
+        const finalHeal = Math.floor(self.stats.Att * attRatio + healValue);
+        let totalHeal = 0;
+        for (const targetId of ctx.targets) {
+            totalHeal += ctx.api.heal(targetId, finalHeal);
+        }
+        return {
+            skillId: ctx.skillId,
+            casterId: ctx.caster,
+            targets: ctx.targets,
+            totalDamage: 0,
+            totalHeal,
+            totalShield: 0,
+            triggeredBy: ctx.trigger
+        };
+    }
+};
+/**
+ * 示例：多段伤害技能，段数或伤害随等级提升
+ */
+const upgradableMultiHitSkill = {
+    onCast(ctx) {
+        const { level, levelParams } = ctx;
+        const self = ctx.api.getUnit(ctx.caster);
+        if (!self || ctx.targets.length === 0) {
+            return {
+                skillId: ctx.skillId,
+                casterId: ctx.caster,
+                targets: [],
+                totalDamage: 0,
+                totalHeal: 0,
+                totalShield: 0,
+                triggeredBy: ctx.trigger
+            };
+        }
+        // 基础段数 + 等级解锁额外段数
+        const baseHits = levelParams.baseHits ?? 2;
+        const bonusHitsAtLevel = levelParams.bonusHitsAtLevel ?? 5;
+        const totalHits = level >= bonusHitsAtLevel ? baseHits + 1 : baseHits;
+        // 每段伤害系数
+        const hitRatio = levelParams.hitRatio ?? 0.3;
+        const hitDamage = Math.floor(self.stats.Att * hitRatio);
+        let totalDamage = 0;
+        const targetId = ctx.targets[0];
+        for (let i = 0; i < totalHits; i++) {
+            const r = ctx.api.damage(ctx.caster, targetId, hitDamage);
+            totalDamage += r.damage;
+        }
+        return {
+            skillId: ctx.skillId,
+            casterId: ctx.caster,
+            targets: ctx.targets,
+            totalDamage,
+            totalHeal: 0,
+            totalShield: 0,
+            triggeredBy: ctx.trigger
+        };
+    }
+};
+/**
+ * 示例：Debuff 技能，概率随等级提升
+ */
+const upgradableDebuffSkill = {
+    onCast(ctx) {
+        const { level, levelParams } = ctx;
+        // 基础概率 + 等级加成
+        const baseProb = levelParams.baseProb ?? 0.5; // 50%
+        const probPerLevel = levelParams.probPerLevel ?? 0.05; // 每级+5%
+        const applyChance = Math.min(1, baseProb + (level - 1) * probPerLevel);
+        // levelParams 仅支持 number，Debuff 类型固定为 slow
+        const buffId = "slow";
+        for (const targetId of ctx.targets) {
+            // 假设概率判定通过
+            ctx.api.addBuff(ctx.caster, targetId, buffId);
+        }
+        return {
+            skillId: ctx.skillId,
+            casterId: ctx.caster,
+            targets: ctx.targets,
+            totalDamage: 0,
+            totalHeal: 0,
+            totalShield: 0,
+            triggeredBy: ctx.trigger
+        };
+    }
+};
+/**
+ * 导出所有示例脚本
+ */
+export const sampleUpgradeScripts = {
+    "sample.upgradable.damage": upgradableDamageSkill,
+    "sample.upgradable.shield": upgradableShieldSkill,
+    "sample.upgradable.heal": upgradableHealSkill,
+    "sample.upgradable.multihit": upgradableMultiHitSkill,
+    "sample.upgradable.debuff": upgradableDebuffSkill
+};
+/**
+ * 使用示例：
+ *
+ * // 在初始化战斗单位时，配置技能等级和参数
+ * const skill: SkillDefinition = {
+ *   id: "hero.skill.1",
+ *   mode: "script",
+ *   type: "core",
+ *   scriptId: "sample.upgradable.damage",
+ *   energyCost: 30,
+ *   energyGain: 0,
+ *   cooldown: 2,
+ *   targetRule: "nearest",
+ *   element: "fire",
+ *   level: 3 as const, // 技能等级 3
+ *   levelParams: {
+ *     baseRatio: 0.5,      // 基础系数 50%
+ *     ratioPerLevel: 0.08  // 每级+8%
+ *   }
+ * };
+ *
+ * // 等级3的实际系数 = 0.5 + (3-1) * 0.08 = 0.66 = 66%
+ */

package/dist/battle/skillEngine.d.ts

@@ -1,9 +1,14 @@
 import type { BattleScriptApi, ElementType, ISkillScript, ScriptRuntimeContext, SkillDefinition, SkillResult, SkillTemplate, TriggerContext, UnitModel } from "./types";
 import { SeedRng } from "./random";
+interface ApplyDamageResult {
+    damage: number;
+    imbalanceDelta: number;
+    triggeredImbalanceBreak: boolean;
+}
 interface SkillEngineDeps {
     rng: SeedRng;
     getUnits: () => UnitModel[];
-    applyDamage: (sourceId: string, targetId: string, value: number, staggerElement?: ElementType) => number;
+    applyDamage: (sourceId: string, targetId: string, value: number, staggerElement?: ElementType) => ApplyDamageResult;
     applyHeal: (targetId: string, value: number) => number;
     applyShield: (targetId: string, value: number) => number;
     applyBuff: (sourceId: string, targetId: string, buffId: string) => void;
@@ -32,5 +37,6 @@ export declare class SkillExecutor {
     private readonly scriptEngine;
     constructor(configEngine: ConfigSkillEngine, scriptEngine: ScriptSkillEngine);
     execute(skill: SkillDefinition, caster: UnitModel, deps: SkillEngineDeps, trigger: SkillResult["triggeredBy"], triggerCtx?: TriggerContext, selectedTargetsOverride?: UnitModel[]): SkillResult;
+    private linkBuffHitsToDamage;
 }
 export {};

package/dist/battle/skillEngine.js

@@ -1,13 +1,13 @@
 import { calcDamage, calcEffectProbability, calcHealOrShield } from "./formula";
 import { selectTargets } from "./targeting";
 export class ScriptSkillEngine {
-    scripts = new Map();
+    scripts = new Map(); // 存储已注册的技能脚本
     registerScript(scriptId, script) {
         this.scripts.set(scriptId, script);
     }
     cast(scriptId, ctx) {
-        const script = this.scripts.get(scriptId);
-        if (!script) {
+        const script = this.scripts.get(scriptId); // 获取技能脚本
+        if (!script) { // 如果技能脚本不存在
             return {
                 skillId: ctx.skillId,
                 casterId: ctx.caster,
@@ -103,7 +103,10 @@ export class ConfigSkillEngine {
                     if (step.kind === "damage") {
                         const shieldBefore = target.runtime.Shield;
                         const damageRes = calcDamage({ ...caster, stats: effectiveCaster }, { ...target, stats: effectiveTarget }, raw, skill.type, skill.element, deps.rng);
-                        const done = deps.applyDamage(caster.id, target.id, damageRes.finalDam, skill.element);
+                        const applyResult = deps.applyDamage(caster.id, target.id, damageRes.finalDam, skill.element);
+                        const done = applyResult.damage;
+                        const imbalanceDelta = applyResult.imbalanceDelta;
+                        const triggeredImbalanceBreak = applyResult.triggeredImbalanceBreak;
                         const shieldAbsorbed = Math.min(shieldBefore, damageRes.finalDam);
                         totalDamage += done;
                         hits.push({
@@ -116,6 +119,8 @@ export class ConfigSkillEngine {
                             criticalValue: damageRes.critDam,
                             finalValue: done,
                             isRepression: damageRes.isRepression,
+                            imbalanceDelta,
+                            triggeredImbalanceBreak: triggeredImbalanceBreak || undefined,
                             damageBreakdown: {
                                 preMitigation: raw,
                                 postMitigation: damageRes.finalDam,
@@ -219,6 +224,7 @@ export class SkillExecutor {
                 caster: caster.id,
                 targets: result.targets,
                 skillId: skill.id,
+                skillType: skill.type,
                 trigger,
                 triggerContext: triggerCtx,
                 api: deps.createScriptApi(skill.element),
@@ -241,6 +247,35 @@ export class SkillExecutor {
         if (triggerCtx && result.targets.length === 0) {
             result.targets = [...triggerCtx.sourceTargets];
         }
+        if (result.hits && result.hits.length > 0) {
+            this.linkBuffHitsToDamage(result.hits);
+        }
         return result;
     }
+    linkBuffHitsToDamage(hits) {
+        const latestDamageIndexByTarget = new Map();
+        for (let i = 0; i < hits.length; i++) {
+            const hit = hits[i];
+            hit.hitIndex = i;
+            if (hit.effectType === "damage") {
+                hit.triggeredBuffHitIndices = undefined;
+                latestDamageIndexByTarget.set(hit.targetId, i);
+                continue;
+            }
+            if (hit.effectType !== "buff") {
+                continue;
+            }
+            const sourceIndex = latestDamageIndexByTarget.get(hit.targetId);
+            if (sourceIndex !== undefined) {
+                hit.sourceDamageHitIndex = sourceIndex;
+                const sourceDamageHit = hits[sourceIndex];
+                if (sourceDamageHit.effectType === "damage") {
+                    if (!sourceDamageHit.triggeredBuffHitIndices) {
+                        sourceDamageHit.triggeredBuffHitIndices = [];
+                    }
+                    sourceDamageHit.triggeredBuffHitIndices.push(i);
+                }
+            }
+        }
+    }
 }

package/dist/battle/types.d.ts

@@ -142,6 +142,7 @@ export interface SkillTemplateStep {
     fixedProbByLevel?: number[];
     canCrit?: boolean;
     scaleStat?: "Att" | "Def" | "Mhp";
+    scaleStatByLevel?: number[];
     flat?: number;
     flatByLevel?: number[];
     repeat?: number;
@@ -162,6 +163,8 @@ export interface SkillResult {
     hits?: SkillHitDetail[];
 }
 export interface SkillHitDetail {
+    /** 当前hit在SkillResult.hits中的索引位置 */
+    hitIndex?: number;
     targetId: UnitId;
     effectType: "damage" | "heal" | "shield" | "buff";
     element: ElementType;
@@ -173,6 +176,19 @@ export interface SkillHitDetail {
     isRepression: -1 | 0 | 1;
     appliedBuffId?: string;
     resisted?: boolean;
+    /** 本次hit造成的失衡值变化 */
+    imbalanceDelta?: number;
+    /** 本次hit是否触发了失衡破击 */
+    triggeredImbalanceBreak?: boolean;
+    /**
+     * 当effectType=buff时，若由同一次技能中的某个damage hit触发，
+     * 则记录该damage hit在SkillResult.hits中的索引
+     */
+    sourceDamageHitIndex?: number;
+    /**
+     * 当effectType=damage时，记录由该damage触发的buff hit索引列表
+     */
+    triggeredBuffHitIndices?: number[];
     damageBreakdown?: {
         preMitigation: number;
         postMitigation: number;
@@ -260,6 +276,7 @@ export interface ScriptRuntimeContext {
     caster: UnitId;
     targets: UnitId[];
     skillId: string;
+    skillType: SkillType;
     trigger: SkillResult["triggeredBy"];
     api: BattleScriptApi;
     triggerContext?: TriggerContext;
@@ -268,8 +285,13 @@ export interface ScriptRuntimeContext {
     /** 技能升级参数 */
     levelParams: Record<string, number>;
 }
+export interface DamageResult {
+    damage: number;
+    imbalanceDelta: number;
+    triggeredImbalanceBreak: boolean;
+}
 export interface BattleScriptApi {
-    damage(sourceId: UnitId, targetId: UnitId, value: number): number;
+    damage(sourceId: UnitId, targetId: UnitId, value: number): DamageResult;
     heal(targetId: UnitId, value: number): number;
     shield(targetId: UnitId, value: number): number;
     adjustImbalance(targetId: UnitId, delta: number): number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hrbattle",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "一个基于回合制战斗引擎，支持技能脚本、buff系统和效果解析。",
   "type": "module",
   "main": "dist/index.js",