basil
/
geometry-tower-defense-base
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
geometry-tower-defense-base/docs/CombatNodeArchitecture.md

26 KiB
Raw Blame History

CombatNode 设计规范（开发约束）

最后更新：2026-03-12

1. 适用范围与目标

本文描述 CombatNode 域的后续开发标准。

说明：

  • 本文是“目标架构约束”，不要求当前代码已经完全达成。
  • 后续新增功能、重构、拆分类、review 职责边界时，以本文为准。
  • 如果当前实现与本文不一致，新增代码优先向本文收敛，而不是继续扩大旧结构。

核心目标：

  • CombatScheduler 收敛为“状态机管理器”，不再继续堆积加载、结算、奖励选择等业务细节。
  • 战斗内资源收口到独立资源服务，由内部管理，不再由 CombatNodeComponent 直接持有真值。
  • MapEntity 通过 MapData + Event 获取战斗上下文，不反查 CombatNode 域内部状态。

2. 架构总览

2.1 CombatNodeComponent（入口 Facade）

文件：Assets/GameMain/Scripts/CustomComponent/CombatNode/CombatNodeComponent.cs

长期职责：

  • 读取并缓存 DRLevel / DRLevelPhase / DRLevelSpawnEntry。
  • 按主题筛选关卡。
  • 启动/停止 CombatScheduler。
  • 对外暴露只读运行时属性。
  • 提供少量用户入口，例如 StartCombat、TryEndCombatByPlayer。

长期不负责：

  • 不直接持有 Coin / Gold / BaseHp / Loot Backpack 的真值。
  • 不直接缓存本局建塔属性快照。
  • 不直接发布战斗流程事件。
  • 不直接处理敌人掉落、结算、奖励选择、地图加载。

2.2 CombatScheduler（状态机管理器）

文件：Assets/GameMain/Scripts/CustomComponent/CombatNode/CombatScheduler/CombatScheduler.cs

长期职责：

  • 持有共享运行时数据与共享服务实例。
  • 管理状态实例。
  • 提供统一的 ChangeState(...) 状态迁移入口。
  • 提供敌人事件的公共处理入口。
  • 作为状态机生命周期边界，统一做运行时重置。

长期不负责：

  • 不直接硬编码加载流程。
  • 不直接硬编码结算流程。
  • 不直接硬编码奖励选择 UI 逻辑。
  • 不直接硬编码 PhaseEndType 结束条件。

推荐状态类命名：

  • CombatLoadingState
  • CombatRunningPhaseState
  • CombatWaitingForPhaseEndState
  • CombatSettlementState
  • CombatRewardSelectionState
  • CombatFinishFormState
  • CombatWaitingForReturnState
  • CombatFailedState

实现约束：

  • 上述状态类可以作为 CombatScheduler 的嵌套类实现，也可以拆成独立文件；但必须只服务于 CombatScheduler 状态机，不形成独立业务边界。
  • 共享数据与共享服务统一收口到 CombatScheduler 内部持有的运行时承载体，不允许散落在各状态类中。
  • 若 CombatScheduler 体量过大，允许在其内部实现中继续拆出：
    • CombatSchedulerRuntime：承载共享运行时字段与共享服务引用
    • CombatSchedulerCoordinator：承载多个状态共用的流程辅助方法
  • 上述拆分只属于 CombatScheduler 的内部实现细化，不改变 CombatScheduler 作为唯一状态机边界的职责。
  • 所有状态切换只能通过 CombatScheduler.ChangeState(...) 完成。
  • 状态类不能彼此直接操控。

2.3 EnemyManager（敌人域 Facade）

文件：Assets/GameMain/Scripts/CustomComponent/CombatNode/EnemyManager/EnemyManager.cs

长期职责：

  • 对状态机提供统一敌人域接口。
  • 编排敌人子服务。
  • 暴露只读事实：
    • AliveEnemyCount
    • IsPhaseSpawnCompleted
    • HasAliveBoss
  • 在敌人死亡或到家时，通过公共入口向 CombatScheduler 上报：
    • OnEnemyDefeated(DREnemy enemy)
    • OnEnemyReachedBase(DREnemy enemy)

长期不负责：

  • 不直接给资源入账。
  • 不直接扣基地血量。
  • 不直接决定状态切换。

