框架实现进度与待办
一、已创建的文件结构（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/通知/结算 — 纯本地显示)
七、快速开始步骤
- 在Y3编辑器中创建物编对象（第三节列出的所有单位/Buff/技能/物品/投射物/特效）
- 获取物编Key值，填入
config/const.lua
- 在地图中布置区域（第四节列出的所有标签区域）
- 在地图中绘制NPC路径（Road），添加对应标签
- 准备NPC模型，填入
NPC_MODEL_POOL
- 在编辑器中运行测试
- 根据测试结果逐步完善 UI、音效、数值
