# 《王者峡谷》Web 版设计文档（内部开发规范）

> 目标：本地运行的类王者荣耀 5v5 MOBA。Three.js 3D 锁视角，单机对 AI。
> 纯静态站点：ES Modules + 本地 vendored three.js，无构建步骤，无外部素材，无网络依赖。
> 运行方式：项目根目录 `python3 -m http.server 8787`，浏览器打开 `http://localhost:8787`。

## 技术约束（所有阶段必须遵守）

- three.js 已 vendored 在 `lib/three.module.js`（r160），import 方式：`import * as THREE from '../lib/three.module.js'`（相对路径按文件位置调整）。index.html 中用 importmap：`{"imports": {"three": "./lib/three.module.js"}}`，业务代码统一 `import * as THREE from 'three'`。
- 禁止任何外部 URL 素材（贴图/模型/音频/字体）。所有视觉资源程序化生成（几何体 + Canvas 纹理 + 粒子）。音效用 WebAudio 合成；播报用 `speechSynthesis`（zh-CN），失败静默降级。
- 一切素材缺失时游戏必须能正常玩（健壮性优先）。
- 性能：低模 + 共享材质 + 对象池（粒子/飘字/血条 DOM）。60fps 目标。同屏单位约 60 个。
- 调试钩子：所有 console error 收集到 `window.__errors`；`window.__game` 暴露游戏主对象；页面加载成功 boot 完成后设 `document.title='KING_OK'`；失败设 `'KING_ERR: '+msg`。供自动化验证用。
- 代码注释用中文，适度即可。不引入任何 npm 依赖。

## 文件结构

```
index.html            入口,importmap,全屏canvas容器,UI根div
start.command         双击启动脚本 (cd 到目录 && python3 -m http.server 8787)
lib/three.module.js
src/config.js         全部数值配置(地图/英雄/小兵/塔/装备/AI参数),常量表,禁止魔法数字散落
src/utils.js          数学/对象池/事件总线
src/engine/renderer.js 场景/灯光/雾/相机rig(锁定跟随,俯仰55°,固定朝向敌方基地),阴影
src/engine/input.js   虚拟摇杆(指针事件)+键盘WASD/QWER回退+技能按钮事件分发
src/engine/audio.js   WebAudio合成音效(攻击/技能/击杀/塔毁/胜利),TTS播报
src/engine/vfx.js     粒子系统/弹道拖尾/地面指示圈/范围箭头/受击闪白/死亡消散
src/world/map.js      地形/河道/草丛/防御塔与水晶模型/野区装饰/基地/泉水
src/world/models.js   程序化角色模型工厂(英雄5种/小兵3种/野怪),简单骨骼式摆动动画
src/game/state.js     GameState:单位表/队伍/时间/比分/事件;单位基类(移动/血蓝/伤害/死亡)
src/game/skills.js    5套英雄技能定义+施放逻辑+弹道+Buff系统
src/game/spawner.js   小兵波次/英雄重生计时/野怪刷新/经验金币分配
src/game/ai.js        英雄AI(分路/对线/打野/团战/撤退/回城/买装)+小兵仇恨
src/game/shop.js      装备数据+购买逻辑+推荐出装
src/ui/hud.js         血条蓝条DOM覆盖/技能按钮(冷却/拖动瞄准)/普攻键/召唤师技能/回城/飘字
src/ui/minimap.js     Canvas小地图(地形底图+单位点+塔+视野框)
src/ui/screens.js     选英雄界面/击杀横幅(第一滴血..五连绝世)/记分板/胜利失败结算
src/main.js           启动/主循环(fixed timestep 逻辑 30Hz + 渲染)/模块装配
```

## 地图（王者峡谷，世界坐标 x∈[-90,90], z∈[-90,90]，y 向上）

- 蓝方基地 (-72,-72)，红方基地 (72,72)。河道为对角线 z=-x（左上-右下），宽 14，水面半透明蓝色。
- 三条兵线（路径点，双方共用，红方反向行走）：
  - 中路: [(-70,-70), (0,0), (70,70)]（对角直线）
  - 上路: [(-70,-70), (-80,-40), (-80,40), (-40,80), (40,80), (70,70)]（左边缘→上边缘）
  - 下路: [(-70,-70), (-40,-80), (40,-80), (80,-40), (80,40), (70,70)]（下边缘→右边缘）
