DevilutionX 在 RG99(OpenDingux)上的安装、按键映射与硬件适配解析
DevilutionX 在 RG99(OpenDingux)上的安装、按键映射与硬件适配解析
本文以 DevilutionX 官方 RG99 平台手册(docs/manual/platforms/rg99.md)为核心,完整讲解在安伯尼克 RG99 这类 32 MiB 内存的 OpenDingux 掌机上安装、运行《暗黑破坏神 1》的完整流程:从 OpenDingux 分支固件准备、OPK 应用安装、MPQ 数据解包瘦身,到按键映射、存档路径与兼容性说明。同时结合仓库中 CMake/platforms/rg99.cmake 与 Packaging/OpenDingux/ 下的打包脚本,深入剖析 RG99 版本为适配极低内存和 SDL1 硬件缩放所做的一系列针对性优化,帮助读者既会装、会玩,也理解其底层原理。
一、安装前的关键前提
官方文档的第一句话就是最重要的警告:
This version is experimental and requires using an unsupported fork of OpenDingux!
RG99 版本属于实验性移植,且必须使用一个非官方的 OpenDingux 分支固件。这意味着:
- 你现有的 OpenDingux 正式版固件无法直接运行该 OPK,需要先刷入社区维护的 fork 版本(官方文档指向
od-contrib/buildroot的 releases 页面获取该固件); - 由于固件本身不受官方支持,遇到问题时应优先在社区渠道反馈,并接受可能存在的不稳定因素;
- 整个安装链路上任何一步(固件、OPK、数据目录)出错都可能导致游戏无法启动。
从 docs/building.md 的构建说明可知,DevilutionX 的 OpenDingux / RetroFW 系列移植共用一套 buildroot 工具链,构建目标包括 lepus、retrofw、rg99、rg350、gkd350h(见 Packaging/OpenDingux/targets.sh),其中 RG99 是内存最紧张的目标平台,这也是后文大量特殊优化的根源。
二、三步完成安装
官方手册给出的安装流程共三步,下面逐步展开并结合仓库说明每一步的目的。
第 1 步:安装 OpenDingux fork 固件
从 od-contrib/buildroot 的 release 页面下载对应 RG99 的分支固件并刷机。这是后续一切操作的基础,务必确认固件版本与你的 RG99 机型匹配。
第 2 步:复制 OPK 应用到 apps 目录
将 devilutionx-rg99.opk 下载后复制到设备的 apps 目录。RG99 的 OPK 与其他 OpenDingux 平台(如 RG350 手册 中的 /media/sdcard/APPS/、gkd350h 手册 中的 /media/data/apps)一样,属于应用菜单扫描目录,放入后即可在系统应用列表中出现。
OPK 内部结构由 Packaging/OpenDingux/package-opk.sh 的打包逻辑决定:打包脚本会把 rg99.desktop 重命名为 default.rg99.desktop、把 rg99-manual.txt 重命名为 readme.rg99.txt,连同编译出的 devilutionx 可执行文件、assets/ 资源目录一起用 mksquashfs 压成 .opk。而 Packaging/OpenDingux/rg99.desktop 中的 X-OD-NeedsDownscaling=true 表明 RG99 版本依赖系统的画面缩放能力(具体原理见后文硬件适配章节)。
第 3 步:解包并瘦身 MPQ 数据
RG99 版本以 UNPACKED_MPQS 模式运行,即不再直接读取 diabdat.mpq 等 MPQ 压缩包,而是读取解包后的散文件目录。官方要求使用 devilutionx-mpq-tools 工具集中的 unpack_and_minify 对 MPQ 内容进行解包(unpack)并压缩瘦身(minify):
unpack:把 MPQ 内部资源(CEL/CL2/CLX 图形、WAV 音效、TSV 文本表等)释放为普通文件;minify:对资源做重编码与压缩(如降低音频采样、压缩图像格式),大幅减小体积,使其能在 RG99 的存储与内存限制下加载。
从 CMake/platforms/rg99.cmake 第 2~6 行可以看到这一模式的根源:
# RG99 has the same layout as RG300 but only 32 MiB RAM
set(BUILD_ASSETS_MPQ OFF)
set(UNPACKED_MPQS ON)
set(UNPACKED_SAVES ON)
set(NONET ON)
set(USE_SDL1 ON)
其中 UNPACKED_MPQS ON 正是解包模式开关;UNPACKED_SAVES ON 让存档也以散文件而非 .sv MPQ 记录形式保存;NONET ON 禁用联网功能;USE_SDL1 ON 使用内存占用更小的 SDL 1.2。在 CMakeLists.txt 中这两个选项的注释也印证了这一点:当 UNPACKED_MPQS 与 UNPACKED_SAVES 同时开启时,MPQ 支持会被完全移除,因此数据目录必须是以解包形式存在的。
解包后的目录在 Source/engine/assets.cpp 中通过 FindUnpackedMpqFile 等逻辑直接按相对路径检索散文件,不再经过 MPQ 解压层,既省去了运行时解压的 CPU/内存开销,也避免了 squashfs 上随机读取 MPQ 的高延迟。
第 4 步(合并进第 3 步后的放置):数据目录与 SD 卡符号链接
将解包瘦身得到的多个结果目录整体复制到设备上的固定路径:
/media/data/local/home/.local/share/diasurgical/devilution/
注意官方手册特意强调这里写的是「resulting directories」(多个目录),因为解包产物通常按 diabdat、hellfire 等分区组织,需要连同目录结构一起复制。
由于 RG99 的板载存储空间极为有限,官方建议先把 ~/.local 目录迁移到 SD 卡再做软链接:
mv /media/data/local/home/.local /media/sdcard/dotlocal
ln -s /media/data/local/home/.local /media/sdcard/dotlocal
这两条命令的执行顺序有讲究:先把真实数据移动到 SD 卡上的 dotlocal,再让原路径变成指向 SD 卡的符号链接。这样游戏数据、存档都落在 SD 卡上,避免写爆板载存储。注意命令参数方向:ln -s <目标> <链接名>,即先写 SD 卡实际位置,再写原路径。
数据文件清单(补充)
官方随 OPK 附带的手册 Packaging/OpenDingux/rg99-manual.txt 还明确了各数据文件的来源:
| 数据文件 | 用途 |
|---|---|
diabdat.mpq |
原版《暗黑破坏神 1》光盘或 GOG 安装目录中的主数据文件,必需 |
hellfire.mpq、hfmonk.mpq、hfmusic.mpq、hfvoice.mpq |
地狱火资料片数据,可选 |
fonts.mpq |
中、日、韩文字体支持包,可选 |
pl.mpq |
波兰语语音包,可选 |
这些 MPQ 同样需要先经 unpack_and_minify 处理成散文件再放入上述目录。
三、完整按键映射
官方手册列出了 RG99 的完整按键方案,下表整理为便于查阅的形式(与 rg99-manual.txt 一致):
| 按键 | 功能 |
|---|---|
| 十字键(D-pad) | 移动英雄 |
| A | 攻击近处敌人、与城镇 NPC 和商人对话、物品栏中拾取/放置物品、主菜单中确认 |
| B | 选择法术、菜单中返回 |
| X | 拾取物品、打开附近箱子与门、物品栏中使用物品 |
| Y | 施放法术、主菜单中删除角色 |
| R | 使用腰带中的法力药水 |
| L | 使用腰带中的生命药水 |
| Start + Select | 游戏菜单(备用组合:Start + ↑) |
| Start + L 或 ← | 角色信息 |
| Start + R 或 → | 物品栏 |
| Start + ↓ | 地图 |
| Start + Y | 任务日志 |
| Start + B | 法术书 |
| Select + A/B/X/Y | 快捷法术 |
| Select + 十字键 | 移动地图/光标 |
| Select + L | 鼠标左键点击 |
| Select + R | 鼠标右键点击 |
| Suspend | 地图 |
这些组合键本质上模拟了桌面版的鼠标左右键与快捷键,且与 CMake/platforms/rg99.cmake 中的底层键盘映射一一对应。例如该文件第 47~62 行定义了 KBCTRL_BUTTON_* 系列:B → SDLK_LCTRL、A → SDLK_LALT、Y → SDLK_SPACE、X → SDLK_LSHIFT、右肩键 R → SDLK_BACKSPACE、左肩键 L → SDLK_TAB、Start → SDLK_RETURN、Suspend → SDLK_END、Select → SDLK_ESCAPE。同时 DEVILUTIONX_GAMEPAD_TYPE Nintendo 表明手柄布局按任天堂 ABXY 习惯映射(A 在右、B 在下),与按键表完全吻合。文件第 46 行 PREFILL_PLAYER_NAME ON 还会在创建角色时自动预填玩家名,省去在软键盘上输入的痛苦。
四、存档位置与兼容性
游戏存档与 diablo.ini 配置文件存放在:
/media/home/.local/share/diasurgical/devilution/
注意与数据目录的差异:数据目录在 /media/data/...,而存档目录在 /media/home/...,这与 rg99-manual.txt 中「~ 即你的 home 目录,默认为 /media/data/home」的说明一致,两者是设备上的不同分区/路径。
存档的兼容性由 DevilutionX 项目本身的存档格式保证:
Saves are compatible with PC saves from Diablo 1 and DevilutionX.
即 RG99 上创建的存档可以与 PC 版《暗黑 1》及桌面版 DevilutionX 的存档互换使用。这得益于 RG99 构建使用 UNPACKED_SAVES ON——存档以散文件形式存放,但内部结构仍是标准的 Diablo 1 存档格式(英雄名、进度、物品栏等字段完全一致),只是存储容器从 MPQ 换成了普通文件。
五、硬件适配源码解读:为什么 RG99 版本如此特殊
RG99 移植版最值得研究的是它针对 32 MiB 内存这一硬约束所做的全套适配,全部集中在 CMake/platforms/rg99.cmake。除了前面提到的 UNPACKED_MPQS / UNPACKED_SAVES / NONET / USE_SDL1 四大开关,还有以下关键优化:
1. 二进制体积与内存占用
- 动态链接 libstdc++:
DEVILUTIONX_STATIC_CXX_STDLIB OFF。注释说明这能省约 1.3 MiB——OPK 以 squashfs 挂载,二进制会被解压到内存,而系统的 libstdc++ 常驻磁盘,动态链接可显著降低内存峰值; - 编译优化旗标:
-fmerge-all-constants与-fsection-anchors各省约 4 KiB; - 减小线程栈:通过链接器参数
-Wl,-z,stack-size=32768把默认 128 KiB 的线程栈降到 32 KiB(musl 的线程栈默认值与 glibc 不同,详见链接器注释),这是低内存设备常见的关键手段; - 关闭 16 位调色板透明查找表:
DEVILUTIONX_PALETTE_TRANSPARENCY_BLACK_16_LUT OFF,省下 128 KiB。
2. 音频与视频适配
- 音频流式加载:
STREAM_ALL_AUDIO_MIN_FILE_SIZE 4096——音频文件超过 4 KiB 即从磁盘流式读取,避免整段载入内存; - 更小的音频缓冲:
DEFAULT_AUDIO_BUFFER_SIZE 768; - 降低重采样质量:
DEFAULT_AUDIO_RESAMPLING_QUALITY 2,以音质换帧率; - SDL1 视频模式:
SDL1_VIDEO_MODE_BPP 8强制 8 位调色板表面;SDL1_FORCE_SVID_VIDEO_MODE ON与SDL1_FORCE_DIRECT_RENDER ON启用直渲染;SDL1_VIDEO_MODE_FLAGS SDL_HWSURFACE|SDL_FULLSCREEN要求硬件表面——这是因为 RG99 的硬件缩放器只能缩放 YUV 数据,而 SDL 库可自动把 8 位调色板表面转成 YUV,配合.desktop里的X-OD-NeedsDownscaling=true,由硬件完成 320×240 游戏画面到屏幕分辨率的缩放,双缓冲视频模式则用于播放过场视频(SDL1_VIDEO_MODE_SVID_FLAGS ... SDL_DOUBLEBUF)。
3. 启动流程优化
Packaging/OpenDingux/build.sh 中针对 rg99 有专门分支:OPK 内额外打入 devilutionx-from-disk.sh 和 devilutionx-umount-opk-and-run.sh,且桌面入口的 Exec 被改写为 devilutionx-from-disk.sh。这个启动器(devilutionx-from-disk.sh)的注释解释了动机:先解除 OPK 的 squashfs 挂载、把内容复制到磁盘再运行,以避免 squashfs 的内存开销。脚本会:
- 检测第一个 mmcblk 存储分区(回退到
/media/data/local/home)作为解包目标; - 用 MD5 比对已解包二进制与 OPK 内二进制,相同则跳过复制(增量更新友好);
- 执行
devilutionx-umount-opk-and-run.sh卸载当前挂载点后直接运行磁盘上的可执行文件。
这一「挂载→解包→卸载→运行」的链条是 RG99 版特有的低内存启动策略,也解释了为什么 RG99 的 OPK 比普通平台的更复杂。
六、自行构建 RG99 版本
如果你想从源码自行构建,docs/building.md 的「OpenDingux / RetroFW」小节给出了通用流程:使用 buildroot 工具链,并确保本机装有 mksquashfs,然后执行:
TOOLCHAIN=<path/to/toolchain> Packaging/OpenDingux/build.sh rg99
构建产物为 build-rg99/devilutionx-rg99.opk(package-opk.sh 中 TARGET=rg99 时扩展名即为 rg99)。工具链本身可从 OpenDingux buildroot 的 release 页面获取,仓库不内置该工具链。
七、排错与注意事项速查
- 游戏不显示/黑屏:确认已刷入
od-contrib的 fork 固件(正式版 OpenDingux 无法运行);确认X-OD-NeedsDownscaling所需的硬件缩放链路可用; - 数据读取失败:确认
diabdat.mpq已用unpack_and_minify解包,且目录层级与/media/data/local/home/.local/share/diasurgical/devilution/完全对应,解包产生的多个目录都要复制; - 存储不足:先执行符号链接步骤,把
.local重定向到 SD 卡,再复制数据; - 内存不足/卡顿:RG99 仅有 32 MiB 内存,不要同时开启过多后台应用;音频重采样质量已在构建期调低,如需改回可自行以默认 CMake 选项重建;
- 存档位置:不要与数据目录混淆,存档在
/media/home/.local/share/diasurgical/devilution/。
八、延伸阅读
- 安装总览:docs/installing.md(覆盖各平台的通用与分平台安装说明)
- 构建指南:docs/building.md
- RG99 硬件适配完整配置:CMake/platforms/rg99.cmake
- OpenDingux 打包脚本:package-opk.sh、build.sh
- 数据文件与按键手册:rg99-manual.txt
- 解包模式资源加载实现:Source/engine/assets.cpp
其他 OpenDingux 平台(RG350、gkd350h、lepus、retrofw)的手册可在 docs/manual/platforms/ 目录下找到,它们共用同一套 OPK 打包机制,仅在资源路径与按键细节上有所差异,可作为对照参考。有关本移植版的最新发布信息与社区讨论,请参阅官方手册底部的 Resources 一节。