godot-genre-action-rpg

What this skill does

# Genre: Action RPG

Expert blueprint for action RPGs emphasizing real-time combat, character builds, loot, and progression.

## NEVER Do (Expert Anti-Patterns)

### Combat & Progression
- NEVER use linear damage scaling for progression; strictly use an **exponential curve** (e.g., `base * pow(1.15, level)`) to maintain the power fantasy.
- NEVER allow defense stats to stack linearly to 100%; strictly use a **Diminishing Returns** formula (e.g., `armor / (armor + 100.0)`) to prevent invincibility.
- NEVER skip Hit Recovery (Stagger); strictly implement a brief stagger state (0.2s - 0.5s) on significant hits to prevent "floaty" combat.
- NEVER hide critical stats from the player; strictly provide a detailed character sheet for theory-crafting (Crit Chance, Resistance, etc.).
- NEVER make loot drops visually identical; strictly differentiate rarities with color-coded beams (purple/gold) and distinct sound cues.
- NEVER calculate hitboxes, knockbacks, or combat movement in `_process()`; strictly use `_physics_process()` for deterministic results.
- NEVER evaluate exact floating-point equality (==) for combat thresholds; strictly use `is_equal_approx()`.
- NEVER use the ! (NOT) operator in AnimationTree Advance Condition expressions; strictly use explicit boolean equality (`is_walking == false`).

### Technical & Architecture
- NEVER store character stats or massive inventories as Nodes; strictly use **Resource-based data containers** for lightweight memory overhead.
- NEVER forget to call `duplicate()` on shared Resources; modifying one goblin's stats must not affect all other instances.
- NEVER rigidly couple combat detection to specific classes; strictly use **Duck-Typing** (e.g., `if body.has_method(&"take_damage")`) for interaction.
- NEVER rely on the UI SceneTree as the source of truth for inventory; strictly separate data logic from visualization.
- NEVER recalculate stats every frame; strictly trigger recalculation only on gear changes or level-ups.
- NEVER parse massive RPG save files synchronously; strictly offload heavy parsing to the `WorkerThreadPool`.
- NEVER synchronize complex Resource types over the network; strictly serialize changes into primitive Dictionaries or PackedByteArrays.
- NEVER manage character state by coupling child nodes to parent existence; strictly use signals for loose coupling ("Signal Up, Call Down").
- NEVER use standard Strings for high-frequency AI state identifiers; strictly use `StringName` for optimized hash comparisons.

### Performance & AI
- NEVER instantiate/destroy hundreds of objects (projectiles, damage text) per second; strictly use **Object Pooling**.
- NEVER delete active combat entities via `free()`; strictly use `queue_free()` for safe deferred disposal.
- NEVER calculate complex loot drops or parse massive late-game inventories on the main thread; strictly offload heavy RNG rolls and array iterations to the **WorkerThreadPool**.
- NEVER use nested if/elif blocks for complex Boss AI; strictly use a modular **StateMachine** or pattern matching.
- NEVER iterate through the SceneTree for global state changes; strictly use **Signal Groups** (`call_group()`).
- NEVER move `OccluderInstance3D` nodes attached to dynamic characters; this causes CPU BVH rebuild stalls.

---

## 🛠 Expert Components (scripts/)

### Original Expert Patterns
- [damage_label_manager.gd](scripts/damage_label_manager.gd) - High-performance pooled system for floating damage numbers and critical hits.
- [telegraphed_enemy.gd](scripts/telegraphed_enemy.gd) - Advanced AI component for Soul-like wind-ups, AOE indicators, and timed attacks.

