Buff系统重构（会议用）

[Steinwaysj]

老框架介绍

简化流程

  flowchart LR
      A[CSV配置] --> B[BuffJudge<br/>条件判定]
      B --> C{触发类型}

      C -->|简单逻辑| D[字符串匹配]
      C -->|复杂逻辑| E[XLogic模块]

      D --> F[创建Buff实例]
      E --> F

      F --> G[更新状态]
      G --> H[加入动态列表]
      H --> I[生效处理]

      style A fill:#ffeb3b
      style B fill:#2196f3
      style C fill:#9c27b0
      style F fill:#4caf50

Loading

当前现状

当前的Buff系统存在严重的技术债务，耦合度很高，而且OOP程度低，Buff管理分散，业务逻辑分散；生命周期定义混乱，并且整个系统性能很差，存在大量不必要的对象构造。

• 痛点分析：
  • 高耦合设计：Buff实例直接持有整个模拟器对象(sim_instance)，形成"上帝对象"依赖，导致单元测试几乎无法开展
  • 低内聚实现：面向对象程度低，Buff管理逻辑分散在各个角落，缺乏统一的生命周期管理
  • 静态类型检查极其不友好：开启类型检查后整个代码完全没法看（历史遗留问题）
  • 架构混乱：业务逻辑与Buff框架深度绑定，相同逻辑无法复用，每个Buff都是独立的"脚本孤岛"
  • 性能瓶颈：存在大量不必要的对象构造和销毁，内存使用效率低下
  • 业务界定混乱：外部系统可以通过其他方法干涉Buff的触发（如直接触发、提前剔除等），导致业务逻辑管理混乱。
  • 缺少Pytest

重构目标（具体化、可衡量）

###新架构示意图：

  flowchart TD
      A[游戏事件] --> B[EventRouter<br/>事件路由]
      B --> C[Registry<br/>注册中心]
      C --> D[ConditionEvaluator<br/>条件评估]
      D --> E{条件满足?}
      E -->|是| F[EffectExecutor<br/>效果执行]
      E -->|否| G[跳过]
      F --> H[BuffInstance<br/>Buff实例]
      H --> I[BuffStore<br/>存储管理]
      I --> J[应用效果]

      style A fill:#e1f5fe
      style B fill:#fff3e0
      style D fill:#f3e5f5
      style F fill:#e8f5e8
      style I fill:#fff8e1

Loading

目录结构

  flowchart TD
      A[Buff/] --> B[definitions/<br/>数据定义]
      A --> C[registry.py<br/>注册中心]
      A --> D[engine/<br/>核心引擎]
      A --> E[store/<br/>存储管理]

      B --> B1[BuffDefinition]
      B --> B2[Condition/Effect]

      D --> D1[EventRouter]
      D --> D2[ConditionEvaluator]
      D --> D3[EffectExecutor]

      E --> E1[BuffStore]
      E --> E2[BuffInstance]

      style A fill:#e3f2fd
      style B fill:#fff3e0
      style C fill:#f3e5f5
      style D fill:#e8f5e8
      style E fill:#fff8e1

Loading

• 按“条件”“效果”两大模块拆分职责，利用数据库注册Buff，统一处理逻辑；
• 新增 definitions模块（BuffDefinition, Trigger, Condition, Effect, TargetSelector 数据类）与 registry.py。
• 设计SQLite架构（数据类名暂定），包含：
  • buffs（基础信息、叠层规则、持续方式、受益人）
  • buff_triggers（事件类型、触发参数）
  • buff_effects（效果模板 ID、约束参数，格式为JSON，内部处理用pydantic）
• 引入 engine 模块，划分三个核心服务：
  • EventRouter（按事件类型筛选候选 Buff，避免全部遍历，提高性能）
  • ConditionEvaluator（Buff判定逻辑核心。解释器式遍历条件树，可组合比较/区间/标签判定）
  • EffectExecutor（基于效果模板调用对应的计算函数）
  • 逐步淘汰现有BuffLoadLoop