3. 状态机模型

3.1 状态列表（目标）

  • Loading
  • RunningPhase
  • WaitingForPhaseEnd
  • Settlement
  • RewardSelection
  • FinishForm
  • WaitingForReturn
  • Failed

说明：

  • 正常结束流只有一条状态链：
    • Settlement -> RewardSelection(可选) -> FinishForm -> WaitingForReturn
  • 正常通关、玩家主动结束、基地血量归零都走同一条结束链。
  • Failed 仅用于异常失败，不用于“基地被击破”这类正常战斗失败。

3.2 CombatLoadingState

职责：

  • 通过 CombatLoadSession 执行地图与基础战斗 UI 加载。
  • 从局内资源管理器读取本局快照。
  • 组装 MapData 并发起 ShowEntity(MapEntity)。

约束：

  • 只负责加载，不负责初始化局内资源。
  • 局内资源必须在进入状态机前初始化完成。

3.3 CombatRunningPhaseState

职责：

  • 执行当前 DRLevelPhase 的行为。
  • 推进 SpawnEntry 时序与出怪。
  • 管理 EnemySpawnDirector 的阶段级初始化与重置。
  • 在新 phase 开始时发布：
    • CombatProcessEventArgs
    • CombatEnemyHpRateChangedEventArgs

退出条件：

  • 当前 phase 的所有 SpawnEntry 已执行完毕时，进入 WaitingForPhaseEnd。
  • 若共享“结束战斗请求标记”已置位，也可结束当前运行态并转入正常结束链。

不负责：

  • 不根据 PhaseEndType 判断 phase 是否真正结束。
  • 不直接根据 BaseHp 或敌人死亡事件切状态。

3.4 CombatWaitingForPhaseEndState

职责：

  • 不再生成新敌人。
  • 根据 PhaseEndType 判断当前 phase 是否结束。

约束：

  • PhaseEndType 的判断由独立判定服务负责，不在状态内硬编码。
  • 每种 PhaseEndType 对应一个实现类。
  • 该判定服务为本状态专用，不作为全局共享服务常驻在 CombatScheduler 上。

3.5 CombatSettlementState

职责：

  • 进入时统一构造结算上下文。
  • 根据共享资源状态完成结算修正。
  • 决定后续进入 RewardSelection 还是 FinishForm。

负责的逻辑包括：

  • 基地血量奖励/惩罚。
  • 满血奖励选择的准入判断。
  • 生成最终展示摘要。
  • 准备待合并的结算背包快照。

约束：

  • 不依赖单独的 CombatEndReason 字段。
  • BaseHp <= 0 表示基地被击破。
  • 正常通关与玩家主动结束在结算产出上不区分原因。

3.6 CombatRewardSelectionState

职责：

  • 绑定、配置、打开、关闭 RewardSelectForm。
  • 处理奖励选择过程。
  • 将奖励选择结果写入“结束状态链持有的结算上下文”。

约束：

  • 不重新判断“是否应该出现奖励选择”。
  • 只处理选择过程本身。

3.7 CombatFinishFormState

职责：

  • 绑定、配置、打开、关闭 CombatFinishForm。
  • 读取结算上下文并展示最终结算结果。

3.8 CombatWaitingForReturnState

职责：

  • 等待玩家从结算返回。
  • 完成地图与战斗基础 UI 清理。
  • 完成正常退出收尾。
  • 在整场战斗真正退出时发布 NodeCompleteEventArgs。

3.9 CombatFailedState

职责：

  • 表示异常失败。
  • 保存并展示错误信息。
  • 执行异常收尾与剩余资源回收。

约束：

  • Failed 只处理异常路径。
  • “基地血量为 0”不进入 Failed。

4. 共享服务与推荐命名

4.1 命名后缀词典

  • Scheduler：只用于状态机边界或阶段推进总控，例如 CombatScheduler。
  • Manager：只用于子域 Facade/聚合入口，例如 EnemyManager。
  • Coordinator：只用于跨状态、跨服务的流程编排，不持有独立业务真值。
  • Service：只用于聚焦业务行为，不承担框架事件桥接或异步句柄跟踪。
  • Calculator：只用于纯计算与结果组装，不直接提交状态或驱动 UI。
  • Session：只用于一次加载/交互过程的生命周期对象。
  • Bridge：只用于框架边界适配器。
  • Runtime：只用于运行时可变状态承载。
  • Context：只用于被动数据包或共享上下文。
  • Result：只用于动作输出或结算产出；若外围服务名已表达动作语义，不再重复动作前缀。
  • Flags：只用于聚合布尔控制项，不承载流程编排逻辑。
  • Resolver：只用于映射、查找、判定、解析职责。
  • Tracker：只用于跟踪运行中的实体或事实真值。
  • Port：只用于向内部状态或 use case 暴露的受限宿主接口。

