docs: 为游戏地图模块添加详细的代码注释

为游戏地图模块的脚本文件添加全面的注释，说明每个组件的职责、关键设计、依赖关系和使用方式。注释覆盖了英雄信息面板、技能卡槽位管理器、排行榜弹窗、卡牌控制器、背景滚动组件等核心功能模块，提高了代码的可读性和维护性。

同时修复了英雄预制体的激活状态和技能效果预制体的尺寸参数。

assets/script/game/map/MissSkillsComp.ts

@@ -1,3 +1,25 @@
+/**
+ * @file MissSkillsComp.ts
+ * @description 场上技能卡槽位管理器组件（UI 视图层）
+ *
+ * 职责：
+ *   1. 管理场上已使用的 **技能卡** 的可视化槽位（最多 10 个）。
+ *   2. 监听 UseSkillCard 事件，当玩家使用技能卡时实例化 SkillBoxComp 并放入空闲槽位。
+ *   3. 监听 RemoveSkillBox 事件，当技能生效完毕后回收槽位并重新排列。
+ *
+ * 关键设计：
+ *   - slots 数组预定义了 10 个固定坐标位（2 行 × 5 列），
+ *     每个槽位记录是否占用及对应节点引用。
+ *   - 当某个 SkillBox 销毁时，触发 rearrangeSlots 将剩余节点
+ *     紧凑地重排到前置槽位，避免视觉空洞。
+ *   - SkillBox 的实例化使用 skill_box Prefab，在编辑器中绑定。
+ *
+ * 依赖：
+ *   - SkillBoxComp（SkillBoxComp.ts）—— 单个技能卡的效果控制组件
+ *   - GameEvent.UseSkillCard —— 技能卡使用事件
+ *   - GameEvent.RemoveSkillBox —— 技能卡移除事件
+ *   - smc.map.MapView.scene.entityLayer —— 技能节点的父容器（SKILL 节点）
+ */
 import { mLogger } from "../common/Logger";
 import { _decorator, Node, Prefab, instantiate, Vec3 } from "cc";
 import { ecs } from "../../../../extensions/oops-plugin-framework/assets/libs/ecs/ECS";
@@ -8,21 +30,39 @@ import { GameEvent } from "../common/config/GameEvent";
 import { smc } from "../common/SingletonModuleComp";
 const { ccclass, property } = _decorator;
 
+/** 技能槽位数据结构 */
 interface SkillBoxSlot {
+    /** 该槽位的固定 X 坐标 */
     x: number;
+    /** 该槽位的固定 Y 坐标 */
     y: number;
+    /** 是否已被占用 */
     used: boolean;
+    /** 占用该槽位的节点引用 */
     node: Node | null;
 }
 
-/** 视图层对象 */
+/**
+ * MissSkillsComp —— 场上技能卡槽位管理器
+ *
+ * 在战斗场景中管理已激活的技能卡显示位置。
+ * 2 行 × 5 列 = 10 个槽位，不足时提示已满。
+ */
 @ccclass('MissSkillsComp')
 @ecs.register('MissSkillsComp', false)
 export class MissSkillsComp extends CCComp {
+    /** 调试日志开关 */
     private debugMode: boolean = true;
+
+    /** 技能卡 Prefab（在编辑器中赋值） */
     @property({type: Prefab})
     private skill_box: Prefab = null;
 
+    /**
+     * 预定义的 10 个槽位坐标（2 行 × 5 列）：
+     * 第 1 行 y=240：x = -320, -240, -160, -80, 0
+     * 第 2 行 y=320：x = -320, -240, -160, -80, 0
+     */
     private slots: SkillBoxSlot[] = [
         { x: -320, y: 240, used: false, node: null },
         { x: -240, y: 240, used: false, node: null },
@@ -36,16 +76,26 @@ export class MissSkillsComp extends CCComp {
         { x: 0,    y: 320, used: false, node: null },
     ];
 
+    /** 注册事件监听 */
     onLoad() {
         oops.message.on(GameEvent.UseSkillCard, this.onUseSkillCard, this);
         oops.message.on(GameEvent.RemoveSkillBox, this.onRemoveSkillBox, this);
     }
 
+    /** 移除事件监听 */
     onDestroy() {
         oops.message.off(GameEvent.UseSkillCard, this.onUseSkillCard, this);
         oops.message.off(GameEvent.RemoveSkillBox, this.onRemoveSkillBox, this);
     }
 
+    /**
+     * 处理技能卡移除事件：
+     *   1. 在 slots 中找到对应节点并释放。
+     *   2. 调用 rearrangeSlots 紧凑重排。
+     *
+     * @param event  事件名
+     * @param args   要移除的节点引用
+     */
     private onRemoveSkillBox(event: string, args: any) {
         const node = args as Node;
         let removed = false;
@@ -62,7 +112,12 @@ export class MissSkillsComp extends CCComp {
         }
     }
 
+    /**
+     * 紧凑重排：将所有有效节点按顺序移到前置槽位。
+     * 确保视觉上不会出现中间空洞。
+     */
     private rearrangeSlots() {
+        // 收集所有有效节点
         const validNodes: Node[] = [];
         for (let i = 0; i < this.slots.length; i++) {
             if (this.slots[i].used && this.slots[i].node && this.slots[i].node.isValid) {
@@ -71,7 +126,7 @@ export class MissSkillsComp extends CCComp {
             this.slots[i].used = false;
             this.slots[i].node = null;
         }
-        
+        // 按顺序重新分配
         for (let i = 0; i < validNodes.length; i++) {
             if (i < this.slots.length) {
                 this.slots[i].used = true;
@@ -81,6 +136,11 @@ export class MissSkillsComp extends CCComp {
         }
     }
 
+    /**
+     * 处理使用技能卡事件：提取 uuid 和 card_lv 后调用 addSkill。
+     * @param event  事件名
+     * @param args   卡牌数据（含 uuid、card_lv）
+     */
     private onUseSkillCard(event: string, args: any) {
         const payload = args ?? event;
         const uuid = Number(payload?.uuid ?? 0);
@@ -93,7 +153,17 @@ export class MissSkillsComp extends CCComp {
         
     }
 
+    /**
+     * 在场上添加一个技能卡：
+     *   1. 在 slots 中查找空闲位。
+     *   2. 实例化 skill_box Prefab 并放置在空闲位坐标。
+     *   3. 获取或添加 SkillBoxComp 并初始化。
+     *
+     * @param uuid     技能 UUID
+     * @param card_lv  技能卡等级
+     */
     addSkill(uuid: number, card_lv: number) {
+        // 技能节点的父容器
         var parent = smc.map.MapView.scene.entityLayer!.node!.getChildByName("SKILL")!;
         
         if (!this.skill_box) {
@@ -101,12 +171,14 @@ export class MissSkillsComp extends CCComp {
             return;
         }
 
+        // 查找空闲槽位
         const emptyIndex = this.slots.findIndex(slot => !slot.used);
         if (emptyIndex === -1) {
             mLogger.warn(this.debugMode, "MissSkillsComp", "skill_box slots are full");
             return;
         }
 
+        // 实例化并放入槽位
         const node = instantiate(this.skill_box);
         node.parent = parent;
         node.setPosition(new Vec3(this.slots[emptyIndex].x, this.slots[emptyIndex].y, 0));
@@ -114,11 +186,12 @@ export class MissSkillsComp extends CCComp {
         this.slots[emptyIndex].used = true;
         this.slots[emptyIndex].node = node;
 
+        // 初始化技能效果组件
         const comp = node.getComponent(SkillBoxComp) || node.addComponent(SkillBoxComp);
         comp.init(uuid, card_lv);
     }
 
-    /** 视图对象通过 ecs.Entity.remove(ModuleViewComp) 删除组件是触发组件处理自定义释放逻辑 */
+    /** ECS 组件移除时销毁节点 */
     reset() {
         this.node.destroy();
     }