DevilutionX 在 RG99(OpenDingux)上的安装、按键映射与硬件适配解析

原创2026-09-23 10:02:181,995 阅读
文章标签:游戏开发图形学跨平台

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 的内存开销。脚本会:

  1. 检测第一个 mmcblk 存储分区(回退到 /media/data/local/home)作为解包目标;
  2. 用 MD5 比对已解包二进制与 OPK 内二进制,相同则跳过复制(增量更新友好);
  3. 执行 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/。

八、延伸阅读

其他 OpenDingux 平台(RG350、gkd350h、lepus、retrofw)的手册可在 docs/manual/platforms/ 目录下找到,它们共用同一套 OPK 打包机制,仅在资源路径与按键细节上有所差异,可作为对照参考。有关本移植版的最新发布信息与社区讨论,请参阅官方手册底部的 Resources 一节。

登录后查看全文
DevilutionX