godot-genre-action-rpg

绝对不要做的事（专家级反模式）

战斗与成长

• 绝不要在线性伤害缩放的基础上推进成长；必须使用指数曲线（例如 base * pow(1.15, level)），以维持力量幻想。
• 绝不要让防御属性线性叠加至 100%；必须使用递减收益公式（例如 armor / (armor + 100.0)），以防止无敌。
• 绝不要跳过受击恢复（硬直）；必须在受到重击时加入短暂的硬直状态（0.2s - 0.5s），以避免战斗显得“飘忽”。
• 绝不要向玩家隐藏关键属性；必须提供详细的角色面板，便于理论构筑（暴击率、抗性等）。
• 绝不要让不同稀有度的战利品在视觉上毫无区别；必须用颜色编码的光束（紫色／金色）和不同的音效提示来区分。
• 绝不要在 _process() 中计算命中判定框、击退或战斗移动；必须使用 _physics_process() 来获得确定性结果。
• 绝不要对战斗阈值进行精确浮点数相等比较（==）；必须使用 is_equal_approx()。
• 绝不要在 AnimationTree Advance Condition 表达式中使用 !（NOT）运算符；必须使用明确的布尔值比较（is_walking == false）。

技术与架构

• 绝不要将角色属性或大型库存存储为 Node；必须使用基于Resource 的数据容器，以降低内存开销。
• 绝不要忘记对共享的 Resources 调用 duplicate()；修改一只地精的属性绝不能影响其他所有实例。
• 绝不要将战斗检测与特定类紧密耦合；必须使用鸭子类型（例如 if body.has_method(&"take_damage")）进行交互。
• 绝不要依赖 UI SceneTree 作为库存的事实来源；必须将数据逻辑与可视化分开。
• 绝不要每帧都重新计算属性；必须仅在装备变化或升级时触发重新计算。
• 绝不要同步解析大型 RPG 存档文件；必须将繁重的解析工作交给 WorkerThreadPool。
• 绝不要通过网络同步复杂的 Resource 类型；必须将变更序列化为基本类型的 Dictionaries 或 PackedByteArrays。
• 绝不要通过让子节点耦合于父节点是否存在来管理角色状态；必须使用信号实现松散耦合（“信号向上传递，调用向下传递”）。
• 绝不要在高频 AI 状态标识符中使用标准 Strings；必须使用 StringName 进行优化的哈希比较。

性能与 AI

• 绝不要每秒实例化／销毁数百个对象（弹体、伤害文本）；必须使用对象池。
• 绝不要通过 free() 删除正在参与战斗的实体；必须使用 queue_free() 安全地延迟释放。
• 绝不要在主线程中计算复杂的战利品掉落，或解析大型后期游戏库存；必须将繁重的随机数生成计算和数组遍历交给 WorkerThreadPool。
• 绝不要用嵌套的 if/elif 代码块编写复杂的 Boss AI；必须使用模块化的 StateMachine 或模式匹配。
• 绝不要遍历 SceneTree 来进行全局状态变更；必须使用信号组（call_group()）。
• 绝不要移动附加在动态角色上的 OccluderInstance3D 节点；这会导致 CPU BVH 重建卡顿。

---

专家组件（scripts/）

必须遵守：在决定是否要在此处编写 CombatController/RPGStats 教程之前，先阅读对应脚本。 不要加载同类型的其他游戏技能（平台游戏、赛车游戏等），也不要深入讲解完整的库存／能力系统，除非 Skill Chain 表格要求这样做——请专注于 ARPG 战斗、战利品与成长路径。

战斗与命中结算

• hitbox_component.gd — MANDATORY 启用/禁用 Area 碰撞箱 + 多重命中防护。
• duck_typed_hitbox.gd — MANDATORY 通过 has_method(&"take_damage") 建立耦合。
• health_component.gd — 作为子组件的 HP / 死亡信号。
• aoe_physics_query.gd — MANDATORY 使用 PhysicsServer 实现 AoE（不为每次爆炸创建 Node）。
• aoe_group_broadcaster.gd — 按阵营/AoE 进行组广播。
• combat_event_bus.gd / signal_combat_decoupler.gd / combat_log_connector.gd — 解耦的战斗总线/日志。
• damage_label_manager.gd — MANDATORY 池化浮动数字。
• stat_reduction_solver.gd — 递减收益护甲 / 抗性计算。