4.2 CombatLoadSession

文件：Assets/GameMain/Scripts/CustomComponent/CombatNode/CombatScheduler/CombatLoadSession.cs

长期定位：

  • 长期保留的独立加载服务。
  • 专门负责地图与战斗内基础 UI 的加载/清理。

职责：

  • 加载地图实体。
  • 打开/关闭 CombatInfoForm。
  • 跟踪加载成功/失败状态。
  • 对外提供 CurrentMap 与 IsReady。

4.2.x CombatSchedulerRuntime / CombatSchedulerCoordinator（实现细化）

当前实现允许：

  • 用 CombatSchedulerRuntime 承载所有状态共享的运行时字段与共享服务引用。
  • 用 CombatSchedulerCoordinator 承载多个状态共用的流程辅助逻辑。

约束：

  • 两者都必须由 CombatScheduler 持有并统一管理生命周期。
  • 两者都不替代 CombatScheduler 对外暴露状态机边界。
  • Runtime 不负责状态切换。
  • Coordinator 不持有独立业务真值，只能围绕共享运行时做编排辅助。
  • 状态类只允许通过 Runtime + Coordinator 访问共享状态与共享流程，不应再直接耦合其他状态实现细节。

4.3 PhaseLoopRuntime

文件：Assets/GameMain/Scripts/CustomComponent/CombatNode/CombatScheduler/PhaseLoopRuntime.cs

长期定位：

  • 长期保留的独立 phase runtime 服务。

职责：

  • 维护当前 DRLevelPhase。
  • 维护 DisplayPhaseIndex、PhaseCount。
  • 维护统一的 phase 时间基准，例如 phaseElapsedTime 或 phaseStartTime。
  • 负责进入下一 phase。
  • 持有统一“请求结束战斗”标记。

约束：

  • 只做 phase 运行时数据管理，不直接切状态。

4.4 CombatRunResourceStore

文件：Assets/GameMain/Scripts/CustomComponent/CombatNode/CombatScheduler/CombatRunResourceStore.cs

目标职责：

  • 持有本局 Coin 真值。
  • 持有本局累计 Gold 真值。
  • 持有本局 BaseHp 真值。
  • 持有本局战利品背包。
  • 持有本局建塔属性快照。
  • 提供只读快照给结束状态链与加载状态使用。
  • 发布资源变化事件：
    • CombatCoinChangedEventArgs
    • CombatBaseHpChangedEventArgs

初始化约束：

  • 在进入状态机前完成初始化。
  • 由内部从 PlayerInventory 获取并缓存本局建塔快照。

事件约束：

  • Coin / BaseHp 变化事件同时携带“当前值”和“变化量”。
  • Gold 只是结算累计值，不要求战斗内实时事件驱动。

4.5 InventoryGenerationComponent

文件：Assets/GameMain/Scripts/CustomComponent/InventoryGeneration/InventoryGenerationComponent.cs

目标职责：

  • 作为局外组件产出的统一运行时入口。
  • 对外提供：
    • BuildShopGoods(...)
    • ResolveEnemyDrop(...)
    • BuildRewardCandidates(...)
  • 在内部编排：
    • DropPoolRoller
    • RewardCandidateBuilder
    • OutGameDropRuleService
    • OutGameDropItemBuilder
    • InventoryGenerationRandomContext

约束：

  • CombatNode 域不直接持有或复制组件产出规则。
  • CombatScheduler 与结算状态链只调用统一入口，不直接访问掉落池滚动或组件实例构造细节。
  • InventoryGenerationComponent 负责运行时入口、稳定临时实例 Id、Tag 随机上下文以及 runSeed/sequenceIndex 相关上下文。
  • 掉落是否产出组件由 OutGameDropRuleService 决定；掉落池行到组件实例的构造由 OutGameDropItemBuilder 决定。

