1. 项目缘起为什么我们需要一个元数据生成脚本如果你是一个游戏收藏爱好者或者像我一样喜欢在PC上搭建一个属于自己的复古游戏库那你一定对Pegasus Frontend天马前端不陌生。这是一个高度可定制、界面炫酷的游戏前端启动器尤其深受RetroArch等模拟器用户的喜爱。它的强大之处在于能够将散落在硬盘各处的游戏ROM整理成一个带有精美封面、简介和视频预览的现代化游戏库。而这一切华丽展示的基础就是一个看似不起眼的文本文件metadata.pegasus.txt。这个文件就是Pegasus前端的“游戏库目录”里面以特定格式记录了每个游戏的标题、文件路径、发行年份、开发商、简介、以及最重要的——各种媒体文件如封面图、截图、视频的链接。手动维护这个文件那简直是噩梦。想象一下你新添加了100个SFC游戏意味着你要打开文本编辑器对照着ROM文件名逐行敲入100条包含十多个字段的记录还要确保图片、视频的路径完全正确。任何一点格式错误比如少了个冒号、路径用了反斜杠都会导致游戏在前端里“隐形”或者变成“光头”游戏。所以一个能自动扫描ROM文件夹、并批量生成标准格式metadata.pegasus.txt的脚本就成了刚需。网上虽然有一些现成的工具但要么配置复杂要么不够灵活无法完美匹配我的个人收藏习惯和文件夹结构。于是自己动手写一个批处理.bat脚本就成了最直接、最可控的解决方案。这个脚本的核心目标很简单我指定一个装满ROM的文件夹它就能自动为我生成一个“开箱即用”的元数据文件让我能立刻在Pegasus里看到整齐、带封面的游戏列表。2. 脚本核心设计思路与方案选型2.1 为什么选择批处理BAT脚本在Windows环境下实现自动化脚本有多种选择PowerShell功能更强大Python更灵活但最终我选择了最传统的批处理脚本。原因有三点零依赖、即时可用和透明可控。批处理脚本是Windows原生支持的不需要安装任何额外的解释器或运行环境双击即可运行对任何Windows用户都极其友好。其次它的语法虽然简单但处理文件遍历、文本拼接这类任务绰绰有余。最重要的是整个脚本是纯文本的每一行命令都清晰可见我可以完全掌控它做了什么如何匹配我的文件修改起来也毫无门槛。对于这样一个专注于本地文件处理、逻辑相对固定的任务批处理脚本的轻量化和直接性优势明显。2.2 元数据文件格式深度解析在动手之前必须吃透Pegasus的元数据文件格式。它采用的是类似INI的键值对结构但有自己的规则。一个完整的游戏条目Entry看起来是这样的game: 游戏显示标题 file: ROM文件的完整路径 developer: 游戏开发商 publisher: 游戏发行商 genre: 游戏类型 description: 一段详细的游戏介绍 release: 游戏发行日期 players: 支持玩家数量 rating: 评分 assets.boxfront: 封面图路径 assets.screenshot: 游戏截图路径 assets.video: 预览视频路径关键规则1文件头。文件通常以一行import common.metadata.txt开头用于导入共享的通用设置如默认图片路径但我们的生成脚本可以暂时忽略这个专注于生成核心的游戏列表部分。关键规则2条目分隔。每个游戏条目之间必须用一个空行进行分隔。这是格式正确与否的关键空行告诉Pegasus“上一个游戏的信息结束了下一个开始了。”关键规则3路径格式。file和assets相关的路径必须使用正斜杠/并且最好是相对于Pegasus前端配置文件settings.txt中game_dirs项所设置根目录的相对路径。如果是绝对路径则需要使用file:///协议头例如file:///C:/Games/ROMs/super_mario.nes。为了通用性和可移植性我们的脚本将采用相对路径方案。关键规则4标题处理。game字段是显示在前端的名称。ROM文件名通常是像Super Mario Bros. (U) [!].nes这样的包含地区、版本号等信息。直接使用这个作为标题很不美观。因此脚本需要包含一个“清理”逻辑去除括号内的内容、文件扩展名等得到干净的游戏名。2.3 脚本的宏观工作流程设计基于以上分析脚本需要完成一个清晰的管道化操作输入用户指定ROM所在的根目录例如D:\RetroGames\NES。扫描递归遍历该目录及其所有子目录找出所有目标扩展名的ROM文件如 .nes, .smc, .bin等。解析对每个ROM文件名进行“美化”处理生成干净的game标题。构造为每个游戏构造一个完整的元数据条目块包含game、file、以及预定义的assets路径模板。输出将所有条目块用空行连接写入到一个新的metadata.pegasus.txt文件中。其中最核心的挑战在于第3步文件名美化和第4步路径构造的灵活性与准确性。3. 核心细节解析与实操要点3.1 文件名美化从“脏名字”到“净标题”ROM收藏界的文件名有一套“潜规则”例如The Legend of Zelda, The - A Link to the Past (U) (V1.0) [!].smc这个文件名包含了核心标题The Legend of Zelda, The - A Link to the Past地区码(U)代表美版版本号(V1.0)校验标记[!]代表GoodDump完整正确的ROM文件扩展名.smc我们的目标是将它简化为The Legend of Zelda, The - A Link to the Past批处理脚本处理字符串能力有限但我们可以利用一些技巧。主要思路是层层剥离去除扩展名使用%~nI变量扩展可以直接获取文件名不含扩展名。去除括号及其中内容这是最复杂的一步。批处理没有内置的正则表达式替换但可以用for循环和字符替换的笨办法或者借助一个外部小工具sed。为了保持零依赖我选择了一个折中的批处理方案多次使用变量替换操作。set “clean_name!filename!” rem 循环替换掉所有 (*) 格式的内容包括括号本身 :clean_loop for /f “tokens1* delims()” %%a in (“%clean_name%”) do set “clean_name%%a%%b” if not “!clean_name:*(!”“!clean_name!” goto clean_loop这个循环会不断尝试移除第一个遇到的(和)及其之间的内容直到字符串中不再包含(为止。虽然对于嵌套括号处理不佳但对于绝大多数ROM文件名格式已经足够。 3.去除方括号及其中内容同样的逻辑处理[...]。 4.修剪首尾空格使用set “clean_name!clean_name: !”进行简单处理更复杂的修剪需要额外技巧。实操心得文件名美化规则不可能100%完美。有些ROM的命名不规范或者包含特殊符号。我的经验是先实现一个覆盖80%情况的规则生成文件后用文本编辑器的“查找和替换”功能手动修正剩下的20%异常标题这比在脚本中编写极其复杂的异常处理逻辑要高效得多。3.2 媒体文件路径的智能匹配Pegasus前端允许为不同类型的媒体指定路径。通常我们会将封面图boxfront、截图screenshot、标题屏title screen等分类放在不同的文件夹里并以游戏名或ROM文件名来命名这些图片。脚本需要为每个游戏生成类似下面的资产行assets.boxfront: ./media/nes/boxart/Super Mario Bros.png assets.screenshot: ./media/nes/screenshot/Super Mario Bros.png这里的关键在于路径模板。我们不可能让脚本去猜测你的图片命名习惯因此最好的办法是让脚本遵循一个约定。在脚本中我会定义几个基础路径变量set “COVER_PATH./media/%%GAME_PLATFORM%%/boxart/%%GAME_TITLE%%.png” set “SCREENSHOT_PATH./media/%%GAME_PLATFORM%%/screenshot/%%GAME_TITLE%%.png”%%GAME_PLATFORM%%和%%GAME_TITLE%%是占位符。当脚本处理一个位于D:\RetroGames\NES\下的ROM时它会将NES作为平台名将美化后的游戏标题作为标题替换掉占位符从而生成具体的路径。注意事项媒体文件的扩展名不一定是.png也可能是.jpg。更健壮的脚本可以预先检查文件是否存在。但作为生成脚本它的首要任务是创建“正确格式”的元数据文件。至于媒体文件是否真的存在可以由后续的Pegasus前端扫描来报告缺失或者由用户自行补充。脚本的职责是建立正确的“预期”和“链接”。3.3 递归遍历与文件过滤批处理中for /r命令是递归遍历目录树的神器。for /r “ROM_ROOT” %%i in (*.nes *.smc *.bin *.gen) do ( … )这行命令会遍历ROM_ROOT目录下所有后缀为.nes,.smc,.bin,.gen的文件。这里有一个重要细节%%~fi会得到文件的绝对路径如D:\RetroGames\NES\Super Mario Bros.nes而我们需要的是相对于Pegasus游戏目录的相对路径。假设Pegasus的game_dirs设置为D:/RetroGames那么我们需要将绝对路径转换为像./NES/Super Mario Bros.nes这样的形式。这可以通过字符串替换实现set “relative_path!full_path:%ROM_ROOT%.!” set “relative_path!relative_path:\/!”第一行将绝对路径中的根目录部分替换为.当前目录第二行将所有反斜杠\替换为正斜杠/符合Pegasus的要求。4. 实操过程与核心环节实现下面我将拆解脚本的关键部分并附上详细的注释。假设我们的ROM库根目录是D:\MyGames里面按平台分了子文件夹如NESSNESGBA等。4.1 脚本框架与用户输入echo off setlocal enabledelayedexpansion chcp 65001 nul rem 启用延迟变量扩展并设置代码页为UTF-8防止中文乱码 rem 设置ROM文件的根目录 set “ROM_ROOTD:\MyGames” rem 设置输出的元数据文件路径 set “META_FILEmetadata.pegasus.txt” rem 清空或创建新的元数据文件 echo. “%META_FILE%” rem 注意这里没有写入 import 行可根据需要添加4.2 核心循环遍历、处理、写入这是脚本的心脏部分。我们遍历所有子目录中的常见ROM文件。for /r “%ROM_ROOT%” %%i in (*.nes *.smc *.sfc *.gba *.gb *.gbc *.md *.gen *.bin *.cue) do ( rem 获取文件完整路径、文件名、扩展名、所在目录 set “full_path%%~fi” set “file_name%%~ni” set “file_ext%%~xi” set “file_dir%%~dpi” rem —————— 1. 生成美化后的游戏标题 —————— set “clean_title!file_name!” rem 调用一个子过程来清理标题 call :clean_filename “!clean_title!” clean_title rem 此时 !clean_title! 应为清理后的结果 rem —————— 2. 计算相对路径关键步骤 —————— rem 将完整路径中的ROM根目录替换为“.” set “relative_path!full_path:%ROM_ROOT%.!” rem 将Windows路径分隔符\替换为Pegasus要求的/ set “relative_path!relative_path:\/!” rem —————— 3. 推断游戏平台用于媒体路径 —————— rem 获取文件相对于ROM_ROOT的父文件夹名通常就是平台名 set “platform_path!file_dir:%ROM_ROOT%!” for %%f in (“!platform_path!\.”) do set “platform_name%%~nxf” rem 处理可能的多级子目录这里简单取第一级目录 for /f “tokens1 delims\” %%p in (“!platform_name!”) do set “platform%%p” rem —————— 4. 构造媒体文件路径模板 —————— rem 这里使用一个简单的模板假设媒体文件与ROM同名放在特定目录下 set “cover_path./media/!platform!/boxart/!clean_title!.png” set “screenshot_path./media/!platform!/screenshot/!clean_title!.png” rem —————— 5. 将游戏条目写入文件 —————— ( echo game: !clean_title! echo file: !relative_path! echo developer: Unknown echo publisher: Unknown echo genre: Unknown echo description: Placeholder description for !clean_title!. echo release: 1900-01-01 echo players: 1 echo rating: 0.0 echo assets.boxfront: !cover_path! echo assets.screenshot: !screenshot_path! echo. ) “%META_FILE%” )4.3 文件名清理子过程:clean_filename子过程负责处理复杂的字符串清理。:clean_filename setlocal set “str%~1” rem 移除扩展名如果传入的是带扩展名的文件名但主循环已处理 rem 循环移除 () 及其内部内容 :loop_para for /f “tokens1,2 delims()” %%a in (“%str%”) do ( if not “%%b”“” set “str%%a%%b” ) if not “%str:(%”“%str%” goto loop_para rem 循环移除 [] 及其内部内容 :loop_bracket for /f “tokens1,2 delims[]” %%a in (“%str%”) do ( if not “%%b”“” set “str%%a%%b” ) if not “%str:[%”“%str%” goto loop_bracket rem 移除常见的版本标识符如 Rev A, v1.1等需根据实际情况调整 set “str%str: Rev A% set “str%str: v1.% set “str%str: (V1.0)% rem 可以继续添加其他需要移除的特定字符或词组 rem 修剪首尾空格简单的 for /f “tokens*” %%i in (“%str%”) do set “str%%i” for /f “delims” %%i in (“%str%”) do set “str%%i” endlocal set “%~2%str%” goto :eof4.4 脚本执行与输出将以上所有代码块保存为一个.bat文件例如generate_pegasus_meta.bat双击运行。脚本会安静地遍历D:\MyGames目录并在同一目录下生成metadata.pegasus.txt文件。打开生成的文件你会看到类似如下的内容game: Super Mario Bros file: ./NES/Super Mario Bros.nes developer: Unknown publisher: Unknown genre: Unknown description: Placeholder description for Super Mario Bros. release: 1900-01-01 players: 1 rating: 0.0 assets.boxfront: ./media/NES/boxart/Super Mario Bros.png assets.screenshot: ./media/NES/screenshot/Super Mario Bros.png game: The Legend of Zelda A Link to the Past file: ./SNES/The Legend of Zelda A Link to the Past.smc developer: Unknown publisher: Unknown genre: Unknown description: Placeholder description for The Legend of Zelda A Link to the Past. release: 1900-01-01 players: 1 rating: 0.0 assets.boxfront: ./media/SNES/boxart/The Legend of Zelda A Link to the Past.png assets.screenshot: ./media/SNES/screenshot/The Legend of Zelda A Link to the Past.png5. 常见问题与排查技巧实录即使有了脚本在实际整合到Pegasus前端时你仍可能会遇到一些问题。下面是我在多次使用和调试中积累的排查经验。5.1 游戏在前端中不显示这是最常见的问题根本原因通常是file:路径不正确。检查1相对路径的基准。确认你的metadata.pegasus.txt文件放置的位置以及Pegasus的settings.txt中game_dirs是如何设置的。game_dirs应该指向你的ROM根目录本例中是D:/MyGames。脚本生成的file: ./NES/...是基于这个根目录的相对路径。如果game_dirs设置的是D:/MyGames/NES那么路径就匹配不上了。检查2路径分隔符。确保脚本生成的路径使用的是正斜杠/而不是反斜杠\。Pegasus在Windows上也要求使用/。检查3文件实际存在。手动复制file:后面的路径在文件资源管理器中拼接并检查ROM文件是否确实存在。5.2 游戏封面等媒体不显示媒体不显示但游戏列表有这说明元数据文件被正确读取了但资产路径有问题。检查1媒体文件命名。脚本生成的assets.boxfront: ./media/NES/boxart/Super Mario Bros.png是一个预期路径。你需要检查在D:\MyGames\media\NES\boxart\目录下是否存在名为Super Mario Bros.png的图片文件。文件名必须完全匹配包括大小写在Windows上通常不区分但最好一致和扩展名。检查2目录结构。确认你的媒体文件夹结构是否和脚本中定义的模板一致./media/[平台名]/[资产类型]/。如果不一致需要修改脚本中的路径模板变量。技巧使用占位图。在初期可以不用准备所有封面。Pegasus允许在common.metadata.txt中设置缺失媒体的默认图片。你可以先让脚本生成然后运行Pegasus它会列出所有缺失的媒体文件你再根据列表去逐一搜集这样目标更明确。5.3 游戏标题显示异常有残留括号或版本号这说明文件名清理子过程:clean_filename没有完全处理你的ROM命名风格。排查方法在脚本中在处理每个文件后添加一行调试输出将清理前和清理后的文件名都打印出来。echo Original: !file_name! Cleaned: !clean_title! debug_log.txt运行脚本后查看debug_log.txt找到那些清理不干净的文件名样本。针对性增强分析这些样本的规律。例如发现还有(J)或(Europe)没被移除可能是因为你的清理循环只处理了英文括号()而有些ROM用的是全角括号或其它字符。在:clean_filename过程中添加对应的替换规则即可例如set “str%str:(J)%”。5.4 脚本运行缓慢或卡住如果ROM库非常大数万个文件批处理脚本可能会运行较长时间。优化建议1减少遍历范围。如果平台目录是分开的可以分别对每个平台运行脚本而不是一次性扫描整个根目录。修改ROM_ROOT为D:\MyGames\NES即可。优化建议2精简文件匹配模式。for /r … in (*.nes *.smc … )中的匹配模式越多遍历时比较开销越大。只包含你确实拥有的ROM格式。根本解决对于超大规模库批处理可能不是最佳选择。可以考虑将核心逻辑用Python重写速度会有数量级的提升。但批处理脚本的轻便优势依然存在适合中小型库的快速搭建和维护。5.5 元数据信息过于模板化脚本为所有游戏填充了Unknown和Placeholder description。要获得真实的开发商、发行年份、描述等信息需要接入外部数据库。进阶方向这是脚本可以进化的地方。你可以让脚本在生成条目时调用一个外部工具或API。例如结合Skraper这样的命令行工具先让Skraper根据ROM文件去在线数据库如ScreenScraper.fr拉取元数据和媒体文件并生成一个初始的metadata.pegasus.txt。然后你的批处理脚本可以在这个文件的基础上进行格式微调和批量修改发挥“后期处理”的作用将自动抓取和个性化定制结合起来这才是最高效的工作流。