• 构建新的 BuffInstance（只含状态），并通过 BuffStore（封装对 DYNAMIC_BUFF_DICT 的CRUD）完成解耦。
• 对每个已解耦的新模块增加test case

补充材料

展开查看原有框架的详细流程图

注：本流程图为Ai绘制！

  flowchart TD
      A[游戏循环开始<br/>Game Loop Start] --> B[Load阶段<br/>技能事件触发]

      B --> C[BuffLoadLoop<br/>Buff加载循环]

      C --> D{遍历所有角色<br/>Traverse Characters}

      D --> E[前台角色处理<br/>Process On-Field Buff]
      D --> F[后台角色处理<br/>Process Backend Buff]

      E --> G{遍历角色Buff_0<br/>Iterate Buff_0}
      F --> G

      G --> H{Buff是否应该处理?<br/>schedule_judge?<br/>passively_updating?}
      H -->|否| G
      H -->|是| I[计算受益角色<br/>Calculate Beneficiaries]

      I --> J[ProcessBuff<br/>处理单个Buff]

      J --> K[BuffInitialize<br/>Buff初始化]
      J --> L[BuffJudge<br/>Buff判定]

      K --> M{从缓存获取?<br/>Cache Hit?}
      M -->|是| N[返回缓存结果]
      M -->|否| O[读取CSV配置<br/>Load CSV Config]
      O --> P[创建配置字典<br/>Create Config Dict]

      L --> Q{简单逻辑?<br/>simple_judge_logic?}
      Q -->|是| R[Simple Judge<br/>字符串匹配判定]
      Q -->|否| S[Complex Judge<br/>调用xjudge方法]

      N --> T{判定通过?<br/>Judge Passed?}
      R --> T
      S --> T
      P --> T

      T -->|否| G
      T -->|是| U{简单效果逻辑?<br/>simple_effect_logic?}

      U -->|是| V[遍历子任务<br/>Iterate Sub-Missions]
      U -->|否| W[调用xeffect<br/>复杂效果逻辑]

      V --> X{子任务在当前tick?<br/>Sub-Mission Active?}
      X -->|否| V
      X -->|是| Y[创建新Buff实例<br/>Create New Buff Instance]

      Y --> Z[Buff Update<br/>更新Buff状态]
      W --> AA[设置状态变更<br/>Mark State Changed]

      Z --> BB{子任务类型<br/>Sub-Mission Type}
      BB -->|start| CC[update_cause_start<br/>开始逻辑]
      BB -->|hit| DD[update_cause_hit<br/>命中逻辑]
      BB -->|end| EE[update_cause_end<br/>结束逻辑]

      CC --> FF{简单开始逻辑?<br/>simple_start_logic?}
      DD --> GG{简单命中逻辑?<br/>simple_hit_logic?}
      EE --> HH{简单结束逻辑?<br/>simple_end_logic?}

      FF -->|是| II[标准开始处理<br/>Standard Start Process]
      FF -->|否| JJ[调用xstart<br/>复杂开始逻辑]

      GG -->|是| KK[标准命中处理<br/>Standard Hit Process]
      GG -->|否| LL[调用xhit<br/>复杂命中逻辑]

      HH -->|是| MM[标准结束处理<br/>Standard End Process]
      HH -->|否| NN[调用xend<br/>复杂结束逻辑]

      II --> OO[更新层数和时间<br/>Update Count & Duration]
      JJ --> OO
      KK --> OO
      LL --> OO
      MM --> OO
      NN --> OO

      OO --> PP{状态是否变更?<br/>State Changed?}
      AA --> PP
      PP -->|否| V
      PP -->|是| QQ[添加到Loading Dict<br/>Add to LOADING_BUFF_DICT]

      V --> RR[所有子任务完成?<br/>All Sub-Missions Done?]
      RR -->|否| X
      RR -->|是| G

      QQ --> SS[所有Buff处理完成?<br/>All Buffs Processed?]
      SS -->|否| G
      SS -->|是| TT[BuffAdd阶段<br/>Buff添加阶段]

      TT --> UU{遍历Loading Dict<br/>Iterate LOADING_BUFF_DICT}

      UU --> VV[获取角色Buff列表<br/>Get Character Buff List]

      VV --> WW{列表是否为空?<br/>List Empty?}
      WW -->|是| UU
      WW -->|否| XX[取出Buff实例<br/>Pop Buff Instance]

      XX --> YY{Buff是否有效?<br/>Buff Valid?<br/>active=True<br/>count>0<br/>endticks>0}
      YY -->|否| VV
      YY -->|是| ZZ{Buff已存在?<br/>Buff Already Exists?}

      ZZ -->|是| AAA[移除旧Buff<br/>Remove Old Buff]
      ZZ -->|否| BBB[添加到Dynamic Dict<br/>Add to DYNAMIC_BUFF_DICT]
      AAA --> BBB

      BBB --> CCC{是Debuff?<br/>Is Debuff?}
      CCC -->|是| DDD[添加到敌人Debuff列表<br/>Add to Enemy Debuff List]
      CCC -->|否| VV
      DDD --> VV

      VV --> EEE{所有角色处理完成?<br/>All Characters Done?}
      EEE -->|否| UU
      EEE -->|是| FFF[Schedule阶段<br/>调度阶段]

      FFF --> GGG[更新活跃Buff<br/>Update Active Buffs]
      GGG --> HHH[处理Buff效果<br/>Process Buff Effects]
      HHH --> III[清理过期Buff<br/>Clean Expired Buffs]
      III --> JJJ[游戏循环继续<br/>Game Loop Continue]

      style A fill:#e1f5fe
      style TT fill:#fff3e0
      style FFF fill:#f3e5f5
      style JJJ fill:#e8f5e8

