# 框架实现进度与待办

## 一、已创建的文件结构（25个文件）

```
maps/EntryMap/script/
├── main.lua                     ← 入口
├── config/
│   ├── const.lua                ← 全局常量
│   └── balance.lua              ← 数值配置
├── core/
│   ├── game_manager.lua         ← 局状态机
│   ├── player_manager.lua       ← 玩家管理
│   ├── npc_manager.lua          ← NPC管理
│   ├── mode_manager.lua         ← 游戏模式
│   └── timer_manager.lua        ← 全局计时
├── systems/
│   ├── suspicion.lua            ← 怀疑值系统
│   ├── disguise.lua             ← 换装系统
│   ├── corpse.lua               ← 尸体与藏尸
│   ├── assassination.lua        ← 刺杀系统
│   ├── item_spawner.lua         ← 物品刷新
│   └── circle.lua               ← 缩圈系统
├── profession/
│   ├── base.lua                 ← 职业注册基类
│   ├── shadow_blade.lua         ← 影刃
│   ├── mimic.lua                ← 千面
│   ├── eagle_eye.lua            ← 鹰眼
│   ├── surgeon.lua              ← 医师
│   ├── phantom.lua              ← 幽灵
│   └── hound.lua                ← 猎犬
├── ai/
│   └── npc_behavior.lua         ← NPC行为AI
└── ui/
    ├── hud.lua                  ← HUD更新
    ├── notification.lua         ← 通知系统
    └── scoreboard.lua           ← 结算面板
```

---

## 二、各模块已实现的功能

### 2.1 main.lua — 入口

