Godot Genre Action Rpg

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 - High-performance pooled system for floating damage numbers and critical hits.
• telegraphed_enemy.gd - Advanced AI component for Soul-like wind-ups, AOE indicators, and timed attacks.

Modular Components

• character_stats_resource.gd - Modular data container for base RPG attributes and scaling logic.
• entity_stat_duplicator.gd - Pattern for ensuring unique death/health state for instanced enemies.
• duck_typed_hitbox.gd - Safe combat interaction system for players, enemies, and props.
• combat_log_connector.gd - Signal-binding logic for decoupled combat event logging.
• aoe_physics_query.gd - Performance-optimized AoE detection using direct PhysicsServer queries.
• hierarchical_state_base.gd - Robust base for managing complex ARPG character behavior.
• animation_condition_sync.gd - Safe synchronization logic for AnimationTree Advance Conditions.
• threaded_inventory_loader.gd - WorkerThreadPool-driven background parsing for large inventories.
• typed_inventory_storage.gd - High-performance strongly-typed dictionary for item storage.
• 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

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

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

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 intelligence: int = 10
@export var vitality: int = 10

# Derived stats (calculated from attributes)
var derived_stats: Dictionary = {}

# Modifiers from equipment, buffs, etc.
var flat_modifiers: Dictionary = {}    # +50 health
var percent_modifiers: Dictionary = {} # +10% damage

var level: int = 1
var experience: int = 0
var skill_points: int = 0

func _init() -> void:
    recalculate_stats()

func recalculate_stats() -> void:
    derived_stats = {
        # Health: Vitality-based
        "max_health": vitality * 10 + 100,
        "health_regen": vitality * 0.5,
        
        # Mana: Intelligence-based
        "max_mana": intelligence * 8 + 50,
        "mana_regen": intelligence * 0.3,
        
        # Physical: Strength + Dexterity
        "physical_damage": strength * 2,
        "armor": strength + vitality,
        
        # Critical: Dexterity-based
        "crit_chance": 5.0 + dexterity * 0.2,
        "crit_damage": 150.0 + dexterity * 0.5,
        
        # Speed: Dexterity-based
        "attack_speed": 1.0 + dexterity * 0.01,
        "move_speed": 100.0 + dexterity * 2
    }
    
    # Apply modifiers
    for stat_name in derived_stats:
        var base := derived_stats[stat_name]
        var flat := flat_modifiers.get(stat_name, 0.0)
        var percent := percent_modifiers.get(stat_name, 0.0)
        derived_stats[stat_name] = (base + flat) * (1.0 + percent / 100.0)

func get_stat(stat_name: String) -> float:
    if stat_name in derived_stats:
        return derived_stats[stat_name]
    return get(stat_name)

func add_experience(amount: int) -> void:
    experience += amount
    while experience >= get_xp_for_next_level():
        experience -= get_xp_for_next_level()
        level += 1
        skill_points += 5
        level_up.emit(level)

func get_xp_for_next_level() -> int:
    # Exponential scaling
    return int(100 * pow(1.5, level - 1))

---

Loot System

Item Generation

class_name LootGenerator
extends Node

enum Rarity { COMMON, UNCOMMON, RARE, EPIC, LEGENDARY }

const RARITY_WEIGHTS := {
    Rarity.COMMON: 60,
    Rarity.UNCOMMON: 25,
    Rarity.RARE: 10,
    Rarity.EPIC: 4,
    Rarity.LEGENDARY: 1
}

const RARITY_AFFIX_COUNT := {
    Rarity.COMMON: 0,
    Rarity.UNCOMMON: 1,
    Rarity.RARE: 2,
    Rarity.EPIC: 3,
    Rarity.LEGENDARY: 4
}

@export var affix_pool: Array[ItemAffix]
@export var base_items: Array[ItemBase]

func generate_item(item_level: int, magic_find: float = 0.0) -> Item:
    var rarity := roll_rarity(magic_find)
    var base := base_items.pick_random()
    
    var item := Item.new()
    item.base = base
    item.rarity = rarity
    item.item_level = item_level
    
    # Roll affixes based on rarity
    var affix_count := RARITY_AFFIX_COUNT[rarity]
    var available_affixes := affix_pool.duplicate()
    
    for i in affix_count:
        if available_affixes.is_empty():
            break
        var affix := available_affixes.pick_random()
        available_affixes.erase(affix)
        item.affixes.append(generate_affix_roll(affix, item_level))
    
    return item

