godot-rpg-stats

可用脚本

必须根据场景阅读后再实现：

• 模板／基础属性 → base_stats_resource.gd
• 运行时堆叠 + 响应式重算 → stats_component_reactive.gd + stat_modifier_stacking.gd
• 增益／减益数据 → status_effect_data.gd（Type.ADDITIVE / MULTIPLICATIVE / OVERRIDE）
• 战斗计算 → damage_formula_handler.gd

base_stats_resource.gd

用于存储基础属性（Str、Dex、Int）和派生缩放规则的核心数据容器。

status_effect_data.gd

使用 StatusEffectData.Type { ADDITIVE, MULTIPLICATIVE, OVERRIDE } 定义并序列化增益／减益。

stats_component_reactive.gd

负责通过活动修饰符堆叠进行 JIT（即时）属性计算的协调器。

exp_progression_resource.gd

使用成长因子和基础 XP 定义由数据驱动的升级曲线。

dynamic_stat_label_sync.gd

响应式 UI 钩子，无需轮询即可让 Label 与属性变化同步。

damage_formula_handler.gd

用于复杂战斗计算和伤害计算的集中式 RefCounted 工具。

stat_modifier_stacking.gd

用于处理唯一与可堆叠增益以及刷新持续时间的逻辑。

resource_stat_inheritance.gd

用于通过专用属性（元素抗性）扩展基础属性的模式。

persistent_character_stats.gd

用于将角色成长序列化到 .tres 文件。

level_up_system.gd

用于发放经验并触发升级奖励的逻辑。

rpg_stat_resource.gd

带上限的基础属性 Resource，包含 setter 限制和 stat_changed 信号。

derived_stat_resource.gd

当基础属性依赖项发生变化时重新计算的派生属性。

equipment_tooltip_helper.gd

BBCode 装备对比工具提示（_make_custom_tooltip）。

RPG 属性中绝对不要做的事

• 绝不要用整数表示百分比 — 始终使用 float（0.0–1.0 或 0.0–100.0），避免截断。
• 绝不要在不发出信号的情况下修改 current_health — 不广播会导致 UI 不同步。
• 绝不要只依赖加法修饰符 — 长期成长应使用乘法或混合缩放。
• 绝不要添加没有唯一 ID 或 Key 的修饰符 — 移除特定效果时需要它们。
• 绝不要使用没有成长上限的指数 XP 公式 — 无上限的 pow() 会溢出或导致等级卡死。
• 绝不要忘记限制派生值 — 负活力不能导致最大 HP 为负值（maxi(val, 1)）。
• 绝不要在 _process() 中执行大量属性重算 — 仅在修饰符／基础值变化时重新计算（响应式）。
• 绝不要在逻辑中硬编码属性名称 — 使用 StringNames 或枚举。
• 绝不要将临时运行时增益存储在永久 Save Resource 中 — 序列化前移除短时长修饰符。
• 绝不要直接在 Character 脚本中计算伤害 — 集中到 damage_formula_handler.gd 中。
• 绝不要在示例中臆造仅基于 Dictionary 的修饰符 API — 与 StatusEffectData.Type 和堆叠脚本保持一致。

---

决策树

层级	职责	脚本
资源模板	由设计师编写的基础属性、曲线和继承	base_stats_resource.gd、exp_progression_resource.gd、resource_stat_inheritance.gd
运行时 StatsComponent	复制/实例化模板、应用/移除修饰符、发出信号、即时计算派生属性	必须使用 stats_component_reactive.gd + stat_modifier_stacking.gd
StatusEffectData	类型化增益条目（ADDITIVE / MULTIPLICATIVE / OVERRIDE）	status_effect_data.gd
DamageFormula（RefCounted）	Player/NPC 共用的纯战斗计算	必须使用 damage_formula_handler.gd
持久化	保存成长数据；先清除运行时增益	persistent_character_stats.gd
UI 同步	标签监听信号——不轮询	dynamic_stat_label_sync.gd

不要粘贴入门级 class_name Stats / Dictionary 装备教程——请转至上述脚本。

---

API 对齐（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

堆叠 / 刷新 / 唯一与可堆叠行为：必须使用 stat_modifier_stacking.gd。通过 stats_component_reactive.gd 应用，确保派生属性在每次变更时只重新计算一次。

---

高级提醒（有脚本支持）

1. 上限 — rpg_stat_resource.gd；在 setter 中进行钳制；绝不允许属性溢出。
2. 依赖图 — derived_stat_resource.gd；基础属性变更时，派生属性通过信号重新计算——绝不使用 _process。
3. 装备 — 装备/卸下时通过堆叠 API 注册/移除修饰符 ID；通过 equipment_tooltip_helper.gd 显示工具提示。

深入了解（按需加载）

装备钩子、伤害公式、技能门槛、高级上限/派生/工具提示模式——references/elite-stat-patterns.md。

参考

渐进式披露：仅在研究特定 API 时打开官方文档链接；转到相关领域时加载相关技能——不要预加载整个知识网络。

官方文档

• 资源 — 说明为什么基础属性、曲线和状态效果应放在 Resource 模板中，并按角色复制或实例化。
• Resource — 了解 duplicate()、resource_local_to_scene 以及共享与独立语义，避免所有敌人共用同一个 HP Resource。
• GDScript 导出属性 — 使用 @export / @export_group，让设计师无需修改代码即可在 Inspector 中调整属性和成长数值。
• 使用信号 — 使用 stat_changed / stats_recalculated，让 UI 和派生属性能够响应变化，而无需通过 _process 轮询。
• 保存游戏 — 序列化成长进度 Resource，并在写入前移除仅供运行时使用的增益效果。
• Godot 项目中的文件路径 — 了解 user:// 与 res:// 的区别，以便持久化保存角色 .tres。
• ResourceSaver — 角色升级后将属性 Resource 写入磁盘。
• ResourceLoader — 恢复成长进度时检查并加载路径。
• RefCounted — 将伤害公式和纯战斗数学逻辑与场景树分离。
• 随机数生成 — 使用带种子的暴击／浮动值抽取，让平衡性测试可重复。
• Label — 将文本绑定到由信号驱动的属性刷新，以同步 HUD。
• SceneTree — 使用 create_timer 定时让增益效果过期，无需为每个效果创建 Node。

相关技能

前置条件

• godot-project-foundations — 在构建 CharacterStats 资源前，先了解场景树、Resources 和项目布局。
• godot-gdscript-mastery — 掌握响应式属性组件所用的类型化 getter、setter 和信号连接。
• godot-resource-data-patterns — 掌握属性数据的继承、.tres 模板和组合模式。
• godot-signal-architecture — 了解所有权和扇出规则，避免 hp_changed / level_up 造成 UI 循环。

补充技能

• godot-ability-system — 根据等级／属性进行门控并应用临时修正值的能力。
• godot-inventory-system — 装备加成会在装备／卸下时注册和移除修正值 ID。
• godot-combat-system — 命中判定会使用此堆栈中的攻击、防御和暴击数据。
• godot-save-load-systems — 围绕 ResourceSaver 构建完整的进度数据保存流程。
• godot-ui-containers — 监听重新计算后的属性数据的角色面板和工具提示。
• godot-economy-system — 与等级曲线和装备属性预算相关联的金币／经验值消耗机制。
• godot-monte-carlo-balancer — 在确定数值前，对矩阵测试强度曲线、修正值堆栈和伤害波动。

下游／使用方

• godot-genre-action-rpg — 依赖属性、装备修正值和衍生战斗属性的 ARPG 配装。
• godot-genre-roguelike — 在每次游戏流程之间重置的流程范围修正值和成长机制。
• godot-turn-system — 根据共享属性计算伤害公式的回合制战斗。

主技能

• godot-master — 用于跨技能发现的库路由器和镜像模块入口。