- 防御塔每方每路 3 座（外塔T1→中塔T2→高地塔T3），塔在兵线旁。蓝方塔位（红方中心对称取负）：
  - 中路: (-46,-46) (-28,-28) (-12,-12)
  - 上路: (-80,-10) (-80,28) (-80,58)
  - 下路: (-10,-80) (28,-80) (58,-80)
- 水晶(基地核心): 各方基地内侧,无敌直至本方任意一路 3 塔全破。泉水在水晶后方,每秒回 20% 血蓝;敌方进入泉水每秒受 2000 真实伤害。
- 野区: 河道两侧各 2 块野区的对角象限。每方: 红BUFF营(-30,10)附近 / 蓝BUFF营(10,-30)附近（红方对称），小野营 2 处。龙坑: 暴君(-22,22) 河道左上侧, 主宰(22,-22) 河道右下侧。
- 草丛: 河道两岸与各路边共约 14 片（2x4 单位绿色半透明草块）。单位在草丛内对敌方不可见（AI 与普攻不锁定其中单位，进入草丛的敌方显形）。
- 装饰: 野区树木(圆锥+圆柱)约 120 棵、石头、基地围墙、旗帜。地面 Canvas 纹理 2048²：草地底色+路线上土路+河道+基地石台+野区深色。

## 数值体系

- 伤害公式: 实际伤害 = 面板 × 100/(100+对应抗性)。暴击默认 200%。
- 英雄: 5 级属性成长, 1-15 级。移速 6.4~7.2 u/s。近战攻击距离 2.6, 射手 9.5, 法师 9。
- 英雄池（玩家开局 5 选 1，其余由 AI 补位，红蓝双方各 5 英雄不重复）：
  1. 亚瑟·战士(近战): 被动无。S1 誓约之盾:3s 移速+30% 并强化下次普攻(额外 120+0.6AD 伤害+沉默1s)。S2 回旋打击:3s 内每秒对半径4内敌人造成 90+0.5AD。Ult 圣剑裁决:跃向 8 内目标造成 350+1.0AD+目标已损生命 12% 伤害。
  2. 后羿·射手(远程): S1 炙热之风:4s 内普攻三连发(每发 60%AD)。S2 燎原箭雨:对 6 半径区域 240+0.8AD 伤害+减速30% 2s。Ult 灼日之矢:直线超远(60)弹道,命中英雄眩晕 0.5~2.5s(随距离)+400+1.0AD。
  3. 妲己·法师(远程): S1 灵魂冲击:弹道 280+0.75AP。S2 偶像魅力:弹道命中眩晕 1.2s+180+0.5AP。Ult 女王崇拜:5 团狐火自动追踪 10 内敌人(优先英雄)每团 160+0.45AP。
  4. 牛魔·坦克(近战): S1 咆哮之斧:横扫 200+0.7AD+减速25%。S2 横行霸道:冲锋 8 距离击退路径敌人+220+0.6AD。Ult 山崩地裂:半径 5 击飞 1s+300+0.8AD+自身 500 护盾 3s。
  5. 兰陵王·刺客(近战): 被动 脱战 3s 后隐身(草丛/攻击破隐)。S1 秘技·分身:召唤分身普攻 3 次(60%AD)。S2 秘技·影蚀:掷匕 260+0.7AD+标记,3s 内再受兰陵王伤害触发 180+0.5AD。Ult 秘技·暗袭:突进至 9 内目标身后,400+1.2AD。
  - 技能加点自动：6/11/15 级点大招前…改为 4/8/12 级点大招,其余按 S1>S2 交替。技能 CD: S1 8s, S2 10s, Ult 40s(基础,随等级减)。