func roll_rarity(magic_find: float) -> Rarity:
    var weights := RARITY_WEIGHTS.duplicate()
    # Magic find increases rare+ drops
    weights[Rarity.RARE] *= (1.0 + magic_find / 100.0)
    weights[Rarity.EPIC] *= (1.0 + magic_find / 100.0)
    weights[Rarity.LEGENDARY] *= (1.0 + magic_find / 100.0)
    
    var total := 0.0
    for w in weights.values():
        total += w
    
    var roll := randf() * total
    for rarity in weights:
        roll -= weights[rarity]
        if roll <= 0:
            return rarity
    return Rarity.COMMON

func generate_affix_roll(affix: ItemAffix, item_level: int) -> Dictionary:
    # Scale affix values with item level
    var min_roll := affix.min_value * (1.0 + item_level * 0.1)
    var max_roll := affix.max_value * (1.0 + item_level * 0.1)
    return {
        "affix": affix,
        "value": randf_range(min_roll, max_roll)
    }

Equipment System

class_name Equipment
extends Node

signal equipment_changed(slot: String, item: Item)

enum Slot { HEAD, CHEST, HANDS, LEGS, FEET, WEAPON, OFFHAND, RING1, RING2, AMULET }

var equipped: Dictionary = {}  # Slot -> Item

func equip(item: Item) -> Item:
    var slot: Slot = item.base.slot
    var previous: Item = equipped.get(slot)
    
    # Unequip old item
    if previous:
        remove_item_stats(previous)
    
    # Equip new item
    equipped[slot] = item
    apply_item_stats(item)
    equipment_changed.emit(Slot.keys()[slot], item)
    
    return previous  # Return to inventory

func apply_item_stats(item: Item) -> void:
    var stats := owner.stats as RPGStats
    
    # Base stats
    for stat_name in item.base.base_stats:
        stats.flat_modifiers[stat_name] = stats.flat_modifiers.get(stat_name, 0) + item.base.base_stats[stat_name]
    
    # Affix stats
    for affix_data in item.affixes:
        var affix := affix_data["affix"] as ItemAffix
        var value := affix_data["value"]
        if affix.is_percent:
            stats.percent_modifiers[affix.stat] = stats.percent_modifiers.get(affix.stat, 0) + value
        else:
            stats.flat_modifiers[affix.stat] = stats.flat_modifiers.get(affix.stat, 0) + value
    
    stats.recalculate_stats()

---

Ability System

Skill Trees and Unlocks

class_name SkillTree
extends Resource

@export var skills: Array[Skill]
@export var connections: Dictionary  # skill_id -> Array[prerequisite_ids]

func can_unlock(skill_id: String, unlocked_skills: Array[String]) -> bool:
    if skill_id in unlocked_skills:
        return false  # Already unlocked
    
    var prereqs: Array = connections.get(skill_id, [])
    for prereq in prereqs:
        if prereq not in unlocked_skills:
            return false
    return true

func unlock_skill(skill_id: String, player: Node) -> bool:
    var skill := get_skill(skill_id)
    if not skill or player.stats.skill_points < skill.cost:
        return false
    
    player.stats.skill_points -= skill.cost
    player.unlocked_skills.append(skill_id)
    player.ability_manager.add_ability(skill.ability)
    return true

Active Abilities

class_name ActiveAbility
extends Resource

@export var name: String
@export var cooldown: float = 5.0
@export var mana_cost: int = 20
@export var damage_multiplier: float = 2.0
@export var aoe_radius: float = 0.0
@export var effect_scene: PackedScene

var current_cooldown: float = 0.0

func can_use(caster: Node) -> bool:
    return current_cooldown <= 0 and caster.stats.current_mana >= mana_cost

func use(caster: Node, target_position: Vector2) -> void:
    if not can_use(caster):
        return
    
    caster.stats.current_mana -= mana_cost
    current_cooldown = cooldown
    
    var effect := effect_scene.instantiate()
    effect.global_position = target_position
    effect.damage = int(caster.stats.get_stat("physical_damage") * damage_multiplier)
    effect.caster = caster
    caster.get_tree().current_scene.add_child(effect)

func update_cooldown(delta: float) -> void:
    current_cooldown = max(0, current_cooldown - delta)

---

Enemy Design

Scaling Difficulty

class_name EnemySpawner
extends Node

@export var base_enemy_scene: PackedScene
@export var area_level: int = 1

func spawn_enemy(position: Vector2) -> Node:
    var enemy := base_enemy_scene.instantiate()
    enemy.global_position = position
    
    # Scale stats with area level
    var stats := enemy.stats as RPGStats
    var level_mult := 1.0 + (area_level - 1) * 0.15
    
    stats.vitality = int(stats.vitality * level_mult)
    stats.strength = int(stats.strength * level_mult)
    stats.recalculate_stats()
    
    # Scale rewards
    enemy.xp_reward = int(enemy.xp_reward * level_mult)
    enemy.loot_table.item_level = area_level
    
    add_child(enemy)
    return enemy