| 功能 | 状态 | 说明 |
|------|------|------|
| 游戏初始化事件注册 | ✅ 完成 | 绑定 `游戏-初始化` 事件，设置随机种子，启动所有管理器 |
| 所有模块预加载 | ✅ 完成 | require 全部 config/core/systems/profession/ai/ui 模块 |
| 6个职业注册 | ✅ 完成 | 加载所有 profession/*.lua，注册到 base |
| 单位死亡事件 | ✅ 完成 | 监听 `单位-死亡`，若死亡单位是玩家则调用 PlayerMgr |
| 技能施法事件 | ✅ 完成 | 监听 `技能-施法开始`，路由到职业技能处理器 |
| 键盘输入事件 | ✅ 完成 | F键=刺杀, E键=互动/换装/藏尸, G键=拖拽尸体 |

### 2.2 config/const.lua — 全局常量

| 内容 | 状态 | 说明 |
|------|------|------|
| 游戏模式配置 | ✅ 完成 | `GAME_MODE` 支持 ffa/team/vip_escort |
| 玩家单位 Key | ⚠️ 占位 | `unit_player_assassin`，需在物编中创建后填入实际值 |
| NPC 单位 Key | ⚠️ 占位 | 4种NPC类型，需物编创建 |
| NPC 模型池 | ❌ 空表 | `NPC_MODEL_POOL = {}`，需填入模型Key列表 |
| Road 路径列表 | ❌ 空表 | `ROAD_LIST = {}`，需填入路径或由代码自动收集 |
| 10个 Buff Key | ⚠️ 占位 | 怀疑值3级Buff + 护盾/毒/标记等，需物编创建 |
| 6个技能 Key | ⚠️ 占位 | 6个职业的主动技能，需物编创建 |
| 8个物品 Key | ⚠️ 占位 | 毒针/飞刀/护甲等8种物品，需物编创建 |
| 投射物/特效 Key | ⚠️ 占位 | 飞刀投射物、烟雾/脚印特效，需物编创建 |
| 状态枚举 | ⚠️ 占位 | 无敌/定身/隐身，需确认引擎中的实际枚举名 |
| 阵营玩家 | ✅ 完成 | NPC=玩家31, 红队=玩家30, 蓝队=玩家29 |

### 2.3 config/balance.lua — 数值配置

| 内容 | 状态 | 说明 |
|------|------|------|
| 6种职业血量 | ✅ 完成 | 90~110 HP 差异化 |
| 移速配置 | ✅ 完成 | 基础5.0, NPC步行3.0 |
| 刺杀数值 | ✅ 完成 | 范围2m, 前摇0.5s/0.2s, 伤害70/105 |
| 怀疑值数值 | ✅ 完成 | 击杀/拖拽/失手时的增量 |
| 换装时间 | ✅ 完成 | 普通3s, 千面1.5s |
| 尸体/藏尸 | ✅ 完成 | 30秒腐烂，5m发现距离 |
| 复活配置 | ✅ 完成 | 1次复活，8秒等待 |
| 积分配置 | ✅ 完成 | 击杀+100, 死亡-20, 藏尸+15 |
| 物品刷新 | ✅ 完成 | 45秒刷新周期 |
| 缩圈配置 | ✅ 完成 | 初始120m, 最小20m, 首缩3分钟 |

### 2.4 core/game_manager.lua — 局状态机

| 功能 | 状态 | 说明 |
|------|------|------|
| 状态定义 | ✅ 完成 | PREPARE → PLAYING → OVERTIME → ENDED |
| on_prepare | ✅ 完成 | 初始化NPC、玩家、物品、模式、怀疑值；10秒无敌 |
| on_playing | ✅ 完成 | 启动缩圈，计时进入OVERTIME |
| on_overtime | ✅ 完成 | 怀疑值倍率×2，NPC减少30% |
| on_ended | ✅ 完成 | 停止系统，排名结算，显示胜负 |

### 2.5 core/player_manager.lua — 玩家管理

| 功能 | 状态 | 说明 |
|------|------|------|
| 初始化所有玩家 | ✅ 完成 | 获取所有玩家，为每人创建单位 |
| 创建玩家单位 | ✅ 完成 | 设HP/移速/物品栏，初始伪装，赋予技能 |
| 玩家死亡处理 | ✅ 完成 | 积分结算、标记尸体、判断复活、胜负检查 |
| 复活 | ✅ 完成 | 新生点、满血、新伪装、清零怀疑值 |
| 积分操作 | ✅ 完成 | add_score |
| 查询接口 | ✅ 完成 | get_data_by_unit, get_all_player_units, get_alive_count, get_rankings |
| 随机出生点 | ✅ 完成 | 从 `player_spawn` 标签区域中随机选取 |
| 随机NPC模型 | ✅ 完成 | 从模型池中随机（需填充 NPC_MODEL_POOL） |

### 2.6 core/npc_manager.lua — NPC管理

| 功能 | 状态 | 说明 |
|------|------|------|
| 批量生成NPC | ✅ 完成 | 按权重随机类型（平民50%/巡逻20%/商贩15%/闲逛15%） |
| 类型分配行为 | ✅ 完成 | 巡逻/平民=沿路径，商贩=固定，闲逛=区域漫游 |
| 路径收集 | ✅ 完成 | 按标签自动搜集 road_main_loop/patrol/alley/square |
| 闲逛AI | ✅ 完成 | 在中心点15m范围内随机移动，5~12秒间隔 |
| 恐慌触发 | ✅ 完成 | 指定半径内NPC朝反方向逃跑，8~12秒后恢复 |
| 逃跑方向计算 | ✅ 完成 | calc_flee_point 反方向计算 |
| 缩减NPC数量 | ✅ 完成 | 按比例随机移除（紧迫期用） |

### 2.7 core/mode_manager.lua — 游戏模式

| 功能 | 状态 | 说明 |
|------|------|------|
| 独狼模式 (FFA) | ✅ 完成 | 所有玩家互为敌人 |
| 组队模式 (Team) | ✅ 完成 | 均分两队 red/blue |
| VIP护送模式 | ✅ 完成 | 随机VIP(200HP,减速)，分护送/刺杀队 |
| 假VIP生成 | ✅ 完成 | 在 fake_vip_spawn 区域创建伪VIP |
| 检查点系统 | ✅ 完成 | checkpoint 区域按序号排列，VIP进入触发通知 |
| 撤离点 | ✅ 完成 | exit_point 区域，VIP到达=护送队获胜 |
| 复活判断 | ✅ 完成 | 按模式判断是否允许复活 |
| 胜负检查 | ✅ 完成 | FFA=剩1人, Team=一方全灭, VIP=VIP死亡无复活 |

### 2.8 systems/suspicion.lua — 怀疑值系统

| 功能 | 状态 | 说明 |
|------|------|------|
| 每秒循环更新 | ✅ 完成 | 同步Timer循环所有存活玩家 |
| 自然衰减 | ✅ 完成 | -0.5/秒 |
| 奔跑检测 | ✅ 完成 | 移速>NPC×1.2 → +2/秒 |
| 静止过久 | ✅ 完成 | 静止>5秒 → +1/秒 |
| 混入人群 | ✅ 完成 | 5m内NPC≥3 → -1/秒 |
| 暗区加成 | ✅ 完成 | 在 `light_dark` 区域内 → -1/秒 |
| 倍率系统 | ✅ 完成 | 紧迫期怀疑值增长×2 |
| 阈值Buff | ✅ 完成 | 0-29无/30黄色/60橙色/80红色，自动切换Buff |
| 红色减速 | ✅ 完成 | ≥80时降低移速，恢复后还原 |

### 2.9 systems/disguise.lua — 换装系统

| 功能 | 状态 | 说明 |
|------|------|------|
| 对尸体换装 | ✅ 完成 | 距离检查、前摇、模型互换、清零怀疑值 |
| 千面职业加速 | ✅ 完成 | 千面换装1.5秒（普通3秒） |
| 换装期间定身 | ✅ 完成 | 添加定身状态+播放引导动画 |
| 尸体留证据 | ✅ 完成 | 尸体换成玩家旧外观 |
| 互动点降怀疑 | ✅ 完成 | 4种互动点（长椅/告示栏/水井/摊位），各有不同动画和怀疑值减少 |

### 2.10 systems/corpse.lua — 尸体与藏尸

| 功能 | 状态 | 说明 |
|------|------|------|
| 拖拽尸体 | ✅ 完成 | 尸体跟随玩家，降低移速，持续增加怀疑值 |
| 释放尸体 | ✅ 完成 | 停止跟随，恢复移速 |
| 藏尸 | ✅ 完成 | 在 hide_spot 区域检查容量，隐藏尸体，加分 |
| 拖拽状态清理 | ✅ 完成 | 恢复移速，移除计时器 |
| 尸体发现扫描 | ✅ 完成 | 每2秒扫描，5m内发现未隐藏尸体 |
| 发现后反应 | ✅ 完成 | 全局通知 + 触发附近NPC恐慌 |

### 2.11 systems/assassination.lua — 刺杀系统

| 功能 | 状态 | 说明 |
|------|------|------|
| 刺杀前置检查 | ✅ 完成 | CD、距离、换装/拖拽/攻击状态、准备期 |
| 背刺判定 | ✅ 完成 | 攻击者在目标背后(夹角>120°)=背刺 |
| 前摇系统 | ✅ 完成 | 正面0.5秒, 背刺0.2秒, 带动画 |
| 护盾抵挡 | ✅ 完成 | 有护盾Buff则消耗护盾不造成伤害 |
| 目击者检查 | ✅ 完成 | 10m内有NPC/玩家=被目击, 影响怀疑值增量 |
| 击杀处理 | ✅ 完成 | NPC→标记尸体+恐慌+30秒腐烂; 玩家→死亡流程 |
| 消声器联动 | ✅ 完成 | 持有消声器Buff时击杀不触发恐慌 |
| 冷却系统 | ✅ 完成 | 击杀5秒/命中3秒/未命中2秒 |

### 2.12 systems/item_spawner.lua — 物品系统

| 功能 | 状态 | 说明 |
|------|------|------|
| 初始化刷新点 | ✅ 完成 | 读取 item_spawn 区域，每个点生成一个物品 |
| 权重随机 | ✅ 完成 | 8种物品不同权重（毒针15/飞刀10/护甲15/...） |
| 拾取事件 | ✅ 完成 | 监听 `单位-获得物品`，+3怀疑值 |
| 刷新倒计时 | ✅ 完成 | 45秒重生，紧迫期加速至22.5秒 |

### 2.13 systems/circle.lua — 缩圈系统

| 功能 | 状态 | 说明 |
|------|------|------|
| 初始全图圈 | ✅ 完成 | 120m半径圆形区域 |
| 首次缩圈 | ✅ 完成 | 3分钟后触发 |
| 动画缩小 | ✅ 完成 | 每秒缩0.5m，缩至目标值 |
| 多次缩圈 | ✅ 完成 | 每隔90秒再次缩圈，缩至60%，最小20m |
| 圈外伤害 | ✅ 完成 | 每2秒对圈外玩家造成10点伤害 |

### 2.14 profession/ — 6个职业技能

| 职业 | 技能名 | 状态 | 说明 |
|------|--------|------|------|
| 影刃 | 暗影突进 | ✅ 完成 | 前方5m瞬移+0.8秒隐身+终点自动刺杀 |
| 千面 | 完美模仿 | ✅ 完成 | 跟随最近NPC+10秒内怀疑值-5/秒 |
| 鹰眼 | 洞察之眼 | ✅ 完成 | 15m范围扫描，标记所有玩家3秒 |
| 医师 | 麻醉陷阱 | ✅ 完成 | 放置陷阱(最多2个)，定身2秒，90秒后消失 |
| 幽灵 | 幽灵漫步 | ✅ 完成 | 4秒完全隐身+无碰撞+移速加成 |
| 猎犬 | 血迹追踪 | ✅ 完成 | 标记目标20秒+脚印特效，NPC目标提前消失+返还50%CD |

### 2.15 ai/npc_behavior.lua — NPC行为

| 功能 | 状态 | 说明 |
|------|------|------|
| 行为循环 | ✅ 完成 | 每2秒遍历所有NPC执行状态机tick |
| 状态机 | ✅ 完成 | idle → 30%概率互动/70%移动; moving → 到达后idle; interacting → 计时回idle |
| 互动点检测 | ✅ 完成 | 检查4种互动点，播放对应动画，等待后恢复 |

### 2.16 ui/ — UI模块

| 模块 | 状态 | 说明 |
|------|------|------|
| hud.lua | ⚠️ 框架 | 0.5秒本地更新循环已搭建，UI绑定需用 LocalUILogic 实现 |
| notification.lua | ⚠️ 框架 | broadcast/kill_notify/player_notify 接口定义好，UI显示待实现 |
| scoreboard.lua | ⚠️ 框架 | show/hide 接口定义好，结算面板UI待实现 |

---

## 三、你需要在 Y3 编辑器中创建的物编对象

### 3.1 单位 (Unit)

| 物编名称 | 用途 | 关键设置 |
|----------|------|---------|
| `unit_player_assassin` | 玩家角色单位 | HP=100, 移速=5.0, 物品栏=2格 |
| `unit_npc_civilian` | 平民NPC | HP=1, 无攻击 |
| `unit_npc_patrol` | 巡逻NPC | HP=1, 无攻击 |
| `unit_npc_vendor` | 商贩NPC | HP=1, 无攻击, 固定不动 |
| `unit_npc_wanderer` | 闲逛NPC | HP=1, 无攻击 |

### 3.2 Buff (魔法效果)

| 物编名称 | 用途 | 关键设置 |
|----------|------|---------|
| `buff_sus_yellow` | 轻微可疑(30+) | 持续时间=-1, 头顶黄色特效 |
| `buff_sus_orange` | 明显可疑(60+) | 持续时间=-1, 头顶橙色特效 |
| `buff_sus_red` | 高度可疑(80+) | 持续时间=-1, 头顶红色标记 |
| `buff_shield` | 护甲片护盾 | 持续30秒, 抵挡1次刺杀 |
| `buff_silencer` | 消声器效果 | 持续30秒, 击杀不触发恐慌 |
| `buff_poison` | 中毒效果 | 持续3秒, 心跳1秒, 每次17伤害 |
| `buff_eagle_mark` | 鹰眼标记 | 持续3秒, 头顶标记特效 |
| `buff_trap_root` | 陷阱定身 | 持续2秒 |
| `buff_tracked` | 追踪标记 | 持续20秒 |
| `buff_footprint` | 脚印标记 | 持续5秒, 心跳0.5秒 |

### 3.3 技能 (Ability)

| 物编名称 | 对应职业 | 冷却 | 施法类型 |
|----------|---------|------|---------|
| `abi_shadow_dash` | 影刃-暗影突进 | 45秒 | 无目标施法 |
| `abi_perfect_mimic` | 千面-完美模仿 | 60秒 | 无目标施法 |
| `abi_insight_eye` | 鹰眼-洞察之眼 | 50秒 | 无目标施法 |
| `abi_anesthesia_trap` | 医师-麻醉陷阱 | 35秒 | 无目标施法 |
| `abi_ghost_walk` | 幽灵-幽灵漫步 | 50秒 | 无目标施法 |
| `abi_blood_track` | 猎犬-血迹追踪 | 40秒 | 对单位施法 |

### 3.4 物品 (Item)

| 物编名称 | 物品名 | 类型 |
|----------|--------|------|
| `item_poison_needle` | 毒针 | 主动使用, 1次 |
| `item_throwing_knife` | 飞刀 | 主动使用, 1次 |
| `item_armor_plate` | 护甲片 | 主动使用, 1次 |
| `item_smoke_bomb` | 烟雾弹 | 主动使用, 1次 |
| `item_disguise_mask` | 易容面具 | 主动使用, 1次 |
| `item_tracker_powder` | 追踪粉 | 主动使用, 1次 |
| `item_silencer` | 消声器 | 主动使用, 1次 |
| `item_jammer` | 干扰装置 | 主动使用, 1次 |

### 3.5 投射物 & 特效

| 物编名称 | 用途 |
|----------|------|
| `proj_throwing_knife` | 飞刀投射物 |
| `sfx_smoke_bomb` | 烟雾弹粒子特效 |
| `sfx_footprint` | 脚印粒子特效 |

### 3.6 NPC 模型

需要准备 **至少8~15个** 不同外观的NPC模型（男女老少等），填入 `const.lua` 的 `NPC_MODEL_POOL`。玩家初始外观从中随机选取。

---

## 四、你需要在 Y3 编辑器地图中配置的区域和路径

### 4.1 区域 (Area) — 需添加标签

| 标签名 | 形状 | 数量建议 | 用途 |
|--------|------|---------|------|
| `player_spawn` | 圆形 | 8个 | 玩家出生点 |
| `npc_spawn` | 圆形 | 10~15个 | NPC出生区域 |
| `hide_spot` | 圆形(R=2) | 10~20个 | 藏尸点，需设KV `capacity`(整数) |
| `item_spawn` | 圆形(R=1) | 15~20个 | 物品刷新点 |
| `interact_bench` | 圆形(R=1.5) | 5~8个 | 长椅互动点 |
| `interact_board` | 圆形(R=1.5) | 3~5个 | 告示栏互动点 |
| `interact_well` | 圆形(R=1.5) | 2~4个 | 水井互动点 |
| `interact_vendor` | 圆形(R=2) | 3~5个 | 摊位互动点 |
| `light_dark` | 圆形 | 若干 | 暗区（减怀疑值加成） |
| `checkpoint` | 圆形(R=3) | 3~5个 | VIP模式检查点，需设KV `order`(整数) |
| `exit_point` | 圆形(R=3) | 1~2个 | VIP撤离点 |
| `fake_vip_spawn` | 圆形 | 2~3个 | 假VIP出生点 |

### 4.2 路径 (Road)

| 标签名 | 数量建议 | 用途 |
|--------|---------|------|
| `road_main_loop` | 2~3条 | 主街道环线，分配给平民/巡逻NPC |
| `road_patrol` | 3~5条 | 巡逻路线 |
| `road_alley` | 2~4条 | 支线小巷 |
| `road_square` | 1~2条 | 广场路线 |

---

## 五、代码层面仍需完成的工作

### 5.1 高优先级

| 序号 | 任务 | 文件 | 说明 |
|------|------|------|------|
| 1 | **填入物编Key** | `config/const.lua` | 在编辑器中创建好物编对象后，将实际Key值替换占位的 `or 0` |
| 2 | **填入NPC模型池** | `config/const.lua` → `NPC_MODEL_POOL` | 至少8~15个模型Key |
| 3 | **确认状态枚举名** | `config/const.lua` → `STATE_*` | 确认 `clicli.const.UnitEnumState` 中 `无敌`/`定身`/`隐身` 的实际枚举名 |
| 4 | **物品使用逻辑** | 新建或扩展 | 8种物品的主动使用效果（毒针、飞刀、烟雾弹等），需监听物品技能施法事件 |

### 5.2 中优先级

| 序号 | 任务 | 文件 | 说明 |
|------|------|------|------|
| 5 | **HUD UI实现** | `ui/hud.lua` | 用 LocalUILogic 绑定UI元件：怀疑值条、物品栏、倒计时 |
| 6 | **通知UI实现** | `ui/notification.lua` | 用 LocalUILogic 实现屏幕通知、击杀提示 |
| 7 | **结算面板实现** | `ui/scoreboard.lua` | 用 LocalUILogic 实现排行榜和结算界面 |
| 8 | **镜头设置** | 新建 `systems/camera.lua` 或在 `main.lua` 中 | 设置第三人称跟随镜头 / 观战模式镜头切换 |
| 9 | **键盘映射完善** | `main.lua` | 确认实际使用的按键事件名，当前按键绑定方式可能需要根据引擎API调整 |

### 5.3 低优先级（后续打磨）

| 序号 | 任务 | 说明 |
|------|------|------|
| 10 | 音效系统 | 环境音、刺杀音效、心跳声（怀疑值高时） |
| 11 | 视野阻挡 | 建筑/墙壁视野阻挡设置 |
| 12 | 天气/昼夜 | 地图氛围（月夜/黄昏/雨天） |
| 13 | 数值调优 | 根据测试反馈调整 balance.lua |
| 14 | 多地图支持 | 月夜集市/黄昏庄园/雨中教堂 |

---

## 六、系统依赖关系图

```
main.lua (入口 + 事件注册)
  │
  ├─ game_manager (局状态机)
  │    ├─ mode_manager (模式规则)
  │    │    └─ player_manager (玩家生死)
  │    │         ├─ suspicion (怀疑值)
  │    │         ├─ disguise (伪装)
  │    │         ├─ assassination (刺杀)
  │    │         └─ profession/* (职业技能)
  │    ├─ npc_manager (NPC管理)
  │    │    └─ npc_behavior (行为AI)
  │    ├─ corpse (尸体管理)
  │    ├─ item_spawner (物品)
  │    ├─ circle (缩圈)
  │    └─ timer_manager (计时)
  │
  └─ ui/* (HUD/通知/结算 — 纯本地显示)
```

---

## 七、快速开始步骤

1. **在Y3编辑器中创建物编对象**（第三节列出的所有单位/Buff/技能/物品/投射物/特效）
2. **获取物编Key值**，填入 `config/const.lua`
3. **在地图中布置区域**（第四节列出的所有标签区域）
4. **在地图中绘制NPC路径**（Road），添加对应标签
5. **准备NPC模型**，填入 `NPC_MODEL_POOL`
6. **在编辑器中运行测试**
7. 根据测试结果逐步完善 UI、音效、数值