### Modular Components
- [character_stats_resource.gd](scripts/character_stats_resource.gd) - Modular data container for base RPG attributes and scaling logic.
- [entity_stat_duplicator.gd](scripts/entity_stat_duplicator.gd) - Pattern for ensuring unique death/health state for instanced enemies.
- [duck_typed_hitbox.gd](scripts/duck_typed_hitbox.gd) - Safe combat interaction system for players, enemies, and props.
- [combat_log_connector.gd](scripts/combat_log_connector.gd) - Signal-binding logic for decoupled combat event logging.
- [aoe_physics_query.gd](scripts/aoe_physics_query.gd) - Performance-optimized AoE detection using direct PhysicsServer queries.
- [hierarchical_state_base.gd](scripts/hierarchical_state_base.gd) - Robust base for managing complex ARPG character behavior.
- [animation_condition_sync.gd](scripts/animation_condition_sync.gd) - Safe synchronization logic for AnimationTree Advance Conditions.
- [threaded_inventory_loader.gd](scripts/threaded_inventory_loader.gd) - WorkerThreadPool-driven background parsing for large inventories.
- [typed_inventory_storage.gd](scripts/typed_inventory_storage.gd) - High-performance strongly-typed dictionary for item storage.
- [high_speed_aggro_broadcaster.gd](scripts/high_speed_aggro_broadcaster.gd) - Group-based broadcasting pattern for instant localized AI alerts.

---

## Core Loop

`Combat → Loot → Level Up → Build Power → Challenge Harder Content → Repeat`

## Skill Chain

`godot-project-foundations`, `godot-characterbody-2d`, `godot-combat-system`, `godot-rpg-stats`, `godot-inventory-system`, `godot-ability-system`, `godot-quest-system`, `godot-economy-system`, `godot-save-load-systems`

---

## Combat System

### Real-Time Combat with Stats

```gdscript
class_name CombatController
extends Node

signal damage_dealt(target: Node, amount: int, type: String)
signal enemy_killed(enemy: Node, xp_reward: int)

func calculate_damage(attacker: RPGStats, defender: RPGStats, base_damage: int) -> Dictionary:
    # Physical damage formula
    var attack_power := attacker.get_stat("strength") * 2 + base_damage
    var defense := defender.get_stat("armor")
    
    # Damage reduction formula (diminishing returns)
    var reduction := defense / (defense + 100.0)
    var final_damage := int(attack_power * (1.0 - reduction))
    
    # Critical hit check
    var crit_chance := attacker.get_stat("crit_chance") / 100.0
    var is_crit := randf() < crit_chance
    if is_crit:
        final_damage = int(final_damage * attacker.get_stat("crit_damage") / 100.0)
    
    return {
        "damage": max(1, final_damage),
        "is_crit": is_crit,
        "damage_type": "physical"
    }

func apply_damage(target: Node, damage_result: Dictionary) -> void:
    if target.has_method("take_damage"):
        target.take_damage(damage_result["damage"], damage_result["is_crit"])
        damage_dealt.emit(target, damage_result["damage"], damage_result["damage_type"])
```

### Hitbox/Hurtbox Combat

```gdscript
class_name Hitbox
extends Area2D

@export var damage: int = 10
@export var knockback_force: float = 200.0
@export var attack_owner: Node

var has_hit: Array[Node] = []  # Prevent multi-hit per swing

func _ready() -> void:
    monitoring = false  # Enable only during attack frames

func enable() -> void:
    has_hit.clear()
    monitoring = true

func disable() -> void:
    monitoring = false

func _on_area_entered(area: Area2D) -> void:
    if area is Hurtbox:
        var target := area.owner_entity
        if target != attack_owner and target not in has_hit:
            has_hit.append(target)
            var result := CombatController.calculate_damage(
                attack_owner.stats, target.stats, damage
            )
            CombatController.apply_damage(target, result)
            apply_knockback(target)

func apply_knockback(target: Node) -> void:
    var direction := (target.global_position - attack_owner.global_position).normalized()
    if target.has_method("apply_knockback"):
        target.apply_knockback(direction * knockback_force)
```

---

## RPG Stats System

### Attribute-Based Stats

```gdscript
class_name RPGStats
extends Resource

signal stat_changed(stat_name: String, new_value: float)
signal level_up(new_level: int)

# Base attributes (increased on level up)
@export var strength: int = 10
@export var dexterity: int = 10
@export var