4.5.x InventoryGenerationRandomContext

文件：Assets/GameMain/Scripts/CustomComponent/InventoryGeneration/InventoryGenerationRandomContext.cs

目标职责：

  • 统一承载组件产出链路的随机合同。
  • 统一派生：
    • 商店 / 掉落 / 奖励候选的稳定随机流
    • 稳定临时组件 InstanceId
    • InventoryTagRandomContext

约束：

  • ShopGoodsBuilder、DropPoolRoller、RewardCandidateBuilder 不再直接使用全局 UnityEngine.Random。
  • 同一 runSeed + sequenceIndex + sourceType + localOrdinal 下，应得到一致的物品本体与 Tag 结果。

4.6 CombatSettlementCalculator

文件：Assets/GameMain/Scripts/CustomComponent/CombatNode/CombatSettlementCalculator.cs

目标职责：

  • 只负责结算计算与 CombatSettlementContext 组装。
  • 负责基地血量奖励、奖励选择准入、奖励背包快照与耐久扣减目标计算。

约束：

  • 不直接并包到玩家库存。
  • 不直接打开 UI。
  • 不承担奖励候选生成。

4.7 CombatSettlementCommitter

文件：Assets/GameMain/Scripts/CustomComponent/CombatNode/CombatSettlementCommitter.cs

目标职责：

  • 只负责把结算结果提交到玩家库存。
  • 负责结算背包并包与延迟耐久扣减落地。

约束：

  • 不重新计算结算上下文。
  • 不直接生成奖励候选或打开 UI。

4.8 IPhaseEndCondition

目标职责：

  • 作为 PhaseEndType 判定接口。
  • 每种 PhaseEndType 对应一个实现类。

只读输入：

  • 当前 DRLevelPhase
  • phase 时间信息
  • AliveEnemyCount
  • IsPhaseSpawnCompleted
  • HasAliveBoss

输出：

  • bool ShouldExit

约束：

  • 不直接切状态。
  • 不直接发事件。
  • 不直接改资源。

5. EnemyManager 子服务边界

5.1 EnemySpawnDirector

文件：Assets/GameMain/Scripts/CustomComponent/CombatNode/EnemyManager/EnemySpawnDirector.cs

职责：

  • 长期保留为独立服务。
  • 基于 spawnEntries + phase time 计算当前应执行的刷怪行为。
  • 提供“当前 phase 的 SpawnEntry 是否已全部执行完”的事实。

生命周期：

  • 由 CombatRunningPhaseState 在状态进入/退出时初始化与重置。

5.2 EnemySpawnPathResolver

文件：Assets/GameMain/Scripts/CustomComponent/CombatNode/EnemyManager/EnemySpawnPathResolver.cs

职责：

  • 缓存当前地图可用 Spawner。
  • 提供出生点与路径解析。

5.3 EnemyLifecycleTracker

文件：Assets/GameMain/Scripts/CustomComponent/CombatNode/EnemyManager/EnemyLifecycleTracker.cs

职责：

  • 维护 AliveEnemyCount 真值。
  • 维护 HasAliveBoss 真值。
  • 追踪本局 tracked 敌人。
  • 导出 tracked ids 供清场使用。

Boss 识别规则：

  • Boss 身份由 DRLevelSpawnEntry.EntryType == Boss 决定。
  • 不由 DREnemy 自身类型决定。

5.4 EnemyConfigProvider

文件：Assets/GameMain/Scripts/CustomComponent/CombatNode/EnemyManager/EnemyConfigProvider.cs

职责：

  • 读取 DREnemy。
  • 处理默认配置兜底。
  • 计算循环周目下的基础血量倍率。

6. 事件与数据流规范

6.1 MapEntity 与 Combat 域解耦

必须保持：

  • MapEntity 不直接查询 CombatNodeComponent 的运行时资源字段。
  • 战斗初始上下文通过 MapData 注入。
  • Coin 初值通过 MapData 传入。
  • 后续 Coin 变化通过 CombatCoinChangedEventArgs 同步。
  • TowerStatsData 等本局不变量直接放进 MapData。
  • MapEntity 不反查 Combat 域内部服务。

