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

8.7 KiB
Raw Blame History

CS · 枪火对决

第一人称 1v1 对枪。Rust 权威服务端 + 纯静态 WebGL 前端,打开网页就能打,不装客户端、不注册账号、前端零构建、零外部资源。

大厅

浏览器 A ──┐                    ┌── 60Hz 权威模拟(移动 / 命中 / 伤害 / 回合)
           ├── WebSocket ───────┤
浏览器 B ──┘                    └── 房间状态(比分 / 回合 / 观战席)
     └── 观战者

Rust(axum + tokio)          public/ 里的 html/css/js 由同一个进程托管
画面 说明
战斗 第一人称视角、枪模、后坐力、准星、血量与弹药
地图 48×48m 对称地图「沙漠据点」,中央高台 + 两侧小屋 + 掩体

跑起来

需要 Rust 工具链(cargo 1.75+)。

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 头:

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 请求,断网也能跑。

编译成单文件程序

cargo build --release

产物:target/release/cs,约 1.5 MB(自带 HTTP/WS 服务 + 内嵌前端资源,不依赖任何运行时)。

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:

cargo run            # 起服务
# 改 public/index.html、style.css、js/client/*.js,存盘刷新即可

服务端对静态资源发 Cache-Control: no-cache。

movement.js 是 physics.rs 的镜像、weapons.js 是 weapons.rs 的镜像: 改移动常数或武器数值要两边一起改,服务端才是权威,前端那份只负责「看起来跟手」。

测试

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。