属性与成长

• base_stat_resource.gd / character_stats_resource.gd — 以 Resource 为先的属性。
• deep_stat_duplicator.gd / entity_stat_duplicator.gd — MANDATORY 生成时调用 duplicate(true)。
• leveling_table.gd — XP / 等级曲线。
• cooldown_coroutine.gd — 等待技能冷却。

AI / 动画 / 背包性能

• telegraphed_enemy.gd — MANDATORY 类魂游戏式蓄力动作 / AoE 预警。
• hierarchical_state_base.gd — Boss/玩家战斗 FSM 基类。
• animation_condition_sync.gd — 不使用 ! 的 AnimationTree Advance Conditions。
• high_speed_aggro_broadcaster.gd — 通过组实现局部仇恨广播。
• threaded_inventory_loader.gd — MANDATORY 使用 WorkerThreadPool 解析背包。
• typed_inventory_storage.gd — 类型化物品字典存储。
• combat_damage_calculator.gd — 递减收益伤害 + 暴击判定。
• loot_generator.gd — 按权重决定稀有度 + 按阶级决定词缀数量。
• enemy_area_scaler.gd — 生成时按区域等级调整属性/XP 倍率。

---

核心循环

战斗 → 战利品 → 升级 → 提升战力 → 挑战更高难度的内容 → 重复

技能链

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 → godot-monte-carlo-balancer

决策树（不贴整段类代码）

问题	决策	脚本 / 关联项
近战 / 投射物接触	在 _physics_process 中逐帧处理 Area 碰撞箱	hitbox_component + duck_typed_hitbox
护甲叠加效果异常	使用递减收益，而非线性百分比	stat_reduction_solver
伤害数字导致卡顿	池化标签	damage_label_manager
共享的哥布林 HP 变动影响所有实例	实例化时深度复制 Resources	deep/entity_stat_duplicator
Boss 中嵌套 if/elif 过多	分层 FSM + 预警	hierarchical_state_base + telegraphed_enemy
AoE 成本过高	PhysicsServer 查询 / 分组	aoe_physics_query / aoe_group_broadcaster
后期背包解析卡顿	WorkerThreadPool	threaded_inventory_loader
AnimationTree 状态来回切换	显式布尔 Advance Conditions	animation_condition_sync
完整战利品词缀 / 背包 UI	此处不要重复讲解	godot-inventory-system
快捷栏技能 / 法力	此处不要重复讲解	godot-ability-system
修正值叠加 / 曲线	此处不要重复讲解	godot-rpg-stats

架构概览（组合）

优先使用 Health/Hitbox 子组件（godot-composition），而不是继承 BaseEnemy。UI 通过信号观察；库存的 Resource 才是真实数据来源，绝不能以 HUD 树为准。

常见问题（简述）

• 战斗手感轻飘 → 添加受击恢复/硬直。
• 掉落物千篇一律 → 添加稀有度光束和音效（可以使用 RenderingServer 的实例参数）。
• 战斗受帧率影响 → 仅在 _physics_process 中处理命中判定。

超出决策树范围，深入探讨战斗/掉落物/装备/区域缩放时，必须参阅：arpg-subsystems-deep.md。首次接入命中框和属性时，不要加载此文档——请使用上面的脚本。

高级 ARPG 元系统

1. 巅峰等级 / 无限成长资源

将等级上限后的力量存储在一个复制的 Resource 中；等级变更时发出 emit_changed()；绝不修改缓存模板。

2. 基于着色器的掉落物光束

通过 RenderingServer.instance_geometry_set_shader_parameter 在共享着色器上设置稀有度颜色——避免大量 duplicate() 材质。

3. 基于属性快照的战斗日志

缓冲 Dictionary 快照；定期写入 user://（绝不写入 res://）。

参考

渐进式阅读： 仅在实现相应 API 时浏览官方文档（Resources、Area/物理查询、信号/组、AnimationTree、WorkerThreadPool、存档）。接入战斗、属性、库存、技能或平衡时，再打开相关技能文档——不要预先加载整个知识体系。

官方文档

• 资源 — ARPG 属性、战利品词缀、升级表和装备模板应放在 Resource 资源中，这样设计师无需重写战斗代码，就能编辑 .tres 数据。
• Resource — 生成实例时，始终对共享的属性/战利品模板执行 duplicate(true)，避免一个哥布林的 HP 或物品栏变更改写所有实例的 .tres。
• GDScript 导出变量 — @export / 类型化 Dictionary 可通过检查器调整伤害、抗性、经验曲线和装备槽位的数值，无需重新编译脚本即可平衡游戏。
• 使用 Area2D — Hitbox/hurtbox 重叠信号是引擎中实时近战和投射物接触检测的基础。
• 射线投射 — 直接的空间状态形状/射线查询可用于高实体数量场景下的范围伤害和直线检测，无需为每次爆炸生成一个 Node。
• 空闲与物理处理 — 在 _physics_process 中处理 hitbox、击退、攻击预警和追击逻辑，以确保战斗在固定时间步长下具有确定性。
• 使用信号 — 战斗日志、经验值授予、Boss 阶段和 HUD 伤害飘字应通过订阅信号实现，而不是直接引用战斗角色。
• 群组 — 阵营仇恨和范围伤害应使用 call_group / call_group_flags，而不是每帧遍历 SceneTree。
• 场景组织 — 遵循“信号向上传递，调用向下发起”：父节点/UI 观察战斗；管理器调用 hitbox 和状态节点——绝不要把 HUD 当作物品栏数据的权威来源。
• 使用 AnimationTree — 使用显式布尔值同步攻击/移动 Advance Conditions（表达式中不要使用 !），确保连招和硬直状态可靠。
• WorkerThreadPool — 在主线程之外解析大型后期游戏物品栏、战利品结果和存档数据，确保战斗保持 60 FPS。
• 保存游戏 — 将等级、装备、技能等级和冷却结束时间戳与其他进度数据一同持久化——绝不要将运行时日志写入 res://。

相关技能

前置条件

• godot-project-foundations — 在为 ARPG 添加战斗、物品栏和存档系统之前，必须先打好自动加载项、文件夹布局和输入/项目设置的基础。
• godot-characterbody-2d — 玩家/敌人的移动和 move_and_slide 是受击恢复、追击和攻击前摇所依赖的移动基础。
• godot-resource-data-patterns — 属性、词缀和升级曲线应优先使用 Resource；在设计由大量 Node 组成的角色面板之前，请先阅读此项。
• godot-signal-architecture — 战斗总线、health_changed 和战利品拾取事件需要明确的信号归属，确保 UI/日志永远不掌握战斗数据的权威信息。

补充技能

• godot-combat-system — 伤害流程、受击反应和目标选择会使用命中框／受伤框事件；本类型技能会将这些事件接入构建与战利品系统。
• godot-rpg-stats — 指数伤害曲线、递减护甲和修正器叠加需要专门的属性／修正器层。
• godot-inventory-system — 装备栏位、稀有度阶级和词缀随机结果位于独立于 SceneTree HUD 的库存数据中。
• godot-ability-system — 冷却时间、法力消耗和技能树授予的技能可与战斗命中判定组合，用于热键栏 ARPG。
• godot-composition — 对模块化 RPG 单位，优先使用 HealthComponent / HitboxComponent 子节点，而不是深层的 BaseEnemy 继承。
• godot-state-machine-advanced — Boss 预警、硬直和施法／引导状态应归入分层 FSM，而非嵌套的 if/elif AI。

下游／使用方

• godot-monte-carlo-balancer — 伤害曲线、战利品稀有度和技能消耗可调后，可通过蒙特卡洛配装模拟，在发布前验证 DPS/TTK 区间。
• godot-quest-system — 击杀／收集／Boss 阶段目标会使用此类型循环所产生的相同战斗和库存事件。
• godot-economy-system — 掉落稳定后，商贩定价以及资源消耗／产出循环会建立在战利品稀有度和制作系统之上。
• godot-save-load-systems — 为支持长时间 ARPG 游戏流程，角色构筑、装备和技能等级必须能够通过持久化存档架构完整往返。

主技能

• godot-master — 技能库路由器和镜像模块入口；用于查找同级技能，或在编辑 Domain Skill 后同步共享脚本镜像。