EmulationStation gamelist.xml 从零开始完全指南

2026-03-30 11:21:51作者：郜逊炳

一、概念解析：认识游戏列表文件

在EmulationStation这个灵活的模拟器前端中，gamelist.xml扮演着"游戏档案管理员"的角色。它是一个XML格式的配置文件，负责存储每个游戏系统的元数据信息，让你的游戏库不仅能被机器识别，还能以美观的方式呈现给玩家。

新手提示：元数据就像是游戏的"身份证"，包含了从基本信息到详细描述的各类数据，是实现精美游戏展示的基础。

1.1 核心功能与价值

gamelist.xml的主要作用包括：

提供游戏的基本信息展示（名称、封面、描述等）
支持高级筛选和排序功能
记录游戏的游玩统计数据
实现个性化的游戏库组织方式

没有gamelist.xml，EmulationStation只能显示简单的文件名列表；有了它，你才能拥有带封面、描述和各种分类信息的精美游戏界面。

1.2 文件存储位置与加载优先级

EmulationStation采用"就近原则"查找gamelist.xml文件，优先级从高到低依次为：

系统ROM目录：{ROM路径}/gamelist.xml
（与游戏ROM文件存放在同一目录，便于随ROM一起备份）
用户配置目录：~/.emulationstation/gamelists/{系统名称}/gamelist.xml
（用户个人定制的配置，不会影响其他用户）
系统全局目录：/etc/emulationstation/gamelists/{系统名称}/gamelist.xml
（系统级配置，适用于多用户共享的场景）

新手提示：建议将gamelist.xml保存在ROM目录中，这样在迁移或备份ROM时能自动包含元数据配置。

知识点总结

gamelist.xml是存储游戏元数据的核心配置文件
支持多位置存储，优先级从高到低为：ROM目录 > 用户目录 > 系统目录
元数据决定了游戏在界面中的展示方式和可用信息

二、实践指南：gamelist.xml配置详解

2.1 XML文件基本结构

gamelist.xml采用标准XML格式，以<gameList>作为根标签，包含多个<game>或<folder>子元素。每个游戏或文件夹的元数据都封装在对应的标签中。

基础结构示例：

<gameList>
    <!-- 单个游戏条目 -->
    <game>
        <path>{ROM路径}/chrono_trigger.sfc</path>  <!-- 游戏ROM文件路径 -->
        <name>时空之轮</name>  <!-- 显示名称 -->
        <desc>史克威尔1995年发行的经典RPG游戏，被誉为史上最伟大的游戏之一。</desc>  <!-- 详细描述 -->
        <image>{图片路径}/chrono_trigger.png</image>  <!-- 封面图片路径 -->
        <releasedate>19950311T000000</releasedate>  <!-- 发行日期（ISO格式） -->
        <developer>Square</developer>  <!-- 开发商 -->
        <publisher>Square</publisher>  <!-- 发行商 -->
        <genre>角色扮演</genre>  <!-- 游戏类型 -->
        <players>1</players>  <!-- 支持玩家数量 -->
    </game>
    
    <!-- 可以有多个游戏条目 -->
    <game>
        <!-- ... -->
    </game>
    
    <!-- 文件夹条目 -->
    <folder>
        <!-- ... -->
    </folder>
</gameList>

2.2 元数据标签说明

游戏(`<game>`)标签属性

标签名	数据类型	说明	示例值
`name`	字符串	游戏显示名称（必填）	`时空之轮`
`desc`	字符串	游戏详细描述	`经典RPG游戏，时间旅行题材`
`image`	图片路径	游戏封面/截图路径	`./images/chrono_trigger.png`
`thumbnail`	图片路径	缩略图路径（当前版本未使用）	`./thumbs/chrono_trigger.png`
`rating`	浮点数	游戏评分（0-1之间）	`0.95`
`releasedate`	日期时间	ISO格式日期时间	`19950311T000000`
`developer`	字符串	开发商名称	`Square`
`publisher`	字符串	发行商名称	`Square`
`genre`	字符串	游戏类型	`角色扮演`
`players`	整数	支持玩家数量	`1-2`
`playcount`	整数	游玩次数（自动记录）	`15`
`lastplayed`	日期时间	最后游玩时间（自动记录）	`20231025T193000`

文件夹(`<folder>`)标签属性

标签名	数据类型	说明	示例值
`name`	字符串	文件夹显示名称	`角色扮演游戏`
`desc`	字符串	文件夹描述	`包含各类经典RPG游戏`
`image`	图片路径	文件夹图标路径	`./folder_images/rpg.png`
`thumbnail`	图片路径	文件夹缩略图路径（当前版本未使用）	`./folder_thumbs/rpg.png`

新手提示：所有路径支持三种格式：绝对路径（如/home/user/ROMs/images/xxx.png）、相对路径（如./images/xxx.png，相对于ROM目录）和用户主目录路径（如~/images/xxx.png）。

2.3 元数据类型详解

gamelist.xml支持多种数据类型，了解它们的格式要求有助于正确配置：

字符串(string)：普通文本内容，直接填写
```
<developer>Square Enix</developer>
```

图片路径(image_path)：支持三种格式

<!-- 绝对路径 -->
<image>/home/user/ROMs/snes/images/chrono_trigger.png</image>

<!-- 相对路径（相对于ROM目录） -->
<image>./images/chrono_trigger.png</image>

<!-- 相对用户主目录路径 -->
<image>~/emulation/images/chrono_trigger.png</image>

⚠️ 重要注意事项：图片会被自动缩放以适应主题，建议使用适当分辨率（建议800×600左右）以平衡显示效果和加载速度。

浮点数(float)：以字符串形式表示的浮点数值，范围0-1
```
<rating>0.95</rating>  
```
整数(integer)：以字符串形式表示的整数值
```
<players>2</players>  
```
日期时间(datetime)：ISO格式日期时间字符串，格式为%Y%m%dT%H%M%S
```
<releasedate>19950311T000000</releasedate>  
```

知识点总结

gamelist.xml以<gameList>为根标签，包含<game>和<folder>子元素
游戏标签支持名称、描述、图片、评分等多种元数据
路径可以是绝对路径、相对路径或用户主目录路径
不同数据类型有特定的格式要求，需严格遵循

三、进阶技巧：优化与管理gamelist.xml

3.1 实用配置技巧

🔧 路径处理最佳实践

使用相对路径可以使你的配置更具可移植性，当移动ROM文件夹时无需修改路径
EmulationStation会自动尝试将绝对路径转换为相对路径，便于配置迁移

📌 字符编码注意事项

⚠️ 重要注意事项：当前版本不支持Unicode字符，建议使用ASCII字符集，避免中文等特殊字符显示异常

🔧 默认值优化策略

对于等于默认值的属性（如players=1），系统不会写入XML文件以减少冗余
仅在需要修改默认值时才添加相应标签

3.2 命令行参数应用

EmulationStation提供了与gamelist相关的命令行参数，可根据需要灵活使用：

--gamelist-only：仅显示gamelist.xml中定义的游戏，忽略未配置的ROM文件
```
./emulationstation --gamelist-only
```
--ignore-gamelist：完全忽略gamelist.xml文件，仅显示原始ROM文件列表
```
./emulationstation --ignore-gamelist
```

新手提示：这些参数可用于测试配置或临时查看不同显示效果，不影响实际配置文件。

3.3 批量管理与高级应用

对于拥有大量游戏的玩家，手动编辑gamelist.xml效率低下，可采用以下方法：

使用内置刮削工具 EmulationStation提供了内置的游戏元数据刮削功能，可以自动从在线数据库获取游戏信息。通过UI界面的"刮削游戏"选项即可使用。
开发自定义刮削器 对于特殊需求，可以参考项目中es-app/src/scrapers/目录下的刮削器实现（如GamesDBScraper.cpp和TheArchiveScraper.cpp），开发自定义刮削器。
批量编辑工具 可使用XML编辑器或专用工具如"Skraper"等批量处理游戏元数据，支持正则表达式替换、批量导入导出等功能。
版本控制管理 将gamelist.xml纳入版本控制（如Git），可以跟踪元数据的变更历史，方便回滚和协作。
自动化生成脚本 编写简单的脚本（如Python或Shell脚本）从文件名或其他元数据来源自动生成gamelist.xml，特别适合有规律命名的ROM集合。

3.4 原创优化建议

🔧 元数据备份策略 创建定期备份gamelist.xml的脚本，避免因意外丢失精心维护的游戏元数据。可以使用简单的cron任务实现自动备份：

# 示例：每天凌晨3点备份gamelist.xml到备份目录
0 3 * * * cp {ROM路径}/gamelist.xml {备份路径}/gamelist_$(date +%Y%m%d).xml

📌 分级目录结构 对于大型游戏库，使用<folder>标签创建分级目录结构，配合自定义图片，可以打造更具组织性的游戏库：

<folder>
    <name>角色扮演</name>
    <image>./folder_icons/rpg.png</image>
    <game>
        <!-- RPG游戏1 -->
    </game>
    <game>
        <!-- RPG游戏2 -->
    </game>
</folder>