Loading

以上系统在拓展、同名Buff的不同处理、Buff需要判断受益人来确定是否触发等实际业务方面存在较多问题！同时，性能也非常差。

[ZH1637]

1.角色的动态属性没有增量更新的问题，重构之后应该会有个触发动态属性更新的事件？
2.buff和事件的更新应该需要一个时间轴之类的历史记录？每个时间节点上需要对应的上下文，这样也方便后期测试。这个方式其实也确保了buff更新过程中的可溯源，这样也不需要新建一个buff用来更新了
3.针对具体的buff或者事件更新，尝试能否进行矩阵化计算？就是提前哈希可能触发的事件和buff，通过类似于字典的get方法拿到所要更新的对象后，直接去更新。这样应该能避免掉多次的遍历
4.关于危局之类的环境buff，除了模拟一个空的代理人之外，其实环境buff可以独立为一个事件，一个每个ticket都会触发环境buff的事件
5.buff和事件的联动个人认为还有个关键点，在于事件条件符合时候，buff的具体行为，这个其实也可以抽象出来，类似于层数的增减，buff的生命周期行为，buff需要生效的对象等等。buff去触发事件时同理。

[TommrraraSnow]

1. 后来想了一下，Buff Effect增量更新，动态面板Lazy Load是最好的方法
2. 可以试试，目前的选型是树状条件判断，叶子节点保留上下文可能会更好
3. 目前期望的选型是用事件系统+Router的逻辑来避免遍历，不清楚相较于你的想法哪个更好，可能需要示例
4. 目前也是这么打算的
5. 目前打算通过Buff触发时，可以动态注册事件触发器来解决这个问题，需要事件系统可以动态注册与解除注册

[ZH1637]

classDiagram
    
    class 事件监听器 {
        tick触发的事件
        Buff生命周期触发的事件
        触发buff更新事件+代理人属性更新事件
    }
    class buff更新事件 {
        （所有可能的事件条件做哈希）
        影响什么buff
        buff新增
        buff消亡
        buff目标变更
        buff层数变更
    }
    
    class Buff {
        （所有可能的buff做哈希）
        名称
        生命周期事件
        属性计算方式
        生命周期行为
        所属对象--引用
    }

    事件监听器 --> buff更新事件
    buff更新事件 --> Buff
    Buff --> 事件监听器

Loading