Files
cs/README.md
T
rong 00d63ba736 feat: CS 枪火对决 —— Rust 权威服务端 + 手写 WebGL 前端的第一人称 1v1 对枪
- 服务端 60Hz 固定步长模拟:重力/摩擦/轴分离碰撞/上台阶,客户端预测回滚
- 命中裁决:射线打墙打人(身体 + 头部盒),射速/弹匣/换弹/伤害/比分全在服务端
- 回合制:3 秒准备、先到 8 分、100 秒平局;观战自由视角
- 机器人陪练:视线检测 + 反应延迟 + 点射偏差,能单人开练
- 前端零依赖:手写 WebGL(程序化贴图、地图合批、粒子、曳光弹、假投影、黄昏天空)
- 2D Canvas 枪模 + WebAudio 合成音效,无任何图片/音频/CDN 资源
- 地图 level.json 前后端同源,tools/gen_level.py 四分镜像生成,绝对对称
- 测试:14 组规则单测 + 6 组联机 e2e
2026-10-22 21:53:45 +08:00

197 lines
8.7 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 对称地图「沙漠据点」,中央高台 + 两侧小屋 + 掩体 |
## 跑起来
需要 Rust 工具链(`cargo` 1.75+)。
```bash
cargo run --release # 或 cargo run 走 debug,编译更快
```
打开 <http://localhost:3000>,点「练习模式」就能和机器人对枪。
首次编译约 3~5 分钟(拉依赖 + 编 axum/tokio),之后增量编译几秒。
## 两个人怎么玩
**同一个 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 米矮台) |
| 鼠标左键 | 开火(步枪按住连发,手枪单发) |
| `R` | 换弹 |
| `1` / `2` | 切步枪 / 手枪 |
| `Tab` | 记分板 |
| `Esc` | 解锁鼠标(暂停菜单,可调灵敏度) |
## 打起来是什么样
- 每回合双方**满血 100、满弹**,在固定出生点复活,3 秒准备时间后开打。
- 命中身体 / 头部伤害不同:AK 一枪头 108(秒杀),沙漠之鹰 166;打身体分别 27 / 52。
- 谁先倒下,对方得 1 分,**先到 8 分**赢下整场。回合间隔 3.5 秒自动重开。
- 单回合 100 秒打不完算平局,双方都不加分。
- 步枪 30 发 / 备用 90,手枪 7 发 / 备用 35;换弹有 2 秒多空窗,别在对手冲脸时换。
- 移动、腾空会放大散布;后坐力会抬枪口,需要自己压枪。
- 爆头、击杀、被击杀都有独立音效和画面反馈(命中标记、受击红晕、击杀播报)。
## 代码结构
```
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 矢量绘制)
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` —— 14 组规则断言:出生点不卡墙、射线挡墙、冻结 3 秒、前进/摩擦、命中盒分头身、射速限制、击杀加分与回合重开、8 分结束、弹匣打空、换弹、机器人会动、观战占位、中离暂停、输入队列防加速。
- `tests/e2e.rs` —— 6 组联机断言:建房→加入→冻结→开打→移动生效、观战者看得到但动不了、机器人会出门、狂发 200 帧输入不会瞬移、未知房号报错、`/health` 与静态资源。
单跑某一组:`cargo test --test e2e` / `cargo test 击杀`。
## 还没做的
- 语音 / 文字聊天(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`。