ClockworkPi GameShell 安装 DevilutionX:菜单插件、自动编译与按键映射完整指南

原创2026-09-23 18:13:051,862 阅读
文章标签:游戏开发图形学跨平台

ClockworkPi GameShell 安装 DevilutionX:菜单插件、自动编译与按键映射完整指南

DevilutionX 是经典游戏《暗黑破坏神》面向现代操作系统的开源移植版本,而 ClockworkPi GameShell(CPi GameShell)是一款自带键盘、屏幕与电池的开源掌机。本指南以仓库中的 Packaging/cpi-gamesh/readme.md 为骨架,结合其配套的菜单插件 __init__.py、构建脚本 build.sh 以及游戏资源加载源码,完整讲解如何在 GameShell 上通过系统菜单一键克隆、编译、安装并游玩 DevilutionX,包括游戏数据文件(MPQ)的放置规则、中/日/韩文字体与波兰语语音包配置,以及一套完整的掌机按键映射方案。读完本文,你将能够在 GameShell 上独立完成从菜单安装到正常游戏的整个流程。

一、包结构:GameShell 菜单插件由哪些文件组成

在 Packaging/cpi-gamesh/ 目录下,DevilutionX 为 CPi GameShell 提供了一整套打包与安装支撑,核心文件如下:

文件 作用
readme.md 安装、运行与按键映射说明(本文的主体)
__init__.py GameShell 系统菜单(基于 Pygame 的 launcher)插件,负责图标展示、版本检查、git 拉取、编译与启动
build.sh 一键构建脚本:安装依赖、配置 CMake、编译并把插件与图标安装回菜单
Devilution.png 256×256 的菜单图标,暗黑风格骷髅图案,用于在 GameShell 菜单中标识该应用

安装的思路非常简单:GameShell 的启动菜单(/home/cpi/apps/Menu)按目录识别应用,把 __init__.py 复制到一个新建目录下,菜单中就会多出一个以 Devilution.png 为图标的条目,从菜单进入该条目即可进行安装、升级、编译与启动的全部操作。__init__.py 中对路径的约定可以在源码中直接看到(__init__.py):

_GamePath = "/home/cpi/games/devilutionX"
_GameExecutable = _GamePath + "/build/devilutionx"
_GameExecutableRevision = _GameExecutable + ".rev"
_GameBuildScript = _GamePath + "/Packaging/cpi-gamesh/build.sh -t " + pipes.quote(os.path.dirname(os.path.abspath( __file__ )))
_GamePNG = _GamePath + "/Packaging/cpi-gamesh/Devilution.png"
_DevilutionDiabdatmpq = "/home/cpi/.local/share/diasurgical/devilution/diabdat.mpq"

可见源码仓库被克隆到 /home/cpi/games/devilutionX,编译产物为 build/devilutionx,而游戏数据文件 diabdat.mpq 需要放置到用户数据目录 /home/cpi/.local/share/diasurgical/devilution/。

DevilutionX 在 GameShell 菜单中使用的游戏图标

二、安装 DevilutionX:菜单驱动的自动克隆与编译

在 GameShell 菜单中进入 devilutionX 条目后,界面底部会出现功能提示(_FootMsg),依次为 "Nav / Check / Upgrade / Back / Play"。未安装时按 X 键即可触发安装:

  1. 克隆仓库:若 /home/cpi/games/devilutionX 不存在,插件执行 git clone --single-branch --branch master <仓库地址> . 进行单分支克隆(__init__.py)。
  2. 自动安装依赖:构建脚本会执行 sudo apt install -y cmake libsdl2-dev libbz2-dev libsodium-dev(build.sh),自动补齐编译所需的 CMake 与 SDL 等开发包。
  3. 配置并编译:执行 CMake 构建,关键参数为(build.sh):
cmake -S. -Bbuild -DCMAKE_BUILD_TYPE=Release -DTARGET_PLATFORM=cpigamesh -DDISABLE_LTO=ON
cmake --build build -j $(getconf _NPROCESSORS_ONLN)

