feat(effect): 添加效果系统模块 (#332)

实现 Buff/Debuff 效果管理和属性修改器系统: 核心功能: - 效果容器管理效果的应用、移除和更新 - 支持持续时间类型: 永久/计时/条件 - 支持叠加规则: 刷新/叠加/独立/替换/忽略 - 效果标签系统用于分类和查询 - 效果优先级和互斥标签支持 - 效果事件系统 (应用/移除/叠加/刷新/跳动/过期) 修改器系统: - 属性修改器支持加法/乘法/覆盖/最小值/最大值操作 - 优先级分层计算 (基础/加法/乘法/最终) - 数值计算器自动按优先级应用修改器蓝图节点 (12个): - ApplyEffect: 应用效果 - RemoveEffect/RemoveEffectByTag: 移除效果 - HasEffect/HasEffectTag: 检查效果 - GetEffectStacks/GetEffectRemainingTime/GetEffectCount: 查询效果 - ClearAllEffects: 清除所有效果 - OnEffectApplied/OnEffectRemoved/OnEffectTick: 效果事件
2025-12-25 15:17:06 +08:00
parent 275124b66c
commit 4d501ba448
15 changed files with 1917 additions and 0 deletions
--- a/packages/effect/src/core/IEffect.ts
+++ b/packages/effect/src/core/IEffect.ts
@@ -0,0 +1,306 @@
+/**
+ * @zh 效果接口定义
+ * @en Effect Interface Definitions
+ */
+
+// =============================================================================
+// 持续时间类型 | Duration Types
+// =============================================================================
+
+/**
+ * @zh 持续时间类型
+ * @en Duration type
+ */
+export type DurationType = 'permanent' | 'timed' | 'conditional';
+
+/**
+ * @zh 持续时间配置
+ * @en Duration configuration
+ */
+export interface IEffectDuration {
+    /**
+     * @zh 持续时间类型
+     * @en Duration type
+     */
+    readonly type: DurationType;
+
+    /**
+     * @zh 持续时间（秒），仅 timed 类型有效
+     * @en Duration in seconds, only valid for timed type
+     */
+    readonly duration?: number;
+
+    /**
+     * @zh 剩余时间（秒）
+     * @en Remaining time in seconds
+     */
+    remainingTime?: number;
+
+    /**
+     * @zh 条件检查函数，仅 conditional 类型有效
+     * @en Condition check function, only valid for conditional type
+     */
+    readonly condition?: () => boolean;
+}
+
+// =============================================================================
+// 叠加规则 | Stacking Rules
+// =============================================================================
+
+/**
+ * @zh 叠加规则类型
+ * @en Stacking rule type
+ */
+export type StackingRule = 'refresh' | 'stack' | 'independent' | 'replace' | 'ignore';
+
+/**
+ * @zh 叠加配置
+ * @en Stacking configuration
+ */
+export interface IStackingConfig {
+    /**
+     * @zh 叠加规则
+     * @en Stacking rule
+     */
+    readonly rule: StackingRule;
+
+    /**
+     * @zh 最大叠加层数（stack 规则）
+     * @en Maximum stack count (for stack rule)
+     */
+    readonly maxStacks?: number;
+
+    /**
+     * @zh 每层效果强度倍率（stack 规则）
+     * @en Effect intensity multiplier per stack (for stack rule)
+     */
+    readonly stackMultiplier?: number;
+}
+
+// =============================================================================
+// 效果接口 | Effect Interface
+// =============================================================================
+
+/**
+ * @zh 效果定义
+ * @en Effect definition
+ */
+export interface IEffectDefinition {
+    /**
+     * @zh 效果类型 ID
+     * @en Effect type ID
+     */
+    readonly typeId: string;
+
+    /**
+     * @zh 显示名称
+     * @en Display name
+     */
+    readonly displayName: string;
+
+    /**
+     * @zh 描述
+     * @en Description
+     */
+    readonly description?: string;
+
+    /**
+     * @zh 图标
+     * @en Icon
+     */
+    readonly icon?: string;
+
+    /**
+     * @zh 标签（用于分组、互斥、增强）
+     * @en Tags (for grouping, exclusion, enhancement)
+     */
+    readonly tags: readonly string[];
+
+    /**
+     * @zh 持续时间配置
+     * @en Duration configuration
+     */
+    readonly duration: IEffectDuration;
+
+    /**
+     * @zh 叠加配置
+     * @en Stacking configuration
+     */
+    readonly stacking: IStackingConfig;
+
+    /**
+     * @zh 周期性触发间隔（秒），0 表示不周期触发
+     * @en Periodic trigger interval in seconds, 0 means no periodic trigger
+     */
+    readonly tickInterval?: number;
+
+    /**
+     * @zh 互斥标签（拥有这些标签的效果会被移除）
+     * @en Exclusive tags (effects with these tags will be removed)
+     */
+    readonly exclusiveTags?: readonly string[];
+
+    /**
+     * @zh 效果优先级（用于处理顺序）
+     * @en Effect priority (for processing order)
+     */
+    readonly priority?: number;
+}
+
+/**
+ * @zh 效果实例
+ * @en Effect instance
+ */
+export interface IEffectInstance {
+    /**
+     * @zh 实例唯一 ID
+     * @en Instance unique ID
+     */
+    readonly instanceId: string;
+
+    /**
+     * @zh 效果定义
+     * @en Effect definition
+     */
+    readonly definition: IEffectDefinition;
+
+    /**
+     * @zh 效果来源（施加者 ID）
+     * @en Effect source (applier ID)
+     */
+    readonly sourceId?: string;
+
+    /**
+     * @zh 当前叠加层数
+     * @en Current stack count
+     */
+    stacks: number;
+
+    /**
+     * @zh 剩余时间（秒）
+     * @en Remaining time in seconds
+     */
+    remainingTime: number;
+
+    /**
+     * @zh 下次触发时间（秒）
+     * @en Next tick time in seconds
+     */
+    nextTickTime: number;
+
+    /**
+     * @zh 效果数据
+     * @en Effect data
+     */
+    data: Record<string, unknown>;
+
+    /**
+     * @zh 效果是否激活
+     * @en Whether the effect is active
+     */
+    isActive: boolean;
+
+    /**
+     * @zh 应用时间戳
+     * @en Application timestamp
+     */
+    readonly appliedAt: number;
+}
+
+// =============================================================================
+// 效果事件 | Effect Events
+// =============================================================================
+
+/**
+ * @zh 效果事件类型
+ * @en Effect event type
+ */
+export type EffectEventType = 'applied' | 'removed' | 'stacked' | 'refreshed' | 'ticked' | 'expired';
+
+/**
+ * @zh 效果事件
+ * @en Effect event
+ */
+export interface IEffectEvent {
+    /**
+     * @zh 事件类型
+     * @en Event type
+     */
+    readonly type: EffectEventType;
+
+    /**
+     * @zh 效果实例
+     * @en Effect instance
+     */
+    readonly effect: IEffectInstance;
+
+    /**
+     * @zh 目标实体 ID
+     * @en Target entity ID
+     */
+    readonly targetId: string;
+
+    /**
+     * @zh 事件时间戳
+     * @en Event timestamp
+     */
+    readonly timestamp: number;
+
+    /**
+     * @zh 额外数据
+     * @en Extra data
+     */
+    readonly data?: Record<string, unknown>;
+}
+
+/**
+ * @zh 效果事件监听器
+ * @en Effect event listener
+ */
+export type EffectEventListener = (event: IEffectEvent) => void;
+
+// =============================================================================
+// 效果处理器 | Effect Handler
+// =============================================================================
+
+/**
+ * @zh 效果处理器接口
+ * @en Effect handler interface
+ */
+export interface IEffectHandler<TTarget = unknown> {
+    /**
+     * @zh 效果应用时调用
+     * @en Called when effect is applied
+     */
+    onApply?(effect: IEffectInstance, target: TTarget): void;
+
+    /**
+     * @zh 效果移除时调用
+     * @en Called when effect is removed
+     */
+    onRemove?(effect: IEffectInstance, target: TTarget): void;
+
+    /**
+     * @zh 效果叠加时调用
+     * @en Called when effect is stacked
+     */
+    onStack?(effect: IEffectInstance, target: TTarget, newStacks: number): void;
+
+    /**
+     * @zh 效果刷新时调用
+     * @en Called when effect is refreshed
+     */
+    onRefresh?(effect: IEffectInstance, target: TTarget): void;
+
+    /**
+     * @zh 效果周期触发时调用
+     * @en Called on periodic tick
+     */
+    onTick?(effect: IEffectInstance, target: TTarget, deltaTime: number): void;
+
+    /**
+     * @zh 效果更新时调用（每帧）
+     * @en Called on update (every frame)
+     */
+    onUpdate?(effect: IEffectInstance, target: TTarget, deltaTime: number): void;
+}