@cc-component/cc-guide 1.0.0

package/.cc-ex-component.md

@@ -0,0 +1,12 @@
+# 系统组件添加常用扩展方法
+
+## 前置条件
+[游戏引擎](https://www.cocos.com/en/creator-download)
+[开发框架](https://github.com/a1076559139/cocos-creator-frame-3d)
+
+## 使用案例
+```TS
+import {} from 'db://pkg/@gamex/cc-ex-component';
+
+...
+```

package/assets/guide/common/GuideTool.ts

@@ -0,0 +1,33 @@
+import { Layers, Node, Widget } from "cc";
+export function CreateNode(name: string) {
+    const node = new Node(name);
+    node.layer = Layers.Enum.UI_2D;
+    const w: Widget = node.addComponent(Widget);
+    w.isAlignLeft = w.isAlignRight = w.isAlignTop = w.isAlignBottom = true;
+    w.left = w.right = w.top = w.bottom = 0;
+    w.alignMode = 2;
+    w.enabled = true;
+    return node;
+}
+
+
+export function IsJson(value: string) {
+    const str = value
+    // 检查是否为字符串类型
+    if (typeof str !== 'string') {
+        return false;
+    }
+
+    // 检查是否为空字符串
+    if (str.trim().length === 0) {
+        return false;
+    }
+
+    try {
+        const parsed = JSON.parse(str);
+        // 确保解析结果是对象或数组（JSON的顶级必须是对象或数组）
+        return (typeof parsed === 'object' && parsed !== null) || Array.isArray(parsed);
+    } catch (e) {
+        return false;
+    }
+}

package/assets/guide/common/GuideTool.ts.meta

@@ -0,0 +1,9 @@
+{
+  "ver": "4.0.24",
+  "importer": "typescript",
+  "imported": true,
+  "uuid": "2bc2716f-1610-4f74-acee-0ded34bdcfc2",
+  "files": [],
+  "subMetas": {},
+  "userData": {}
+}

package/assets/guide/common/Log.ts

@@ -0,0 +1,82 @@
+
+export const Log = {
+    _enabled: true,
+
+    enable(enabled: boolean): void {
+        this._enabled = enabled;
+    },
+
+    // 自动从调用栈中提取用户代码的文件名和行号
+    _getCallerInfo(): string {
+        // 仅在 Cocos 编辑器预览中启用自动调用位置（最可靠）
+        if (!this._enabled) return '';
+
+        try {
+            const stack = new Error().stack;
+            if (!stack) return '';
+            // console.log(stack)
+
+            const lines = stack.split('\n');
+            for (let i = 2; i < lines.length; i++) {
+                const line = lines[i].trim();
+                if (!line || line.includes('ExTool.ts')) continue;
+                //console.log(line)
+                //   console.log("-----------------------------------------")
+                // 匹配 Cocos 编辑器中的典型格式:
+                // at onLoad (assets/scripts/GameCtrl.ts:25:12)
+                const match = line.match(/assets\/[^)]+\.ts:(\d+):\d+/);
+                if (match) {
+                    const full = match[0];
+                    const parts = full.split('/');
+                    const fileAndLine = parts[parts.length - 1]; // "GameCtrl.ts:25"
+                    return fileAndLine;
+                }
+            }
+        } catch (e) {
+            // ignore
+        }
+        return '';
+    },
+
+    debug(message?: any, ...optionalParams: any[]): void {
+        if (this._enabled) {
+            const caller = this._getCallerInfo();
+            console.debug?.(`[DEBUG][${caller}]`, message, ...optionalParams);
+        }
+    },
+    error(message?: any, ...optionalParams: any[]): void {
+        if (this._enabled) {
+            const caller = this._getCallerInfo();
+            console.error?.(`[ERROR][${caller}]`, message, ...optionalParams);
+        }
+    },
+    group(groupTitle?: string, ...optionalParams: any[]): void {
+        if (this._enabled) {
+            const caller = this._getCallerInfo();
+            console.group?.(`[GROUP][${caller}] ${groupTitle || ''}`, ...optionalParams);
+        }
+    },
+    groupEnd(): void {
+        if (this._enabled) {
+            console.groupEnd?.();
+        }
+    },
+    info(message?: any, ...optionalParams: any[]): void {
+        if (this._enabled) {
+            const caller = this._getCallerInfo();
+            console.info?.(`[INFO][${caller}]`, message, ...optionalParams);
+        }
+    },
+    log(message?: any, ...optionalParams: any[]): void {
+        if (this._enabled) {
+            const caller = this._getCallerInfo();
+            console.log?.(`[LOG][${caller}]`, message, ...optionalParams);
+        }
+    },
+    warn(message?: any, ...optionalParams: any[]): void {
+        if (this._enabled) {
+            const caller = this._getCallerInfo();
+            console.warn?.(`[WARN][${caller}]`, message, ...optionalParams);
+        }
+    }
+};

package/assets/guide/common/Log.ts.meta

@@ -0,0 +1,9 @@
+{
+  "ver": "4.0.24",
+  "importer": "typescript",
+  "imported": true,
+  "uuid": "cd2b794d-dac4-4c85-a20a-daf98a5eecb1",
+  "files": [],
+  "subMetas": {},
+  "userData": {}
+}

package/assets/guide/common/ViewUtil.ts

@@ -0,0 +1,163 @@
+/*
+ * @Author: dgflash
+ * @Date: 2021-08-16 09:34:56
+ * @LastEditors: dgflash
+ * @LastEditTime: 2023-01-19 14:52:12
+ */
+import { Animation, AnimationClip, EventTouch, instantiate, Node, Prefab, Size, UITransform, v3, Vec3 } from "cc";
+
+/** 显示对象工具 */
+export class ViewUtil {
+    /**
+     * 把Node当前的节点树结构根据Node命名转成一个js对象,重名的组件会覆盖，
+     * Node的name不应该包含空格键，否则将跳过
+     * @param parent 被遍历的Node组件
+     * @param obj    绑定的js对象 (可选)
+     */
+    static nodeTreeInfoLite(parent: Node, obj?: Map<string, Node>): Map<string, Node> | null {
+        let map: Map<string, Node> = obj || new Map();
+        let items = parent.children;
+        for (let i = 0; i < items.length; i++) {
+            let _node = items[i];
+            if (_node.name.indexOf(" ") < 0) {
+                map.set(_node.name, _node);
+            }
+            ViewUtil.nodeTreeInfoLite(_node, map);
+        }
+        return map;
+    }
+
+    /**
+     * 正则搜索节点名字,符合条件的节点将会返回
+     * @param reg     正则表达式
+     * @param parent  要搜索的父节点
+     * @param nodes   返回的数组（可选）
+     */
+    static findNodes(reg: RegExp, parent: Node, nodes?: Array<Node>): Array<Node> {
+        let ns: Array<Node> = nodes || [];
+        let items = parent.children;
+        for (let i = 0; i < items.length; i++) {
+            let _name: string = items[i].name;
+            if (reg.test(_name)) {
+                ns.push(items[i]);
+            }
+            ViewUtil.findNodes(reg, items[i], ns);
+        }
+        return ns;
+    };
+
+    /**
+     * 节点之间坐标互转
+     * @param a         A节点
+     * @param b         B节点
+     * @param aPos      A节点空间中的相对位置
+     */
+    static calculateASpaceToBSpacePos(a: Node, b: Node, aPos: Vec3): Vec3 {
+        const world: Vec3 = a.getComponent(UITransform)!.convertToWorldSpaceAR(aPos);
+        return b.getComponent(UITransform)!.convertToNodeSpaceAR(world);
+    }
+
+    /**
+     * 屏幕转空间坐标
+     * @param event 触摸事件
+     * @param space 转到此节点的坐标空间
+     */
+    static calculateScreenPosToSpacePos(event: EventTouch, space: Node): Vec3 {
+        const uil = event.getUILocation();
+        const worldPos: Vec3 = v3(uil.x, uil.y);
+        return space.getComponent(UITransform)!.convertToNodeSpaceAR(worldPos);
+    }
+
+    // /**
+    //  * 显示对象等比缩放
+    //  * @param targetWidth       目标宽
+    //  * @param targetHeight      目标高
+    //  * @param defaultWidth      默认宽
+    //  * @param defaultHeight     默认高
+    //  */
+    // static uniformScale(targetWidth: number, targetHeight: number, defaultWidth: number, defaultHeight: number) {
+    //     const widthRatio = defaultWidth / targetWidth;
+    //     const heightRatio = defaultHeight / targetHeight;
+    //     let ratio;
+    //     widthRatio < heightRatio ? ratio = widthRatio : ratio = heightRatio;
+    //     return new Size(Math.floor(targetWidth * ratio), Math.floor(targetHeight * ratio));
+    // }
+
+    // /**
+    //  * 从资源缓存中找到预制资源名并创建一个显示对象（建议使用GameComponent里的同名方法，能自动管理内存施放）
+    //  * @param path        资源路径
+    //  * @param bundleName  资源包名
+    //  */
+    // static createPrefabNode(path: string, bundleName: string = resLoader.defaultBundleName): Node {
+    //     const p = resLoader.get(path, Prefab, bundleName);
+    //     if (p) {
+    //         return instantiate(p);
+    //     }
+    //     return null!;
+    // }
+
+    // /**
+    //  * 加载预制并创建预制节点（建议使用GameComponent里的同名方法，能自动管理内存施放）
+    //  * @param path        资源路径
+    //  * @param bundleName  资源包名
+    //  */
+    // static createPrefabNodeAsync(path: string, bundleName: string = resLoader.defaultBundleName): Promise<Node> {
+    //     return new Promise(async (resolve, reject) => {
+    //         const p = await resLoader.loadAsync(bundleName, path, Prefab);
+    //         if (p) {
+    //             resolve(instantiate(p));
+    //         }
+    //         else {
+    //             Log.error(`名为【${path}】的资源加载失败`);
+    //             resolve(null!);
+    //         }
+    //     });
+    // }
+
+    // /**
+    //  * 添加节点动画
+    //  * @param path              资源路径
+    //  * @param node              目标节点
+    //  * @param onlyOne           是否唯一
+    //  * @param isDefaultClip     是否播放默认动画剪辑
+    //  */
+    // static addNodeAnimation(path: string, node: Node, onlyOne: boolean = true, isDefaultClip: boolean = false) {
+    //     if (!node || !node.isValid) {
+    //         return;
+    //     }
+
+    //     let anim = node.getComponent(Animation);
+    //     if (anim == null) {
+    //         anim = node.addComponent(Animation);
+    //     }
+
+    //     const clip = resLoader.get(path, AnimationClip) as AnimationClip;
+    //     if (!clip) {
+    //         return;
+    //     }
+
+    //     if (onlyOne && anim.getState(clip.name) && anim.getState(clip.name).isPlaying) {
+    //         return;
+    //     }
+
+    //     if (isDefaultClip) {
+    //         anim.defaultClip = clip;
+    //         anim.play();
+    //         return;
+    //     }
+
+    //     // 播放完成后恢复播放默认动画
+    //     anim.once(Animation.EventType.FINISHED, () => {
+    //         if (anim!.defaultClip) {
+    //             anim!.play();
+    //         }
+    //     }, this);
+
+    //     if (anim.getState(clip.name)) {
+    //         anim.play(clip.name);
+    //         return
+    //     }
+    //     anim.createState(clip, clip!.name);
+    //     anim.play(clip!.name);
+    // }
+}

package/assets/guide/common/ViewUtil.ts.meta

@@ -0,0 +1,9 @@
+{
+  "ver": "4.0.24",
+  "importer": "typescript",
+  "imported": true,
+  "uuid": "ecc914a4-84ed-42cc-a0db-ef5098e67ba5",
+  "files": [],
+  "subMetas": {},
+  "userData": {}
+}

package/assets/guide/common.meta

@@ -0,0 +1,9 @@
+{
+  "ver": "1.2.0",
+  "importer": "directory",
+  "imported": true,
+  "uuid": "188831bd-d962-4961-8f7a-bf6d6f33d76d",
+  "files": [],
+  "subMetas": {},
+  "userData": {}
+}

package/assets/guide/guide/Guide.ts

@@ -0,0 +1,42 @@
+
+/*
+ * @Author: dgflash
+ * @Date: 2021-11-18 17:47:56
+ * @LastEditors: dgflash
+ * @LastEditTime: 2022-09-06 10:15:10
+ */
+
+import { IGuideData } from "./model/GuideCommon";
+import { GuideModelComp } from "./model/GuideModelComp";
+import { GuideViewComp } from "./view/GuideViewComp";
+import { Node } from "cc";
+
+/** 
+ * 新手引导
+ * 1、组件方式绑定到引导 Node 上自动注册引导数据
+ * 2、通过设置引导步骤可回复到上次引导点
+ * 3、触发引导分为穿透模式与事件模拟模式（模拟模式不会导致不规则图形在引导区域中导致误点）
+ */
+export class Guide {
+    GuideModel!: GuideModelComp;
+    GuideView!: GuideViewComp;
+    init(param: IGuideData) {
+        this.GuideModel = new GuideModelComp();
+        this.GuideModel.loadData(param)
+
+    }
+
+    /** 加载引导资源 */
+    load(node: Node) {
+        this.GuideView = node.addComponent(GuideViewComp);
+    }
+
+    /** 检查指定引导是否触发 */
+    check(step: number) {
+        if (this.GuideModel) {
+            this.GuideModel.step = step;
+            this.GuideView.check();
+        }
+    }
+
+}

package/assets/guide/guide/Guide.ts.meta

@@ -0,0 +1,9 @@
+{
+  "ver": "4.0.24",
+  "importer": "typescript",
+  "imported": true,
+  "uuid": "8b977f3b-3562-4115-bddf-154294f8e943",
+  "files": [],
+  "subMetas": {},
+  "userData": {}
+}