@cc-component/cc-fly 0.0.0-stage → 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/fly/Interface.ts

@@ -0,0 +1,32 @@
+import { Vec3 } from "cc";
+
+import { Component } from "cc";
+import { Node } from "cc";
+import { FlyBasePlayer } from "./base/FlyBasePlayer";
+import { PlayerBuffType } from "./base/FlyPlayerBuffSystem";
+
+declare module "cc" {
+
+}
+declare global {
+    namespace FlyModule {
+        /**开启日志打印 */
+        //export function Debug(enabled: boolean);
+        // 调用 A* 路径寻找，从 (1,1) 到 (5,5),attackDis: 攻击距离
+        /**
+        * 开始抛物线缓动
+        * @param item 运动节点
+        * @param target_postion 目标位置
+        * @param update 更新 运动中回调
+        * @param offset_ratio 最高点 的偏移量
+        * @param time 动画时间
+        * @param is_random 是否随机上下方向
+        * @param start_position 起始位置--比如 父节点的位置和 抛物线的起点位置 不同，，用父节点的起始位置就传入
+        */
+        export function RunParabola(item: Node, target_postion: Vec3, update: (ratio: number) => void, param?: { offset_ratio?: number, is_random: boolean, time?: number, speed?: number, scale_offset_with_distance?: boolean, offset_reference_distance?: number, start_position?: Vec3, is_end_clone?: boolean });
+
+        export function OnSkillAnim<T extends FlyBasePlayer>(call: (buffType: PlayerBuffType | any, attacker: T, primaryTarget: T, candidateTargets: readonly T[], onHit: (target: T) => void) => void): void
+    }
+}
+// // 必须在 game.init() 之前设置！
+//macro.ENABLE_TRANSPARENT_CANVAS = true;

package/assets/fly/Interface.ts.meta

@@ -0,0 +1,9 @@
+{
+  "ver": "4.0.24",
+  "importer": "typescript",
+  "imported": true,
+  "uuid": "b295f1b0-6f95-4fef-af46-2cdb71f3cd40",
+  "files": [],
+  "subMetas": {},
+  "userData": {}
+}

package/assets/fly/base/BuffUI.ts

@@ -0,0 +1,68 @@
+import { _decorator, Component, instantiate, Label, Layout, Node } from 'cc';
+import { PlayerBuffDescription } from './FlyPlayerBuffSystem';
+import { FlyBasePlayer } from './FlyBasePlayer';
+const { ccclass, property } = _decorator;
+
+@ccclass('FlyBuffUI')
+export class FlyBuffUI extends Component {
+    @property({ type: FlyBasePlayer, displayName: '显示 Buff 的角色' })
+    private FlyBasePlayer: FlyBasePlayer | null = null;
+
+    @property({ type: Label })
+    private templateLabel: Label | null = null;
+
+    private layout: Layout | null = null;
+    private displayedLabels: Node[] = [];
+    private lastDescription = '';
+
+    protected onLoad(): void {
+        this.layout = this.node.getComponent(Layout);
+        if (this.templateLabel) {
+            this.templateLabel.node.active = false;
+        }
+    }
+
+    protected update(): void {
+        if (!this.FlyBasePlayer?.buffSystem)
+            return;
+
+        const descriptions = this.FlyBasePlayer?.buffSystem?.getBuffDescriptions() ?? [];
+        const currentDescription = JSON.stringify(descriptions);
+        if (currentDescription === this.lastDescription) return;
+
+        this.lastDescription = currentDescription;
+        this.refreshLabels(descriptions);
+    }
+
+    private refreshLabels(descriptions: PlayerBuffDescription[]): void {
+        if (!this.templateLabel) return;
+
+        for (const labelNode of this.displayedLabels) {
+            if (labelNode.isValid) labelNode.destroy();
+        }
+        this.displayedLabels = [];
+
+        for (const buff of descriptions) {
+            const labelNode = instantiate(this.templateLabel.node);
+            labelNode.parent = this.node;
+            labelNode.active = true;
+            const label = labelNode.getComponent(Label);
+            if (!label) {
+                labelNode.destroy();
+                continue;
+            }
+            label.string = this.formatBuffDescription(buff);
+            this.displayedLabels.push(labelNode);
+        }
+
+        this.layout?.updateLayout();
+    }
+
+    private formatBuffDescription(buff: PlayerBuffDescription): string {
+        const details: string[] = [buff.description];
+        if (buff.duration !== undefined) {
+            details.push(`持续${buff.duration}秒`);
+        }
+        return details.join('，');
+    }
+}

package/assets/fly/base/BuffUI.ts.meta

@@ -0,0 +1,9 @@
+{
+  "ver": "4.0.24",
+  "importer": "typescript",
+  "imported": true,
+  "uuid": "0ffef054-401a-41c6-afdb-d2577b984187",
+  "files": [],
+  "subMetas": {},
+  "userData": {}
+}

package/assets/fly/base/FlyArrowLauncher.ts

@@ -0,0 +1,166 @@
+import { _decorator, Component, Enum, Node, Prefab, Vec3 } from 'cc';
+import { FlyBaseHit } from './FlyBaseHit';
+import { FlyBaseBullet } from './FlyBaseBullet';
+import { FlyNodePoolUtil } from './FlyNodePoolUtil';
+
+export interface FlyArrowLauncherConfig {
+    arrowTemplateType?: FlyArrowTemplateType;
+    arrow?: Node | null;
+    hit?: Node | null;
+    arrowPrefab?: Prefab | null;
+    hitPrefab?: Prefab | null;
+    poolParent?: Node | null;
+    isRandom?: boolean;
+    offsetRatio?: number;
+    scaleOffsetWithDistance?: boolean;
+    offsetReferenceDistance?: number;
+    speed?: number;
+    time?: number;
+    arrowReturnDelay?: number;
+}
+
+export enum FlyArrowTemplateType {
+    Node,
+    Prefab,
+}
+
+export type FlyArrowHitCallback = (hitPosition: Vec3, arrow: Node) => void;
+
+const { ccclass, property } = _decorator;
+
+@ccclass('FlyArrowLauncher')
+export class FlyArrowLauncher extends Component {
+    private static nextPoolId = 0;
+    private readonly poolId = FlyArrowLauncher.nextPoolId++;
+
+    @property({ type: Enum(FlyArrowTemplateType), displayName: '资源类型' })
+    arrowTemplateType = FlyArrowTemplateType.Node;
+
+    @property({ type: Node, displayName: '箭矢节点', tooltip: '箭矢对象池使用的模板节点，需挂载 FlyBaseBullet。', visible(this: FlyArrowLauncher) { return this.arrowTemplateType === FlyArrowTemplateType.Node; } })
+    arrow: Node = null;
+
+    @property({ type: Node, displayName: '命中效果节点', tooltip: '命中粒子对象池使用的模板节点，需挂载 FlyBaseHit。', visible(this: FlyArrowLauncher) { return this.arrowTemplateType === FlyArrowTemplateType.Node; } })
+    hit: Node = null;
+
+    @property({ type: Prefab, displayName: '箭矢 Prefab', tooltip: '作为箭矢对象池模板。', visible(this: FlyArrowLauncher) { return this.arrowTemplateType === FlyArrowTemplateType.Prefab; } })
+    arrowPrefab: Prefab = null;
+
+    @property({ type: Prefab, displayName: '命中效果 Prefab', tooltip: '作为命中效果对象池模板。', visible(this: FlyArrowLauncher) { return this.arrowTemplateType === FlyArrowTemplateType.Prefab; } })
+    hitPrefab: Prefab = null;
+
+    @property({ type: Node, displayName: '箭矢和命中父节点', tooltip: '箭矢和命中效果共用此父节点；未设置时使用发射器所在节点。' })
+    poolParent: Node = null;
+
+    @property({ displayName: '随机抛物线方向', tooltip: '启用后随机选择抛物线弯曲方向。' })
+    isRandom = true;
+
+    @property({ displayName: '抛物线偏移比例', tooltip: '控制抛物线最高点相对起终点距离的偏移比例。' })
+    offsetRatio = 0.5;
+
+    @property({ displayName: '弧线随距离缩放', tooltip: '开启后距离越远弧线幅度越大，距离越近幅度越小；关闭时使用参考距离对应的固定幅度。' })
+    scaleOffsetWithDistance = true;
+
+    @property({ displayName: '弧线参考距离', tooltip: '反向距离缩放的基准距离；默认 500 单位时弧线高度与原效果一致。' })
+    offsetReferenceDistance = 500;
+
+    @property({ displayName: '发射速度', tooltip: '大于 0 时按距离和速度计算时长；否则使用动画时间。' })
+    speed = 500;
+
+    @property({ displayName: '动画时间', tooltip: '发射速度小于或等于 0 时使用的动画时长，单位为秒。' })
+    time = 0.5;
+
+    @property({ displayName: '箭矢回收延迟', tooltip: '箭矢到达终点后等待多久再返回对象池，单位为秒。' })
+    arrowReturnDelay = 0.2;
+
+    private poolsRegistered = false;
+    private get arrowPoolKey(): string { return `FlyArrowLauncher:${this.poolId}:arrow`; }
+    private get hitPoolKey(): string { return `FlyArrowLauncher:${this.poolId}:hit`; }
+    private get arrowTemplate(): Node | Prefab | null {
+        return this.arrowTemplateType === FlyArrowTemplateType.Prefab ? this.arrowPrefab : this.arrow;
+    }
+    private get hitTemplate(): Node | Prefab | null {
+        return this.arrowTemplateType === FlyArrowTemplateType.Prefab ? this.hitPrefab : this.hit;
+    }
+
+    protected onLoad(): void {
+        this.registerPools();
+    }
+
+    onDestroy(): void {
+        FlyNodePoolUtil.clear(this.arrowPoolKey);
+        FlyNodePoolUtil.clear(this.hitPoolKey);
+    }
+
+    setConfig(config: FlyArrowLauncherConfig): void {
+        const templatesChanged =
+            (config.arrowTemplateType !== undefined && config.arrowTemplateType !== this.arrowTemplateType) ||
+            (config.arrow !== undefined && config.arrow !== this.arrow) ||
+            (config.hit !== undefined && config.hit !== this.hit) ||
+            (config.arrowPrefab !== undefined && config.arrowPrefab !== this.arrowPrefab) ||
+            (config.hitPrefab !== undefined && config.hitPrefab !== this.hitPrefab) ||
+            (config.poolParent !== undefined && config.poolParent !== this.poolParent);
+
+        if (templatesChanged && this.poolsRegistered) {
+            FlyNodePoolUtil.clear(this.arrowPoolKey);
+            FlyNodePoolUtil.clear(this.hitPoolKey);
+            this.poolsRegistered = false;
+        }
+
+        if (config.arrowTemplateType !== undefined) this.arrowTemplateType = config.arrowTemplateType;
+        if (config.arrow !== undefined) this.arrow = config.arrow;
+        if (config.hit !== undefined) this.hit = config.hit;
+        if (config.arrowPrefab !== undefined) this.arrowPrefab = config.arrowPrefab;
+        if (config.hitPrefab !== undefined) this.hitPrefab = config.hitPrefab;
+        if (config.poolParent !== undefined) this.poolParent = config.poolParent;
+        if (config.isRandom !== undefined) this.isRandom = config.isRandom;
+        if (config.offsetRatio !== undefined) this.offsetRatio = config.offsetRatio;
+        if (config.scaleOffsetWithDistance !== undefined) this.scaleOffsetWithDistance = config.scaleOffsetWithDistance;
+        if (config.offsetReferenceDistance !== undefined) this.offsetReferenceDistance = config.offsetReferenceDistance;
+        if (config.speed !== undefined) this.speed = config.speed;
+        if (config.time !== undefined) this.time = config.time;
+        if (config.arrowReturnDelay !== undefined) this.arrowReturnDelay = config.arrowReturnDelay;
+
+        if (templatesChanged) this.registerPools();
+    }
+
+    fire(start: Vec3, end: Vec3, onHit?: FlyArrowHitCallback): void {
+        if (!this.poolsRegistered || !this.arrowTemplate || !this.hitTemplate) return;
+
+        const arrow = FlyNodePoolUtil.get(this.arrowPoolKey);
+        arrow.setWorldPosition(start);
+        arrow.getComponent(FlyBaseBullet).play();
+
+        let completed = false;
+        FlyModule.RunParabola(arrow, end, (ratio) => {
+            if (ratio < 1 || completed || !arrow.isValid) return;
+            completed = true;
+            const hit = FlyNodePoolUtil.get(this.hitPoolKey);
+            hit.setWorldPosition(arrow.worldPosition);
+            hit.getComponent(FlyBaseHit).play();
+            onHit?.(hit.worldPosition, arrow);
+            this.scheduleOnce(() => {
+                if (arrow.isValid) FlyNodePoolUtil.put(arrow);
+            }, this.arrowReturnDelay);
+        }, {
+            is_random: this.isRandom,
+            offset_ratio: this.offsetRatio,
+            scale_offset_with_distance: this.scaleOffsetWithDistance,
+            offset_reference_distance: this.offsetReferenceDistance,
+            speed: this.speed,
+            time: this.time,
+            start_position: start,
+        });
+    }
+
+    private registerPools(): void {
+        const arrowTemplate = this.arrowTemplate;
+        const hitTemplate = this.hitTemplate;
+        if (!arrowTemplate || !hitTemplate) return;
+
+        const poolParent = this.poolParent ?? this.node;
+        FlyNodePoolUtil.register(this.arrowPoolKey, arrowTemplate, poolParent);
+        FlyNodePoolUtil.register(this.hitPoolKey, hitTemplate, poolParent);
+        if (this.arrow) this.arrow.active = false;
+        this.poolsRegistered = true;
+    }
+}

