feat: 新增英雄召唤事件并优化UI布局与组件注释

- 在 MissionHeroComp 中召唤英雄后派发 MasterCalled 事件，以更新英雄信息面板
- 调整 hnode.prefab 中多个节点的位置和尺寸，优化界面布局
- 为多个 TypeScript 组件文件添加详细注释，说明职责、关键设计和依赖关系
- 在 MissionCardComp 中完善英雄信息面板的创建、排序和布局逻辑

assets/script/game/map/view/map/layer/EntityLayer.ts

@@ -1,3 +1,21 @@
+/**
+ * @file EntityLayer.ts
+ * @description 实体图层组件（场景显示层）
+ *
+ * 职责：
+ *   1. 作为所有游戏实体（英雄、怪物）的 **父容器节点**。
+ *   2. 预留深度排序逻辑（当前已注释，按 Y 坐标排序子节点渲染顺序）。
+ *   3. 提供 clear() 方法清除所有子节点（用于场景重置）。
+ *
+ * 关键设计：
+ *   - 使用 Timer（0.2 秒间隔）降频排序，避免每帧排序导致性能问题。
+ *   - 深度排序按 Y 坐标从大到小（Y 越小渲染越靠前），
+ *     模拟 2D 俯视角的遮挡关系。
+ *   - 如果后续切换为全 3D 渲染，则不需要 2D 深度排序。
+ *
+ * 依赖：
+ *   - Timer（oops-framework）—— 降频计时器
+ */
 /*
  * @Author: dgflash
  * @Date: 2022-08-04 15:22:33
@@ -10,17 +28,26 @@ import { Timer } from '../../../../../../../extensions/oops-plugin-framework/ass
 const { ccclass, property } = _decorator;
 
 /**
- * 物体层
+ * EntityLayer —— 实体图层
+ *
+ * 所有英雄和怪物节点的父容器，预留深度排序功能。
+ *
  * 注：
- * 1、这里的深度排序，如果有性能问题，可考虑修改为非每帧排序
- * 2、如果全3D世界显示角色相关显示对象，则不需要2D深度排序，只引用2D地图上的位置信息
+ *   1. 如果深度排序存在性能问题，可修改为非每帧排序（使用 Timer 降频）。
+ *   2. 如果全 3D 渲染，则不需要 2D 深度排序，只引用 2D 地图上的位置信息。
  */
 @ccclass('EntityLayer')
 export default class EntityLayer extends Component {
+    /** 降频计时器（0.2 秒间隔，当前 update 中只调用 update 但未使用返回值） */
     private timer: Timer = new Timer(0.2);
 
+    /**
+     * 帧更新：
+     * 预留深度排序调用位（当前已注释排序逻辑）。
+     */
     update(dt: number) {
         this.timer.update(dt)
+        // 预留：按 Y 坐标排序子节点渲染顺序
         // if (this.timer.update(dt))
         //     this.node.children.sort(this.zIndexSort);
     }
@@ -28,6 +55,10 @@ export default class EntityLayer extends Component {
     protected start(): void {
     }
 
+    /**
+     * 清除该图层下的所有子节点。
+     * 由 MapViewScene.reset() 在场景重置时调用。
+     */
     public clear() {
         this.node.children.forEach(n => {
             

assets/script/game/map/view/map/layer/MapLayer.ts

@@ -1,3 +1,23 @@
+/**
+ * @file MapLayer.ts
+ * @description 地图背景图层组件
+ *
+ * 职责：
+ *   1. 管理地图背景图片（bgImg）的显示和尺寸。
+ *   2. 提供 width / height 属性供其他组件查询地图实际尺寸。
+ *   3. 提供 init() 初始化方法同步 UITransform 尺寸。
+ *   4. 提供 clear() 清理方法释放背景图片引用。
+ *
+ * 关键设计：
+ *   - 地图尺寸由 bgImg 的 UITransform 决定，非固定值。
+ *   - clear() 仅释放 spriteFrame 引用（置 null），不销毁节点。
+ *
+ * 依赖：
+ *   - cc.Sprite —— 背景图片组件
+ *   - cc.UITransform —— 读写节点尺寸
+ *
+ * @author 落日故人 QQ 583051842
+ */
 import { Component, Layers, Node, Sprite, SpriteFrame, Texture2D, UITransform, Vec3, _decorator } from 'cc';
 import { oops } from '../../../../../../../extensions/oops-plugin-framework/assets/core/Oops';
 import { LayerUtil } from '../../../../../../../extensions/oops-plugin-framework/assets/core/utils/LayerUtil';
@@ -6,31 +26,37 @@ import { smc } from '../../../../common/SingletonModuleComp';
 const { ccclass, property } = _decorator;
 
 /**
- * 地图层 
- * @author 落日故人 QQ 583051842
- * 
+ * MapLayer —— 地图背景图层
+ *
+ * 管理背景图片的尺寸和清理，由 MapViewScene 持有引用。
  */
 @ccclass('MapLayer')
 export default class MapLayer extends Component {
 
-
+    /** 背景图片 Sprite（在编辑器中绑定） */
 	@property(Sprite)
 	private bgImg: Sprite | null = null;
 
+    /**
+     * 初始化：将 MapLayer 节点的 UITransform 尺寸
+     * 同步为背景图片的实际宽高。
+     */
 	public init(): void {
 		this.getComponent(UITransform)!.width = this.width;
 		this.getComponent(UITransform)!.height = this.height;
 	}
 
-
+    /** 清理：释放背景图片的 spriteFrame 引用 */
 	public clear(): void {
 		this.bgImg!.spriteFrame = null;
 	}
 
+    /** 获取背景图片 Sprite 引用 */
 	public get bgImage(): Sprite {
 		return this.bgImg!;
 	}
 
+    /** 获取地图宽度（读取背景图片 UITransform 的 width） */
 	public get width(): number {
 		if (this.bgImg) {
 			return this.bgImg.getComponent(UITransform)!.width;
@@ -38,6 +64,7 @@ export default class MapLayer extends Component {
 
 	}
 
+    /** 获取地图高度（读取背景图片 UITransform 的 height） */
 	public get height(): number {
 		if (this.bgImg) {
 			return this.bgImg.getComponent(UITransform)!.height;

assets/script/game/map/view/map/layer/SkillLayer.ts

@@ -1,3 +1,22 @@
+/**
+ * @file SkillLayer.ts
+ * @description 技能效果图层组件（场景显示层）
+ *
+ * 职责：
+ *   1. 作为所有技能效果节点（弹道、范围指示器、特效等）的 **父容器**。
+ *   2. 预留 doSkill() 方法用于外部触发技能视觉效果。
+ *   3. 提供 clear() 方法清除所有技能效果子节点。
+ *   4. 持有 light 预制体引用（预留，用于技能光效实例化）。
+ *
+ * 关键设计：
+ *   - 与 EntityLayer 类似，使用 Timer 降频处理。
+ *   - 深度排序逻辑当前已注释（预留）。
+ *   - clear() 遍历子节点但未执行实际清理（需后续补充）。
+ *
+ * 依赖：
+ *   - Timer（oops-framework）—— 降频计时器
+ *   - BoxSet —— 游戏常量配置
+ */
 /*
  * @Author: dgflash
  * @Date: 2022-08-04 15:22:33
@@ -11,23 +30,30 @@ import { BoxSet } from '../../../../common/config/GameSet';
 const { ccclass, property } = _decorator;
 
 /**
- * 物体层
- * 注：
- * 1、这里的深度排序，如果有性能问题，可考虑修改为非每帧排序
- * 2、如果全3D世界显示角色相关显示对象，则不需要2D深度排序，只引用2D地图上的位置信息
+ * SkillLayer —— 技能效果图层
+ *
+ * 所有技能视觉效果节点的父容器，预留排序和技能触发功能。
  */
 @ccclass('SkillLayer')
 export default class SkillLayer extends Component {
+    /** 降频计时器（0.2 秒间隔） */
     private timer: Timer = new Timer(0.2);
+
+    /** 技能光效预制体（在编辑器中绑定，预留） */
     @property(Prefab)
     light: Prefab = null;
+
+    /** 初始化：预留全局事件监听位 */
     onLoad(){
         // oops.message.on("do_use_skill", this.doSkill, this);
 
     }
+
+    /** 外部触发技能效果（预留） */
     doSkill(){
     }
    
+    /** 帧更新（预留深度排序逻辑） */
     update(dt: number) {
         // this.timer.update(dt)
         // if (this.timer.update(dt))
@@ -37,6 +63,7 @@ export default class SkillLayer extends Component {
     start(){
     }
 
+    /** 清除图层下的所有技能效果节点（预留实现） */
     public clear() {
         this.node.children.forEach(n => {
 

assets/script/game/map/view/map/layer/light.ts

@@ -1,16 +1,27 @@
+/**
+ * @file light.ts
+ * @description 光效组件（占位 / 预留）
+ *
+ * 职责：
+ *   当前为空实现的占位组件，预留用于技能光效或环境光效的扩展。
+ *   后续可在 onLoad / start / update 中加入光照逻辑。
+ */
 import { _decorator, Component, Node } from 'cc';
 const { ccclass, property ,} = _decorator;
 
+/** light —— 光效占位组件（预留扩展） */
 @ccclass('light')
 export class light extends Component {
  
     start() {
 
     }
+
     protected onLoad(): void {
         
        
     }
+
     update(deltaTime: number) {
         
     }