godot-ability-system

架构决策：管理器应放在哪里？

范围	策略	脚本
每个角色／敌人／炮塔	以场景为作用域的管理器，作为子节点（默认）	实体上的 ability_manager.gd，或组合式 ability_container.gd
跨场景共享的解锁／配置目录	Autoload 仅存储目录／进度数据（等级、解锁标记）——不存储实时施法状态	精简的 Autoload 数据；施法仍通过实体管理器进行
全局“可在任何地方施放任意能力”的 Autoload	避免使用	会破坏封装性和多人游戏中的权威性

已确定的策略：实时冷却、GCD 和 execute() 由施法者下的场景作用域 AbilityManager / AbilityContainer 处理。Autoload 可以存储解锁等级，但不得作为战斗施法的判定依据。技能树 UI 读取／写入进度数据，然后调用施法者的管理器——战斗中绝不调用 /root/AbilityManager.use_*。

绝对不要做

• 绝不要在 _process() 中计时冷却／状态持续时间——使用 _physics_process(delta) 或一次性 Timer，确保冷却时间在帧率突增时仍保持确定性。
• 设计需要防止连续施法时，绝不要忘记全局冷却（GCD）——需要时，在施法之间设置短暂的共享锁（0.5–1.5 秒）。
• 绝不要在管理器中硬编码能力效果——采用策略模式：每项能力都是一个带有 execute() 的 Resource／节点（ability_resource.gd）。
• 绝不要允许在动画锁定期间施法——通过 is_casting／动画信号进行限制。
• 绝不要在未进行时间标准化的情况下保存剩余冷却时间浮点数——持久化绝对结束时间戳（Time.get_unix_time_from_system() + remaining）。
• 绝不要将实时战斗施法状态放入全局 Autoload——使用场景作用域的管理器（见决策表）。进度数据可以放在 Autoload 中。
• 绝不要一概禁止或一概要求使用对象池——GDScript 的引用计数机制意味着轻量级 VFX 可以不使用对象池；当弹幕／范围效果的生成／销毁频率很高，或分析器显示存在分配开销时，应使用对象池。在测量结果证明有必要之前，优先使用 instantiate／queue_free。
• 绝不要构建深层的能力继承树——使用 Resources + 容器进行组合（godot-composition）。

---

黄金路径（强制）

1. ability_resource.gd — 数据 + 虚拟 execute()
2. ability_manager.gd 或 ability_container.gd — 场景作用域的施法／冷却
3. buff_stat.gd — 存在增益／修正效果时使用
4. 伤害结算 → godot-combat-system

不要将冗长的内联 AbilityManager / ComboSystem / SkillTreeManager 代码粘贴到场景中。技能树是进度 UI + 前置条件图，用于向施法者的容器授予 Resources。

可用脚本

• ability_resource.gd — 新建能力前必须阅读
• ability_manager.gd — 必须使用由 Resource 驱动的冷却注册表（场景范围）
• ability_container.gd — 必须使用的替代方案：为每项能力组合节点/Timer
• buff_stat.gd — 模块化增益属性（没有增益时不要加载）
• combo_tracker.gd — 带时间窗口的连击链 → 终结技
• charge_ability.gd — 多层充能恢复（类似 Flash）
• skill_node.gd / skill_tree_manager.gd — 前置条件图 + 点数消耗（仅用于成长系统）
• status_effect.gd / status_effect_manager.gd — 持续触发的 DoT/增益（需要 duplicate(true)）
• ability_caster_network.gd — 本地预测，由权威端验证 RPC 框架

冷却与状态计时约定

• 冷却注册表更新和状态 process_tick 必须使用物理帧 delta（_physics_process），或使用由容器持有的 Timer 节点。
• 能力的命中检测在施加冲量/执行查询时，仍须在物理帧中进行。
• UI 可以在 _process 中读取冷却进度，但不能作为其数据来源。

专家技巧（简要）

• **依赖注入：**父节点注入施法者上下文；能力不得调用 get_node("/root/Player")。
• 鸭子类型命中：has_method(&"take_damage") / 战斗 DamageData — 参见战斗技能。
• **范围效果（AoE）：**使用 call_group 或空间查询；每次施放时不要扫描整个场景树。
• **网络：**本地预测，由权威端验证 can_use + 费用（godot-multiplayer-networking）。
• **技能树可视化工具：**使用 @tool GraphEdit 构建设计时图；运行时仍由场景管理器授予 Resources。

状态效果与连击（关键原因）

注意：运行时应用的状态/增益模板必须使用 duplicate(true)。一个被污染的 .tres 会影响所有共享该资源的角色 — 参见 status_effect_manager.gd。

