RetroArch核心元数据编辑：自定义名称与描述全攻略

引言：为什么需要自定义核心元数据？

在RetroArch（跨平台的libretro API前端）使用过程中，用户经常会遇到核心名称不直观、描述信息不清晰的问题。例如默认的"nes_libretro"核心名称既不显示完整平台名称，也无法区分不同版本。通过编辑核心元数据，玩家可以实现：

• 个性化分类：将"Genesis Plus GX"重命名为"Sega Genesis 增强版"
• 多版本管理：为同一核心的不同分支添加版本标识（如"MAME 2003-Plus"）
• 清晰化描述：补充核心特性说明（如"支持光枪游戏/强制4:3比例"）

本文将系统讲解RetroArch核心元数据的存储结构、编辑方法和高级技巧，帮助玩家打造专属的模拟器核心库。

核心元数据系统架构

元数据存储双轨制

RetroArch采用"编译时定义+运行时加载"的双层元数据管理机制：

flowchart TD
    A[源代码层] -->|编译生成| B[可执行程序]
    C[.info文件层] -->|运行时读取| B
    B --> D[核心信息展示]
    E[用户编辑] -->|覆盖| C

• 静态定义：核心基础信息在core_info.c中通过struct retro_core_info结构体定义
• 动态配置：用户可编辑的元数据存储在.info文件中，优先级高于静态定义

关键技术文件解析

通过代码分析，RetroArch处理核心信息的关键组件包括：

文件路径	功能描述	关键函数
core_info.c	核心元数据管理中心	core_info_init() core_info_get_display_name()
core_info.h	元数据结构定义	struct retro_core_info struct core_info
core_updater_list.c	核心更新元数据处理	core_updater_list_parse()

核心元数据加载流程：

sequenceDiagram
    participant RA as RetroArch主程序
    participant CI as core_info模块
    participant FS as 文件系统
    RA->>CI: 初始化核心信息系统
    CI->>FS: 扫描系统目录下的.info文件
    FS-->>CI: 返回info文件列表
    CI->>CI: 解析文件内容到core_info结构体
    CI-->>RA: 提供格式化的核心信息

.info文件格式详解

文件定位与命名规则

RetroArch核心元数据文件采用.info扩展名，遵循以下存储逻辑：

1. 内置核心：随程序安装的核心通常位于
   system/info/ 或 ~/.config/retroarch/cores/ 目录
2. 用户安装核心：通过在线 updater 安装的核心位于
   ~/.config/retroarch/downloads/cores/ 目录
3. 命名规范：采用[核心文件名]_libretro.info格式，如
   snes9x_libretro.info 对应 SNES 模拟器核心

完整字段说明

.info文件采用INI-like格式，包含以下关键字段（带*为必须字段）：

字段名	数据类型	描述	示例
display_name*	字符串	核心显示名称	Snes9x - Super Nintendo Emulator
author*	字符串	开发者/维护者信息	byuu, Near, Snes9x Team
description	字符串	功能描述文本	Highly compatible SNES emulator with advanced features
core_name*	字符串	内部核心标识	snes9x
supported_extensions*	列表	支持的文件扩展名	.smc .sfc .fig .swc .mgd
license*	字符串	开源协议类型	GPLv2
hardware_level	整数	硬件需求等级	3
require_fullpath	布尔值	是否需要完整路径	false
categories	列表	分类标签	Emulator, Super Nintendo

标准.info文件示例

display_name = "Nestopia UE"
author = "Martin Freij, R. Belmont, et al."
description = "Highly accurate Nintendo Entertainment System emulator with enhanced features"
core_name = "nestopia_ue"
supported_extensions = ".nes .fds .unf .unif .nez .zip .7z"
license = "GPLv2"
permissions = ""
display_version = "1.52.0"
categories = "Emulator, Nintendo Entertainment System"
systemname = "Nintendo Entertainment System"
database = "Nintendo - Nintendo Entertainment System"
manufacturer = "Nintendo"
year = "1983"
hardware_level = "4"
libraryname = "Nestopia UE"
supports_no_game = "false"
require_fullpath = "false"

实战：手动编辑元数据文件

基础编辑流程

以下是自定义核心名称和描述的标准步骤：

1. 定位目标文件
   通过RetroArch的"核心信息"界面查看核心路径，或直接在文件管理器中搜索：

   # Linux/macOS系统
   find ~/.config/retroarch -name "*.info" | grep "目标核心关键词"
   
   # Windows系统
   dir %APPDATA%\RetroArch\cores\*.info /s /b | findstr "目标核心关键词"
   

2. 备份原始文件
   编辑前创建备份，防止意外错误：

   cp snes9x_libretro.info snes9x_libretro.info.bak
   

