Game Event Director

用于通用游戏项目里“事件发生 -> 玩家看见 -> 状态改变 -> 后续系统读到”的链路开发。不假设题材、平台、横竖屏或引擎，始终从当前项目事实源判断。

启动检查

1. 先读项目级指令和当前上下文，例如 AGENTS.md、CLAUDE.md、README、任务文档或 active context；只读与本轮任务直接相关的部分。
2. 用 rg 定位事件名、任务名、director/manager/system/controller、配置、存档字段、测试和 UI 消费端。
3. 如果事件包含面板、弹窗、HUD、按钮或结算界面，叠加 game-ui-panels。
4. 如果事件包含角色、单位、载具、镜头、动画、路径或站位表现，叠加 game-entity-movement-presentation。
5. 如果要改场景、Prefab、资源元数据、节点绑定、动画轨道或编辑器资产，先遵循项目已有的引擎/资产安全流程；没有流程时先停下给 planned files 和风险说明。

执行流程

1. 锁定事件合同

先明确事件合同，再动代码：

• purpose：玩家应该理解什么变化，或被迫做什么选择。
• trigger：由时间、输入、区域、任务、资源、战斗、道具、建筑、NPC、网络/服务端状态、存档 flag 中的哪一项触发。
• phase：未解锁、待触发、进行中、可处理、结算中、已完成、失败、跳过如何表示。
• result：写回资源、背包、任务、角色、战斗、经济、世界状态、存档、日志、成就或分析中的哪些字段。
• reentry：读档、换场景、暂停恢复、重复进入面板、失败重试、跳过后是否可恢复。

2. 画出消费面

列出会读取或展示该事件状态的面：

• 纯逻辑、配置、数据表或规则层。
• director、manager、system、controller 或调度层。
• 引擎组件、脚本、场景节点、动画、音效、VFX、镜头或实体表现。
• UI 面板、气泡、对话、按钮、提示、结算、复盘或日志。
• 存档、任务、成就、遥测、测试和运行时 QA 点。

3. 做 planned files 判断

低风险、范围明确时可以直接做：单次不超过 5 个业务文件、无架构变化、无核心玩法口径变化。

出现以下情况先停下给方案和证据：

• 触及核心循环、经济、任务、战斗、存档、网络同步、UI 框架或场景结构。
• 单轮计划改动超过 5 个业务文件。
• 用户指令、设计文档、代码事实、当前版本目标之间冲突。
• 需要删除旧逻辑、重写公共事件框架或迁移已有存档字段。

4. 最小实现

• 把事件判定和结果写回放在 core、规则层、配置或既有系统内；引擎组件和 UI 只做绑定、转发和表现。
• 优先复用已有事件类型、任务状态、配置格式、弹窗、对话、镜头、实体 director 和日志管线。
• 不为单个事件新增宽泛框架；需要抽象时先证明至少有两个真实消费者。
• UI 显示必须来自真实事件状态，不做只有文案没有触发链路的“空事件”。
• 完成、失败、跳过、过期和重入状态都要可查询，避免只靠一次性弹窗判断。

5. 验证

按改动类型选择最小有效检查：

• 纯逻辑：覆盖触发条件、结果写回、重复触发、失败/跳过、读档/重入边界。
• UI 或数据转换：同步覆盖 ViewModel、panel adapter 或消费端测试。
• 共享类型或脚本：跑项目已有的 typecheck、build、lint 或等价检查。
• 场景、Prefab、镜头、动画、遮挡、节奏、音画同步：列为编辑器/真机/运行时 QA；不要用单元测试冒充视觉验证。
• 收尾跑项目可用的 diff whitespace 检查，例如 git diff --check。

输出合同

汇报时至少说明：

• event_contract：触发、阶段、结果、重入规则。
• surfaces：涉及 core、system、component、UI、实体、镜头、存档或日志中的哪些面。
• changed：实际改动文件和原因。
• verification：跑过的测试、typecheck、build、lint 或 diff check。
• qa：仍需编辑器、真机、截图或运行时确认的可视/时序问题。
• next：只给一个最推荐后续动作。

失败条件

出现以下情况要停下，不继续硬做：

• 只做了弹窗、文案或动画，没有真实触发条件和状态写回。
• UI 字段、奖励、任务结果或日志没有可靠数据源。
• 事件结果会改变核心玩法、经济、任务、存档或联网状态，但产品口径不明确。
• 需要删除旧逻辑或重写公共事件框架。
• 同一测试、类型、资源或运行时问题连续 2 次修复仍失败。
• 声称“视觉已验证”，但没有编辑器、真机、截图、录屏或运行时证据。