docs(game): 为英雄合成系统添加详细注释

为 MissionHeroComp 组件中的关键属性和方法添加 JSDoc 注释，以提升代码可读性和维护性。注释涵盖了英雄召唤队列、合成规则、链式合成流程以及事件监听管理等核心逻辑，便于后续开发者理解系统行为。

assets/script/game/map/MissionHeroComp.ts

@@ -16,25 +16,39 @@ const { ccclass } = _decorator;
 @ccclass('MissionHeroCompComp')
 @ecs.register('MissionHeroComp', false)
 export class MissionHeroCompComp extends CCComp {
+    /** 英雄出生时的掉落高度，用于表现从空中落地 */
     private static readonly HERO_DROP_HEIGHT = 260
+    /** 预留计时器 */
     timer:Timer=new Timer(2)
+    /** 预留状态：友方是否全部死亡 */
     Friend_is_dead:boolean=false
+    /** 当前处理的英雄 uuid */
     current_hero_uuid:number=0
+    /** 当前英雄数量缓存 */
     current_hero_num:number=-1
+    /** 合成规则：2 合 1 或 3 合 1 */
     merge_need_count:number=2
+    /** 允许合成的最高等级 */
     merge_max_lv:number=3
+    /** 是否正在执行一次合成流程 */
     is_merging:boolean=false
+    /** 是否正在消费召唤队列，防止并发处理 */
     is_processing_queue:boolean=false
+    /** 召唤请求队列，保证召唤与合成串行 */
     summon_queue:{ uuid: number; hero_lv: number }[]=[]
+    /** 预留英雄列表 */
     heros:any=[]
     onLoad(){
+        /** 节点事件监听 */
         this.on(GameEvent.FightReady,this.fight_ready,this)
         this.on(GameEvent.Zhaohuan,this.zhao_huan,this)
         this.on(GameEvent.MissionEnd,this.clear_heros,this)
+        /** 全局消息监听 */
         oops.message.on(GameEvent.CallHero,this.call_hero,this)
     }
 
     onDestroy(){
+        /** 清理监听，避免节点销毁后仍响应消息 */
         oops.message.off(GameEvent.CallHero,this.call_hero,this)
         oops.message.off(GameEvent.FightReady,this.fight_ready,this)
         oops.message.off(GameEvent.Zhaohuan,this.zhao_huan,this)
@@ -44,12 +58,14 @@ export class MissionHeroCompComp extends CCComp {
     start() {
         // this.test_call()
     }
+    /** 关卡结束时，清理全部存活英雄 */
     clear_heros(){
         const heroes = this.getAliveHeroes();
         for (let i = 0; i < heroes.length; i++) {
             heroes[i].destroy();
         }
     }
+    /** 战斗准备阶段重置出战英雄计数 */
     fight_ready(){
         smc.vmdata.mission_data.hero_num=0
     }
@@ -57,17 +73,19 @@ export class MissionHeroCompComp extends CCComp {
 
     // }
 
+    /** 预留：召唤事件扩展入口 */
     private zhao_huan(event: string, args: any){
 
     }
 
+    /** 召唤请求入口：归一化参数并进入串行队列 */
     private async call_hero(event: string, args: any){
         const uuid = Number(args?.uuid ?? 1001);
         const hero_lv = Math.max(1, Number(args?.hero_lv ?? 1));
         this.summon_queue.push({ uuid, hero_lv });
         this.processSummonQueue();
     }
-       /** 添加英雄 */
+    /** 添加英雄：固定出生点上方生成，再落至落点 */
     private addHero(uuid:number=1001,hero_lv:number=1) {
         console.log("addHero uuid:",uuid)
         let hero_pos=0
@@ -79,6 +97,7 @@ export class MissionHeroCompComp extends CCComp {
         return hero;
     }
 
+    /** 添加合成后的新英雄，并覆盖为聚合后的属性 */
     private addMergedHero(uuid:number, hero_lv:number, ap:number, hp_max:number): number {
         const hero = this.addHero(uuid, hero_lv);
         const model = hero.get(HeroAttrsComp);
@@ -90,6 +109,7 @@ export class MissionHeroCompComp extends CCComp {
         return model.lv;
     }
 
+    /** 获取当前全部存活友方英雄 */
     private getAliveHeroes(): Hero[] {
         const heroes: Hero[] = [];
         ecs.query(ecs.allOf(HeroAttrsComp)).forEach((entity: ecs.Entity) => {
@@ -102,6 +122,7 @@ export class MissionHeroCompComp extends CCComp {
         return heroes;
     }
 
+    /** 挑选可参与本次合成的英雄组 */
     private pickMergeHeroes(aliveHeroes: Hero[], uuid: number, hero_lv: number, needCount: number = 3): Hero[] {
         const mergeHeroes: Hero[] = [];
         for (let i = 0; i < aliveHeroes.length; i++) {
@@ -115,6 +136,7 @@ export class MissionHeroCompComp extends CCComp {
         return mergeHeroes;
     }
 
+    /** 统计满足同 uuid、同等级的可合成英雄数量 */
     private countMergeHeroes(aliveHeroes: Hero[], uuid: number, hero_lv: number): number {
         let count = 0;
         for (let i = 0; i < aliveHeroes.length; i++) {
@@ -127,14 +149,17 @@ export class MissionHeroCompComp extends CCComp {
         return count;
     }
 
+    /** 读取当前合成需要数量，仅支持 2 或 3 */
     private getMergeNeedCount(): number {
         return this.merge_need_count === 2 ? 2 : 3;
     }
 
+    /** 判断该等级是否还能继续向上合成 */
     private canMergeLevel(hero_lv: number): boolean {
         return hero_lv < Math.max(1, this.merge_max_lv);
     }
 
+    /** 串行消费召唤队列，避免同帧并发触发多次合成导致状态错乱 */
     private async processSummonQueue() {
         if (this.is_processing_queue) return;
         this.is_processing_queue = true;
@@ -149,6 +174,7 @@ export class MissionHeroCompComp extends CCComp {
         }
     }
 
+    /** 处理单次召唤：先生成，再检测是否触发合成，再尝试链式合成 */
     private async handleSingleSummon(uuid: number, hero_lv: number) {
         this.addHero(uuid, hero_lv);
         if (!this.canMergeLevel(hero_lv)) return;
@@ -165,6 +191,7 @@ export class MissionHeroCompComp extends CCComp {
         }
     }
 
+    /** 将一组合成素材向出生点汇聚并销毁，全部完成后返回 */
     private mergeDestroyAtBirth(mergeHeroes: Hero[], spawnPos: Vec3): Promise<void> {
         return new Promise((resolve) => {
             let doneCount = 0;
@@ -185,6 +212,7 @@ export class MissionHeroCompComp extends CCComp {
         });
     }
 
+    /** 播放合成爆点特效，使用 oneCom 控制特效生命周期 */
     private playMergeBoomFx(worldPos: Vec3): Promise<void> {
         return new Promise((resolve) => {
             const scene = smc.map?.MapView?.scene;
@@ -210,6 +238,7 @@ export class MissionHeroCompComp extends CCComp {
         });
     }
 
+    /** 执行一次完整合成：聚合属性、销毁素材、播放特效、生成高一级英雄 */
     private async mergeGroupHeroes(mergeHeroes: Hero[], uuid: number, hero_lv: number): Promise<number> {
         let sumAp = 0;
         let sumHpMax = 0;
@@ -227,6 +256,7 @@ export class MissionHeroCompComp extends CCComp {
         return this.addMergedHero(uuid, Math.min(this.merge_max_lv, hero_lv + 1), sumAp, sumHpMax);
     }
 
+    /** 链式合成：当前等级合成完成后，继续尝试更高等级，直到条件不满足 */
     private async tryChainMerge(uuid: number, startLv: number) {
         let checkLv = Math.max(1, startLv);
         const needCount = this.getMergeNeedCount();
@@ -252,7 +282,7 @@ export class MissionHeroCompComp extends CCComp {
 
 
     
-    /** 视图对象通过 ecs.Entity.remove(ModuleViewComp) 删除组件是触发组件处理自定义释放逻辑 */
+    /** 视图对象通过 ecs.Entity.remove(ModuleViewComp) 删除组件时触发，用于自定义释放逻辑 */
     reset() {
         // this.node.destroy();
     }