记录 Quake III Arena
q3tourney4单关卡浏览器移植 的完整开发过程:目标、架构、数据管线、运行时模块、踩坑与修复、测试体系和体积优化。适用对象:接手这个项目的开发者。按本文顺序读一遍,可以独立完成改数值、调画面、修 Bot、重生成数据这四类工作。
目录
1. 项目概览
1.1 目标
把 Quake III Arena 的竞技场 q3tourney4 做成一款无需安装、双击即玩的浏览器游戏,尽量还原原版:
- 地图几何、贴图、lightmap、天空盒与原版一致;
- 玩家移动手感取自 Q3
bg_pmove.c; - 1v1 对战:Bot(SARGE)会寻路、开门、走跳板、打枪、捡装备;
- 武器、护甲、拾取物、门、跳板、音效、HUD 齐全;
- 单文件 HTML + 少量外部数据脚本,运行时不联网、不依赖引擎。
1.2 约束
| 约束 | 说明 |
|---|---|
| 运行时 | 纯静态资源,file:// 直接打开;不访问网络 |
| 渲染 | three.js r147(本地 vendor/three.min.js) |
| 数据 | 全部从 baseq3/pak0.pk3 离线预生成,原 pk3 只读 |
| 管线 | Python 仅标准库(zipfile/struct/zlib/base64/array/json) |
| 体积 | 首屏不能走全量资源(原版 pak0 约 500MB),必须精选 |
| 无引擎 | 不跑 id Tech 3,而是用 BSP 数据 + 自研碰撞/物理/AI |
1.3 成果概览
| 指标 | 数值 |
|---|---|
| 世界三角形 | 14,431 |
| 去重后顶点 | 16,634 |
| 碰撞 brush | 1,337 |
| 门 | 12 扇(6 个 team) |
| 出生点 / 拾取物 / 跳板 | 9 / 26 / 4 |
| 地图 shader / 导出贴图 | 102 / 91 |
| 音效 | 31 个(11025 Hz 单声道) |
| 导航节点 | 3,820(最多 4 层) |
| 自动化断言 | 206(probe)+ 21(GLSL) |
| 运行文件总体积 | 约 7.8 MB |
2. 运行方式与文件清单
2.1 必需文件
q3tourney4.html 全部逻辑 + HUD(约 175 KB)
q3tourney4.map.js 几何 / 碰撞 / lightmap / 缩略图(约 1.47 MB)
q3tourney4.tex.js 高清贴图 dataURL(约 3.68 MB)
q3tourney4.weapons.js 武器 md3(约 433 KB)
q3tourney4.items.js 拾取物 md3(约 340 KB)
q3tourney4.player.js 机器人三件套模型 + 动画(约 281 KB)
q3tourney4.sfx.js 音效 wav dataURL(约 858 KB)
vendor/three.min.js three.js r147(约 594 KB)
直接双击 q3tourney4.html 即可。脚本全部是普通 <script src>,没有 fetch、模块加载或跨域请求。
2.2 不需要的文件
baseq3/、pak0.pk3:只在生成数据时读取;spearmint*.exe/.dll、SDL2*.dll:原版引擎,与本移植无关;.workbuddy-ai/tmp/t4/:数据管线与测试脚本,属于开发工具;Saltline-zh.html、各类 readme/license:无关。
2.3 浏览器要求
- 支持 WebGL 1/2、Pointer Lock、AudioContext;
- 推荐 Chrome/Edge 最新版;
- 首次点击画面锁定鼠标后才开始对局(浏览器自动播放策略要求用户手势后才能开音频)。
3. 总体架构
┌─────────────────────────────┐
│ baseq3/pak0.pk3(只读) │
└──────────────┬──────────────┘
│ Python 离线管线(仅标准库)
┌───────────────────────┼───────────────────────────┐
▼ ▼ ▼
bsp2json.py texupgrade.py sfxextract.py
md3build.py thumb.ps1 md3player.py
│ │ │
▼ ▼ ▼
q3tourney4.map.js q3tourney4.tex.js q3tourney4.sfx.js
q3tourney4.weapons.js q3tourney4.items.js q3tourney4.player.js
│ │ │
└───────────────────────┴──────────────┬────────────┘
▼
q3tourney4.html(运行时)
┌──────────────┬──────────────┬──────────────┐
│ 渲染 │ 物理/碰撞 │ 玩法/AI │
│ BSP 分组 │ swept AABB │ 门/跳板/武器 │
│ lightmap │ PM 移动 │ 导航/A* │
│ chrome 反射 │ 台阶/滑步 │ Bot/Bot 开火 │
└──────────────┴──────────────┴──────────────┘
核心设计原则:
- 数据与逻辑分离:地图/贴图/模型/音效全部离线生成,运行时零解析 BSP。
- 玩家与 Bot 共用物理:
pmMove(body, dt, cmd)参数化,手感和碰撞完全一致。 - 所有“光”都用 Sprite + 径向渐变贴图:three 的灯光对
MeshBasicMaterial无效,地图亮度完全由 lightmap 决定。 - 宁可先跑通数据管线,也不手写地图:所有几何、UV、lightmap 都来自 BSP。
4. 数据管线
4.1 BSP → map.js(bsp2json.py)
4.1.1 读取与解包
- 读取 IBSP v46 的 lump 表(shader、平面、节点、叶、模型、brush、面、顶点、lightmap 等);
- 只保留渲染和碰撞需要的数据;
- 全程
struct.unpack_from,不依赖第三方库。
4.1.2 面 → 三角形
Q3 的多边形是 GL_TRIANGLE_FAN,扇心固定是顶点 0:
三角形 i: (pts[0], pts[i+1], pts[i])
凹多边形必须按这个顺序输出,不能简单倒序顶点,否则会在凹角处留下洞(曾出现“y=416 墙面透到三楼”的事故)。
Patch(曲面)按 SUB×SUB 网格细分后,每个格子拆两个三角形。
4.1.3 坐标转换
Q3 是 Z-up,three 是 Y-up,使用纯旋转(行列式 +1,不翻绕序):
three.x = q3.x
three.y = q3.z
three.z = -q3.y
4.1.4 lightmap 图集
BSP 自带 128×128 的 lightmap 页。地图共 8 页,按 4 列 × 2 行 拼成 512×256 图集:
col = page % 4
row = page / 4
atlas_pos = (col*128 + u*128, row*128 + v*128)
顶点的 lmuv 在数据里存的是图集归一化坐标:
atlas_u = (col + u) * 128 / 512
atlas_v = (row + v) * 128 / 256
注意:BSP 顶点自带的 lu/lv 是页内归一化坐标且已落在 texel 中心,直接套上面的公式即可。不要用面的 lightmapVecs —— 在 patch 面上这些值是垃圾,只有顶点 lu/lv 是准的。
纹理参数必须为:
LinearFilter(不能 mipmap / Nearest);ClampToEdge;LinearEncoding(不解码成 sRGB,否则暗部塌掉)。
4.1.5 对比度烘焙
原版 lightmap 偏灰。这里做了一次对比度变换:
out = clamp(raw * 1.10 - 5, 0, 255)
斜率 >1、基底为负:暗部更暗、亮部更亮,均值基本不变。
这一步已经挪到 bsp2json.py 里,直接在生成 PNG 前逐字节处理。好处:
- 浏览器少跑 13 万次循环;
- PNG 压得更小(裸 RGB 524 KB → PNG 250 KB)。
4.1.6 缩略图
每个 shader 从 pk3 里带一张 32×32 的 RGBA 缩略图,用于“高清图还没解码完”的一两帧。生成时 2×2 平均降到 16×16,体积变成 1/4,肉眼几乎无差。
导出为 裸 RGBA 的 base64,运行时 DataTexture 直接读,不需要图片解码。
4.1.7 顶点数组打包(重要)
早期 map.js 用 JSON 明文数组,1.4 MB 只是顶点数据。现在改为 typed array 的二进制 + base64:
| 字段 | 类型 | 精度/说明 |
|---|---|---|
position | float32 | Q3 单位,2 位小数 |
normal | int8 | round(v * 127),解码 /127 |
uv | float32 | 4 位小数 |
lmuv | float32 | 5 位小数 |
color | uint8 | 顶点色 0–255 |
shader | uint8 | shader 索引 |
index | uint16 | 顶点索引 |
数据格式:
geometry: {
enc: 'b64',
count: 16634,
position: '<base64>',
normal: '<base64>',
...
}
生成端用 Python array 模块保证小端序;运行时用 atob + Uint8Array + Float32Array/Int8Array/... 还原。
节省:1.44 MB → 约 0.87 MB,并且解析更快(不用逐字符 parse 数字)。
4.1.8 其它数据
| 字段 | 内容 |
|---|---|
brushes | 每把 brush 的平面 [nx,ny,nz,d](4 位小数),只保留 SOLID + PLAYERCLIP |
doors | team/min/max/dir/dist/speed/wait、门刷平面、门几何(明文数组,量很小) |
spawns/items/jumpads | 实体坐标与目标点 |
shaders | 名称 + 16×16 缩略图 |
4.2 贴图 → tex.js(texupgrade.py)
- 只导出“确实有面用到”的 shader,避免把 pak0 全量 1000+ 张贴图打进首屏;
- jpg 直接复用原始字节(浏览器原生解码,零损失、零解码成本);
- tga 用纯 Python 解码成 PNG(支持 type 2/10、24/32bpp、RLE、上下翻转);
- 地图 shader 名与 pak 文件名对不上的,走
ALIAS显式映射(例如bluemetal1b_chrome → bluemetal1b_shiny、slime1 → slime7、跳板/天空/灯头等); - 统计面数时必须把门几何也算进去,否则只在门上使用的贴图会漏掉(门贴图曾经一直停在 32×32 缩略图);
- 同一个 dataURL 被多个 shader 共用时,输出为「唯一串数组 + 名字→序号表」,运行时还原成
{name: url},避免同一张图存多遍。
4.3 md3 模型(md3build.py / md3player.py)
4.3.1 武器 / 拾取物
- 从 pak0 提取
models/weapons2/*、models/powerups/*的 md3; - 法线使用 Q3 的
LatLongToNormal还原:
a = lowByte * 2π / 256
b = highByte * 2π / 256
x = cos(a) * sin(b)
y = sin(a) * sin(b)
z = cos(b)
旧代码把 a/b 用反、少乘 sin(b),导致法线随机,模型看起来“缺了一块”。
- 绕序与 three 的正面方向一致(否则整把枪被背面剔除);
- 输出顶点、法线、UV、索引和贴图 dataURL。
4.3.2 玩家模型(SARGE 三件套)
head.md3 / upper.md3 / lower.md3分开装配;- 层级:
legs --tag_torso--> upper --tag_head--> head,upper 的原点在腰部,必须按 tag 摆放; _1/_2后缀是 LOD,不是帧续接;- 该 pak 的
lower.md3没有可用的走/跑循环,所以走路动画是程序化摆腿:- 绕髋关节旋转顶点;
- 用「高度权重 W + 左右插值 SIDE」组合,跨裆处不会被撕开;
- 站立时播放 99–108 帧的真实微动。
4.4 音效 → sfx.js(sfxextract.py)
- 从 pak0 波浪中精选 31 个(全量 600+ 个约 30 MB,首屏扛不住);
- 立体声混单声道、降采样到 11025 Hz、去尾部静音,体积约减半;
- 输出 wav dataURL;
- 事件表覆盖:机枪/霰弹/火箭/电磁/等离子、跳板、落地、受伤、死亡、拾取、开门、脚步、Tesla 等。
5. 运行时架构
主文件 q3tourney4.html 是一个大 IIFE,按职责分块。
5.1 坐标系与包围盒
toThree(x,y,z) = [x, z, -y]
toQ3(x,y,z) = [x, -z, y]
玩家包围盒有两份,别混用:
| 常量 | 值 | 坐标系 |
|---|---|---|
PM.MINS/MAXS | [-15,-15,-24] / [15,15,32] | Q3 序(z 竖直) |
PM.BMIN/BMAX | [-15,-24,-15] / [15,32,15] | three 序(y 竖直) |
trace() 只接受 BMIN/BMAX。曾经传错,玩家实际变成 30×30×30 的方块。
角度:Q3 angle 0 = +X,three yaw 0 = -Z,换算 yaw = (angle - 90) * π / 180。
5.2 渲染链路与亮度
完整链路,顺序不能变:
贴图 LinearEncoding(不解码)
× lightmap(LinearEncoding,字节值直乘)
× LM_SCALE = 1.5π
→ ACESFilmicToneMapping(exposure = 0.85)
→ outputEncoding = sRGBEncoding
- 贴图与 lightmap 都不做 sRGB 解码,和 Q3 一样“字节值直接乘”;
- 最终输出做 sRGB 编码,这一步就是 gamma 提亮;
- ACES 负责压高光,避免亮贴图过曝成纯白;
- 不要用 exposure 救亮度:ACES 在高段压得狠,降曝光只会让对比更平。
地图材质统一是 MeshBasicMaterial,没有实时光照:
- 有 lightmap 的面:
map × lightMap × LM_SCALE; nolightmap面(灯、液体、天空、光束):不挂 lightMap,靠贴图/顶点色自发光;- 地面类 shader 额外压暗到
color × 0.84并加对比,避免大块地面像塑料。
5.3 动态光(GLSL 注入)
因为材质是 Basic,THREE.Light 完全无效。照 Q3 R_AddDynamicLights 的做法:
- 用
material.onBeforeCompile往 shader 里注入最多 4 个点光; - vertex 在
#include <project_vertex>后写vDynWPos; - fragment 在
#include <output_fragment>前把光强叠加到outgoingLight; - 法线用
cross(dFdx(vDynWPos), dFdy(vDynWPos))求,省一个 attribute; - 所有材质共享同一组
DYN_POS/DYN_COLuniform,每帧改一次全生效; - 光源来源:火箭、等离子、爆炸、枪口闪光。
5.4 金属反射(chrome)
Q3 的金属面第一层是 tcGen environment 球面反射图(chrome_env*)。three 的 Basic 材质不支持,于是:
- 在
map_fragment后按reflect(view, normal)采样环境图; - 反射强度压到 6%:
mix(env, base, 0.94)或base + env * 0.06; - 早期版本 50% 会像镜子一样晃眼,这是视觉反馈后调下来的。
5.5 地图构建
buildMap() 按 shader 分组:
- 遍历索引三角形,按 shader 索引分桶;
- 每桶生成一个
BufferGeometry(position/normal/uv/lmuv/color); nolightmap三角形的判定:三个顶点的lmuv全为 0;- 每个 shader 一个材质:
- 先用 16×16 缩略图(同步可用,保证第一帧有画面);
- 异步解码 tex.js 的高清图,解码完替换
mat.map; - 灯具贴图额外做“增益 + 加法基底”提亮(灯罩是被自己灯光照亮的);
- 地板类压暗 + 提对比;
- 门材质同样走高清明文贴图(曾经停在 32×32 缩略图,近看一格一格)。
5.6 碰撞
trace(start, end, bmin, bmax) 是 swept AABB vs brush 凸包:
- 对每个 brush 的每个平面做 slab/射线裁剪,求进入/离开参数;
- 输出
{fraction, endpos, normal, startsolid}; - 加 0.125 的表面 epsilon,防止贴面抖动;
- 世界碰撞、Bot 视线、导航采样、子弹命中全部共用它。
5.7 玩家 / Bot 物理
pmMove(body, dt, cmd) 是参数化的(玩家和 Bot 传不同的 body):
- 常量取自
bg_pmove.c:重力 800、速度 320、加速度 10、摩擦 6、跳跃 270、台阶 18; - 照
PM_StepSlideMove实现:pmAccel/pmFriction;clipVelocity(overbounce 1.001);- 滑步迭代最多 4 次;
- 台阶抬升;
- 每帧按
1/120拆最多 4 个子步。
overbounce 的坑:落地后速度会被弹成 +0.0067,下一帧被判定为腾空,ground 状态每帧丢失,导致跳不起来。修法:法线 y > 0.7 时把小正速度归零。
5.8 门
- 12 扇
func_door,按team分组联动; - 状态:
baseMin/baseMax、min/max、target(0 关 / 1 开)、t(0–1)、holdUntil; - 触发:玩家 / Bot 进入门框外扩
DOOR_PAD = 10的判定体; - 关门时如果有人站在门内,自动反转开门;
- 射击开门:命中点落在门盒 ±4 内,整组
target = 1;已经全开时刷新holdUntil,避免刚开就关; - 门移动用
speed线性插值,到 1 后按wait保持。
5.9 跳板
Q3 的 trigger_push 不是“朝目标点直线弹”,而是先解抛物线:
height = 目标高度 - 触发体中心高度
time = sqrt(height / (0.5 * g))
水平速度 = 水平距离 / time
垂直速度 = time * g
这样顶点正好落在 target_position。运行时直接把速度赋给玩家,不做逐帧推力。
5.10 导航网格
- 格子 24×24,多层柱状采样(最多 4 层),不是单张高度图;
- 节点存脚底高度
y,运行时视点 =y + NAV_EYE(24); - 边类型:
| kind | 含义 | 生成 | Bot 行为 |
|---|---|---|---|
| 0 | 走 | 4 邻域 + 视线净空 | 正常走 |
| 1 | 跳板 | 真实模拟抛物线 | 上板 |
| 2 | 跳下 | 落差 24–260 | 大落差主动起跳 |
| 3 | 补边 | 跨分量 / 窄门洞 | 正常走 |
| 4 | 跳上 | 落差 2–40 | 主动起跳 |
- 安全区:从出生点做反向洪水,标出“能回到出生点”的节点。跳下/跳板是单向边,图上必然有“掉下去爬不上来”的死区;A* 只在安全子图里搜,再做 2 轮膨胀;
- A* 用二叉堆 + 闭集。不要改回线性扫开表:目标不可达时会空转数万次,Bot 每 0.55 秒重算一次,直接卡成幻灯片。
5.11 Bot
难度表:
| 参数 | EASY | NORMAL | HARD | 含义 |
|---|---|---|---|---|
| react | 0.62 | 0.34 | 0.16 | 看到人后延迟开火(秒) |
| aimErr | 0.160 | 0.075 | 0.032 | 瞄准抖动(弧度) |
| turn | 3.0 | 5.2 | 8.0 | 转速上限(弧度/秒) |
| fireGap | 1.45 | 1.00 | 0.75 | 开火间隔倍率 |
| dmg | 0.55 | 1.00 | 1.30 | 伤害倍率 |
| speed | 0.78 | 0.92 | 1.00 | 移速倍率 |
| strafe | 0.20 | 0.42 | 0.60 | 侧移幅度 |
| sight | 1400 | 2000 | 2800 | 视野距离 |
每帧流程:
闪光衰减 → 死亡/坠落重生 → 感知 → 朝向(双频正弦抖动)
→ 移动意图(世界方向)→ 台沿护栏 → 转朝向(有转速上限)
→ pmMove 分子步 → 走空兜底 → 卡死处理 → 开火 → 模型同步 → 摆腿
关键设计:
- 瞄准与移动解耦:交战时 yaw 对着玩家,但移动必须沿导航路径。先算世界方向,最后再折算成相对 yaw 的
fw/st,否则玩家站在台下时 Bot 会直线走空; - 台沿护栏:
botDropAhead/botLedgeBad预判前方是否走空,落差过大就起跳或绕行; - 走空兜底:下落超过 140 且 2 秒内没有起跳,才拉回安全点(频繁瞬移是之前“闪动”投诉的根因);
- 卡死处理:
botUnstuck在长时间无位移时向邻近安全节点挪动; - 重生:坠落/死亡后回到安全点,重置弹药与武器;
- 拾取:和玩家共用
pickups规则(血包、护甲、武器、弹药); - 死亡掉枪:Bot 死亡后在尸体位置生成一把带光晕的武器,可被玩家拾取。
5.12 武器
| id | 名称 | 伤害 | 射速 | 弹匣 | 类型 | 备注 |
|---|---|---|---|---|---|---|
| mg | MACHINEGUN | 7 | 0.10s | 200 | hitscan | 散布 0.017 |
| sg | SHOTGUN | 10×11 | 1.00s | 50 | hitscan | 散布 0.085 |
| rl | ROCKET LAUNCHER | 100 | 0.80s | 50 | proj | 溅射 100 / 半径 120 / 击退 320 |
| rg | RAILGUN | 100 | 1.50s | 50 | hitscan | 无散布 |
| pg | PLASMA GUN | 20 | 0.10s | 200 | proj | 溅射 20 / 半径 40 / 击退 60 |
- 抛射物有真实弹道、撞墙爆炸、溅射伤害和
splashKick击退; - 玩家与 Bot 都走
fireHitscan/fireProjectile; - 打门统一走
doorShootOpen。
5.13 特效
- 所有光效 = Sprite + 径向渐变
glowTex(),加色混合; - 枪口闪光挂在视图模型场景;
- 爆炸 = 火球 Sprite + 火花 Points + 动态光;
- railgun(照原版实现):
- 核心是正对摄像机的四边形光带(宽 ±6 =
r_railCoreWidth),不是圆柱; - 贴图
gfx/misc/railcorethin_mono,中间只有一条细亮线,UV 沿长度按len / 256平铺,加色 + 滚动; - 螺旋来自沿射线每 10 单位一个
raildisc_mono2光环,绕轴每步 10°、偏轴 4,用 Points 批量绘制; - 起点从枪口(右下前方 7 / 下 5)出射,否则条带会侧对镜头几乎看不见;
- 命中点爆闪 + 火花;
- 生命 0.5 秒线性淡出。
- 核心是正对摄像机的四边形光带(宽 ±6 =
5.14 HUD
- 血量:60px 大号数字 +
HEALTH标签,左侧橙色标记条 + 渐隐底板,低血变红发光; - 盔甲:并入血量面板,14px 金色
ARMOR xxx; - 弹药:56px 数字 + 固定
AMMO标签 + 武器名; - 武器列表:11.5px,当前武器高亮橙色;
- 顶部比分 32px、计时 12px;
- 受伤红屏、死亡镜头下沉、结算层、难度选择层。
5.15 比赛流程与输入
- 1v1,frag limit 10,时限 600 秒;
- 击杀加分、死亡重生(保留场景状态);
- 结束冻结玩法并显示结算层,可“再来一局”或“换难度”;
- 输入:WASD / 空格 / Shift 慢走 / 左键射击 / 1–5 换枪 / F 飞行(调试用)/ ESC 释放鼠标 / M 静音;
- 主循环包在
try/catch里:单帧异常不会让循环停摆(否则一次报错永久黑屏)。
6. 开发阶段
按依赖顺序推进,每一阶段都有可验收的产物:
| 阶段 | 内容 | 验收 |
|---|---|---|
| P0 数据管线 | BSP → 几何 / lightmap / 碰撞 / 实体;贴图导出 | 能在 three 里看到完整地图 |
| P1 渲染基线 | 坐标系、材质分组、lightmap、天空、亮度链路 | 贴图与明暗和原版一致 |
| P2 物理 | swept AABB、PM 移动、台阶、跳跃 | 9 个出生点能稳定站住、能爬上台阶 |
| P3 玩法 | 门、跳板、拾取物、武器、伤害、特效 | 能开门、上跳板、捡枪、打死 Bot |
| P4 Bot | 导航网格、A*、感知、移动、开火、难度 | Bot 能自主走图并击杀玩家 |
| P5 比赛流程 | 比分、计时、结算、重生 loadout、音效 | 完整对局可结束并重开 |
| P6 视觉打磨 | 地面质感、门贴图、反射强度、对比度、死枪、railgun | 按用户逐条反馈迭代 |
| P7 工程化 | 测试探针、体积优化、HUD 重做、文档 | 206 + 21 断言全绿 |
7. 关键问题与根因
这一节是项目里最值钱的部分:症状 → 根因 → 修法。
7.1 渲染 / 亮度
| 症状 | 根因 | 修法 |
|---|---|---|
| 地面一块亮一块暗,拼接明显 | lightmap UV 按“页内像素坐标”直接采样,每个面只采到页内一小块 | 改为图集归一化 (col+u)*128/512 |
| 每个 texel 采到半格,接缝 | lu/lv 已是 texel 中心,又加了 0.5 | 去掉多余偏移;断言最小采样 = 0.5 texel |
| 金属面像镜子、晃眼 | chrome 反射占比 50% | 压到 6% |
| 整体偏暗 | 贴图解码 + 输出线性,两头都压暗 | 全链路线性 + sRGB 输出 + ACES |
| 对比太平、发灰 | 重映射 v*0.95+12 把暗部托起来 | 改为 v*1.10-5(斜率 >1、负基底) |
| 亮面糊成纯白 | 线性 tone mapping 直接截断 | 改 ACES,压高光保中间调 |
| 门近看一格一格 | 门材质一直用 32×32 缩略图;且缩略图统计漏了门几何 | 门材质走高清明文贴图;统计面数时补门几何 |
| 局部墙面透到三楼 | 凹多边形倒序顶点,扇心三角化留洞 | 固定扇心顶点 0,按 (0,i+1,i) 输出 |
| 灯 / 液体 / 天空也乘 lightmap,发黑 | nolightmap 面未单独分组 | lmuv 全 0 的三角形单独建组,不挂 lightMap |
7.2 物理 / 碰撞
| 症状 | 根因 | 修法 |
|---|---|---|
| 跳不起来 | overbounce 产生 +0.0067 竖直速度,ground 状态每帧丢失 | 法线 y>0.7 时把小正速度归零 |
| 玩家变成方块 | 把 Q3 序的 MINS/MAXS 传给了 three 序的 trace | 统一使用 BMIN/BMAX |
| Bot 脚底闪烁 | 模型与地面共面 z-fighting | 模型整体抬高 PLY_DY + 0.8,并关闭部件视锥剔除 |
| Bot 在走道里一闪一闪 | 模拟里 Bot 被一扇关着的门挡住,2–6 秒后被 botUnstuck 挪走 | 测试补 updateDoors;走空兜底阈值 48→140 且 2 秒冷却 |
7.3 玩法 / AI
| 症状 | 根因 | 修法 |
|---|---|---|
| 火箭打在身上没有“轰开” | 溅射只扣血,没有速度 | splashKick + 武器 knock |
| 打门不开 | 只有触碰触发,没有射击触发 | doorShootOpen:命中点落在门盒 ±4 内开门 |
| Bot 站台下时直线走空 | 移动意图直接朝玩家坐标 | 移动沿导航路径;瞄准与移动解耦 |
| 导航目标不可达时卡顿 | A* 线性扫开表,空转数万次 | 二叉堆 + 闭集 + 安全子图 |
| Bot 掉到地下室回不来 | 跳下/跳板是单向边 | 从出生点反向洪水标 safe,A* 只在安全子图搜索 |
| Bot 死了不留枪 | 死亡只播特效 | dropWeaponOnDeath 在尸体位置生成可拾取武器 |
7.4 工具链
| 症状 | 根因 | 修法 |
|---|---|---|
probe 里 bot is not defined | 测试代码在 IIFE 外 | 通过 __T 导出引用 |
| md3 模型“缺一块” | 法线 latlong 解码公式错误 | 按 LatLongToNormal 重算 |
| 贴图导出漏掉只在门上的贴图 | face_cnt 只统计世界几何 | 统计时把 doors[].geometry 也算进去 |
8. 测试体系
8.1 设计原则
不复制一份实现来测,而是直接跑真实代码。
probe.js 的做法:
- 用 Node 加载真实的
three.min.js(只把WebGLRenderer换成假对象,避免需要 WebGL 上下文); - 打桩 DOM / Canvas2D / Image / AudioContext;
- 依次
eval地图、武器、物品、玩家模型、贴图、音效数据; - 从
q3tourney4.html抽出内联脚本,在 IIFE 结束前注入globalThis.__T = { ... }导出; - 在 Node 里直接调用真实函数(物理、门、导航、Bot、开火、拾取、比赛流程)。
好处:测的是同一份代码,不会出现“测试通过但游戏是另一套逻辑”。
8.2 覆盖范围(35 段 / 206 断言)
包括但不限于:
- 启动与数据完整性;
- 9 个出生点站立;
- 移动/跳跃/台阶/滑步;
- 跳板抛物线落点;
- 门开关、team 联动、射击开门、门内有人反转;
- 武器数值、hitscan / 抛射 / 溅射 / 击退;
- 视图模型与枪口位置;
- 主循环 90 帧无异常、动态光槽位;
- 全图站立自检、nolightmap 分组、亮度分布估计;
- 地图闭合性(出生点向四周打射线查洞);
- 高清贴图覆盖率;
- 导航节点规模、A* 可达性;
- Bot 移动、开火链路、武器体系、拾取、死亡掉枪;
- 比赛流程(frag limit / 计时 / 结算 / 重开);
- 音效数据合法性、静音开关;
- lightmap texel 对齐;
- 台沿行走(瞬移 / 静止帧);
- railgun 光带(4 顶点、宽度 12、加色、淡出)。
8.3 GLSL 静态校验(21 断言)
_glsl3.js 从 HTML 里抽出真实的 DYN_GLSL 字符串,检查注入点、uniform 声明、亮度链路、ACES/sRGB、加色混合、静态贴图等。
8.4 固定流程
改完代码后:
cd .workbuddy-ai/tmp/t4
# 1. 语法 + 真实逻辑断言
node probe.js
# 2. GLSL / 渲染链路断言
node _glsl3.js
当前结果:
probe.js PASS 206 FAIL 0
_glsl3.js PASS 21 FAIL 0
8.5 加断言的建议
- 优先在
probe.js里调用真实函数,不要复制逻辑; - 随机行为(Bot 寻路)用范围断言,并打印实际值,便于区分“回归”与“波动”;
- 视觉类问题尽量转成可量化的量(亮度分布、texel 对齐、贴图覆盖率、顶点数)。
9. 体积优化
9.1 结果
| 文件 | 优化前 | 优化后 | 降幅 |
|---|---|---|---|
q3tourney4.map.js | 2,585 KB | 1,468 KB | −43% |
q3tourney4.tex.js | 3,771 KB | 3,682 KB | −2% |
| 合计 | 6.36 MB | 5.15 MB | −1.2 MB |
9.2 map.js 做了什么
- 顶点数组二进制化:JSON 数字 → float32/int8/uint8/uint16 + base64,1.44 MB → 0.87 MB;
- 法线 int8:反射只需要 1/127 精度,267 KB → 67 KB;
- lightmap → PNG:裸 RGB 524 KB → PNG 250 KB,并把对比度烘焙进去;
- 缩略图 32×32 → 16×16:427 KB → 107 KB;
- 索引 uint16、shader uint8、颜色 uint8,均精确无损。
9.3 tex.js 做了什么
- 统计面数时补上门几何(正确性);
- 共用 dataURL 去重:91 个键 / 87 个唯一串,省 89 KB。
9.4 还可以怎么降
剩余大头是 tex.js(3.68 MB)。要再降只能:
- 重编码 JPEG(质量 85–90)或把 >512 的贴图降采样;
- 这会有画质损失,需要单独确认。
10. 已知限制
| 项 | 说明 |
|---|---|
| 模式 | 只有 1v1 死斗,没有 CTF / TDM / 机器人队友 |
| Bot | 3 档难度;寻路偶发 botUnstuck 兜底位移(探针阈值 ≤4 帧) |
| 导航 | navClear 存在极少量“幽灵边”(视线通过但实际走不过去) |
| 音效 | 11025 Hz 单声道,非原版 22 kHz |
| 模型 | 机器人腿是程序化动画,不是原版 md3 跑步循环 |
| 画面 | 固定 FOV 74;无动态阴影;反射是近似球面采样 |
| 资源 | 首屏约 7.8 MB;贴图未重编码 |
| 镜像/传送门 | 未实现 |
11. 二次开发指南
11.1 改数值
| 想改什么 | 位置 |
|---|---|
| 武器伤害/射速/弹匣/击退 | WEAPONS 对象 |
| 玩家移速/重力/跳跃/台阶 | PM 常量 |
| Bot 难度 | BOT_DIFF |
| 亮度/对比 | LM_SCALE、bsp2json.py 的 * 1.10 - 5 |
| 反射强度 | applyChrome() 里的 0.94 / 0.06 |
| 地面压暗 | buildMapMaterials() 的 0.84 |
| railgun 宽度/螺旋 | spawnRail() 的 HW、size、SPACING |
11.2 重生成数据
cd .workbuddy-ai/tmp/t4
# 地图(几何/碰撞/lightmap/缩略图)—— 必须最先跑
python bsp2json.py
# 贴图(依赖 map.js 的 shader 面数统计)
python texupgrade.py
# 模型与音效
python md3build.py
python md3player.py
python sfxextract.py
# 回归
node probe.js
node _glsl3.js
11.3 注意事项
- 不要修改
baseq3/下的任何文件,管线只读; - 改
bsp2json.py的几何格式时,必须同步改 HTML 里的unpackGeo(),并跑probe.js; - 改 lightmap 采样时,先看 probe 第 28 段(texel 对齐)和第 12 段(亮度估计);
- 改导航/Bot 时,先看第 29 段(台沿瞬移/静止),再看实际的 Bot 对局;
- 视觉反馈以实机为准,探针只能保证“没有明显回归”,不能保证“好看”。
12. 附录
12.1 主要常量
| 常量 | 值 |
|---|---|
PM.GRAVITY | 800 |
PM.SPEED | 320 |
PM.JUMP_VEL | 270 |
PM.STEP_HEIGHT | 18 |
PM.BMIN/BMAX | [-15,-24,-15] / [15,32,15] |
PM.VIEW_HEIGHT | 26 |
LM_SCALE | 1.5 * Math.PI |
| toneMappingExposure | 0.85 |
NAV_CELL | 24 |
NAV_STEP | 24 |
NAV_MAX_LAYER | 4 |
NAV_EYE | 24 |
DOOR_PAD | 10 |
VM_SCALE | 0.016 |
| frag limit / 时限 | 10 / 600s |
12.2 文件分工
| 文件 | 作用 |
|---|---|
q3tourney4.html | 运行时全部逻辑与 HUD |
q3tourney4.map.js | 地图数据(打包后的几何) |
q3tourney4.tex.js | 贴图 |
q3tourney4.weapons.js | 武器模型 |
q3tourney4.items.js | 拾取物模型 |
q3tourney4.player.js | 机器人模型/动画 |
q3tourney4.sfx.js | 音效 |
.workbuddy-ai/tmp/t4/bsp2json.py | BSP → map.js |
.workbuddy-ai/tmp/t4/texupgrade.py | pak 贴图 → tex.js |
.workbuddy-ai/tmp/t4/md3build.py | 武器/物品 md3 → js |
.workbuddy-ai/tmp/t4/md3player.py | 玩家三件套 → player.js |
.workbuddy-ai/tmp/t4/sfxextract.py | 音效 → sfx.js |
.workbuddy-ai/tmp/t4/probe.js | 运行时探针(206 断言) |
.workbuddy-ai/tmp/t4/_glsl3.js | GLSL / 渲染链路校验(21 断言) |
12.3 一句话总结
数据全部离线烘好、运行时零解析;玩家和 Bot 共用一套物理与碰撞;所有视觉问题都拆成可量化的断言;改完必跑
probe.js+_glsl3.js。