其中 -DTARGET_PLATFORM=cpigamesh 指定目标平台为 GameShell,-DDISABLE_LTO=ON 关闭链接期优化(LTO),以规避该平台工具链下的链接问题;-j 使用全部可用 CPU 核心并行编译以加快速度。编译完成后,脚本把当前 git 提交号写入 build/devilutionx.rev,并同时安装插件与图标(build.sh):

git rev-parse HEAD > /home/cpi/games/devilutionX/build/devilutionx.rev
mkdir -p /home/cpi/apps/Menu/<target_dir>
cp __init__.py /home/cpi/apps/Menu/<target_dir>
cp Devilution.png /home/cpi/launcher/skin/default/Menu/GameShell/<icon_name>.png

build.sh 还支持 -t/--target 参数指定菜单目标目录,默认目录名为 25_devilutionX;图标会按目录命名规则安装到 GameShell launcher 皮肤目录中。

升级逻辑:已安装时按 X 执行 git pull 拉取更新。插件会对比 git 提交号(devilutionx.rev)与当前 HEAD 是否一致,仅当两者不一致(即存在新提交)时才重新编译(__init__.py)。注意:拉取前会丢弃本地对源码的任何改动,重新编译以仓库最新代码为准。

三、准备游戏数据文件:MPQ 的放置规则与源码印证

编译完成后还需要游戏数据文件才能进入游戏。原始《暗黑破坏神》光盘或 GOG 版本中包含的 DIABDAT.MPQ 必须放置在:

/home/cpi/.local/share/diasurgical/devilution/

这一路径与 DevilutionX 的用户偏好目录(PrefPath)约定一致。在 Source/engine/assets.cpp 的 GetMPQSearchPaths() 中,MPQ 的搜索路径依次包括程序基路径、PrefPath()(Linux 上对应 ~/.local/share/diasurgical/devilution/)、配置路径以及 XDG_DATA_DIRS 下的 diasurgical/devilutionx/ 等目录;LoadGameArchives()(Source/engine/assets.cpp)会依次尝试加载 DIABDAT.MPQ(原版光盘与 GOG 版为大写)、diabdat.mpq,若都不存在则退而尝试免费试玩版数据 spawn.mpq,否则弹出提示要求放入数据文件。

3.1 运行地狱火资料片(Hellfire)

要游玩《暗黑破坏神:地狱火》扩展,除 diabdat.mpq 外还需额外放入 4 个 MPQ 文件:

  • hellfire.mpq
  • hfmonk.mpq(僧侣职业相关数据)
  • hfmusic.mpq(音乐)
  • hfvoice.mpq(语音)

源码中 LoadHellfireArchives()(Source/engine/assets.cpp)会按 hellfire(优先级 8000)、hfmonk(8100)、hfmusic(8200)、hfvoice(8500)依次加载这些 MPQ,并校验僧侣、音乐与语音三部分是否齐全,缺少任何一个都会提示 "Some Hellfire MPQs are missing" 并要求补齐所有 hf*.mpq 文件。同时 LoadCoreArchives() 会先探测 hellfire 是否存在(Source/engine/assets.cpp),以便在游戏内决定是否开放地狱火内容。

3.2 中、日、韩文字体支持:fonts.mpq

DevilutionX 默认仅内置英文等基础字体资源,中文、日文、韩文等非英文界面需要额外下载 fonts.mpq,下载后同样放入游戏数据目录即可。这一点在源码中有直接依据:LoadCoreArchives() 会以 FontMpqPriority 加载 fonts 资源;而 Source/utils/language.cpp 在缺少 fonts.mpq 时会直接报错并提示 "fonts.mpq is required for locale ...",也就是说选择非英文语言却未放置 fonts.mpq 将无法启动游戏。

3.3 波兰语语音包:pl.mpq

如需波兰语语音,可额外下载 pl.mpq 并放入同一目录。语言类 MPQ 的加载逻辑在 LoadLanguageArchive()(Source/engine/assets.cpp)中:当语言代码不是 en 时,会以 LangMpqPriority 加载与语言代码同名的 MPQ 文件。

提示:上述 fonts.mpq 与 pl.mpq 均来自 DevilutionX 官方资产仓库(devilutionx-assets)的 Releases 发布页,按本仓库说明下载后放入游戏数据目录即可。ClockworkOS v0.5 系统因自带库版本较旧,还需要启用 Debian buster-backports 源以获取更新版本的系统库,否则可能因 SDL 等依赖过旧而无法正常运行。

