godot-rpg-stats

Available Scripts

> MANDATORY by scenario — read before implementing:

> - Templates / base attributes → [base_stats_resource.gd](scripts/base_stats_resource.gd)

> - Runtime stack + reactive recalc → [stats_component_reactive.gd](scripts/stats_component_reactive.gd) + [stat_modifier_stacking.gd](scripts/stat_modifier_stacking.gd)

> - Buff/debuff data → [status_effect_data.gd](scripts/status_effect_data.gd) (Type.ADDITIVE / MULTIPLICATIVE / OVERRIDE)

> - Combat math → [damage_formula_handler.gd](scripts/damage_formula_handler.gd)

[base_stats_resource.gd](scripts/base_stats_resource.gd)

Core data container for base attributes (Str, Dex, Int) and derived scaling rules.

[status_effect_data.gd](scripts/status_effect_data.gd)

Serialized buff/debuff definition using StatusEffectData.Type { ADDITIVE, MULTIPLICATIVE, OVERRIDE }.

[stats_component_reactive.gd](scripts/stats_component_reactive.gd)

Orchestrator for JIT (Just-In-Time) stat calculation with active modifier stacking.

[exp_progression_resource.gd](scripts/exp_progression_resource.gd)

Data-driven level-up curve definition using growth factors and base XP.

[dynamic_stat_label_sync.gd](scripts/dynamic_stat_label_sync.gd)

Reactive UI hook for syncing Labels to stat changes without polling.

[damage_formula_handler.gd](scripts/damage_formula_handler.gd)

Centralized RefCounted utility for complex combat math and damage calculations.

[stat_modifier_stacking.gd](scripts/stat_modifier_stacking.gd)

Logic for handling unique vs. stackable buffs and refreshing durations.

[resource_stat_inheritance.gd](scripts/resource_stat_inheritance.gd)

Pattern for extending base stats with specialized attributes (Elemental Resists).

[persistent_character_stats.gd](scripts/persistent_character_stats.gd)

Managing the serialization of character progression to .tres files.

[level_up_system.gd](scripts/level_up_system.gd)

Logic for awarding experience and triggering level-up benefits.

[rpg_stat_resource.gd](scripts/rpg_stat_resource.gd)

Capped base stat Resource with setter clamps + stat_changed signal.

[derived_stat_resource.gd](scripts/derived_stat_resource.gd)

Derived stat that recalculates when base stat dependencies change.

[equipment_tooltip_helper.gd](scripts/equipment_tooltip_helper.gd)

BBCode equipment comparison tooltips (_make_custom_tooltip).

NEVER Do in RPG Stats

• NEVER use integers for percentages — Always use float (0.0–1.0 or 0.0–100.0) to avoid truncation.
• NEVER modify current_health without emitting signals — UI desyncs without broadcasts.
• NEVER rely solely on additive modifiers — Use multiplicative or hybrid scaling for long progressions.
• NEVER add modifiers without a unique ID or Key — Required to remove specific effects.
• NEVER use exponential XP formulas without a growth cap — Uncapped pow() overflows or soft-locks levels.
• NEVER forget to clamp derived values — Negative vitality must not yield negative max HP (maxi(val, 1)).
• NEVER perform heavy stat recalculations in _process() — Recalc only on modifier/base change (reactive).
• NEVER hardcode stat names in logic — Use StringNames or enums.
• NEVER store temporary runtime buffs in a permanent Save Resource — Strip short-duration modifiers before serialize.
• NEVER calculate damage directly in the Character script — Centralize in [damage_formula_handler.gd](scripts/damage_formula_handler.gd).
• NEVER invent Dictionary-only modifier APIs in examples — Align with StatusEffectData.Type and the stacking scripts.

---

Decision Tree

| Layer | Responsibility | Script |

|-------|----------------|--------|

| Resource template | Designer-authored base attributes, curves, inheritance | [base_stats_resource.gd](scripts/base_stats_resource.gd), [exp_progression_resource.gd](scripts/exp_progression_resource.gd), [resource_stat_inheritance.gd](scripts/resource_stat_inheritance.gd) |

| Runtime StatsComponent | Duplicate/instance template, apply/remove modifiers, emit signals, JIT derived stats | MANDATORY [stats_component_reactive.gd](scripts/stats_component_reactive.gd) + [stat_modifier_stacking.gd](scripts/stat_modifier_stacking.gd) |

| StatusEffectData | Typed buff rows (ADDITIVE / MULTIPLICATIVE / OVERRIDE) | [status_effect_data.gd](scripts/status_effect_data.gd) |