---

Common Pitfalls

---

Architecture Overview

AutoLoads:
├── PlayerStats (godot-rpg-stats)
├── InventoryManager (godot-inventory-system)
├── QuestManager (godot-quest-system)
├── LootGenerator (godot-economy-system)
└── GameManager (godot-scene-management)

Player:
├── CharacterBody2D/3D
├── RPGStats
├── Equipment
├── AbilityManager
├── Hitbox/Hurtbox
└── InputHandler

Enemies:
├── AI Controller (state machine)
├── RPGStats (scaled)
├── HealthComponent
├── LootTable
└── Hitbox/Hurtbox

---

Godot-Specific Tips

1. Resources for items: Use Resource for items - easily serializable for save/load 2. Object pooling: Pool damage numbers, projectiles, item pickups 3. Animation callbacks: Use AnimationPlayer method tracks to enable/disable hitboxes 4. Stat recalculation: Only recalculate on equip/level, not every frame

---

Example Games for Reference

• Diablo / Path of Exile - Loot-focused ARPG
• Elden Ring / Dark Souls - Combat-focused action RPG
• Hades - Roguelike ARPG hybrid
• Grim Dawn - Deep character builds

Advanced ARPG Meta-Systems

Expert implementation of high-end ARPG systems for endgame progression and visual polish.

1. Paragon/Ascension System (Resource-Based Progression)

For post-level-cap progression, utilize a custom Resource. This allows for encapsulated methods, signals for UI updates, and efficient serialization.

class_name ParagonStats extends Resource

@export var paragon_level: int = 0
@export var bonus_strength: float = 0.0
@export var bonus_vitality: float = 0.0

const XP_REQUIREMENT_BASE: int = 10000
var current_xp: int = 0

func add_paragon_experience(amount: int) -> void:
    current_xp += amount
    var leveled_up: bool = false
    
    while current_xp >= _get_xp_requirement():
        current_xp -= _get_xp_requirement()
        paragon_level += 1
        bonus_strength += 2.5
        bonus_vitality += 1.5
        leveled_up = true
        
    if leveled_up:
        emit_changed() # Notify UI and combat systems

func _get_xp_requirement() -> int:
    return XP_REQUIREMENT_BASE * (paragon_level + 1)

Architectural Tip: When assigning a paragon template to a character, always use duplicate(true) to avoid modifying the globally cached resource instance.

2. Shader-Based Loot Beams (Visual Cues)

To handle massive loot drops without performance degradation, use the RenderingServer to pass rarity parameters to a shared shader without duplicating materials.

loot_beam.gdshader

shader_type spatial;
render_mode unshaded, cull_disabled;

uniform vec3 rarity_color = vec3(1.0, 1.0, 1.0);

void fragment() {
    ALBEDO = rarity_color;
    EMISSION = rarity_color * 3.0; # High emission for glowing effect
}

loot_drop_manager.gd

class_name LootDropManager extends Node

# Update visual rarity without material duplication overhead
func apply_rarity_visuals(mesh_instance: MeshInstance3D, color: Color) -> void:
    if mesh_instance:
        # Use low-level RenderingServer for high-performance per-instance parameters
        RenderingServer.instance_geometry_set_shader_parameter(
            mesh_instance.get_instance_id(), 
            "rarity_color", 
            color
        )

3. Stat-Snapshot System (Combat Logging)

Combat logs should capture isolated state snapshots in a Dictionary and be flushed to disk periodically to avoid I/O bottlenecks.

class_name CombatLogger extends Node

const LOG_FILE_PATH: String = "user://combat_log.json"
var _session_buffer: Array[Dictionary] = []

func record_event(source: String, target: String, damage: int, is_crit: bool) -> void:
    var snapshot: Dictionary = {
        "timestamp": Time.get_unix_time_from_system(),
        "source": source,
        "target": target,
        "damage": damage,
        "is_crit": is_crit
    }
    _session_buffer.append(snapshot)
    
    # Periodic flush (e.g., every 100 entries) to prevent memory bloat
    if _session_buffer.size() >= 100:
        flush_to_disk()

func flush_to_disk() -> void:
    if _session_buffer.is_empty(): return
    
    var file := FileAccess.open(LOG_FILE_PATH, FileAccess.WRITE)
    if file:
        file.store_string(JSON.stringify(_session_buffer, "\t"))
        file.close()
        # Note: In a real scenario, you'd append to existing logs or rotate files

Anti-Pattern: NEVER write to res:// at runtime. Always use user:// for persistent logs, as res:// is typically read-only in exported builds.

Reference

• Master Skill: godot-master