事件系统与调试指令

与 地图与事件设计、系统与循环 配套。

1. 事件管线

组件	职责
UEventDirectorSubsystem	订阅 RoundStart、TimerSegment、PlayerAction；从 DT_EventLevel 取候选集并随机。
FEventContext	MapId、LogicRound、InstigatorSeat、RandomStream。
IEventEffect	Apply(EventContext&) / Rollback（可选，用于预测回滚）。
EffectHandlerRegistry	EffectType → 工厂注册（C++ 静态注册 + Blueprint 可选）。

已实现效果类型（开工最小集）

EffectType	参数约定	行为
AdjustLandPrice	Param1: 坐标或范围编码；Param2: 增量 int	修改 GameState 内地价覆盖层。
UnlockTiles	Param1: 坐标列表或矩形	将格 TileState 置为有效。
PlayDialog	Param1: 对话资产 Id	UI 子系统播对话；无 UI 时记日志。

权威原则：Apply 仅在 Server 修改 AGameStateSOTT（或专用 UWorldSubsystem 数据容器）；复制到客户端后 UI 刷新。

2. 触发与阶段机协作

逻辑回合开始
  → PhaseController 进入「事件阶段」或内联钩子
  → EventDirector.FireRoundStart(RoundIndex)
  → 对每个选中 EventId 顺序 Apply（或并行无冲突子集）
  → 进入下一玩家阶段

TimerSegment 用于 [01] 解锁竞拍格、市场轮末撮合等 时间驱动 事件，与 LogicRound 解耦。

3. 调试 / GM 指令

类别	约束
Cheat	仅 #if UE_BUILD_DEVELOPMENT，打包 Shipping 编译剔除。
Admin	需 APlayerController 带 bIsAdmin 或独立 Token（联机时慎用）。

建议指令清单

指令	作用域	说明
SOTT.SkipPhase	Server	跳到下一阶段（回归阶段机）。
SOTT.SetCash <seat> <amount>	Server	改现金。
SOTT.FireEvent <EventId>	Server	直接触发总表事件。
SOTT.DumpMarket	Server/Client	打印当前挂单与需求快照。
SOTT.SetLogicRound <n>	Server	强制回合（配合事件测试）。

执行路径：UPlayerInput Exec → Server RPC → AdminCommandHandler 白名单解析 → 调子系统。

4. 与策划表的关系

• DT_EventMaster.EventId 必须在 EffectHandlerRegistry 有处理器，否则 Load 阶段断言。
• 新增效果：先加 C++ 枚举与 Apply 实现，再开放 Excel 行。

5. 安全与日志

• 所有 Cheats 写 结构化日志（Seat、UserId、指令全文、结果码）。
• match_events 表（若启用）同步写入 Cheat 行，便于线上追责。