ClockworkPi GameShell 安装 DevilutionX:菜单插件、自动编译与按键映射完整指南
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 条目后,界面底部会出现功能提示(_FootMsg),依次为 "Nav / Check / Upgrade / Back / Play"。未安装时按 X 键即可触发安装:
- 克隆仓库:若
/home/cpi/games/devilutionX不存在,插件执行git clone --single-branch --branch master <仓库地址> .进行单分支克隆(__init__.py)。 - 自动安装依赖:构建脚本会执行
sudo apt install -y cmake libsdl2-dev libbz2-dev libsodium-dev(build.sh),自动补齐编译所需的 CMake 与 SDL 等开发包。 - 配置并编译:执行 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.mpqhfmonk.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 等依赖过旧而无法正常运行。
四、运行与状态反馈
当满足以下两个条件时,就可以开始游戏:
build/devilutionx可执行文件已存在(编译完成);/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 更新系统库,再按本文流程安装。