- 召唤师技能: 玩家带 闪现(位移 8,CD 120s) + 恢复(8s 回 25% 血,CD 90s)。AI 只用恢复。
- 小兵: 近战兵 HP1300 AD42 射程2; 法师兵 HP850 AD65 射程9; 炮车 HP2600 AD130 射程10 对塔 2 倍伤害。每波 3 近战+2 法师,每第 3 波加 1 炮车。首波 t=10s,之后每 30s。三路同时出兵。金币: 近战42/法师36/炮车90(击杀者),经验共享半径 14。
- 防御塔: HP6500 AD320 射程12 攻速0.8,优先小兵;若敌英雄在塔范围内攻击我方英雄则转火该英雄;对同一英雄连击每次+30%(最多+90%)。必须按 T1→T2→T3 顺序摧毁(前塔未破后塔无敌)。破塔全队+200 金。
- 水晶: HP10000,缓慢回血 1%/s。
- 野怪: 红BUFF(击杀者获得:普攻附带 40+0.2AD 灼烧+减速15%,持续60s) HP4000; 蓝BUFF(CD-20%+回蓝,60s) HP4000; 小野 HP2200。野怪 60s 刷新,脱战回营满血。暴君(8:00 首刷,击杀后 3:00 刷新):全队+150 金+经验。主宰(10:00 首刷):击杀方三路下一波兵变为强化主宰先锋(属性×1.8)。野怪只主动攻击 3.5 范围内敌人。
- 升级: 击杀小兵/野怪/英雄得经验,1-15 级经验表递增;击杀英雄 200 金+助攻 80 金;被动金币 2/s 从 2:00 开始。
- 重生: 8s+2s×等级。回城: 引导 8s(被打断进入 CD 8s),回泉水。
- 装备(6 格,价格/属性简化): 铁剑300(+25AD) 攻速匕400(+25%攻速) 法典500(+40AP) 布甲300(+25护甲) 抗魔斗篷300(+25魔抗) 神速之靴300(+0.8移速) 破军2200(+180AD) 无尽战刃2100(+120AD+25%暴击) 博学者之怒2300(+240AP) 红莲斗篷1800(+120护甲+800HP) 魔女斗篷1800(+120魔抗+800HP) 霸者重装2000(+1500HP+5%回血/s)。推荐出装每英雄预设 6 件,UI 提供"一键购买"逐件购入;AI 有钱自动按推荐买。

## 英雄 AI（ai.js）

状态机: LANE(守线,跟己方小兵推进,塔下猥琐,残血撤退) / FARM_JUNGLE(打野位清野) / TEAMFIGHT(4s 内附近发生≥3 英雄交战则前往支援,15 半径) / PUSH(敌方塔可打且己方兵线优势时推塔) / RETREAT(HP<30% 撤向泉水,安全则回城) / DEFEND(己方塔/水晶被攻时回防)。
- 分路: 双方各 1上1中2下+1打野。
- 技能使用: 敌人进射程且 CD 好就放;Ult 留给英雄目标或团战。普攻锁定最近敌人(英雄优先权重×1.5)。
- 买装: 回泉水时按推荐顺序购买。
- 难度目标: AI 能互相击杀、会推塔,平均对局 8-15 分钟结束。

## UI（王者荣耀式横屏布局,DOM 实现,Pointer Events）

- 左上: 小地图(方形 canvas,地形简图+蓝/红点+塔图标+相机框)。右上: 击杀播报条+比分/时间/FPS。
- 左下: 虚拟摇杆(按下拖动控制移动方向)。右下: 大普攻按钮(按住连续攻击),S1/S2/Ult 技能按钮(冷却遮罩+拖动出现瞄准指示器[方向箭头/范围圈],松开施放;点按=自动瞄准最优目标),闪现/恢复小按钮,回城按钮。
- 底部中央: 血条蓝条/等级/金币/KDA/装备栏(6格)/商店按钮(打开装备面板,含一键购买)。
- 中央横幅: 第一滴血/双杀/三连决胜/四连超凡/五连绝世/团灭/防御塔被摧毁/胜利/失败,配 TTS 播报与合成音效。
- 开局选英雄界面: 5 张英雄卡片(程序化头像:对应配色的几何拼脸/图标)+技能简介,点击"锁定"进入。结算界面: 胜/负、KDA、时长、伤害统计、"再来一局"。
- 桌面调试: WASD 移动,Q/W/E/R 放技能,空格普攻。所有按钮支持鼠标。

## 端口规则（强制）

- 本机有多个端口被占用（已知占用：5000 5173 7000 8000 8080 8440 8451 8787 8791 8931 13564 17890 49443 49445 49449 50065 53743 53746 54029 56510 63278）。**启动任何 HTTP 服务前，必须先用 `lsof -iTCP:<port> -sTCP:LISTEN -P -n` 检测端口空闲，空闲才能用**；优先从 9201~9499 范围挑选。已验证空闲：9201 9202 9301 9417。
- 若 8787 上已有本项目遗留的 python http.server 在跑，可直接复用，不必重复启动。

## 验证标准（每阶段完成前自查）

1. 按上述端口规则起服后可访问,`document.title==='KING_OK'`,`window.__errors` 为空。
2. 无 404/跨域报错;无任何外部资源请求(DevTools network 全为 localhost)。
3. 阶段定义的玩法验收点全部通过,截图存档到 scratchpad 对应目录。