重构(guide): 重构新手引导组件并更新引导prefab配置

将原ECS版本的GuideComp重构为原生Cocos Creator组件，移除冗余ECS依赖优化引导点击与销毁逻辑，改用框架内置UI管理接口移除引导界面更新guide1至guide4四个引导prefab，启用动画自动播放并调整动画配置精简组件事件解绑逻辑，移除冗余的hand节点相关处理代码
2026-06-12 10:54:04 +08:00
parent b178893a17
commit 969cd657f9
5 changed files with 119 additions and 86 deletions
--- a/assets/resources/gui/element/guide1.prefab
+++ b/assets/resources/gui/element/guide1.prefab
@@ -32,10 +32,13 @@
      },
      {
        "__id__": 53
+      },
+      {
+        "__id__": 55
      }
    ],
    "_prefab": {
-      "__id__": 55
+      "__id__": 57
    },
    "_lpos": {
      "__type__": "cc.Vec3",
@@ -258,7 +261,7 @@
    "__prefab": {
      "__id__": 9
    },
-    "playOnLoad": false,
+    "playOnLoad": true,
    "_clips": [
      {
        "__uuid__": "70fd0e99-c640-4497-b2c2-936f5179f227",
@@ -1276,6 +1279,25 @@
    "__type__": "cc.CompPrefabInfo",
    "fileId": "10DsksGxZDUbKjtrjCTMxF"
  },
+  {
+    "__type__": "25122z/cnRPhp90+CJYs5+r",
+    "_name": "",
+    "_objFlags": 0,
+    "__editorExtras__": {},
+    "node": {
+      "__id__": 1
+    },
+    "_enabled": true,
+    "__prefab": {
+      "__id__": 56
+    },
+    "guide_id": 1,
+    "_id": ""
+  },
+  {
+    "__type__": "cc.CompPrefabInfo",
+    "fileId": "c1+YKikClLOZi42oPQXi6+"
+  },
  {
    "__type__": "cc.PrefabInfo",
    "root": {
--- a/assets/resources/gui/element/guide2.prefab
+++ b/assets/resources/gui/element/guide2.prefab
@@ -32,10 +32,13 @@
      },
      {
        "__id__": 53
+      },
+      {
+        "__id__": 55
      }
    ],
    "_prefab": {
-      "__id__": 55
+      "__id__": 57
    },
    "_lpos": {
      "__type__": "cc.Vec3",
@@ -258,7 +261,7 @@
    "__prefab": {
      "__id__": 9
    },
-    "playOnLoad": false,
+    "playOnLoad": true,
    "_clips": [
      {
        "__uuid__": "70fd0e99-c640-4497-b2c2-936f5179f227",
@@ -1276,6 +1279,25 @@
    "__type__": "cc.CompPrefabInfo",
    "fileId": "10DsksGxZDUbKjtrjCTMxF"
  },
+  {
+    "__type__": "25122z/cnRPhp90+CJYs5+r",
+    "_name": "",
+    "_objFlags": 0,
+    "__editorExtras__": {},
+    "node": {
+      "__id__": 1
+    },
+    "_enabled": true,
+    "__prefab": {
+      "__id__": 56
+    },
+    "guide_id": 2,
+    "_id": ""
+  },
+  {
+    "__type__": "cc.CompPrefabInfo",
+    "fileId": "eb5KOwrZlLbZGy9v5ji8QK"
+  },
  {
    "__type__": "cc.PrefabInfo",
    "root": {
--- a/assets/resources/gui/element/guide3.prefab
+++ b/assets/resources/gui/element/guide3.prefab
@@ -32,10 +32,13 @@
      },
      {
        "__id__": 53
+      },
+      {
+        "__id__": 55
      }
    ],
    "_prefab": {
-      "__id__": 55
+      "__id__": 57
    },
    "_lpos": {
      "__type__": "cc.Vec3",
@@ -258,19 +261,15 @@
    "__prefab": {
      "__id__": 9
    },
-    "playOnLoad": false,
+    "playOnLoad": true,
    "_clips": [
-      {
-        "__uuid__": "70fd0e99-c640-4497-b2c2-936f5179f227",
-        "__expectedType__": "cc.AnimationClip"
-      },
      {
        "__uuid__": "be8b49e0-c726-4c44-823e-d50921b886d3",
        "__expectedType__": "cc.AnimationClip"
      }
    ],
    "_defaultClip": {
-      "__uuid__": "70fd0e99-c640-4497-b2c2-936f5179f227",
+      "__uuid__": "be8b49e0-c726-4c44-823e-d50921b886d3",
      "__expectedType__": "cc.AnimationClip"
    },
    "_id": ""
@@ -1276,6 +1275,25 @@
    "__type__": "cc.CompPrefabInfo",
    "fileId": "10DsksGxZDUbKjtrjCTMxF"
  },
+  {
+    "__type__": "25122z/cnRPhp90+CJYs5+r",
+    "_name": "",
+    "_objFlags": 0,
+    "__editorExtras__": {},
+    "node": {
+      "__id__": 1
+    },
+    "_enabled": true,
+    "__prefab": {
+      "__id__": 56
+    },
+    "guide_id": 3,
+    "_id": ""
+  },
+  {
+    "__type__": "cc.CompPrefabInfo",
+    "fileId": "56tM4qzvJP56nvwUPPlzAc"
+  },
  {
    "__type__": "cc.PrefabInfo",
    "root": {
--- a/assets/resources/gui/element/guide4.prefab
+++ b/assets/resources/gui/element/guide4.prefab
@@ -32,10 +32,13 @@
      },
      {
        "__id__": 53
+      },
+      {
+        "__id__": 55
      }
    ],
    "_prefab": {
-      "__id__": 55
+      "__id__": 57
    },
    "_lpos": {
      "__type__": "cc.Vec3",
@@ -258,7 +261,7 @@
    "__prefab": {
      "__id__": 9
    },
-    "playOnLoad": false,
+    "playOnLoad": true,
    "_clips": [
      {
        "__uuid__": "70fd0e99-c640-4497-b2c2-936f5179f227",
@@ -1276,6 +1279,25 @@
    "__type__": "cc.CompPrefabInfo",
    "fileId": "10DsksGxZDUbKjtrjCTMxF"
  },
+  {
+    "__type__": "25122z/cnRPhp90+CJYs5+r",
+    "_name": "",
+    "_objFlags": 0,
+    "__editorExtras__": {},
+    "node": {
+      "__id__": 1
+    },
+    "_enabled": true,
+    "__prefab": {
+      "__id__": 56
+    },
+    "guide_id": 4,
+    "_id": ""
+  },
+  {
+    "__type__": "cc.CompPrefabInfo",
+    "fileId": "6fP5tSSI5J5aznxoZy3ciN"
+  },
  {
    "__type__": "cc.PrefabInfo",
    "root": {
--- a/assets/script/game/map/GuideComp.ts
+++ b/assets/script/game/map/GuideComp.ts
@@ -1,80 +1,28 @@

 import { mLogger } from "../common/Logger";
-import { _decorator, Animation, AnimationClip, EventTouch, Label, Node, NodeEventType, Sprite, SpriteAtlas, Tween, tween, UIOpacity, Vec3, resources, Light, UITransform, Widget, CCInteger, CCString } from "cc";
-import { ecs } from "../../../../extensions/oops-plugin-framework/assets/libs/ecs/ECS";
-import { CCComp } from "../../../../extensions/oops-plugin-framework/assets/module/common/CCComp";
+import { _decorator, Animation, AnimationClip, EventTouch, Label, Node, NodeEventType, Sprite, SpriteAtlas, Tween, tween, UIOpacity, Vec3, resources, Light, UITransform, Widget, CCInteger, CCString, Component } from "cc";
 import { smc } from "../common/SingletonModuleComp";
+import { UIID } from "../common/config/GameUIConfig";
+import { oops } from "db://oops-framework/core/Oops";

 const { ccclass, property } = _decorator;

@ccclass('GuideComp')
-@ecs.register('GuideComp', false)
-export class GuideComp extends CCComp {
+export class GuideComp extends Component {
    /** 是否开启调试日志 */
    private debugMode: boolean = true;

    // ======================== 编辑器绑定节点 ========================

-    /** 手势图标节点 */
-    @property(Node)
-    hand: Node = null!
-     /** 手势图标节点 */
-    @property(Node)
-    clickNode: Node = null!
    /** 引导编号 ID */
    @property({ type: CCInteger })
    guide_id: number = 0
-    /** 动画名称 ID */
-    @property({ type: CCString })
-    animation_name: string = 'dianji';

    onLoad() {
-        // 如果该引导已经完成，则隐藏并销毁本节点
-        if (smc.finish_guides.includes(this.guide_id)) {
-            this.node.active = false;
-            this.node.destroy();
-            return;
-        }
-
-        // 播放手势动画
-        if (this.hand && this.animation_name) {
-            // 延迟一帧播放，防止组件还未完全激活
-            this.scheduleOnce(() => {
-                if (!this.isValid) return; // 防止节点已被销毁
-                
-                // 1. 先尝试在绑定的 this.hand 本身上查找 Animation 组件
-                let anim = this.hand.getComponent(Animation);
-                
-                // 2. 如果没找到，再尝试去它的子节点上找
-                if (!anim) {
-                    anim = this.hand.getComponentInChildren(Animation);
-                }
-
-                if (anim) {
-                    // 确保目标动画状态存在
-                    const animState = anim.getState(this.animation_name);
-                    if (animState) {
-                        anim.play(this.animation_name);
-                        mLogger.log(this.debugMode, 'Guide', `成功播放引导动画: ${this.animation_name}`);
-                    } else {
-                        mLogger.warn(this.debugMode, 'Guide', `找到了 Animation 组件，但组件内未挂载名为 '${this.animation_name}' 的动画剪辑(Clip)。请检查编辑器 Animation 组件的 Clips 列表！`);
-                    }
-                } else {
-                    mLogger.warn(this.debugMode, 'Guide', `在 hand 节点及其子节点下均未找到 Animation 组件，无法播放动画: ${this.animation_name}`);
-                }
-            });
-        }
-
-        // 监听手势节点点击事件
-        if (this.hand) {
-            this.hand.on(NodeEventType.TOUCH_START, this.onTouchStart, this);
-            this.hand.on(NodeEventType.TOUCH_END, this.onGuideClick, this);
-        } else {
-            // 兜底：如果没有绑定手势节点，则监听自身节点
+        // 监听自身节点（即弹窗任意位置）的点击事件
        this.node.on(NodeEventType.TOUCH_START, this.onTouchStart, this);
        this.node.on(NodeEventType.TOUCH_END, this.onGuideClick, this);
    }
-    }

    private onTouchStart(event: EventTouch) {
        // 允许事件穿透，确保底层的实际功能按钮能正常接收到 TOUCH_START 事件
@@ -94,17 +42,25 @@ export class GuideComp extends CCComp {
        // 允许事件穿透，确保底层的实际功能按钮能正常接收到点击事件
        event.preventSwallow = true;

-        // 完成后隐藏并销毁引导节点
+        // 因为通过 oops.gui.open(UIID) 弹出的界面，根节点可能会带有一个阻挡点击的遮罩组件（BlockInputEvents）
+        // 所以应当通过 oops.gui.remove 彻底从框架的层级管理中移除当前界面。
+        let targetUIID = -1;
+        if (this.guide_id === 1) targetUIID = UIID.Guide1;
+        if (this.guide_id === 2) targetUIID = UIID.Guide2;
+        if (this.guide_id === 3) targetUIID = UIID.Guide3;
+        if (this.guide_id === 4) targetUIID = UIID.Guide4;
+
+        if (targetUIID !== -1) {
+            oops.gui.remove(targetUIID);
+        } else {
+            // 兜底方案
            this.node.active = false;
            this.node.destroy();
        }
+    }

    /** 组件销毁时解绑所有事件，防止残留回调 */
    onDestroy() {
-        if (this.hand && this.hand.isValid) {
-            this.hand.off(NodeEventType.TOUCH_START, this.onTouchStart, this);
-            this.hand.off(NodeEventType.TOUCH_END, this.onGuideClick, this);
-        }
        if (this.node && this.node.isValid) {
            this.node.off(NodeEventType.TOUCH_START, this.onTouchStart, this);
            this.node.off(NodeEventType.TOUCH_END, this.onGuideClick, this);
@@ -115,11 +71,4 @@ export class GuideComp extends CCComp {
    init() {
     
    }
-
-    /** ECS 组件移除时的释放钩子：销毁节点 */
-    reset() {
-        if (this.node && this.node.isValid) {
-            this.node.destroy();
-        }
-    }
 }