| DamageFormula (RefCounted) | Pure combat math shared by Player/NPC | MANDATORY [damage_formula_handler.gd](scripts/damage_formula_handler.gd) |

| Persistence | Save progression; strip runtime buffs first | [persistent_character_stats.gd](scripts/persistent_character_stats.gd) |

| UI sync | Labels listen to signals — no polling | [dynamic_stat_label_sync.gd](scripts/dynamic_stat_label_sync.gd) |

Do not paste beginner class_name Stats / Dictionary equipment tutorials — route to the scripts above.

---

API alignment (StatusEffectData)

# Author buffs as Resources — not ad-hoc Dictionary modifiers
var haste := StatusEffectData.new()
haste.name = "Haste"
haste.type = StatusEffectData.Type.MULTIPLICATIVE
haste.attribute = "speed"
haste.value = 1.25
haste.duration = 8.0

var flat_str := StatusEffectData.new()
flat_str.type = StatusEffectData.Type.ADDITIVE
flat_str.attribute = "strength"
flat_str.value = 5.0

var break_def := StatusEffectData.new()
break_def.type = StatusEffectData.Type.OVERRIDE
break_def.attribute = "defense"
break_def.value = 0.0

Stacking / refresh / unique-vs-stackable behavior: MANDATORY [stat_modifier_stacking.gd](scripts/stat_modifier_stacking.gd). Apply through [stats_component_reactive.gd](scripts/stats_component_reactive.gd) so derived stats recalc once per change.

---

Elite reminders (script-backed)

1. Caps — [rpg_stat_resource.gd](scripts/rpg_stat_resource.gd); clamp on setters; never allow overflow attributes.
2. Dependency graphs — [derived_stat_resource.gd](scripts/derived_stat_resource.gd); derived stats recalc from signals when bases change — never _process.
3. Equipment — Register/remove modifier IDs on equip/unequip via stacking API; tooltips via [equipment_tooltip_helper.gd](scripts/equipment_tooltip_helper.gd).

Deep dive (load on demand)

Equipment hooks, damage formula, skill gates, elite cap/derived/tooltip patterns — [references/elite-stat-patterns.md](references/elite-stat-patterns.md).

Reference

> Progressive disclosure: open Official Documentation links only when researching a specific API; load Related Skills when routing to a peer domain — do not preload the whole lattice.

Official Documentation

• Resources — why base stats, curves, and status effects belong on Resource templates you duplicate or instance per character.
• Resource — duplicate(), resource_local_to_scene, and shared-vs-unique semantics that prevent every enemy sharing one HP Resource.
• GDScript exported properties — @export / @export_group so designers tune attributes and scaling in the Inspector without code edits.
• Using signals — stat_changed / stats_recalculated so UI and derived stats react without _process polling.
• Saving games — serialize progression Resources and strip runtime-only buffs before write.
• File paths in Godot projects — user:// vs res:// for persistent character .tres saves.
• ResourceSaver — write character stats Resources to disk after level-ups.
• ResourceLoader — exists / load paths when restoring progression on boot.
• RefCounted — keep damage formulas and pure combat math off the scene tree.
• Random number generation — seeded crit / variance rolls that stay reproducible in balance tests.
• Label — bind text to signal-driven attribute refresh for HUD sync.
• SceneTree — create_timer for timed buff expiry without a per-effect Node.

Related Skills

Prerequisites

• godot-project-foundations — scene tree, Resources, and project layout before building CharacterStats assets.
• godot-gdscript-mastery — typed getters, setters, and signal wiring used by reactive stat components.
• godot-resource-data-patterns — inheritance, .tres templates, and composition patterns for attribute data.
• godot-signal-architecture — ownership and fan-out rules so hp_changed / level_up do not create UI cycles.

Complements

• godot-ability-system — abilities that gate on level/attributes and apply temporary modifiers.
• godot-inventory-system — equipment bonuses that register and remove modifier IDs on equip/unequip.
• godot-combat-system — hit resolution that consumes attack/defense/crit from this stack.
• godot-save-load-systems — full save pipelines around ResourceSaver of progression data.
• godot-ui-containers — character sheets and tooltips that listen to recalculated stats.
• godot-economy-system — gold/XP sinks that couple with level curves and gear stat budgets.
• godot-monte-carlo-balancer — matrix-test power curves, modifier stacks, and damage variance before shipping numbers.

Downstream / consumers

• godot-genre-action-rpg — ARPG builds that rely on attributes, gear mods, and derived combat stats.
• godot-genre-roguelike — run-scoped modifiers and scaling that reset between runs.
• godot-turn-system — turn-based combat that resolves damage formulas from shared stats.

Master

• godot-master — library router and mirrored module entry for cross-skill discovery.