3. 修改关键字段
   使用文本编辑器打开.info文件，修改以下字段：

   ; 修改前
   display_name = "Snes9x"
   description = "Super Nintendo emulator"
   
   ; 修改后
   display_name = "Snes9x 2024 Enhanced"
   description = "Super Nintendo emulator with HD texture support and netplay"
   

4. 验证修改效果
   重启RetroArch，在"加载核心"菜单中确认新名称已生效。若未更新，尝试：

   • 清除缓存：设置 > 界面 > 清除菜单缓存
   • 手动刷新：工具 > 刷新核心信息

高级自定义技巧

添加版本标识

为区分同一核心的不同编译版本，可在名称中加入标识：

display_name = "MAME 2003 (Performance Build)"
description = "Arcade emulator optimized for low-end hardware (2003-Plus fork)"

多语言支持方案

虽然RetroArch原生不支持多语言元数据，但可通过文件名区分：

mame_libretro_zh.info  ; 中文版本
mame_libretro_en.info  ; 英文版本

切换时只需重命名对应文件为mame_libretro.info

批量编辑工具

对于管理大量核心的用户，可使用Python脚本批量修改：

import os
import configparser

INFO_DIR = "~/.config/retroarch/cores/"

for filename in os.listdir(INFO_DIR):
    if filename.endswith(".info"):
        config = configparser.ConfigParser()
        config.read(os.path.join(INFO_DIR, filename))
        
        # 为所有MAME核心添加版本标识
        if "mame" in filename.lower() and not config.get("default", "display_name").endswith("(2024)"):
            new_name = f"{config.get('default', 'display_name')} (2024)"
            config.set("default", "display_name", new_name)
            
            with open(os.path.join(INFO_DIR, filename), 'w') as f:
                config.write(f)

编译时元数据定制

对于高级用户，可通过修改源代码实现更深度的元数据定制。

修改静态定义

在core_info.c中找到目标核心的struct retro_core_info定义：

// 修改前
const struct retro_core_info nestopia_core_info = {
    .display_name = "Nestopia",
    .author       = "Martin Freij",
    .categories   = "Emulator",
    // ...其他字段
};

// 修改后
const struct retro_core_info nestopia_core_info = {
    .display_name = "Nestopia UE Enhanced",
    .author       = "Martin Freij, RetroArch Community",
    .categories   = "Emulator, NES, Famicom",
    .description  = "Accurate NES emulator with advanced features",
    // ...其他字段
};

重新编译核心

修改后使用项目根目录的构建脚本重新编译：

# 清理旧构建
make clean

# 针对特定平台编译
make -f Makefile.libnx  # Switch平台
make -f Makefile.win    # Windows平台
make -f Makefile.apple  # macOS平台

常见问题解决

修改不生效

若编辑后核心名称未更新，按以下流程排查：

stateDiagram
    [*] --> 检查文件路径
    检查文件路径 -->|错误| 重新定位正确.info文件
    检查文件路径 -->|正确| 验证文件权限
    验证文件权限 -->|无写入权限| 使用管理员权限编辑
    验证文件权限 -->|有权限| 检查语法格式
    检查语法格式 -->|格式错误| 修复INI语法问题
    检查语法格式 -->|格式正确| 清除RetroArch缓存
    清除RetroArch缓存 --> 重启RetroArch
    重启RetroArch --> [*]

字段值限制

.info文件各字段有隐性限制，需注意：

• display_name：建议不超过40字符，过长会导致菜单显示截断
• description：单行文本，不支持换行符
• supported_extensions：最多支持20个扩展名，总长度不超过256字符

版本更新覆盖

通过在线更新核心会覆盖自定义元数据，解决方案：

1. 禁用自动更新：在设置 > 在线更新中关闭"自动更新核心"
2. 使用只读属性：设置.info文件为只读（Windows示例）：

   attrib +r %APPDATA%\RetroArch\cores\snes9x_libretro.info
   

3. 创建元数据模板：将自定义配置保存为.info.template，更新后手动恢复

总结与扩展应用

通过本文介绍的方法，用户已掌握核心元数据的编辑技巧。这些知识可进一步扩展到：

• 主题定制：配合自定义名称设计主题图标
• 前端集成：导出元数据用于第三方启动器
• 批量管理：开发脚本实现元数据自动化维护

建议定期备份自定义的.info文件，以便在RetroArch升级后快速恢复个性化配置。未来RetroArch可能会推出官方元数据编辑工具，但目前手动编辑仍是最直接有效的方案。

希望本文能帮助您打造更个性化的复古游戏体验！如有其他问题，欢迎在社区讨论区交流。