四、运行与状态反馈

当满足以下两个条件时,就可以开始游戏:

  1. build/devilutionx 可执行文件已存在(编译完成);
  2. /home/cpi/.local/share/diasurgical/devilution/diabdat.mpq 已就位。

此时菜单界面会显示 "Ready",提示语是游戏内 NPC 风格的台词 "You must venture through the portal...",按 A 键(即 GameShell 菜单的确认键)即可启动游戏(__init__.py 中通过 RUNSYS 事件拉起游戏进程)。若 MPQ 缺失,状态栏会提示 "Gamefile diabdat.mpq missing",此时按确认键可重新检测文件是否就位。

插件的整个交互过程都使用了《暗黑破坏神》的台词风格,例如检查更新时显示 "Lets search the books..."、编译时显示 "Stay awhile and listen."(游戏里 Deckard Cain 的名句)、失败时显示 "Game Over. Better luck next time!",界面还会同时显示当前 git 源码修订号与二进制修订号(__init__.py)。

五、按键映射:GameShell 键盘与 devilutionX 操作的完整对照

由于 GameShell 与 devilutionX 各自拥有互不兼容的修饰键(Shift)机制,按键映射并非一一对应:映射以 GameShell 标准键盘布局为基础,而 devilutionX 内部采用类似任天堂手柄(Nintendo-style)的按键语义。下面是 readme.md 给出的完整映射表,直接照此操作即可:

GameShell 按键 键盘键 devilutionX 按键 devilutionX 动作
D-Pad 方向键 方向键 D-Pad 移动英雄
Select + D-Pad Space + 方向键 Back + D-Pad 模拟鼠标
B K A 攻击附近敌人、与城镇 NPC 和商人对话、拾取/放置物品(背包内)、主菜单确认
A J B 选择法术、菜单中返回
Y I X 拾取物品、打开附近箱子与门、背包中使用物品
X U Y 施放法术、主菜单中删除角色
Select Space Select Select
Start Enter Start 游戏菜单、跳过过场动画
LK1 H L1 使用腰带上的生命药剂
Start + Left Enter + Left Start + Left 角色面板
Start + Right Enter + Right Start + Right 物品栏
LK5 L R1 使用腰带上的法力药剂
Start + Down Enter + Down Start + Down 自动地图
Select + LK1 Space + H Select + L1 鼠标左键点击
Start + X Enter + U Start + Y 任务日志
Start + A Enter + J Start + B 法术书
Select + LK5 Space + L Select + R1 鼠标右键点击
Select + A/B/X/Y Space + J/K/U/I Select + A/B/X/Y 快捷施法

上表共 17 条映射,覆盖了移动、攻击、交互、菜单导航、腰带道具、模拟鼠标与快捷施法等常用操作。从 devilutionX 侧看,A/B/X/Y 属于标准手柄按键语义(ControllerButton_BUTTON_A/B/X/Y,参见 Source/controls/game_controls.cpp 的按键翻译逻辑),因此 GameShell 键盘通过 __init__.py 所在的打包层将物理键翻译成对应的手柄语义后再进入游戏;而 Select + 或 Start + 这类组合键则借助 Space/Enter 充当的 Shift 修饰键来触发 Back/Start 组合动作,这正是映射表看似"绕路"的原因。

六、小结

在 ClockworkPi GameShell 上部署 DevilutionX 可以总结为三步:把 __init__.py 放进菜单目录生成图标 → 在菜单中按 X 完成克隆、装依赖与编译 → 放入 diabdat.mpq(及可选的 hellfire/语言扩展包)后按 A 启动。整个流程由 __init__.py 与 build.sh 全自动驱动,用户几乎无需手工操作命令;游戏数据目录与 MPQ 加载顺序则由 Source/engine/assets.cpp 定义,理解它即可自由扩展地狱火资料片与多语言支持。若要在 ClockworkOS v0.5 上运行,请先配置 buster-backports 更新系统库,再按本文流程安装。

登录后查看全文
DevilutionX