MapData 组装规则：

  • 由 CombatLoadingState 从局内资源管理器读取快照。
  • 由 CombatLoadingState 打包成 MapData 后再 ShowEntity(MapEntity)。

6.2 敌人事件处理

统一边界：

  • EnemyManager 只上报：
    • OnEnemyDefeated(DREnemy enemy)
    • OnEnemyReachedBase(DREnemy enemy)
  • CombatScheduler 公共层负责处理敌人事件的通用副作用：
    • 击杀：调用 GameEntry.InventoryGeneration.ResolveEnemyDrop(...)，再调用局内资源管理器入账。
    • 到家：调用局内资源管理器扣减 BaseHp。

约束：

  • 敌人事件入口不直接调用 ChangeState(...)。
  • BaseHp <= 0 的判断由当前状态在 OnUpdate 中处理。

6.3 战斗流程事件

发布边界：

  • 资源变化事件由局内资源管理器发布。
  • 流程/阶段事件由状态机或具体状态发布。

发布时间：

  • NodeEnterEventArgs：Loading 完成并正式进入首个 RunningPhase 时。
  • CombatProcessEventArgs：新 phase 的 RunningPhase.OnEnter。
  • CombatEnemyHpRateChangedEventArgs：与 CombatProcessEventArgs 同时发布。
  • NodeCompleteEventArgs：WaitingForReturn 完成清理、整场战斗真正退出时。

7. 结束链与结算上下文

7.1 统一结束链

正常结束统一走：

  • Settlement
  • RewardSelection（可选）
  • FinishForm
  • WaitingForReturn

7.2 结算上下文

归属：

  • 作为 CombatScheduler 上的共享字段存在。
  • Settlement 在 OnEnter 时统一构造。
  • RewardSelection 只追加奖励结果。
  • FinishForm 与 WaitingForReturn 只读取。

最小字段集合：

  • 最终结算的 Gold/Coin 结果
  • 待合并的背包快照
  • BaseHp 结算结果
  • 是否进入过奖励选择
  • FinishForm 所需摘要数据

命名约束：

  • 结算上下文中的布尔控制项统一收口到 Flags，不再使用 Flow 命名。

奖励选择约束：

  • 满血奖励选择结果只写入结算上下文。
  • 不直接写入局内资源管理器。
  • 最终由结束状态链统一合并到玩家背包。

8. 核心不变量（必须保持）

  1. CombatScheduler 只做状态机管理与共享运行时收口，不继续吸收具体业务细节。
  2. CombatNodeComponent 不再持有战斗内资源真值。
  3. 局内 Coin / Gold / BaseHp / Loot Backpack / BuildTowerSnapshots 以 CombatRunResourceStore 为唯一真值来源。
  4. 组件产出规则以 InventoryGenerationComponent 为统一运行时入口；战斗掉落与奖励候选都通过它生成。
  5. 存活敌人数与 HasAliveBoss 以 EnemyLifecycleTracker 为唯一真值来源。
  6. Phase 运行时信息与统一结束标记以 PhaseLoopRuntime 为唯一真值来源。
  7. PhaseEndType 的退出条件以 IPhaseEndCondition 实现类为唯一判定入口。
  8. 状态切换只能通过 CombatScheduler.ChangeState(...) 完成。
  9. 敌人事件处理入口不直接切状态，状态只能在自己的 OnUpdate 中决定迁移。
  10. MapEntity 通过 MapData + Event 获取战斗上下文，不反查 Combat 域内部运行时。

9. 清理职责

  • 敌人清理：EnemyManager，且只清理本局 tracked 敌人。
  • 地图与战斗基础 UI 清理：CombatLoadSession。
  • 结算/奖励 UI 清理：结束状态链或 Failed 状态。
  • 运行时数据重置：CombatScheduler 在状态机生命周期边界统一执行。

10. 扩展开发规范

10.1 新增刷怪类型或 SpawnEntry 行为

优先改 EnemySpawnDirector，不要把时序细节塞进 CombatRunningPhaseState。

10.2 新增 Phase 结束条件

新增 IPhaseEndCondition 实现类，不要在 CombatWaitingForPhaseEndState 里写大分支。

10.3 新增敌人掉落规则

优先改 InventoryGenerationComponent 及其下层规则模块，不要在 EnemyManager、CombatScheduler 或状态类里直接计算掉落。

