godot-ability-system
Expert patterns for RPG/action ability systems including cooldown strategies, combo systems, ability chaining, skill trees with prerequisites, upgrade paths, and resource management. Use when implementing unlockable abilities, character progression, or complex skill systems. Trigger keywords: PlayerAbility, AbilityManager, cooldown, SkillTree, SkillNode, prerequisites, can_use, execute, ComboSystem, ability_chain, global_cooldown, charge_system, upgrade_path.
thedivergentai · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add thedivergentai/GD-Agentic-Skills --skill godot-ability-system技能说明
name: godot-ability-system description: "Expert patterns for RPG/action ability systems including cooldown strategies, combo systems, ability chaining, skill trees with prerequisites, upgrade paths, and resource management. Use when implementing unlockable abilities, character progression, or complex skill systems. Trigger keywords: PlayerAbility, AbilityManager, cooldown, SkillTree, SkillNode, prerequisites, can_use, execute, ComboSystem, ability_chain, global_cooldown, charge_system, upgrade_path."
Architecture Decision: Where Does the Manager Live?
| Scope | Policy | Script |
|---|---|---|
| Per character / enemy / turret | Scene-scoped manager as child (default) | ability_manager.gd or composition ability_container.gd on the entity |
| Shared unlock / loadout catalog across scenes | Autoload catalog / progression only (ranks, unlock flags) — not live cast state | Thin Autoload data; casts still go through the entity manager |
| Global "cast any ability anywhere" Autoload | Avoid | Breaks encapsulation and multiplayer authority |
Resolved policy: Live cooldowns, GCD, and execute() run on a scene-scoped AbilityManager / AbilityContainer under the caster. Autoloads may store unlock ranks; they must not be the combat cast oracle. Skill-tree UI reads/writes progression data, then calls into the caster’s manager — never /root/AbilityManager.use_* for combat.
NEVER Do
- NEVER tick cooldowns / status durations in
_process()— Use_physics_process(delta)or one-shot Timers so cooldowns stay deterministic under frame spikes. - NEVER forget global cooldown (GCD) when design needs anti-spam — Small shared lock (0.5–1.5s) between casts when required.
- NEVER hardcode ability effects in the manager — Strategy: each ability is a Resource / node with
execute()(ability_resource.gd). - NEVER allow casts during animation lock — Gate on
is_casting/ anim signals. - NEVER save remaining cooldown floats without time normalization — Persist absolute end timestamps (
Time.get_unix_time_from_system() + remaining). - NEVER put live combat cast state in a global Autoload — Scene-scoped manager (see decision table). Progression Autoloads are fine.
- NEVER blindly ban or blindly require object pools — GDScript refcounting makes pool-optional for light VFX; do pool when spawn/despawn of projectiles/AoE is high-frequency or allocation shows up in the profiler. Prefer instantiate/
queue_freeuntil measured otherwise. - NEVER grow deep ability inheritance trees — Compose Resources + containers (godot-composition).
Golden Path (MANDATORY)
- ability_resource.gd — data + virtual
execute() - ability_manager.gd or ability_container.gd — scene-scoped cast/cooldown
- buff_stat.gd — when buffs/modifiers exist
- Damage resolution → godot-combat-system
Do NOT paste inline AbilityManager / ComboSystem / SkillTreeManager novels into scenes. Skill trees are progression UI + prerequisite graphs that grant Resources to the caster’s container.
Available Scripts
- ability_resource.gd — MANDATORY before new abilities
- ability_manager.gd — MANDATORY Resource-driven cooldown registry (scene-scoped)
- ability_container.gd — MANDATORY alternative: node/Timer composition per ability
- buff_stat.gd — modular buff stats (Do NOT Load if no buffs)
- combo_tracker.gd — windowed combo chains → finisher abilities
- charge_ability.gd — multi-charge recharge (Flash-style)
- skill_node.gd / skill_tree_manager.gd — prerequisite graphs + point spend (progression only)
- status_effect.gd / status_effect_manager.gd — ticking DoTs/buffs (
duplicate(true)required) - ability_caster_network.gd — predict locally, authority validates RPC shell
Cooldown & Status Timing Contract
- Cooldown registry updates and status
process_tickmust use physics-frame delta (_physics_process) orTimernodes owned by the container. - Hit detection from abilities stays on the physics tick when applying impulses / queries.
- UI may read cooldown progress in
_process; it must not own the truth.
Expert Techniques (short)
- Dependency injection: parents inject caster context; abilities do not
get_node("/root/Player"). - Duck-typed hits:
has_method(&"take_damage")/ combat DamageData — see combat skill. - AoE:
call_groupor space queries; do not scan the whole tree each cast. - Networking: predict locally, authority validates
can_use+ costs (godot-multiplayer-networking). - Skill-tree visualizer:
@toolGraphEdit for design-time graphs; runtime still grants Resources to scene managers.
Status Effects & Combos (critical WHY)
CAUTION: Status/buff templates applied at runtime must use
duplicate(true). One poisoned.tresmutates every character sharing that asset — see status_effect_manager.gd.
- Combos: combo_tracker.gd — sequence window + recipe table; finishers remain normal
AbilityResourceentries. - Charges: charge_ability.gd —