timriker/bzo

来源：https://github.com/timriker/bzo

Battlezone Online

一个免费的浏览器端 3D 多人坦克游戏——支持桌面、手机或 VR 头显——可与 BZFlag（https://www.bzflag.org/）的客户端和服务器互通。无需安装任何东西。

立即游玩： · 服务器列表 (https://bz.rikers.org/list) · 帮助：操作与旗帜 (https://bz.rikers.org/help) · BZFlag Discord (https://discord.gg/6DHkggcXM9)

一张在 hix 地图上从北基地出发的对局截图：雷达、瞄准框和一辆红色坦克的残骸

试玩

列表列出公开的 bzo 服务器，以及这些服务器所代理的任何 BZFlag 服务器。点击任意一行即可进入该对局。

服务器基于 Node.js；客户端基于 Three.js，通过 WebSocket、WebTransport 和 WebRTC 通信。

发布内容

每个打了标签的发布版本会包含：

• 一个 GitHub release，其说明由 CHANGELOG.md 生成
• 一个源码 tarball
• 一个带版本号的 Ubuntu 26.04 镜像：ghcr.io/timriker/bzo:-ubuntu26.04
• 一个滚动更新的 ubuntu26.04 标签
• ghcr.io/timriker/bzo: 和 ghcr.io/timriker/bzo:latest，两者均基于 Ubuntu 26.04

每个已发布的镜像都包含 linux/amd64 和 linux/arm64 两种架构变体。发布标签只使用稳定的 vX.Y.Z SemVer 格式；预发布标签和构建元数据标签不会发布。

Docker 镜像基于 Ubuntu 26.04 构建，使用 Ubuntu 自带的 nodejs 软件包（Node.js 22），CI 同样在 Ubuntu 26.04 容器中运行相同版本的 Node。

安装并运行服务器

可使用来自 GitHub Container Registry 的 Docker 镜像，或源码 tarball、git 检出。对大多数人来说，Docker 是更好的安装和更新方式。

docs/installation.md 涵盖了这两种方式，以及配置、在反向代理后运行、列出你的服务器、代理 BZFlag 服务器和更新。

需要轮询服务器的站点（统计、服务器浏览器）可以在 docs/api.md 中找到可查询的接口。

/list 的 Launch 链接会在已安装的 BZFlag 客户端中打开 BZFlag 服务器；docs/bzflag-links.md 介绍了如何在 Linux、Windows 和 macOS 上配置 bzflag:// 协议。

旗帜

bzo 包含 BZFlag 的所有旗帜。

WA 广角旗帜会生成、附着并像其他坏旗帜一样被甩掉，但什么都不做：它只是扩大视野范围，而在 VR 中投影由头显接管。

其余旗帜及其原因见 docs/flags.md。

变更日志与发布说明

• 人类可读的历史记录保存在 CHANGELOG.md
• 带标签的 GitHub release 使用变更日志中对应的小节作为发布说明

操作

docs/controls.md 包含所有操作方式：键盘鼠标、屏幕触控操作、游戏手柄以及 XR 控制器。在游戏中按 / 或 ? 可显示键盘操作说明。

WebXR

VR 模式使用原生 WebXR，需要浏览器和头显支持 immersive-vr。

本地验证时，打开 http://localhost:5154 即可。远程访问时需通过 https:// 提供游戏——使用服务器自身的 https 证书或反向代理；当页面通过 HTTPS 提供时，客户端会自动对 WebSocket 连接使用 wss://。

头显浏览器启动已安装的应用时，会直接尝试进入 VR，不显示二维落地页。xr-launch.js 会在客户端其余部分加载之前请求会话，并在每一个可能携带沉浸式会话所需用户激活的信号上持续请求——window load、focus、page show、visibility change 以及 Launch Handler——渲染器会接管最终得到的那个会话。

如果没有触发这些信号，或在其他所有情况下，VR 模式从按钮启动。已保存的名字会直接加入；没有名字时，XR 菜单会打开加入界面，其中包含与二维入口对话框相同的名字、队伍和坦克选择，因此玩家不需要等待自己看不见的界面。

在 XR 中输入文字使用头显自带的系统键盘，在 Name 或 MOTD 行获得焦点时弹出。Quest Browser 26.1 及更高版本提供此键盘；不支持的头显会将这些行标记为 Desktop only，玩家仍可使用服务器分配的名字加入。每次键盘打开都开始全新的编辑，因此第一个按键会替换整个字段而不是追加。

设置齿轮旁的一键 VR 按钮只在有头显的设备上显示，因为 Android 上的 Chrome 会通过 Cardboard 在任何手机上报告 immersive-vr 支持；在该环境下 VR 模式仍保留在设置菜单中。

如果部署设置了限制性的 Permissions-Policy 头，请允许 xr-spatial-tracking=(self)。

TLS 要么是服务器自身的（https，参见 docs/installation.md），要么来自反向代理（docs/installation.md）。在测试新的浏览器、头显或部署时，请参考 WebXR 验证清单。WebGPU 渲染不在该清单范围内。

开发检查

npm run check

这会运行语法与代码风格检查、服务器启动检查和测试套件。CI 也会在 push 和 pull request 时运行这些检查。

发布流程

先把所有东西提交，不要留下任何遗漏：标签指向的是一棵树，标签发布时仍留在工作目录中的编辑不会进入发布内容——版本号说的是一回事，实际构建的却是另一回事，而且没人能从标签中复现它。这包括别人留下的未提交改动：审查它，说明它是什么，然后提交它，而不是绕过它打标签。

在准备发布之前 git status 应该是干净的，标签推送之后也应再次确认干净；最终仍有待处理内容，意味着发布时漏掉了它。

发布标签只使用稳定的 vX.Y.Z SemVer——预发布版本和构建元数据不会发布。

在本地准备发布：

npm run release:prepare -- 1.0.1

这会更新：

• package.json
• package-lock.json
• public/version.mjs
• CHANGELOG.md

这四个文件都要进入发布提交。public/version.mjs 是最容易被遗漏的，没有它的标签会发布一个报告旧版本号的客户端。

然后编辑新的变更日志小节，使其包含真实的用户可见变更。

在本地验证：

npm run check
npm run release:check -- v1.0.1
npm run release:check:increment -- v1.0.1

然后提交、打标签并推送：

git add package.json package-lock.json public/version.mjs CHANGELOG.md
git commit -m "Release v1.0.1 - 简短描述。Closes #1"
git tag v1.0.1
git push
git push origin v1.0.1

提交主题描述的是发布内容而不是给它贴标签：版本号已经在标签、package.json 和 CHANGELOG.md 中了，而 git log --oneline 是唯一只能看到主题的地方。用几个字说明这次变更，在发布完成了某个 issue 时使用真正的关闭关键字引用它，因为光秃秃的 (#NN) 只是链接。

发布工作流将会：

1. 验证稳定标签比上一个发布更新且指向 main
2. 安装依赖并运行 lint、验证、审计和 CodeQL 检查
3. 如果 package.json 与推送的标签不匹配则失败
4. 如果 CHANGELOG.md 中不包含匹配的非占位符小节则失败
5. 使用 Ubuntu 自带的 Node.js 22 构建并冒烟测试 Ubuntu 26.04 镜像，涵盖 linux/amd64 和 linux/arm64
6. 将验证通过的带版本号和滚动 Docker 标签推广到 GHCR
7. 发布 GitHub release 并附加源码 tarball

发布工作流失败的发布不动它。 bzo 仍在开发中，并非每个标签都会产出制品。修复原因然后进入下一个版本——不要删除或移动已发布的标签，也不要为从未构建成功的版本补建 GitHub release。

无论如何，CHANGELOG.md 都是记录，它已经包含了失败版本对应的小节。

public/version.mjs 由 scripts/prepare-release.mjs 写入，并由 scripts/check-release.mjs 对照标签进行验证。不要手动编辑它，也不要在其他地方重新引入硬编码的客户端版本字符串。

打包资源与许可

代码采用 AGPLv3 许可。资源则不尽相同。bzo 包含来自多个地方的模型、贴图、声音和地图：有些属于 BZFlag 项目，依据其许可使用；有些是为 bzo 制作的；有些是随贡献一同到来的。

一个文件不会因为放在仓库里就继承仓库的许可，而来源无人记录的资源，是留给下一个提问者的问题。

对这里添加的任何内容的期望是：

• 在 pull request 中说明它来自哪里，依据什么条款
• 优先选择与 AGPLv3 分发兼容的条款
• 标注某个文件由某工具导出的头部不构成任何授权，注明作者未调查过也同样不是

树中已有的资源并非都达到这个标准。有些早于这一期望，有些是随贡献而来但凭其自身价值值得接纳。目标是为每一个资源达成清晰、有记录的许可，而不是假装已经完成。

如果你知道这里某个东西的来源，或者你就是它的作者，请在 issue 中说明——这是完成此事最省事的方式。

地图是同一问题的另一种形式：从服务器下载或由客户端保存出来的地图，本身不携带任何授权。地图格式本身见 docs/bzw.md。

AGPL 源码可用性

本项目依据 GNU Affero General Public License v3.0 授权。网络用户可以通过运行中的应用访问 /source 获取源码，或直接访问：