# 技术总览与架构

## Lua脚本目录结构

项目所有逻辑脚本位于 `global_script/` 下，按模块组织：

```
global_script/
├── main.lua                  -- 入口，注册游戏初始化事件
├── config/
│   ├── const.lua             -- 全局常量（物编Key、数值参数）
│   └── balance.lua           -- 可调数值表（伤害、冷却、怀疑值阈值等）
├── core/
│   ├── game_manager.lua      -- 游戏主状态机，局流程控制
│   ├── player_manager.lua    -- 玩家创建、死亡、复活、积分
│   ├── npc_manager.lua       -- NPC批量生成、回收、密度控制
│   ├── mode_manager.lua      -- 模式切换（FFA / Team / VIP）
│   └── timer_manager.lua     -- 全局计时器（局时间、缩圈倒计时）
├── systems/
│   ├── suspicion.lua         -- 怀疑值计算、阈值Buff刷新
│   ├── 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行为树调度
│   ├── patrol_ai.lua         -- 巡逻型AI
│   ├── civilian_ai.lua       -- 居民型AI
│   ├── vendor_ai.lua         -- 商贩型AI
│   └── wanderer_ai.lua       -- 闲逛型AI
└── ui/
    ├── hud.lua               -- HUD更新（怀疑值条、物品栏等）
    ├── notification.lua       -- 全局通知、击杀提示
    └── scoreboard.lua         -- 结算面板
```

---

## 系统依赖关系

```
game_manager (局状态)
    ├── mode_manager (模式规则)
    │       └── player_manager (玩家生死)
    │               ├── suspicion (怀疑值)
    │               ├── disguise (伪装)
    │               ├── assassination (刺杀)
    │               └── profession/* (职业技能)
    ├── npc_manager (NPC管理)
    │       └── ai/* (行为树)
    ├── corpse (尸体管理)
    ├── item_spawner (物品)
    ├── circle (缩圈)
    └── timer_manager (计时)
```

---

## 游戏状态机

```
LOBBY → LOADING → PREPARE(10s不可攻击) → PLAYING → OVERTIME(最后1分钟) → ENDED
```

| 状态 | 持续 | 行为 |
|------|------|------|
| PREPARE | 10秒 | 玩家已生成，不可攻击，可移动 |
| PLAYING | 局时长-10s-60s | 正常游戏 |
| OVERTIME | 60秒 | 怀疑值增速×2，NPC减少30% |
| ENDED | — | 结算面板，停止逻辑 |

---

## 关键同步原则

| 类型 | 使用API | 说明 |
|------|---------|------|
| 游戏逻辑计时 | `y3.timer` (Timer) | 同步计时器，所有客户端一致 |
| 随机数 | `Game.set_random_seed()` | 开局设种子，确保各端随机结果相同 |
| 单位操作 | `Unit.*` 系列 | 服务端执行，自动同步 |
| 纯本地UI | `Player.with_local()` | 仅在本地客户端执行 |
| 本地计时 | `y3.ltimer` (LocalTimer) | 仅用于UI动画等不影响逻辑的场景 |
| 数据同步 | `y3.sync` (Sync) | 将客户端输入同步给服务端 |

---

## 物编对象命名规范

| 类别 | 前缀 | 示例 |
|------|------|------|
| 玩家单位 | `unit_player_` | `unit_player_assassin` |
| NPC单位 | `unit_npc_` | `unit_npc_civilian` |
| Buff | `buff_` | `buff_suspicion_yellow` |
| 技能 | `abi_` | `abi_shadow_dash` |
| 物品 | `item_` | `item_poison_needle` |
| 投射物 | `proj_` | `proj_throwing_knife` |
| 特效 | `sfx_` | `sfx_smoke_bomb` |

---

## 文档索引

| 文档 | 内容 |
|------|------|
| [01_游戏初始化与主循环](01_游戏初始化与主循环.md) | main.lua、状态机、局流程 |
| [02_玩家系统实现](02_玩家系统实现.md) | 玩家单位创建、死亡复活、积分 |
| [03_NPC系统与行为树](03_NPC系统与行为树.md) | NPC生成、行为树、恐慌、互动 |
| [04_伪装与怀疑值系统](04_伪装与怀疑值系统.md) | 怀疑值增减、阈值Buff、换装 |
| [05_战斗与刺杀系统](05_战斗与刺杀系统.md) | 刺杀前摇、背刺、伤害公式 |
| [06_尸体与藏尸系统](06_尸体与藏尸系统.md) | 尸体生命周期、藏尸点、发现事件 |
| [07_职业技能实现](07_职业技能实现.md) | 6个职业技能完整代码 |
| [08_物品系统实现](08_物品系统实现.md) | 刷新点、拾取、每个物品逻辑 |
| [09_游戏模式实现](09_游戏模式实现.md) | FFA / Team / VIP 模式规则 |
| [10_区域与地图系统](10_区域与地图系统.md) | 互动点、藏尸区、缩圈 |
| [11_同步与网络](11_同步与网络.md) | Timer vs LocalTimer、Sync用法 |
| [12_物编配置清单](12_物编配置清单.md) | 所有需要在编辑器中创建的对象 |