54shitaimzf
e465f1cbb0
- Added BattleState class to manage battle flow, including turn management and event handling. - Introduced BuffInstance class to represent buffs applied to combatants. - Created CardInstance class to handle card definitions and cost calculations. - Developed CombatantState class to manage combatant attributes and actions. - Implemented EffectRegistry to apply effects based on event specifications. - Added various handlers (BlockHandler, DamageHandler, DrawHandler, etc.) to process specific events. - Created IntentPlanner and IntentState classes to manage enemy actions and intents. - Established a queue system for handling battle events with BattleEventQueue and BattleEventTask. - Introduced triggers for applying effects based on game events (e.g., OnCardDrawnGainBlockTrigger). - Added necessary UID files for new scripts to ensure proper resource management.
3.9 KiB
3.9 KiB
RFC: 可扩展战斗卡牌架构（Godot 4.6 + GDScript）
1. 摘要
本 RFC 覆盖局内战斗重构，目标是把当前流程升级为统一事件内核。
核心方案：
- 统一事件队列是唯一执行路径。
- 卡牌效果和 Buff 效果统一为事件生产者。
- 出牌器和抽牌器策略化，并通过单点入口切换。
2. 目标与非目标
2.1 目标
- 新增普通卡尽量只新增一个 CardDef 资源文件。
- 支持触发器机制：抽牌、伤害、出牌、弃牌、回合事件可连锁。
- 战斗链路可追踪、可调试、可回归测试。
- 保留未来由局外系统接管规则的单点入口。
2.2 非目标
- 本阶段不实现局外系统逻辑。
- 本阶段不实现复杂表达式引擎。
- 本阶段不实现并发结算。
3. 架构原则
- 命令层只发请求事件，不直改 hp/block/strength/weak。
- 所有效果先入队，再由处理器执行。
- 二次触发统一追加队尾，禁止插队。
- 同帧顺序按速度/权重，实体内按 Buff 获得顺序。
- 策略返回空动作时不自动结束回合。
4. 核心分层
4.1 Content（Resource）
- CardDef：卡牌静态定义（卡面、描述、费用、目标、标签、效果）。
- EffectSpec：事件模板定义（event_type、payload、conditions）。
- ConditionSpec：过滤条件定义。
4.2 Runtime（State + Queue + Handler）
- BattleState：状态容器和原子操作，不负责编排。
- BattleEventQueue：唯一执行队列。
- EventHandler：处理事件并更新状态，必要时产出后续事件。
- BuffInstance：触发订阅实例（包含 acquire_index、stack、duration）。
4.3 Application（Command）
- PlayCardCommand：发布 CARD_PLAY_REQUESTED。
- EndTurnCommand：发布 TURN_END_REQUESTED 与敌方行动请求。
4.4 Infrastructure
- BattleEventBus：事件广播和观测输出。
- DebugLogger：统一链路日志。
4.5 Presentation
- BattleController：读取规则提供器、驱动流程、订阅事件更新 UI。
- BaseCardView：纯展示和交互，不写战斗规则。
5. 统一事件模型
5.1 EventType（首批）
- CARD_PLAY_REQUESTED
- CARD_PLAY_RESOLVED
- CARD_DRAW_REQUESTED
- CARD_DRAWN
- CARD_DISCARDED
- DAMAGE_REQUESTED
- DAMAGE_APPLIED
- BLOCK_REQUESTED
- BLOCK_APPLIED
- WEAK_APPLIED
- TURN_START_REQUESTED
- TURN_STARTED
- TURN_END_REQUESTED
- TURN_ENDED
5.2 EventPayload（最小字段）
- source
- owner
- target
- card_id
- amount
- tags
- chain_id
- queue_index
- producer
6. 策略入口（可迁移）
- BattleRuleProvider 是唯一规则入口。
- active_auto_play_policy：出牌器策略。
- active_draw_policy：抽牌器策略。
- 当前为代码配置，未来可替换为局外系统数据源。
7. 实施顺序
- 文档先行：先完成重构交接文档和现有文档修正。
- 事件内核：落地 EventType/Payload/Task/Queue 和防循环。
- 处理器：伤害/格挡/虚弱/抽牌/弃牌。
- Buff触发器：监听事件并队尾追加后续事件。
- 命令事件化：PlayCard/EndTurn 禁止直改状态。
- 策略化：出牌器和抽牌器接入 BattleRuleProvider。
- 内容模型：CardDef 单文件生产，EffectSpec 事件模板化。
- 测试：顺序、防循环、触发器、策略切换、单卡新增。
8. 验收标准
- 命令层无战斗属性直改。
- 所有效果经 BattleEventQueue 执行。
- 触发器顺序可复现：速度/权重 -> acquire_index -> 队尾追加。
- 仅改 BattleRuleProvider 即可切换出牌器与抽牌器。
- 新增普通卡仅需一个 CardDef 文件。
9. 风险与控制
- 风险：激进重构期间不可玩时间过长。 控制：每个阶段必须可运行并有最小验收。
- 风险：触发链死循环。 控制：深度阈值、步数阈值、去重键。
- 风险：术语和流程理解不一致。 控制：文档先行并与代码同步更新。