• 连击：combo_tracker.gd — 序列时间窗口 + 配方表；终结技仍作为普通的 AbilityResource 条目。
• 充能：charge_ability.gd — 恢复计时应在 _physics_process 中执行，而不是 UI 的 _process。
• 技能树：skill_tree_manager.gd 将能力授予施法者的场景管理器 — 成长系统的 Autoload 只保存等级。
• 保存冷却：持久化绝对结束时间戳（Time.get_unix_time_from_system() + remaining），而不是原始剩余秒数浮点值 — 可防止通过时钟/加载利用漏洞。

对于超出上述要点的连击/充能/技能树/状态/网络深度内容，必须阅读：elite-ability-patterns.md。首次实现 AbilityResource + AbilityManager 时不要加载。

参考

**渐进式披露：**仅在需要实现相应 API（Resources、计时器、信号、存档、多人游戏）时浏览官方文档。连接相邻系统时再打开相关技能 — 不要预先加载整个技能体系。

官方文档

• 资源 — 技能定义、增益效果和状态效果应使用 Resource 数据（而非硬编码在管理器的分支中），这样设计师就能创建和共享资源。
• Resource — 在运行时应用状态效果／增益效果模板时使用 duplicate(true)，以免一个角色的计时状态修改所有角色共享的 .tres。
• GDScript 导出变量 — 使用 @export / @export_group，即可在技能 Resource 的检查器中调整消耗、冷却时间、前置条件和效果数组。
• 使用信号 — 发出 ability_cast、ability_ready 和冷却生命周期信号，让 UI 和特效无需耦合到 AbilityManager 内部即可订阅。
• 场景组织 — 遵循“信号向上、调用向下”：父节点／UI 负责监听；管理器调用技能 Resource／节点，而不是通过全局方式获取战斗状态。
• 空闲处理与物理处理 — 在 _physics_process（固定增量）中推进冷却时间和 GCD；避免在 _process 中进行冷却计算，因为帧率骤降会导致不同步。
• Timer — 在容器式管理器中，为每个技能添加单次触发的 Timer 子节点，是一种简洁的组合模式。
• SceneTreeTimer — create_timer() / await 模式适用于施法时间和短时增益效果，无需为每次施法都添加持久的 Timer 节点。
• 群组 — AoE 技能应使用 call_group（或查询群组），而不是每次命中目标时都手动扫描场景。
• 时间 — 在保存／加载时持久化冷却时间的结束时间戳（get_unix_time_from_system() + 剩余时间），而不是原始剩余时间浮点数。
• 保存游戏 — 将技能解锁等级和绝对冷却结束时间，与其他玩家进度数据一并序列化。
• 高级多人游戏 — 权威施法验证 + @rpc 确认／取消，是引擎对预测式技能施放的基础支持。

相关技能

前置条件

• godot-resource-data-patterns — 技能、增益效果和技能树节点应优先使用 Resource；在为技能数据设计自定义序列化或继承树之前，请先加载此项。
• godot-signal-architecture — 施放／就绪／冷却信号和 UI 钩子依赖规范的信号归属，确保 AbilityManager 与角色和 HUD 解耦。
• godot-composition — 对运行时行为，优先使用 AbilityContainer／组件节点，而非深层的 BaseAbility → MagicAbility → FireAbility 继承。
• godot-gdscript-mastery — 虚拟 execute() / can_cast()、类型化 Resource 以及基于计时器等待的施法流程，都要求掌握扎实的 GDScript 模式。

配套技能

• godot-combat-system — 伤害、受击反应和目标选择管线会使用技能 execute() 的结果；请将 DamageData 与技能元数据分开。
• godot-rpg-stats — 法力／体力消耗、技能等级带来的属性加成以及增益倍率，都需要统一的属性／修正值层。
• godot-input-handling — 快捷栏／动作映射输入应调用 can_use / use_ability，而不是在输入回调中嵌入冷却逻辑。
• godot-animation-player — 动画锁定和施法预警可限制技能连发；将 AnimationPlayer 的开始／结束信号接入 is_casting。
• godot-state-machine-advanced — 施法、引导和打断状态应属于角色状态机，由状态机向技能管理器发起请求，而不是反过来。
• godot-save-load-systems — 技能等级、解锁标记和绝对冷却结束时间必须能在项目存档架构中完整往返。

下游／使用方

• godot-monte-carlo-balancer — 冷却、消耗和伤害／效果资源可调后，可通过蒙特卡洛配装模拟验证技能 DPS／覆盖率区间，再发布数值曲线。
• godot-multiplayer-networking — 预测施法、权限检查和失败 RPC 的回滚，都基于技能管理器将 can_use 与 execute 分离的设计。
• godot-genre-action-rpg — 动作 RPG 的技能栏、技能树和技能连携会将此技能与战斗、属性及成长系统的类型整合逻辑组合起来。
• godot-inventory-system — 消耗型卷轴、技能书以及可授予技能的装备，可将物品栏中的技能授予操作接入 AbilityManager 注册。

主技能

• godot-master — 技能库路由器及镜像模块入口；用于查找同级技能，或在编辑 Domain Skill 后同步共享脚本镜像。