package/assets/fly/base/FlyArrowLauncher.ts.meta

@@ -0,0 +1,9 @@
+{
+  "ver": "4.0.24",
+  "importer": "typescript",
+  "imported": true,
+  "uuid": "3a9d2f4c-7b81-4e06-9c15-2f638a41d7b0",
+  "files": [],
+  "subMetas": {},
+  "userData": {}
+}

package/assets/fly/base/FlyBaseBullet.ts

@@ -0,0 +1,9 @@
+import { _decorator } from 'cc';
+import { FlyPooledParticleEffect } from './FlyPooledParticleEffect';
+
+const { ccclass } = _decorator;
+
+@ccclass('FlyBaseBullet')
+export class FlyBaseBullet extends FlyPooledParticleEffect { }
+
+

package/assets/fly/base/FlyBaseBullet.ts.meta

@@ -0,0 +1,9 @@
+{
+  "ver": "4.0.24",
+  "importer": "typescript",
+  "imported": true,
+  "uuid": "c41cb785-3286-4af2-a72f-459e1f762240",
+  "files": [],
+  "subMetas": {},
+  "userData": {}
+}

package/assets/fly/base/FlyBaseHit.ts

@@ -0,0 +1,10 @@
+import { _decorator } from 'cc';
+import { FlyPooledParticleEffect } from './FlyPooledParticleEffect';
+
+const { ccclass } = _decorator;
+
+@ccclass('FlyBaseHit')
+export class FlyBaseHit extends FlyPooledParticleEffect {
+}
+
+

