godot-rpg-stats

$npx mdskill add thedivergentai/GD-Agentic-Skills/godot-rpg-stats

Designs RPG stat systems with resources, modifiers, and damage formulas.

  • Implements character progression, equipment, and buff systems using Resource-based stats.
  • Depends on Godot 4.7+ and custom scripts for stats, modifiers, and damage calculation.
  • Recommends specific scripts based on the need for base stats, runtime stacking, or combat math.
  • Delivers reusable script templates and patterns for flexible, reactive stat systems.

SKILL.md

.github/skills/godot-rpg-statsView on GitHub ↗
---
name: godot-rpg-stats
description: "Expert blueprint for RPG stat systems (attributes, leveling, modifiers, damage formulas) using Resource-based stats, stackable modifiers, and derived stat calculations. Use when implementing character progression OR equipment/buff systems. Keywords stats, attributes, leveling, modifiers, CharacterStats, derived stats, damage calculation, XP."
---

## Godot 4.7 Baseline

- Expert patterns in this skill target **Godot 4.7+** (stable, 2026-06-18).
- Consult the [Godot 4.7 migration guide](https://docs.godotengine.org/en/4.7/tutorials/migrating/upgrading_to_godot_4.7.html) when upgrading projects from 4.6.
- **NEVER** assume 4.6 defaults (stretch mode, audio area_mask, RichTextLabel percent flags) without checking 4.7 migration notes.

# RPG Stats

Resource-based stats, modifier stacks, and derived calculations define flexible character progression.

## 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)

```gdscript
# 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](https://docs.godotengine.org/en/stable/tutorials/scripting/resources.html) — why base stats, curves, and status effects belong on `Resource` templates you duplicate or instance per character.
- [Resource](https://docs.godotengine.org/en/stable/classes/class_resource.html) — `duplicate()`, `resource_local_to_scene`, and shared-vs-unique semantics that prevent every enemy sharing one HP Resource.
- [GDScript exported properties](https://docs.godotengine.org/en/stable/tutorials/scripting/gdscript/gdscript_exports.html) — `@export` / `@export_group` so designers tune attributes and scaling in the Inspector without code edits.
- [Using signals](https://docs.godotengine.org/en/stable/getting_started/step_by_step/signals.html) — `stat_changed` / `stats_recalculated` so UI and derived stats react without `_process` polling.
- [Saving games](https://docs.godotengine.org/en/stable/tutorials/io/saving_games.html) — serialize progression Resources and strip runtime-only buffs before write.
- [File paths in Godot projects](https://docs.godotengine.org/en/stable/tutorials/io/data_paths.html) — `user://` vs `res://` for persistent character `.tres` saves.
- [ResourceSaver](https://docs.godotengine.org/en/stable/classes/class_resourcesaver.html) — write character stats Resources to disk after level-ups.
- [ResourceLoader](https://docs.godotengine.org/en/stable/classes/class_resourceloader.html) — `exists` / load paths when restoring progression on boot.
- [RefCounted](https://docs.godotengine.org/en/stable/classes/class_refcounted.html) — keep damage formulas and pure combat math off the scene tree.
- [Random number generation](https://docs.godotengine.org/en/stable/tutorials/math/random_number_generation.html) — seeded crit / variance rolls that stay reproducible in balance tests.
- [Label](https://docs.godotengine.org/en/stable/classes/class_label.html) — bind text to signal-driven attribute refresh for HUD sync.
- [SceneTree](https://docs.godotengine.org/en/stable/classes/class_scenetree.html) — `create_timer` for timed buff expiry without a per-effect Node.

### Related Skills

#### Prerequisites
- [godot-project-foundations](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-project-foundations/SKILL.md) — scene tree, Resources, and project layout before building CharacterStats assets.
- [godot-gdscript-mastery](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-gdscript-mastery/SKILL.md) — typed getters, setters, and signal wiring used by reactive stat components.
- [godot-resource-data-patterns](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-resource-data-patterns/SKILL.md) — inheritance, `.tres` templates, and composition patterns for attribute data.
- [godot-signal-architecture](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-signal-architecture/SKILL.md) — ownership and fan-out rules so `hp_changed` / `level_up` do not create UI cycles.

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

#### Downstream / consumers
- [godot-genre-action-rpg](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-genre-action-rpg/SKILL.md) — ARPG builds that rely on attributes, gear mods, and derived combat stats.
- [godot-genre-roguelike](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-genre-roguelike/SKILL.md) — run-scoped modifiers and scaling that reset between runs.
- [godot-turn-system](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-turn-system/SKILL.md) — turn-based combat that resolves damage formulas from shared stats.

#### Master
- [godot-master](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-master/SKILL.md) — library router and mirrored module entry for cross-skill discovery.

More from thedivergentai/GD-Agentic-Skills

SkillDescription
godot-2d-animationExpert patterns for 2D animation in Godot using AnimatedSprite2D and skeletal cutout rigs. Use when implementing sprite frame animations, procedural animation (squash/stretch), cutout bone hierarchies, or frame-perfect timing systems. Trigger keywords: AnimatedSprite2D, SpriteFrames, animation_finished, animation_looped, frame_changed, frame_progress, set_frame_and_progress, cutout animation, skeletal 2D, Bone2D, procedural animation, animation state machine, advance(0).
godot-2d-physicsExpert patterns for Godot 2D physics including collision layers/masks, Area2D triggers, raycasting, and PhysicsDirectSpaceState2D queries. Use when implementing collision detection, trigger zones, line-of-sight systems, or manual physics queries. Trigger keywords: CollisionShape2D, CollisionPolygon2D, collision_layer, collision_mask, set_collision_layer_value, set_collision_mask_value, Area2D, body_entered, body_exited, RayCast2D, force_raycast_update, PhysicsPointQueryParameters2D, PhysicsShapeQueryParameters2D, direct_space_state, move_and_collide, move_and_slide.
godot-3d-lightingExpert patterns for Godot 3D lighting including DirectionalLight3D shadow cascades, OmniLight3D attenuation, SpotLight3D projectors, VoxelGI vs SDFGI, and LightmapGI baking. Use when implementing realistic 3D lighting, shadow optimization, global illumination, or light probes. Trigger keywords: DirectionalLight3D, OmniLight3D, SpotLight3D, shadow_enabled, directional_shadow_mode, directional_shadow_split, omni_range, omni_attenuation, spot_range, spot_angle, VoxelGI, SDFGI, LightmapGI, ReflectionProbe, Environment, WorldEnvironment.
godot-3d-materialsExpert patterns for Godot 3D PBR materials using StandardMaterial3D including albedo, metallic/roughness workflows, normal maps, ORM texture packing, transparency modes, and shader conversion. Use when creating realistic 3D surfaces, PBR workflows, or material optimization. Trigger keywords: StandardMaterial3D, BaseMaterial3D, albedo_texture, metallic, metallic_texture, roughness, roughness_texture, normal_texture, normal_enabled, orm_texture, transparency, alpha_scissor, alpha_hash, cull_mode, ShaderMaterial, shader parameters.
godot-3d-world-buildingExpert patterns for 3D level design using GridMap with MeshLibrary, CSG constructive solid geometry, occlusion, and runtime GridMap builders. Use when building 3D levels, modular tilesets, or BSP-style geometry. For sky/fog/Environment recipes, route to godot-3d-lighting. Trigger keywords: GridMap, MeshLibrary, set_cell_item, get_cell_item, map_to_local, local_to_map, CSGCombiner3D, CSGBox3D, CSGSphere3D, CSGPolygon3D, OccluderInstance3D, bake CSG.
godot-ability-systemExpert 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.
godot-adapt-2d-to-3dExpert patterns for migrating 2D games to 3D including node type conversions, camera systems (third-person, first-person, orbit), physics layer migration, sprite-to-model art pipeline, and control scheme adaptations. Use when porting 2D projects to 3D or adding 3D elements. Trigger keywords: CharacterBody2D to CharacterBody3D, Area2D to Area3D, Camera2D to Camera3D, Vector2 to Vector3, collision_layer migration, sprite to MeshInstance3D, 2D to 3D conversion.
godot-adapt-3d-to-2dExpert patterns for simplifying 3D games to 2D including dimension reduction strategies, 2.5D fake-depth, isometric ports, camera flattening, physics conversion, 3D-to-sprite art pipeline, and control simplification. Use when porting 3D to 2D, building 2.5D / isometric / fake-depth gameplay, creating 2D versions for mobile, or prototyping. Trigger keywords: CharacterBody3D to CharacterBody2D, Camera3D to Camera2D, Vector3 to Vector2, flatten Z-axis, 2.5D, isometric, fake depth, Y-sort, simulated Z, orthogonal projection, 3D to sprite conversion, performance optimization.
godot-adapt-desktop-to-mobileExpert patterns for porting desktop games to mobile including touch control schemes (virtual joystick, gesture detection), UI scaling for small screens, performance optimization for mobile GPUs, battery life management, and platform-specific features. Use when creating mobile ports or cross-platform mobile builds. Trigger keywords: TouchScreenButton, virtual_joystick, gesture_detector, InputEventScreenTouch, InputEventScreenDrag, mobile_optimization, battery_saving, adaptive_performance, MOBILE_ENABLED.
godot-adapt-mobile-to-desktopExpert patterns for scaling mobile games to desktop including mouse/keyboard controls, increased resolution and graphical fidelity, expanded UI layouts, settings menus, window management, and platform-specific features. Use when creating desktop ports or cross-platform releases. Trigger keywords: mouse_controls, keyboard_shortcuts, resolution_scaling, graphics_settings, fullscreen_toggle, window_modes, Steam_integration, desktop_optimization.