AI 军械库坦克大战（tank-battle）· v1.0.0
assets/ 是可读源码，dist/tank-battle.html 是内联打包后的单文件产物（约 120KB，双击即玩，零外部请求）。站点绑定集中在 assets/js/data.js 一个文件里，换站换数据不需要动引擎。
何时使用
- 用户说"玩 / 打开坦克大战"、"改坦克大战的 XX"、"加一张军械卡"
- 给工具站、导航站、活动页做游戏化引流页面
- 需要一个可离线、无依赖的 Canvas 游戏骨架来改造
不适用：联网对战、账号存档、3D 场景——本作是纯本地单机（PvP 为同屏），联机需自行接 WebSocket。
目录地图（改什么去哪个文件）
| 文件 | 职责 |
|---|---|
assets/js/data.js |
站点绑定：SITE、AREAS（战区）、TOOL_CARDS（军械卡）、EFFECTS（12 种效果） |
assets/js/game.js |
状态机、战斗循环、UI、图鉴、战报 PNG |
assets/js/core.js |
地图生成（含连通性校验）、碰撞、像素绘制、WebAudio 音效 |
assets/js/ai.js |
敌军 AI（5 兵种 + 3 档难度）、BOSS 行为 |
assets/index.html |
DOM 骨架，含 /*@CSS@*/ /*@JS@*/ 占位符 |
assets/js/promo.js |
推广/分享层：分享面板（二维码+复制链接+分享文案）、站首页 CTA、竖屏提示、?embed=1 嵌入模式，出口全带 utm 分渠道 |
assets/js/vendor-qr.js |
qrcode-generator（MIT）压缩版，离线生成二维码，无网络请求 |
assets/css/game.css |
全部样式 |
scripts/build.py |
内联打包成单文件 |
scripts/serve.py |
本地预览服务器 |
scripts/smoke.js |
Playwright 端到端冒烟 |
dist/tank-battle.html |
交付物：单文件，可放任意静态空间或直接双击 |
运行与自检
python scripts/serve.py 8899 # → http://127.0.0.1:8899/tank-battle.html
python scripts/build.py # assets/* → dist/tank-battle.html
python scripts/build.py --keep-bundle && node --check dist/_bundle.js # 语法自检
node scripts/smoke.js # 端到端冒烟（需 playwright，见脚本头部说明）
改动后必查：
- 三种模式都能进入战斗并结算，控制台零 pageerror；
- 桌面端不出现虚拟按键（显示条件是
pointer: coarse，不要改回ontouchstart判断）； - 军械卡
id与站内 slug 一致，错链会 404； - 文案里的统计数字（工具数、分类数、卡数）与
data.js实际长度一致，不写死。
玩法
| 模式 | 说明 |
|---|---|
| 人机对战 | 单人闯关，18 战区循环（之后二周目），每 5 关 BOSS（环形弹幕 + 专职拆基地），三档难度 |
| 人人对战 | 同屏 1v1，对称地图，各 3 命，中央定时刷补给 |
| 双人合作 | 两人一屏守基地抗波次 |
操作：P1 WASD + J/空格；P2 方向键 + / 或 Enter；ESC 暂停，M 静音；触屏设备自动显示虚拟按键。
与站点的结合点（改数据即可复用）
| 结合点 | 实现 | 位置 |
|---|---|---|
| 战区 = 站内分类 | AREAS 把 18 个分类映射成 18 个战区，每关锁定一个，掉落池只出该分类 |
data.js |
| 军械卡 = 真实工具 | TOOL_CARDS 105 张，id 为站内 slug，拾取后卡片可点击跳详情页（带 utm） |
data.js |
| 图鉴回访钩子 | 收集进度存 localStorage 跨局保留，未解锁显示"?"，引导回站内补齐 | game.js |
| 战报 PNG | 结算页一键下载 1200x630 战报图，底部印站点签名 | game.js |
换站点绑定：改 data.js 顶部的 SITE 与 AREAS / TOOL_CARDS 两个数组，其余零改动。
推广层（这个游戏的传播机制）
游戏被设计成可脱离站点独立传播的载体，所有出口都回指站内并带 utm_source=tank-battle：
- utm 分渠道：
qr（扫码）、share（转发链接）、cta（菜单/结算按钮）、game（军械卡跳转）分开统计，站内能看出每条渠道带来多少人 - 分享面板（菜单与结算页入口）：离线生成"扫码开打"二维码 + 复制链接 + 一键复制预置分享文案；微信 UA 下显示"右上角 ··· 分享"提示
- 竖屏提示：手机竖屏进入战斗时自动暂停并提示横屏（菜单页不拦截，可点"仍然竖屏继续"）
- 嵌入模式：
?embed=1时收窄边距、隐藏冗余站内链接，可被第三方页面 iframe 嵌入 - 分享规范地址来自
SITE.game，即使本地 file:// 打开，分享出去的也是站内链接
边界与已知坑
- 存档在 localStorage，清浏览器数据会丢图鉴；隐私模式下被禁用，建议走
serve.py - 音效受浏览器自动播放策略限制，首次点击"出战"后才解锁 AudioContext
genMap的 BFS 连通性校验不要随意删，删了会出现"敌人出生点不可达、关卡卡死"- 单机单文件：没有服务端，图鉴无法跨设备同步
引擎参数、AI 决策细节、新增军械卡 / 兵种 / 难度曲线的具体改法，见 references/design.md。