package/assets/fly/base/FlyBaseHit.ts.meta

@@ -0,0 +1,9 @@
+{
+  "ver": "4.0.24",
+  "importer": "typescript",
+  "imported": true,
+  "uuid": "eb746171-d178-4a6b-951c-a91b8e71d419",
+  "files": [],
+  "subMetas": {},
+  "userData": {}
+}

package/assets/fly/base/FlyBaseHp.ts

@@ -0,0 +1,96 @@
+import { Label } from 'cc';
+import { _decorator, Component, ProgressBar, tween, Tween } from 'cc';
+const { ccclass, property } = _decorator;
+
+export interface FlyBaseHpConfig {
+    maxHp?: number;
+    currentHp?: number;
+    animationDuration?: number;
+}
+
+@ccclass('FlyBaseHp')
+export class FlyBaseHp extends Component {
+    @property({ type: ProgressBar, displayName: '血条进度条' })
+    progressBar: ProgressBar | null = null;
+
+    @property({ type: Label, displayName: '血量文本' })
+    textLabel: Label | null = null;
+
+    @property({ displayName: '最大生命值', min: 0 })
+    maxHp = 100;
+
+    @property({ displayName: '当前生命值', min: 0 })
+    currentHp = 100000;
+
+    @property({ displayName: '血条动画时长', min: 0 })
+    animationDuration = 0.2;
+
+    // 初始化时限制当前血量并同步进度条。
+    protected onLoad(): void {
+        this.setHp(this.currentHp, false);
+    }
+
+    // 从代码批量设置血量组件配置并立即同步进度条。
+    public configure(config: FlyBaseHpConfig): void {
+        if (config.maxHp !== undefined && Number.isFinite(config.maxHp)) {
+            this.maxHp = Math.max(1, config.maxHp);
+        }
+        if (config.animationDuration !== undefined && Number.isFinite(config.animationDuration)) {
+            this.animationDuration = Math.max(0, config.animationDuration);
+        }
+        const currentHp = config.currentHp !== undefined && Number.isFinite(config.currentHp)
+            ? config.currentHp
+            : this.currentHp;
+        this.setHp(currentHp, false);
+    }
+
+    // 当前生命值归零时视为死亡。
+    public get isDead(): boolean {
+        return this.currentHp <= 0;
+    }
+
+    // 扣除指定生命值，血量不会低于零。
+    public takeDamage(amount: number): void {
+        if (!Number.isFinite(amount) || amount <= 0) return;
+        this.setHp(this.currentHp - amount);
+    }
+
+    // 恢复指定生命值，血量不会超过最大值。
+    public heal(amount: number, animate = true): void {
+        if (!Number.isFinite(amount) || amount <= 0) return;
+        this.setHp(this.currentHp + amount, animate);
+    }
+
+    // 设置并限制生命值，同时按 0 到 1 的比例更新进度条。
+    public setHp(value: number, animate = true): void {
+        const safeMaxHp = Math.max(0, this.maxHp);
+        this.currentHp = Math.min(safeMaxHp, Math.max(0, value));
+        if (this.textLabel) {
+            this.textLabel.string = `${Math.ceil(this.currentHp)}/${Math.ceil(safeMaxHp)}`;
+        }
+        if (this.progressBar) {
+            const progress = safeMaxHp > 0 ? this.currentHp / safeMaxHp : 0;
+            if (animate && this.animationDuration > 0) {
+                this.playProgressAnimation(progress);
+            } else {
+                Tween.stopAllByTarget(this.progressBar);
+                this.progressBar.progress = progress;
+            }
+        }
+    }
+
+    protected playProgressAnimation(targetProgress: number): void {
+        if (!this.progressBar) return;
+
+        Tween.stopAllByTarget(this.progressBar);
+        tween(this.progressBar)
+            .to(this.animationDuration, { progress: targetProgress }, { easing: 'sineOut' })
+            .start();
+    }
+
+    // 将生命值恢复到最大值。
+    public resetHp(): void {
+        this.setHp(this.maxHp);
+    }
+}
+

package/assets/fly/base/FlyBaseHp.ts.meta

@@ -0,0 +1,9 @@
+{
+  "ver": "4.0.24",
+  "importer": "typescript",
+  "imported": true,
+  "uuid": "bb9456c6-0528-4e71-9d8c-a6d41f4d25ee",
+  "files": [],
+  "subMetas": {},
+  "userData": {}
+}