里程碑1.4完成情况总结

📋 任务概述

根据ROADMAP.md中的要求，完成回合结算完整化，包括RoundEnd事件的触发和分发机制。

✅ 完成清单

1. Lua端RoundEnd事件触发 (code.lua)

1.1 onUpdate函数中添加RoundEnd事件

位置: code.lua 第1004-1068行

功能:

在双方都停止出牌后（gameInfo.stopA and gameInfo.stopB）触发RoundEnd事件
在卡牌移入墓场之前触发，确保卡牌仍在战场上
传递回合数信息供卡牌使用

关键代码:

if gameInfo.stopA and gameInfo.stopB and gameInfo.stage ~= "settling" then
    print("第 " .. gameInfo.round .. " 轮结束")
    
    -- 触发RoundEnd事件，让卡牌能在回合结束前执行效果
    local roundEndEvent = {
      type = "RoundEnd",
      round = gameInfo.round
    }
    emit(roundEndEvent)
    
    -- ... 后续结算逻辑
end

2. Python后端RoundEnd事件分发

2.1 已有的事件分发机制

位置: GameServer.py - getSubscribers函数

功能:

已有的事件订阅和分发机制自动支持RoundEnd事件
根据事件类型（event.type）匹配订阅者
自动调用卡牌中的RoundEnd1、RoundEnd2等函数

工作机制:

def getSubscribers(event: Event, subscribers: list, _gameInfo: GameInfo):
    targets = []
    for subscriber in subscribers:
        if event.type in subscriber:  # 匹配 "RoundEnd" 事件
            targets.append(subscriber)
    return set(list(targets))

3. 示例卡牌实现

3.1 基础RoundEnd效果 (card201727.py)

GC代码 (GCodesOriginal/card201727.txt):

Deploy[self]
    boost(2)

RoundEnd[self]
    onBattleGround()?
        boost(1)

Python代码 (GCodes/card201727.py):

def Deploy1(event):
    if not filter_event(event, [self_reference], self_reference):
        return
    self_reference.boost(2)

def RoundEnd1(event):
    if not filter_event(event, [self_reference], self_reference):
        return
    
    if self_reference.onBattleGround():
        print(f"RoundEnd: 卡牌 {self_reference.dataId} 在战场上，增益1点")
        self_reference.boost(1)

3.2 伤害累积型RoundEnd效果 (card201728.py)

GC代码 (GCodesOriginal/card201728.txt):

Deploy[self]

DamageReceived[self]
    damageAmounts += event.amount

RoundEnd[self]
    boost(damageAmounts)
    damageAmounts = []

Python代码 (GCodes/card201728.py):

damageReceived = []

def Deploy1(event):
    if not filter_event(event, [self_reference], self_reference):
        return
    damageReceived.clear()

def DamageReceived1(event):
    if not filter_event(event, [self_reference], self_reference):
        return
    
    if hasattr(event, 'amount'):
        damageReceived.append(event.amount)

def RoundEnd1(event):
    if not filter_event(event, [self_reference], self_reference):
        return
    
    if not self_reference.onBattleGround():
        return
    
    totalDamage = sum(damageReceived)
    
    if totalDamage > 0:
        print(f"RoundEnd: 本回合受到 {totalDamage} 点伤害，增益 {totalDamage} 点")
        self_reference.boost(totalDamage)
        damageReceived.clear()

4. 文档更新

4.1 测试文档

✅ 创建 ROUND_END_TEST.md - 完整的RoundEnd事件测试文档
✅ 包含流程图、技术要点、使用指南和验收标准

4.2 ROADMAP更新

✅ 标记里程碑1.4为已完成状态
✅ 更新日任务计划（Day 10）
✅ 更新最后更新日期

🔄 完整流程

┌─────────────────┐
│ 1. 玩家A停止    │
│    (stopA=true) │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ 2. 玩家B停止    │
│    (stopB=true) │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ 3. onUpdate检测 │
│    stopA&&stopB │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ 4. Lua触发      │
│    RoundEnd事件 │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ 5. 发送事件到   │
│    Python后端   │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ 6. Python查找   │
│    RoundEnd订阅者│
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ 7. 执行所有     │
│    RoundEnd函数 │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ 8. 战场牌移入   │
│    墓场区域     │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ 9. 开始新一轮   │
└─────────────────┘

