Godot Ability System

Architecture Decision: Where Does the Manager Live?

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_free until measured otherwise.
• NEVER grow deep ability inheritance trees — Compose Resources + containers (godot-composition).

---

Golden Path (MANDATORY)

1. ability_resource.gd — data + virtual execute()
2. ability_manager.gd or ability_container.gd — scene-scoped cast/cooldown
3. buff_stat.gd — when buffs/modifiers exist
4. 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_tick must use physics-frame delta (_physics_process) or Timer nodes 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_group or space queries; do not scan the whole tree each cast.
• Networking: predict locally, authority validates can_use + costs (godot-multiplayer-networking).
• Skill-tree visualizer: @tool GraphEdit 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 .tres mutates every character sharing that asset — see status_effect_manager.gd.

• Combos: combo_tracker.gd — sequence window + recipe table; finishers remain normal AbilityResource entries.
• Charges: charge_ability.gd — recharge ticks belong on _physics_process, not UI _process.
• Skill trees: skill_tree_manager.gd grants abilities to the caster's scene manager — progression Autoloads hold ranks only.
• Save cooldowns: persist absolute end timestamps (Time.get_unix_time_from_system() + remaining), not raw remaining floats — prevents clock/load exploits.

MANDATORY for combos/charges/skill-tree/status/network depth beyond bullets above: elite-ability-patterns.md. Do NOT Load for a first AbilityResource + AbilityManager pass.

Reference

Progressive disclosure: Skim Official Documentation only for the APIs you are implementing (Resources, timers, signals, save, multiplayer). Open Related Skills when wiring adjacent systems—do not preload the whole lattice.