[开发] Q3TOURNEY4 浏览器移植 · 开发文档

👑Lv.11 元老 🌞 骨干会员
2026-11-16 20:19:40

记录 Quake III Arena q3tourney4 单关卡浏览器移植 的完整开发过程:目标、架构、数据管线、运行时模块、踩坑与修复、测试体系和体积优化。

适用对象:接手这个项目的开发者。按本文顺序读一遍,可以独立完成改数值、调画面、修 Bot、重生成数据这四类工作。


目录

  1. 项目概览
  2. 运行方式与文件清单
  3. 总体架构
  4. 数据管线
  5. 运行时架构
  6. 开发阶段
  7. 关键问题与根因
  8. 测试体系
  9. 体积优化
  10. 已知限制
  11. 二次开发指南
  12. 附录

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
碰撞 brush1,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 开火  │
                         └──────────────┴──────────────┴──────────────┘

核心设计原则:

  1. 数据与逻辑分离:地图/贴图/模型/音效全部离线生成,运行时零解析 BSP。
  2. 玩家与 Bot 共用物理:pmMove(body, dt, cmd) 参数化,手感和碰撞完全一致。
  3. 所有“光”都用 Sprite + 径向渐变贴图:three 的灯光对 MeshBasicMaterial 无效,地图亮度完全由 lightmap 决定。
  4. 宁可先跑通数据管线,也不手写地图:所有几何、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:

字段类型精度/说明
positionfloat32Q3 单位,2 位小数
normalint8round(v * 127),解码 /127
uvfloat324 位小数
lmuvfloat325 位小数
coloruint8顶点色 0–255
shaderuint8shader 索引
indexuint16顶点索引

数据格式:

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
doorsteam/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_COL uniform,每帧改一次全生效;
  • 光源来源:火箭、等离子、爆炸、枪口闪光。

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 分组:

  1. 遍历索引三角形,按 shader 索引分桶;
  2. 每桶生成一个 BufferGeometry(position/normal/uv/lmuv/color);
  3. nolightmap 三角形的判定:三个顶点的 lmuv 全为 0;
  4. 每个 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

难度表:

参数EASYNORMALHARD含义
react0.620.340.16看到人后延迟开火(秒)
aimErr0.1600.0750.032瞄准抖动(弧度)
turn3.05.28.0转速上限(弧度/秒)
fireGap1.451.000.75开火间隔倍率
dmg0.551.001.30伤害倍率
speed0.780.921.00移速倍率
strafe0.200.420.60侧移幅度
sight140020002800视野距离

每帧流程:

闪光衰减 → 死亡/坠落重生 → 感知 → 朝向(双频正弦抖动)
→ 移动意图(世界方向)→ 台沿护栏 → 转朝向(有转速上限)
→ pmMove 分子步 → 走空兜底 → 卡死处理 → 开火 → 模型同步 → 摆腿

关键设计:

  • 瞄准与移动解耦:交战时 yaw 对着玩家,但移动必须沿导航路径。先算世界方向,最后再折算成相对 yaw 的 fw/st,否则玩家站在台下时 Bot 会直线走空;
  • 台沿护栏:botDropAhead / botLedgeBad 预判前方是否走空,落差过大就起跳或绕行;
  • 走空兜底:下落超过 140 且 2 秒内没有起跳,才拉回安全点(频繁瞬移是之前“闪动”投诉的根因);
  • 卡死处理:botUnstuck 在长时间无位移时向邻近安全节点挪动;
  • 重生:坠落/死亡后回到安全点,重置弹药与武器;
  • 拾取:和玩家共用 pickups 规则(血包、护甲、武器、弹药);
  • 死亡掉枪:Bot 死亡后在尸体位置生成一把带光晕的武器,可被玩家拾取。

5.12 武器

id名称伤害射速弹匣类型备注
mgMACHINEGUN70.10s200hitscan散布 0.017
sgSHOTGUN10×111.00s50hitscan散布 0.085
rlROCKET LAUNCHER1000.80s50proj溅射 100 / 半径 120 / 击退 320
rgRAILGUN1001.50s50hitscan无散布
pgPLASMA GUN200.10s200proj溅射 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 秒线性淡出。

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 的做法:

  1. 用 Node 加载真实的 three.min.js(只把 WebGLRenderer 换成假对象,避免需要 WebGL 上下文);
  2. 打桩 DOM / Canvas2D / Image / AudioContext;
  3. 依次 eval 地图、武器、物品、玩家模型、贴图、音效数据;
  4. 从 q3tourney4.html 抽出内联脚本,在 IIFE 结束前注入 globalThis.__T = { ... } 导出;
  5. 在 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.js2,585 KB1,468 KB−43%
q3tourney4.tex.js3,771 KB3,682 KB−2%
合计6.36 MB5.15 MB−1.2 MB

9.2 map.js 做了什么

  1. 顶点数组二进制化:JSON 数字 → float32/int8/uint8/uint16 + base64,1.44 MB → 0.87 MB;
  2. 法线 int8:反射只需要 1/127 精度,267 KB → 67 KB;
  3. lightmap → PNG:裸 RGB 524 KB → PNG 250 KB,并把对比度烘焙进去;
  4. 缩略图 32×32 → 16×16:427 KB → 107 KB;
  5. 索引 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 / 机器人队友
Bot3 档难度;寻路偶发 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.GRAVITY800
PM.SPEED320
PM.JUMP_VEL270
PM.STEP_HEIGHT18
PM.BMIN/BMAX[-15,-24,-15] / [15,32,15]
PM.VIEW_HEIGHT26
LM_SCALE1.5 * Math.PI
toneMappingExposure0.85
NAV_CELL24
NAV_STEP24
NAV_MAX_LAYER4
NAV_EYE24
DOOR_PAD10
VM_SCALE0.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.pyBSP → map.js
.workbuddy-ai/tmp/t4/texupgrade.pypak 贴图 → 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.jsGLSL / 渲染链路校验(21 断言)

12.3 一句话总结

数据全部离线烘好、运行时零解析;玩家和 Bot 共用一套物理与碰撞;所有视觉问题都拆成可量化的断言;改完必跑 probe.js + _glsl3.js。

轻量级、高性能、零 MySQL 依赖的PHP社区系统。
| 浏览 9 次 | 回复 0 次

全部回复 (0)

暂无回复

请 登录