# CS · 枪火对决 第一人称 1v1 对枪。**Rust 权威服务端 + 纯静态 WebGL 前端**,手机 / 平板 / 电脑打开网页就能打,不装客户端、不注册账号、前端零构建、零外部资源。 ![大厅](docs/shot-lobby.png) ``` 浏览器 A ──┐ ┌── 60Hz 权威模拟(移动 / 命中 / 伤害 / 回合) ├── WebSocket ───────┤ 浏览器 B ──┘ └── 房间状态(比分 / 回合 / 观战席) └── 观战者 Rust(axum + tokio) public/ 里的 html/css/js 由同一个进程托管 ``` | 画面 | 说明 | | --- | --- | | ![战斗](docs/shot-game.png) | 第一人称视角、枪模、后坐力、准星、血量与弹药 | | ![地图](docs/shot-map.png) | 48×48m 对称地图「沙漠据点」,中央高台 + 两侧小屋 + 掩体 | | ![手机](docs/shot-mobile.png) | 手机横屏:左摇杆 + 右侧按键,HUD 自动让开拇指区域 | ## 跑起来 需要 Rust 工具链(`cargo` 1.75+)。 ```bash cargo run --release # 或 cargo run 走 debug,编译更快 ``` 打开 ,点「练习模式」就能和机器人对枪。 首次编译约 3~5 分钟(拉依赖 + 编 axum/tokio),之后增量编译几秒。 ## 手机上玩 前端会自己判断设备:`(pointer: coarse) and (hover: none)`,或 UA 明确是移动端,就切到触屏模式; 桌面(包括带触屏的笔记本,主指针是鼠标)仍然是键鼠 + 鼠标锁定。 > 建议**横屏**玩,竖屏会盖一层「把设备横过来」的提示。点「创建房间 / 练习模式 / 加入」时会顺带尝试全屏 + 锁定横屏 > (Android Chrome 支持;iOS Safari 不允许网页全屏,需要手动「添加到主屏幕」后横屏打开)。 | 触屏操作 | 作用 | | --- | --- | | 左下摇杆 | 移动(推到边缘是跑,轻推是走) | | 右半屏滑动 | 转视角(拖动多少转多少,跟灵敏度挂钩) | | 右下「开火」 | 按住连发;轻点也保证打出一发 | | 「跳」 | 跳(能上 1 米矮台) | | 「开镜」 | 按住放大(放大镜):走得慢、子弹更聚 | | 「蹲下」 | 按住蹲:盒子变矮、没脚步声,松键才起身 | | 「换弹」 | 换弹 | | 「切枪」 | 步枪 / 手枪互换 | | 右上「≡」 | 打开菜单(继续 / 灵敏度 / 离开) | 触屏模式下的几个细节: - 左下角摇杆、右下角按键都是独立指针,**可以同时推摇杆 + 转视角 + 开枪**(真多点触控,不是模拟)。 - HUD 会重排:血量和弹药挪到屏幕上方,把底部整条让给两个拇指;击杀播报、记分板也跟着下移。 - 手指滑出按钮范围不会「卡住开火」,切后台 / 锁屏会自动松开所有按键。 - 手机和平板的渲染分辨率上限压到 1.3 倍 DPR,枪模烤成位图后每帧只贴一次,省电也省发热。 ## 两个人怎么玩 **同一个 Wi-Fi(最简单)** 1. 你在电脑上打开 `http://localhost:3000`,点「创建房间」,屏幕上会出现 4 位房号。 2. 终端启动时会顺便打印局域网地址,比如 `http://192.168.1.8:3000`。 3. 对方在另一台设备上打开这个地址,输入房号点「加入」。 4. 双方各占一个出生点,斜对角开局。 **不在同一个 Wi-Fi** 把编译出的单文件二进制丢到有公网 IP 的服务器上(见下一节),`PORT=8080 ./cs`。用 Nginx/Caddy 反代时记得放行 WebSocket 的 `Upgrade` 头: ```nginx location / { proxy_pass http://127.0.0.1:8080; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; proxy_set_header Host $host; } ``` **旁观** 大厅里填房号点「观战」,就进入自由视角:WASD 飞、Shift 加速、鼠标转头。 两个座位都有人时,点「加入」也会自动变成观战。 ## 键鼠操作 | 按键 | 作用 | | --- | --- | | `W` `A` `S` `D` | 移动 | | `Shift` | 静步(更慢、更稳、没脚步声) | | `空格` | 跳跃(能跳上 1 米矮台) | | 鼠标左键 | 开火(步枪按住连发,手枪单发) | | 鼠标右键 | 开镜放大(放大镜,按住生效:移速减半、散布大减) | | `C` / `Ctrl` | 蹲下(按住生效:碰撞体 1.75→1.05、没脚步声;头顶有东西站不起来) | | `R` | 换弹 | | `1` / `2` | 切步枪 / 手枪 | | `Tab` | 记分板 | | `Esc` | 解锁鼠标(暂停菜单,可调灵敏度) | ## 打起来是什么样 - 每回合双方**满血 100、满弹**,在固定出生点复活,3 秒准备时间后开打。 - 命中身体 / 头部伤害不同:AK 一枪头 108(秒杀),沙漠之鹰 166;打身体分别 27 / 52。 - 谁先倒下,对方得 1 分,**先到 8 分**赢下整场。回合间隔 3.5 秒自动重开。 - 单回合 100 秒打不完算平局,双方都不加分。 - 步枪 30 发 / 备用 90,手枪 7 发 / 备用 35;换弹有 2 秒多空窗,别在对手冲脸时换。 - 移动、腾空会放大散布;后坐力会抬枪口,需要自己压枪。 - **右键开镜(放大镜)**:FOV 78→30(步枪)/ 42(手枪),移速减半、散布乘以 0.35 / 0.5,灵敏度随 FOV 一起缩放,远点对枪不吃亏。 - **C / Ctrl 蹲下**:碰撞体从 1.75 压到 1.05,命中盒跟着矮,蹲走只有 1.5 m/s 且没脚步声;头顶有东西时松键也站不起来。 - 爆头、击杀、被击杀都有独立音效和画面反馈(命中标记、受击红晕、击杀播报)。 ## 代码结构 ``` src/math.rs 三维向量 / 角度 src/level.rs 地图(AABB 方块)+ 射线求交 src/physics.rs 移动物理:重力、加速、摩擦、轴分离碰撞、上台阶 src/weapons.rs 武器表(伤害 / 射速 / 弹匣 / 散布) src/game.rs 房间状态机:回合、命中裁决、伤害、机器人 AI src/protocol.rs WebSocket 消息契约 src/server.rs 房间管理 + 60Hz 模拟 + 30Hz 快照 + 静态资源 build.rs 把 public/ 压成资源表编进二进制 public/index.html 页面骨架(大厅 + HUD) public/style.css 深色科技风样式 public/level.json 地图数据(前后端同一份) public/js/client/main.js 连接 / 输入 / 预测回滚 / 射击 / 回合 UI public/js/client/renderer.js 手写 WebGL:贴图生成、地图合批、玩家模型、粒子、天空 public/js/client/viewmodel.js 第一人称枪模(2D Canvas 手绘 3/4 视角,侧面 + 顶面挤出 + 剪影投影,离屏缓存) public/js/client/touch.js 触屏操作层:虚拟摇杆、滑动瞄准、开火/跳/换弹/切枪 public/js/client/movement.js 物理的 JS 镜像(客户端预测用) public/js/client/weapons.js 武器表的 JS 镜像(只做表现) public/js/client/sound.js WebAudio 现场合成(枪声 / 脚步 / 命中 / 换弹,无音频文件) public/js/client/hud.js HUD 更新 tools/gen_level.py 地图生成脚本(只写四分之一,镜像出整张图) tools/verify.cjs 无头浏览器截图 + 控制台检查 ``` ## 关键设计 **服务端说了算** 服务端 60Hz 固定步长跑物理,客户端只发「按键位 + 视角」,不直接发坐标。 命中用射线:先打墙,再打人(身体盒 + 头部盒),取最近的那个。射速、弹匣、换弹、伤害、比分全在服务端算, 客户端改不了血量,也改不了子弹。 **客户端预测 + 回滚** 本地用 `movement.js`(`physics.rs` 的镜像)先跑一遍,手感没有延迟; 每张快照带 `ack`(已处理到第几号输入),客户端把没被确认的输入重放一遍,再把「渲染位置 - 预测位置」的残差做指数衰减,肉眼看不到拉扯。 **30Hz 快照 + 插值** 服务端 30Hz 广播全场状态,远端玩家位置在客户端做指数平滑,50ms 的网络抖动不会变成抽搐。 **地图只有一份** `public/level.json` 由 `tools/gen_level.py` 生成(只写 x≤0、z≤0 的四分之一,程序镜像), 服务端 `include_str!` 编进二进制解析,前端 `fetch` 同一份文件。地图尺寸、出生点、碰撞、渲染不可能对不上。 **零外部资源** 贴图全部用 Canvas 现场生成(混凝土 / 木箱 / 金属 / 地砖 + 噪声污渍), 天空、粒子、曳光弹、枪模都是代码画的,音效是 WebAudio 合成的。 整个前端没有一张图片、一个字体、一个 CDN 请求,断网也能跑。 ## 编译成单文件程序 ```bash cargo build --release ``` 产物:`target/release/cs`,**约 1.5 MB**(自带 HTTP/WS 服务 + 内嵌前端资源,不依赖任何运行时)。 ```bash PORT=3000 ./cs ``` `build.rs` 会把 `public/` 整个目录编译进二进制,拷到没装任何东西的电脑 / NAS 上直接跑; `/health` 里能看到 `"engine":"rust"`、`"tick":60`、`"snapshot":30`、`"map":"沙漠据点"`。 - 默认只编「当前系统 + 当前架构」。要给 Linux x86_64 用,就在 Linux 上 `cargo build --release`。 - 前端资源已内嵌,但**程序同目录若存在 `public/`,会优先用磁盘上的版本**,方便临时改页面。 ## 改前端不用编译 `public/` 里的文件就是最终产物,浏览器直接加载 ES module: ```bash cargo run # 起服务 # 改 public/index.html、style.css、js/client/*.js,存盘刷新即可 ``` 服务端对静态资源发 `Cache-Control: no-cache`。 > `movement.js` 是 `physics.rs` 的镜像、`weapons.js` 是 `weapons.rs` 的镜像: > 改移动常数或武器数值要**两边一起改**,服务端才是权威,前端那份只负责「看起来跟手」。 ## 测试 ```bash cargo test ``` - `game::tests` —— 17 组规则断言:出生点不卡墙、射线挡墙、冻结 3 秒、前进/摩擦、命中盒分头身、射速限制、击杀加分与回合重开、8 分结束、弹匣打空、换弹、机器人会动、观战占位、中离暂停、输入队列防加速、蹲下变矮且命中盒跟着变、蹲下和开镜都会减速、矮洞底下站不起来。 - `tests/e2e.rs` —— 6 组联机断言:建房→加入→冻结→开打→移动生效、观战者看得到但动不了、机器人会出门、狂发 200 帧输入不会瞬移、未知房号报错、`/health` 与静态资源。 单跑某一组:`cargo test --test e2e` / `cargo test 击杀`。 前端用无头 Chrome(`tools/verify.cjs`)做了真机视口验证:iPhone 844×390、iPad 1024×768、桌面 1440×900 三种环境, 分别确认触屏控件出现 / 隐藏、摇杆位移 4.36m、滑动转头 0.4rad、点射扣弹、换弹生效,控制台零报错。 ## 还没做的 - 语音 / 文字聊天(cnchess 那套语音链路没搬过来,1v1 对枪用处也不大) - 团队模式、经济系统、买枪、投掷物、穿墙伤害 - 地图只有一张,也没有编辑器(`tools/gen_level.py` 算半个) - 房间状态在内存里,重启即清;也没做多进程横向扩展 - 触屏只做了横屏,竖屏直接提示转屏;也没有做手柄支持 - 反作弊:服务端已经拿走了所有裁定权,但没有做异常输入频率分析 ## 本机编译加速 / 缓存布局 按 `dev-cache-layout` 技能的约定: - **`target/` 留在项目目录**(增量编译 + 复查用),已在 `.gitignore`,没有挪到 `~/Library/Caches` 再软链回来。 - 包缓存实体集中在 `~/.cache`:`~/.cargo/registry -> ~/.cache/cargo/registry`、`~/.npm -> ~/.cache/npm`(本机已验证)。 - 依赖走 USTC sparse 镜像、编译器包了 sccache,配置都在 `~/.cargo/config.toml`,仓库里不需要再放 `.cargo/config.toml`。