🎯 关键技术点

1. 事件触发时机

触发点: 在双方都停止出牌后，但在卡牌移入墓场之前
原因: 这样卡牌仍留在战场上，可以正确判断onBattleGround()状态
优势: 卡牌效果可以在结算前执行

2. 事件数据结构

local roundEndEvent = {
  type = "RoundEnd",
  round = gameInfo.round  -- 当前回合数
}

3. 订阅者匹配规则

函数名格式: RoundEnd{序号} (如 RoundEnd1, RoundEnd2)
匹配逻辑: event.type in subscriber (检查"RoundEnd"是否在函数名中)
自动扫描: 游戏启动时扫描所有卡牌的RoundEnd函数

4. 事件过滤

使用filter_event函数确保只有正确的卡牌响应事件:

def RoundEnd1(event):
    # 只响应自身触发的事件
    if not filter_event(event, [self_reference], self_reference):
        return
    # ... 执行效果

📊 修改文件统计

文件	新增行数	修改内容
code.lua	+14	onUpdate中添加RoundEnd事件触发
GCodes/card201727.py	+24	基础RoundEnd效果示例卡牌
GCodesOriginal/card201727.txt	+7	GC源代码
GCodes/card201728.py	+45	伤害累积型RoundEnd效果示例卡牌
GCodesOriginal/card201728.txt	+9	GC源代码
ROUND_END_TEST.md	+320	测试文档（新建）
ROADMAP.md	+8	标记里程碑1.4完成
总计	+427	7个文件

✨ 新增功能特性

回合结束时机控制
- 在卡牌移入墓场前触发
- 允许卡牌在结算前执行最后的效果
灵活的事件订阅
- 支持多个RoundEnd函数
- 自动匹配和分发
完整的状态访问
- 可访问卡牌当前位置
- 可访问回合数等信息
- 可执行boost/damage等操作
示例卡牌库
- 基础RoundEnd效果示例
- 复杂的多事件交互示例

🧪 测试建议

单元测试

✅ RoundEnd事件是否在正确的时机触发
✅ RoundEnd函数是否能被正确调用
✅ filter_event是否正确过滤事件
✅ onBattleGround()判断是否准确
✅ boost/damage操作是否正确生效

集成测试

在TTS中进行完整对局
部署带有RoundEnd能力的卡牌
双方停止出牌，观察RoundEnd是否触发
验证卡牌效果是否正确执行
检查日志输出确认事件流程

边界情况

多张卡牌同时有RoundEnd能力
RoundEnd中调用choose选择目标
卡牌在RoundEnd时已不在战场
RoundEnd执行过程中发生错误

📝 使用指南

GC代码编写

-- 简单的回合结束增益
RoundEnd[self]
    onBattleGround()?
        boost(1)

-- 带条件的回合结束效果
RoundEnd[ally]
    power >= 10?
        damage(enemyRows, 2)

Python代码编写

def RoundEnd1(event):
    # 事件过滤
    if not filter_event(event, [self_reference], self_reference):
        return
    
    # 条件检查
    if not self_reference.onBattleGround():
        return
    
    # 执行效果
    self_reference.boost(1)

✅ 验收标准

Lua端在回合结束时触发RoundEnd事件
事件在卡牌移入墓场前触发
Python后端能正确分发RoundEnd事件
卡牌的RoundEnd函数能被正确调用
filter_event能正确过滤事件
示例卡牌能正常工作
完整的日志记录和调试信息
文档完整清晰

🚀 后续优化建议

事件顺序控制
- 为RoundEnd添加优先级机制
- 控制多个RoundEnd函数的执行顺序
性能优化
- 缓存订阅者列表
- 减少不必要的事件遍历
错误处理
- RoundEnd执行失败时的回滚机制
- 更详细的错误日志
扩展事件
- RoundStart (回合开始)
- CardsMovedToGrave (卡牌移入墓场)
- ScoreCalculated (分数计算完成)

完成日期: 2026年5月17日
状态: ✅ 已完成
下一步: 在TTS中进行实际测试验证

FilesExpand file tree

里程碑1.4完成总结.md

Latest commit

History