openage 模组包(Modpack)完整指南:资源组织、定义文件与分发机制
openage 模组包(Modpack)完整指南:资源组织、定义文件与分发机制
openage 是一款开源的《帝国时代 II》引擎重制项目,其所有输入资源(游戏数据、图形、声音、脚本、翻译等)都通过 modpack(模组包) 进行组织和加载。本指南以仓库中的 doc/media/openage/modpacks.md 为核心,结合 modpack 定义文件规范、文件引用规范 以及 libopenage/assets 与 openage/convert 下的源码实现,系统讲解 modpack 的组成、定义文件格式、分发方式、许可证要求与寻址规范。读完本文,你将能够独立编写 modpack.toml 定义文件、理解资源加载与依赖解析机制,并掌握 standalone 与 package repository 两种分发路径。
Modpack 是什么?
Modpack 是 openage 引擎的输入资源组织单元。引擎所需的一切外部输入,例如:
- 游戏数据(gamedata)
- 图形(graphics)
- 声音(sounds)
- 脚本(scripts)
- 翻译(translations)
都可以放入一个或多个 modpack 中,也可以将以上内容任意组合。Modpack 的范围没有限制:从一个小型增强补丁到完整的独立游戏(standalone game),都可以是一个 modpack。
在源码层面,这个概念的对应实现位于 libopenage/assets/modpack.h 的 Modpack 类和 ModpackInfo 结构体:
ModpackInfo保存 modpack 的元数据,包括路径、id、版本、仓库名、别名、标题、描述、许可证、依赖、冲突、包含/排除的资产路径以及作者信息(modpack.h);Modpack类封装一个 modpack,提供get_info()获取元数据、check_integrity()做完整性校验(当前实现中抛出一个 "not implemented yet" 错误,见 libopenage/assets/modpack.cpp,属于尚未完成的 TODO)。
在转换侧(converter),openage/convert/entity_object/conversion/modpack.py 的 Modpack 类负责在资源转换导出阶段收集数据文件、媒体文件与元数据文件,并最终生成 modpack 目录结构。
除游戏数据外,modpack 还存储加载配置信息,其中大部分位于 modpack 定义文件(modpack definition file)中。此外,modpack 可以通过声明依赖(dependencies)和冲突(conflicts)来定义与其他 modpack 的交互关系。
Modpack 内部的文件组织结构由创作者自行决定,openage 不强制规定特定的文件结构(当然推荐"合理"的结构),唯一有硬性要求的是 modpack 定义文件的位置与文件名。
Modpack 定义文件(modpack.toml)
文件位置与作用
modpack 定义文件相当于 modpack 的头文件,是 modpack 中唯一必需的文件。它必须放在 modpack 根目录下,且文件名固定为 modpack.toml。
定义文件的主要用途是存储配置参数,例如:
- 内部名称(internal name)、别名(alias)和版本号(version)
- 需要加载的游戏资产路径
- 描述与作者信息
同时,定义文件还可以指定与其他 modpack 的交互:
- 对其他 modpack 的依赖(dependencies)
- 与其他 modpack 的冲突(conflicts)
- 对其他 modpack 的替换(replacement)
- 指定相对其他 mod 的首选加载顺序(preferred load order)
配置格式(TOML)
定义文件使用 TOML 作为配置语言,格式版本为 2(file_version = "2")。完整参数规范见 doc/media/openage/modpack_definition_file.md。建议以如下注释作为文件开头,帮助他人快速识别该文件格式(非强制):
# openage modpack definition file
文件顶层必须指定 file_version 参数:
| 参数 | 数据类型 | 是否可选 | 描述 |
|---|---|---|---|
file_version |
String | 否 | modpack 定义文件格式的版本号。 |
[info] 段:通用信息
[info] 包含 modpack 的通用信息:
| 参数 | 数据类型 | 是否可选 | 描述 |
|---|---|---|---|
packagename |
String | 否 | modpack 的名称。 |
version |
String | 否 | modpack 的内部版本号,必须使用 semver 格式。 |
versionstr |
String | 是 | 人类可读的版本字符串。 |
repo |
String | 是 | 托管该包的仓库名称。 |
alias |
String | 是 | modpack 的别名,可用于替换其他 modpack。 |
title |
String | 是 | 在 UI 中显示的标题。 |
description |
String | 是 | 指向一个短描述文件的路径(最长 500 字符)。 |
long_description |
String | 是 | 指向一个详细描述文件的路径。 |
url |
String | 是 | modpack 网站链接。 |
license |
Array[String] | 是 | modpack 的许可证。 |
版本号语义:
version用于引擎判断 modpack 的最新版本,因此每当 modpack 内容发生变化(例如发布新版本)时应递增它。versionstr是展示给用户看的字符串,可以是任何内容,因此可用于表示任意合理的版本格式。
[assets] 段:资产路径
[assets] 包含 modpack 中资产的路径:
| 参数 | 数据类型 | 是否可选 | 描述 |
|---|---|---|---|
include |
Array[String] | 否 | 加载时需要挂载的资产路径列表。路径允许包含通配符(wildcards)。 |
exclude |
Array[String] | 是 | 需要从挂载中排除的资产路径列表。路径允许包含通配符。 |
[dependency] 段:依赖
[dependency] 包含 modpack 依赖的其他 modpack 列表:
| 参数 | 数据类型 | 是否可选 | 描述 |
|---|---|---|---|
modpacks |
Array[String] | 是 | modpack 别名或标识符(identifier)列表。 |
[conflict] 段:冲突
[conflict] 包含与当前 modpack 冲突的其他 modpack 列表:
| 参数 | 数据类型 | 是否可选 | 描述 |
|---|---|---|---|
modpacks |
Array[String] | 是 | modpack 别名或标识符列表。 |
[authors] 段:作者信息
[authors] 包含 modpack 创作者的信息。每位作者必须有独立的子表 [authors.{authorname}],可设置以下参数:
| 参数 | 数据类型 | 是否可选 | 描述 |
|---|---|---|---|
name |
String | 否 | 作者昵称,在 modpack 内必须唯一。 |
fullname |
String | 是 | 作者全名。 |
since |
String | 是 | 作者开始贡献的发布版本号。 |
until |
String | 是 | 作者停止贡献的发布版本号。 |
roles |
Array[String] | 是 | 作者在 modpack 制作过程中的角色列表。 |
contact |
Table | 是 | 联系信息(见下表)。 |
contact 表可使用的参数:
| 参数 | 数据类型 | 是否可选 | 描述 |
|---|---|---|---|
discord |
String | 是 | Discord 用户名 |
email |
String | 是 | 邮箱地址 |
github |
String | 是 | GitHub 用户名 |
gitlab |
String | 是 | GitLab 用户名 |
irc |
String | 是 | IRC 用户名 |
mastodon |
String | 是 | Mastodon 用户名 |
matrix |
String | 是 | Matrix 用户名 |
reddit |
String | 是 | Reddit 用户名 |
twitter |
String | 是 | Twitter 用户名 |
youtube |
String | 是 | YouTube 用户名 |
[authorgroups] 段:作者组
[authorgroups] 包含作者团队或小组的信息,可作为 [authors] 的补充,用于表示 modpack 是团队协作的成果:
| 参数 | 数据类型 | 是否可选 | 描述 |
|---|---|---|---|
name |
String | 否 | 组或团队名称。 |
authors |
Array[String] | 否 | 作者标识符列表。这些标识符必须与 [authors] 段中的子表键匹配,例如 "xxbunny123" 对应 [authors.xxbunny123]。 |
description |
String | 是 | 指向团队描述文件的路径。 |
一个完整的 modpack.toml 示例
综合以上所有段,一个完整的定义文件示例大致如下:
# openage modpack definition file
file_version = "2"
[info]
packagename = "my_mod"
version = "1.0.0"
versionstr = "1.0.0 stable"
repo = "my_repo"
alias = "mymod"
title = "My Openage Mod"
description = "descriptions/short.txt"
long_description = "descriptions/long.txt"
url = "https://example.org/my_mod"
license = ["CC-BY-SA-4.0", "OFL-1.1"]
[assets]
include = ["data/", "graphics/", "sounds/"]
exclude = ["sounds/unused/"]
[dependency]
modpacks = ["aoe2_base", "fancy_graphics@enhancement_repo"]
[conflict]
modpacks = ["legacy_graphics"]
[authors]
[authors.xxbunny123]
name = "xxbunny123"
fullname = "Jane Doe"
since = "0.5.0"
until = "1.0.0"
roles = ["Artist", "Balance"]
contact = { email = "jane@example.org", github = "xxbunny123" }
[authorgroups]
[authorgroups.mod_team]
name = "Mod Team"
authors = ["xxbunny123", "other_author"]
description = "descriptions/team.txt"
定义文件与源码的对应关系
定义文件并非仅存在于文档中,引擎的加载器会实际解析它。在 C++ 侧,libopenage/assets/modpack.cpp 的 parse_modepack_def() 使用 toml 库逐段解析 modpack.toml:
info表中的name与version是必需项,缺失时直接抛出Error(见 modpack.cpp);assets表中的include是必需项(modpack.cpp),exclude可选;dependency与conflict段如果存在,则其modpacks参数为必需项(modpack.cpp);authors与authorgroups为可选段,每个作者子表必须有name(modpack.cpp)。
在 Python 转换侧,openage/convert/entity_object/export/formats/modpack_info.py 的 ModpackInfo 类负责生成 modpack.toml:dump() 方法按固定顺序输出 file_version、info、assets、dependency、conflict、authors、authorgroups 各段(见 modpack_info.py),并提供 add_author()、add_author_group()、add_include()、add_exclude()、add_dependency()、add_conflict() 等便捷方法。也就是说,converter 从原始游戏资源转换出的 modpack,其定义文件就是通过该类的 dump() 生成的。
分发方式(Distribution)
Modpack 可以通过两种方式分发:独立分发(standalone)和包仓库(package repository),各有其优势。
独立分发(Standalone Distribution)
任何 modpack 都可以通过将 modpack 打成 ZIP 或 tar.gz 压缩包,发布到托管平台或网站上,实现独立分发。openage launcher 可以直接导入该压缩包。
这是发布 openage modpack 的最简单方式,但更新和依赖需要手动处理。因此,若想为用户提供更好的便利性,官方建议使用包仓库。
一个重要的建议:允许所有人下载 modpack 的旧版本——其他 modpack 可能依赖你内容的特定发布版本。
包仓库(Package Repositories)
包仓库(repo)是 modpack 的专用托管平台,其设计灵感来自 Linux 发行版、Python、Rust 等生态的包管理系统。包仓库具备以下优势:
- 可以定期检查更新;
- 如果依赖位于同一仓库中,可以自动下载并安装依赖;
- 可以存储 modpack 的历史记录(历史版本);
- 可以通过关键词或内容过滤器进行搜索;
- 可以对 modpack 进行签名以表明可信度(例如检查漏洞或恶意软件)。
任何人都可以搭建包仓库。用户可以在 openage launcher 中添加任意数量的仓库,openage 安装时会默认添加一些仓库。仓库是分发 mod 的首选方式。
在转换流程中,modpack 导出时还会额外生成一个 manifest.toml 完整性清单文件,见 openage/convert/entity_object/export/formats/modpack_manifest.py:它记录所用的哈希算法以及各文件相对路径对应的哈希值,用于分发后的完整性校验;哈希值由 openage/convert/processor/export/generate_manifest_hashes.py 生成。
许可证(Licensing)
一旦 mod 公之于众,明确其他人可以如何使用、复制它是很必要的。这可以通过为 modpack 添加许可证(license)来实现。使用许可证完全是可选的,但在某些情况下添加它是明智的。例如,许可证可以规定如何署名(give credit),或者是否允许将某个 modpack 的文件整合进其他 modpack。
许可证由每个 modpack 的创作者自行选择。虽然引擎本身采用 GPLv3+ 许可证,但 modpack 的许可证不必与其兼容。仓库(repo)可以决定接受或拒绝哪些许可证,也可以提供默认许可证。
当你复制(copy,而非引用 reference)其他创作者 modpack 中的资产时,务必先检查其许可证——复制文件可能受许可证条款约束。通常来说,将 modpack 作为依赖引用比直接复制文件更安全,也更受认可。
寻址 Modpack(Addressing Modpacks)
本节描述 modpack 的命名与引用标准,以及为此目的的管理要求。
命名约定(Naming Conventions)
Modpack 和仓库的名称只能包含以下字符:
- 拉丁字母(
a-z、A-Z) - 数字(
0-9) - 分隔符(
-、_、.)
建议名称至少 4 个字符(非强制)。仓库可能对 modpack 名称执行更严格的规则,例如词过滤器或前缀。
部分仓库名称被保留,不能使用:
openage:保留给引擎开发者使用,以及 converter 创建的 modpack;local:用于未从仓库安装的 modpack 的内部仓库名。
别名与标识符(Alias and Identifier)
引用 modpack 有两种方式:使用 modpack 标识符(identifier)或使用别名(alias)。官方建议尽可能使用别名,只在绝对必要时使用标识符。
modpack 标识符是由 modpack 名称和仓库名称以 @ 连接而成的唯一字符串:
modname@reponame
未从仓库安装的 mod 使用 local 作为仓库名:
modname@local
别名是在内部快速引用 modpack 的字符串。默认情况下,别名就是 modpack 的名称,但也可以在 modpack 定义文件中指定。别名在加载时必须是唯一的。
modname
别名可以用于替换其他 modpack。例如,某个增强图形包可以通过给自己分配与普通图形包相同的别名,来替换该普通图形包。此后,使用该别名的引用都会指向增强图形包。
版本固定(Version Pinning)
有时由于兼容性问题,可能需要特定版本的 modpack。可以通过在 modpack 标识符后追加版本号、并用 :: 分隔来实现:
modname@reponame::version
跨 modpack 的资源引用
当 modpack 内部的文件需要引用其他 modpack 中的资源时,必须使用以 {modpack_id} 或 {alias} 开头的绝对路径形式。文件引用规范详见 doc/media/openage/file_referencing.md:
"/{aoe2_base@openage}/idle.png" # 使用 modpack 标识符的绝对路径
"/{aoe2_base}/idle.png" # 使用 modpack 别名的绝对路径
相对路径则相对于引用文件所在位置,且只能引用同一 modpack 内的资源:
"idle.png" # 与引用文件同目录下的 idle.png
"./idle.png" # 同上,更显式
"media/attack.png" # 位于 media 子目录下的 attack.png
引擎中的加载流程(源码视角)
理解 modpack 的运行时行为,可以看引擎的 ModManager,定义于 libopenage/assets/mod_manager.h:
register_modpack():将一个 modpack(通过定义文件路径或ModpackInfo)注册到可用列表available;activate_modpacks(load_order):按给定加载顺序"就绪"一组 modpack,包括校验数据完整性、检查加载顺序、将资产挂载到虚拟文件系统(当前实现中挂载与 manifest 校验标记为 TODO,见 mod_manager.h);enumerate_modpacks():静态方法,遍历一个目录,对每个子目录检查是否存在modpack.toml,有则解析并记录其 id(见 mod_manager.h),这正是 launcher 启动时扫描已安装 modpack 的机制。
在 Python 侧,openage/convert/service/init/modpack_search.py 的 enumerate_modpacks() 与 get_modpack_info() 负责在转换/启动流程中扫描 modpack 目录、解析 modpack.toml(可抛出 FileNotFoundError、TypeError、toml.TomlDecodeError 三类异常);query_modpack() 则在未发现 modpack 时以交互方式让用户选择。这与 doc/running.md 描述的行为一致:game 模式启动时若找不到已转换的 modpack,会先询问用户是否进行转换。
结语
Modpack 是 openage 资源管道的核心抽象,贯通转换(converter 生成)、分发(standalone / repository)与加载(ModManager 挂载)全流程。掌握 modpack.toml 的定义规范、命名与寻址规则、依赖/冲突/替换机制,是开发 openage 内容的第一步。进一步阅读可参考: