5月8日,故障报告上线:21款游戏全部地址无效
问题很简单:
打开任何一款游戏,播放器只显示地址无效。
这不是某一款游戏的问题,是全站 21 款无一例外。这排除了一款游戏配置错误的可能,指向了某种系统性的根本错误。
诊断从日志开始。
第一层诊断:ATPlayer 的日志说了什么
Logger 系统设计得很成熟,本地缓冲 + 批量上报,还支持 Debug 模式打开。打开 Debug 模式,日志里反复出现的错误只有一个:
normaliseXMPlayEntry(): game.gameUrl = null
ATPlayer._buildGameUrl(): returns null → iframe.src 未被赋值
游戏数据 normalize 之后,gameUrl 变成了 null。这是所有游戏播放失败的直接原因。
但 gameUrl 字段是从哪里来的?
从 xmplay-library.json 读取的。21 款游戏在 JSON 里明确定义了 gameUrl 字段,路径都写得很清楚:/xmplay/doll-detective-irene/main.html 这样的格式。
问题出在读取的过程中。
第二层诊断:resolveGameUrl() 的盲区
js/core/api.js 里有一个函数叫 resolveGameUrl(),负责把 JSON 里的字段解析成实际可访问的 URL。这个函数在 api.js 里的原始实现是:
function resolveGameUrl(raw) {
if (raw.entryUrl) return raw.entryUrl; // ← 库中无此字段
if (raw.url) return raw.url; // ← 库中无此字段
if (raw.manifestUrl) return raw.manifestUrl; // ← 返回 JSON 路径而非 HTML!
return null; // ← 全站 21 款游戏全部 return null
}
xmplay-library.json 里所有游戏的可玩地址存储在 gameUrl 字段,但 resolveGameUrl() 根本没有读取这个字段。
它优先读取了 entryUrl、url、manifestUrl,三个都没有,然后 return null。
这个 null 沿着调用链向下传递:
resolveGameUrl() → returns null
→ ATPlayer._buildGameUrl() → iframe.src = null
→ 播放器显示地址无效
修复方法很简单,22 行代码:
function resolveGameUrl(raw) {
if (raw.gameUrl) return raw.gameUrl; // ← 优先读取库中实际存在的字段
if (raw.entryUrl) return raw.entryUrl;
if (raw.url) return raw.url;
if (raw.mainUrl) return raw.mainUrl;
// 永远不回退到 manifestUrl(manifest 是 JSON 元数据,不是可运行 HTML)
return null;
}
加一行 if (raw.gameUrl),21 款游戏当天全部恢复播放。
XMP 协议的设计哲学:为什么字段这么多
问题虽然简单,但值得追问一句:为什么 JSON 里有 gameUrl、entryUrl、url、manifestUrl 四个不同名字的地址字段?
XMP 协议是一个多格式生态。同一款游戏,根据发行场景不同,需要不同的可访问路径:
| 字段 | 含义 | 示例 |
|---|---|---|
manifestUrl |
指向 XMP 元数据 JSON | /xmplay/doll-detective-irene/manifest.json |
entryUrl |
标准入口 HTML(XMP-single) | /xmplay/doll-detective-irene/main.html |
gameUrl |
游戏实际可运行的 HTML | /xmplay/doll-detective-irene/main.html |
mainUrl |
备用入口 | 同上 |
manifestUrl 返回的是描述游戏参数的元数据,不是游戏本身。把它当 gameUrl 用,iframe 就只能加载一个 JSON 文件。
这是 XMP 协议设计哲学的一个体现:每个 URL 只做一件事,不同职责用不同字段。
这增加了适配复杂度,但好处是:不同工具链可以按需引用,不需要解析一个万能字段。协议的扩展性更好——当未来有新的 XMP 格式时,只需要加新的 URL 字段,不需要改现有逻辑。
XSP v2 Bridge 协议:播放器和游戏的双向对话
播放地址问题解决后,XMP 协议的核心机制才真正开始工作。
XSP v2 Bridge 是游戏 iframe 和宿主 ATPlayer 之间的通信协议。设计目标只有一个:宿主页面能向游戏注入参数,游戏能向宿主报告状态。
参数注入的完整时序:
① activate → ATPlayer 就绪,通知游戏宿主已准备好
② _resolveParams → 从 URL 参数 / JSON / 预设中解析出游戏需要的参数
③ iframe.load → 游戏 HTML 文件开始加载
④ _injectParams → ATPlayer 通过 postMessage 向游戏注入参数
⑤ bridge.js → 游戏端 bridge 模块建立并响应 __XMP_HANDSHAKE__
⑥ __XMP_READY__ → 游戏就绪,通知宿主开始播放
⑦ game_play_end → 游戏结束,通知宿主触发评分弹窗
这是一个五步握手(activate → resolve → inject → ready → end),每一步都有明确的状态定义和超时处理。协议设计本身相当严密。
审计报告特别指出了两个值得在接入后验证的细节:
第一:params 字段的两套来源问题。 xmplay-library.json 的 params 数组在多个游戏里是空的,但游戏目录下各自有 params/schema.json。两套参数来源之间没有同步——如果 schema.json 更新了,JSON 里不会自动同步。这意味着播放器可能注入了过时的参数,或者注入了游戏不再需要的参数。
第二:部分游戏存在重复条目。 doll-ziyin-desert-inn 在 JSON 里有两个不同的 gameUrl:一个是 /xmplay/doll-ziyin-desert-inn/main.html,一个是 /xmplay/games/doll-ziyin-desert-inn.html。这两个版本之间是否有内容差异,是否需要去重,还没有明确答案。
一个被忽视的漏洞:gameUrl 不存在时代码没有报错
回到 resolveGameUrl() 的原始实现,有一件事值得单独提一下:
if (raw.entryUrl) return raw.entryUrl;
if (raw.url) return raw.url;
if (raw.manifestUrl) return raw.manifestUrl;
return null;
当所有字段都不存在时,函数安静地返回 null,没有任何警告、没有 console.error、没有异常。
在正常情况下这不是问题——字段总是存在。但在调试阶段,这掩盖了真正的问题:gameUrl 字段是存在的,只是代码没有去读它。
如果 resolveGameUrl() 在字段缺失时抛出一个明确的错误(比如 resolveGameUrl: 所有URL字段均不存在, gameId= + raw.id),这个 bug 在开发阶段就会暴露,不需要等上线后用户看到地址无效才知道。
这是一个工程习惯问题:在数据不完整时 fail fast(快速失败),而不是 fail silently(安静失败)。
快速适配脚本:从诊断到修复的工程方法论
_DOC/XMP_Adaptation_Log.md 里记录的不只是问题,还有工程师的诊断路径。这个路径值得任何做 Web 适配工作的开发者参考:
第一步:建立可重现的环境。 verify-xmplay.ps1 脚本对每个游戏 URL 单独测试,生成诊断报告。在运行脚本之前,每个游戏的播放状态都是未知的;运行之后,每个游戏的问题都变成已知的。这是调试效率的基础。
第二步:找到最接近的同类已知问题。 如果 rainy-night-letters-v2 和 doll-ziyin-desert-inn 报同样的错,先看这两个是不是同源的。找到共同特征,就能定位系统性问题而不是个案问题。
第三步:修一个文件,解决所有问题。 找到根因后,修复的是 api.js 里的 resolveGameUrl(),不是每个游戏逐个改 JSON。系统性问题修系统,一次生效。
第四步:写回归测试。 port_game.py 脚本可以批量验证修复后每个游戏是否真实可播放。这是防止修了一个 bug 引入另一个的最直接方法。
写在最后
21 款游戏全部恢复播放之后,工程师在 _DOC 里留下了详细的日志。日志的最后一条写着:
VOXVOY × Xmohe AI Lab
这两个名字并排出现,是这个项目的协作结构:AstroTown 是 VO 的项目,XMP 协议是 XV 的标准。适配工作的本质,是让 VO 的平台能够正确播放 XV 的内容——两个系统之间的接口协议对接。
接口协议的对接从来不靠看起来差不多,靠的是对协议规范的精确理解和逐字段的验证。21 款游戏全部恢复播放的背后,是每一次都正确返回的 resolveGameUrl()。
一个字段,一条 return 语句,21 款游戏,一整天的调试日志。
这就是 Web 适配工作最真实的样子。
XMP 协议系列文章 · 第一篇。下一期:《XMP 游戏格式家族全解析:single / advanced / native 三种格式的适用场景》