10.3.x 新增奖励候选规则

优先改 InventoryGenerationComponent、RewardCandidateBuilder 或 DropPoolRoller，不要在结算状态链里复制一套候选生成规则。

10.4 新增战斗内资源或建塔快照规则

优先改 CombatRunResourceStore，不要回流到 CombatNodeComponent。

10.5 新增地图/战斗基础 UI 加载规则

优先改 CombatLoadSession 或 CombatLoadingState，不要把加载细节塞回 CombatScheduler 本体。

10.6 新增强化结算、奖励选择、结算 UI 逻辑

优先改结束状态链：

  • CombatSettlementState
  • CombatRewardSelectionState
  • CombatFinishFormState
  • CombatWaitingForReturnState

10.7 新增战斗流程事件

优先由具体状态或局内资源管理器发布，不要回流到 CombatNodeComponent。

11. 代码变更检查清单（PR 自检）

  1. 新逻辑是否落在正确的状态或服务，而不是继续堆进 CombatScheduler 本体？
  2. CombatNodeComponent 是否仍然保持为轻量入口 Facade？
  3. 是否破坏了局内资源、掉落判定、phase runtime、phase end 判定的唯一真值来源？
  4. 敌人事件处理是否仍然只做公共副作用，而不直接切状态？
  5. 状态迁移是否仍然统一走 ChangeState(...)？
  6. MapEntity 是否仍然只通过 MapData + Event 获取战斗上下文？
  7. 清理是否仍按”敌人 / 地图基础 UI / 结算 UI / 运行时数据”分工执行？

12. Combat Economy（战斗经济）

Status: 新增段落 — GDD 一致性审查中发现 Coin 经济在实现中存在但未写入文档 最后更新: 2026-04-30

本段说明战斗域内双货币体系的完整设计依据。所有数值均来自数据表驱动，无需代码硬编码。

12.1 双货币架构概述

游戏使用两层货币，分属不同生命周期：

货币 生命周期 存储位置 描述
Coin 单次战斗内 CombatRunResourceStore.CurrentCoin 战斗内部经济，用于建塔/升级/拆除
Gold 整局运行 PlayerInventoryComponent.Gold 跨节点持久，用于商店购买、出售

设计意图: Coin 创造战斗内的即时决策张力（”我现在花 Coin 建塔还是留着防万一？”）；Gold 创造跨节点的战略张力（”我是现在买还是等下一个商店？”）。两层经济分离，防止任一层的决策深度被稀释。

关键约束: Coin 不跨战斗持久，战斗结束时清零。战斗胜利后 GainedGold 入账，GainedCoin 不入账。

12.2 Coin（战斗内部货币）

12.2.1 来源

来源 字段 说明
关卡初始 Coin DRLevel.StartCoin 战斗开始时发放，来源于 CombatRunResourceStore.InitializeForCombat()
敌人击杀奖励 DREnemy.DropCoin 每次击杀敌人时发放，来源于 CombatRunResourceStore.AddEnemyDefeatedReward()

StartCoin 按关卡难度配置，确保玩家在战斗开始时有足够的决策空间。建议低难度关卡 StartCoin 较低，高难度/Boss 关卡较高。

DropCoin 按敌人类型配置。建议普通敌人 DropCoin 较低（5–15），精英敌人较高（20–50），与 DropGold 分开计算。

12.2.2 消耗（Sinks）

操作 消耗方式 触发时机
BuildTower TryConsumeCoin(buildTowerCost[i]) 玩家在战斗内点击建塔位，每槽位独立计费
UpgradeTower TryConsumeCoin(upgradeCost) 玩家升级已有塔
DestroyTower 无消耗；返回 destroyGain Coin 玩家拆除已有塔，Coin 返还

建塔槽位共 4 个（对应 BuildOptionCount = 4），每个槽位可独立消耗 Coin。每槽位的 buildTowerCost[i] 由关卡或战斗阶段配置。

12.2.3 追踪

CombatRunResourceStore.GainedCoin 记录本场战斗累计获得的 Coin。战斗结束时 GainedCoin 计入 RunStats.coinsEarned（跨战斗累计），但 Coin 本身不清零重置于下一个战斗，而是每个新战斗重新从 DRLevel.StartCoin 开始。

// 每场新战斗开始时
CurrentCoin = DRLevel.StartCoin  // 从关卡配置重置，非累加
GainedCoin = 0                  // 重置，用于本场统计

12.2.4 数据驱动约束

约束 值 说明
DRLevel.StartCoin ≥ 0 建议普通关卡 50–200，Boss 关卡 100–300
DREnemy.DropCoin ≥ 0 建议普通敌人 5–15，精英 20–50，Boss 0（避免重复计费）
buildTowerCost[i] ≥ 0 由 CombatSelectFormUseCase 从关卡配置读取，建议 20–80 每槽位
upgradeCost ≥ 0 由 CombatSelectFormUseCase 从关卡配置读取，建议 50–150
destroyGain ≥ 0 建议 = buildTowerCost * 0.5（返还 50%），与商店售价机制一致

12.3 Gold（战斗内获取部分）

战斗过程中 Gold 获取有两个来源：

12.3.1 敌人击杀掉落

// DREnemy 字段
DropGold     // 掉落金币数额
DropPercent  // 掉落概率 [0.0, 1.0]

战斗胜利时（敌人被击杀或波次结束），若随机值 ≤ DropPercent，则 AddEnemyDefeatedReward(gainedCoin, gainedGold) 被调用，gainedGold = DropGold。

12.3.2 关卡胜利奖励

战斗胜利结算时（CombatSettlementState），CombatSettlementCalculator 计算本场战斗总 Gold 奖励：DRLevel.RewardGold，通过 CombatRunResourceStore.AddSettlementGold() 入账。

战斗失败时：无 RewardGold，GainedGold = 0。

12.3.3 追踪

CombatRunResourceStore.GainedGold 记录本场战斗累计获得的 Gold（击杀掉落 + 胜利奖励）。战斗结束时通过 GetRewardInventorySnapshot() 合并至玩家主背包（PlayerInventoryComponent.MergeInventory()），触发 MaxPlayerGold = 9999 上限检查（溢出部分丢弃）。

12.4 Coin 与 Gold 的运行时边界

战斗开始 → InitializeForCombat(level)
    └→ CurrentCoin = level.StartCoin        // Coin 重置
    └→ GainedCoin = 0, GainedGold = 0      // 本场统计重置

战斗过程中（敌人死亡）→ AddEnemyDefeatedReward(dropCoin, dropGold)
    └→ CurrentCoin += dropCoin
    └→ CurrentGold (奖励库存) += dropGold   // 不影响主背包
    └→ GainedCoin += dropCoin
    └→ GainedGold += dropGold

战斗胜利 → AddSettlementGold(RewardGold)
    └→ GainedGold += RewardGold

战斗结束 → GetRewardInventorySnapshot() → MergeInventory()
    └→ 主背包 Gold += min(rewardGold, MaxPlayerGold - currentGold)
    └→ 主背包组件 += 奖励组件
    └→ RunStats.coinsEarned += GainedCoin  // 仅统计，不持久化 Coin

12.5 Progression 的 coinEarned 字段

字段 类型 说明
RunStats.coinsEarned int 跨战斗累计：本 run 所有战斗累计获得的 Coin 总和（战斗失败也计入）

coinsEarned 用于统计目的，不产生任何游戏内效果。它记录玩家在一局 run 中总共获得了多少 Coin — 可用于未来功能（如”累计获得 10000 Coin”成就），但当前无对应解锁或奖励。

12.6 与商店经济的隔离

Coin 仅在战斗域内流通。商店系统（design/gdd/shop.md）处理的 buy/sell 交易仅涉及 Gold，不涉及 Coin。

  • 战斗内不会触发商店交易
  • 商店内不会消耗或获得 Coin
  • 战斗结束时，Coin 不转换为 Gold（GainedCoin 仅计入 RunStats，不进入玩家背包）

12.7 调试与一致性检查

检查项 预期结果
新战斗开始时 CurrentCoin == DRLevel.StartCoin 相等
战斗结束时 GainedCoin ≥ 0 大于等于零
战斗失败时 GainedGold == 0 战斗失败不发放 Gold 奖励
MaxPlayerGold 上限检查 MergeInventory 后背包 Gold ≤ 9999
Coin 消耗后 CurrentCoin ≥ 0 TryConsumeCoin 失败时 CurrentCoin 不变