Emerald 3DS 是《宝可梦 红宝石/绿宝石》系列的任天堂 3DS 原生移植版，支持双屏操作与体感 3D 世界。它的最大特点之一是多语言构建：游戏使用你自有卡带 ROM的语言来编译，官方支持英语、西班牙语（BPES）、法语（BPEF）和意大利语（BPEI）。本教程带你从源码出发，用一条命令构建西/法/意三语的 3DSX 游戏，并讲解构建流程、语言校验机制与安装要点。

🌍 四种语言，全部来自你的 ROM

Emerald 3DS 不分发任何游戏内容，文本、图形、字幕都提取自你本地的一份干净、未修改的 ROM dump。构建器通过 SHA-1 指纹识别卡带语言：

⚠️ 德语、日语卡带以及 ROM hack 均不支持。ROM 只被读入内存，不会被复制、上传或修改。指纹定义见 rom.py。

🛠️ 构建环境准备

在开始之前，请确认你的开发机满足 docs/DEVELOPMENT.md 列出的要求：

1. devkitPro 工具链：devkitARM、libctru、citro2d、citro3d、3dstools（含picasso着色器汇编器）。例如：

   pacman -S --needed libctru citro2d citro3d 3dstools

2. 原生 C/C++ 编译器：用于反编译工具与主机端测试（Windows 下使用 MSYS2 MinGW64 的 gcc/g++）。
3. Python 3.11+ 与 Pillow：本地化脚本与构建器都依赖它。
4. git：拉取锁定版本的引擎源码。

📦 获取源码

仓库本身只包含移植代码、补丁与构建工具，不包含引擎本体。运行 tools/bootstrap.py 会自动完成三件事：

1. 读取 upstream.lock，浅克隆锁定 commit 的 pret/pokeemerald 到build/upstream；
2. 按顺序应用 patches/pokeemerald/ 下的全部移植补丁；
3. 将3ds_port/、builder/、tools/放置进构建树，使 Makefile 的相对路径可用。

git clone https://gitcode.com/gh_mirrors/em/emerald-3ds cd emerald-3ds python tools/bootstrap.py

⚡ 一条命令构建西/法/意版本

这是本教程的核心。bootstrap 提供三个本地化参数，分别对应三种语言（见 bootstrap.py 头部说明）：

# 西班牙语（BPES） python tools/bootstrap.py --make --spanish-rom "/path/to/Pokemon Esmeralda.gba" -j8 # 法语（BPEF） python tools/bootstrap.py --make --french-rom "/path/to/Pokemon Emeraude.gba" -j8 # 意大利语（BPEI） python tools/bootstrap.py --make --italian-rom "/path/to/Versione Smeraldo.gba" -j8

构建成功后，3DSX 会输出到：

build/upstream/3ds_port/emerald3ds.3dsx

三个语言构建会依次执行对应的本地化脚本：

语言专项补丁

除本地化脚本外，每种语言还有专属引擎补丁（均位于PORT_BRIDGE之下），例如 patches/pokeemerald/ 中的：

• 西班牙语：0035-spanish-native-pokedex-units.patch、0036-spanish-berry-tag-layout.patch
• 法语：0041-french-ending-tilemap.patch、0045-french-native-row-dimensions.patch、0047-french-pokedex-number-format.patch
• 意大利语：0049-italian-layout.patch、0050-italian-ending-tilemap.patch

这些补丁处理语言相关的排版细节：法语九列键盘与法文字母表序、意大利语加宽的招式属性表与LA FINE结尾画面、西/意语原生单位（米/千克）等，具体差异说明见 docs/SPANISH.md、docs/FRENCH.md、docs/ITALIAN.md。

🔍 构建过程到底做了什么

以西班牙语为例，--spanish-rom构建的完整链路是：

1. 校验 ROM：localize_spanish.py先核对 ROM 的 SHA-1，以及清单中每个源文件的 SHA-256 指纹，确认无误才会写入任何文件；
2. 提取文本与图形：从你的 ROM 替换名称、对话、菜单、词汇表、吟游诗人歌曲、训练家台词、地图文本与盲文残页文本等，西班牙语共提取 104 项图形资源，并重建 55 页字幕与 Trainer Hill 楼层；
3. 编译 3DSX：在build/upstream/内完成全部编译。

清单文件（tools/locales/）只记录代码位置、ROM 内偏移、符号名与地址，不含任何游戏文本或数据。若移植代码改动过清单覆盖的源文件，本地化会中止并提示Source differs from the pinned patched tree。

🔄 引擎级语言锁定

引擎会校验自身的编译语言：西语构建的 3DSX 只接受由 BPES 生成的数据包，英/法/意同理。语言混用会在启动时被直接拒绝，这是防止"西语引擎 + 英语文本"之类错配的关键设计。

⚠️ 切换语言会重置构建树

反复切换语言（例如先跑--spanish-rom，再跑--french-rom）时，bootstrap 会清空已编译对象与已本地化资源并重建整棵树，避免复用另一种语言的缓存数据。所以一次会话只构建一种语言即可，切换前请做好心理准备等待一次完整编译。

📱 安装到 3DS 并运行

把构建产物放入 SD 卡（或先用测试卡验证，避免覆盖现有安装），目录结构如下：

3ds/emerald3ds/Emerald3DS.3dsx # 构建产物（西班牙语构建即为西语版） 3ds/emerald3ds/Emerald3DS.smdh # 标题密钥 3ds/emerald3ds/emerald3ds.pak # 数据包（由 builder 生成）

来自源码树的 3DSX 已将数据嵌入 RomFS，可直接用 Homebrew Launcher 运行。若要走"引擎 + 数据包"的正式发行形态，可用 builder 从 ROM 生成emerald3ds.pak：

python -m emerald3ds_builder --payload /path/to/payload install --rom /path/to/esmeralda.gba --sd /path/to/sdcard

builder 会自动识别 ROM 语言并选择对应构建变体（Emerald3DS-es.3dsx/Emerald3DS-fr.3dsx/Emerald3DS-it.3dsx均会被保存为Emerald3DS.3dsx），更多命令见 builder/README.md。

别忘了声音：音频需要SD:/3ds/dspfirm.cdc（注意是在3ds/目录根部，而不是3ds/emerald3ds/内），该文件不包含在发行包中，缺失时游戏可以运行但没有声音。存档保存在SD:/3ds/emerald3ds/emerald3ds.sav，更新安装不会覆盖它；详细安装与更新流程见 docs/INSTALLATION.md。

❓ 常见问题速查

📚 小结

• 环境：devkitPro + 主机 C 编译器 + Python 3.11+，python tools/bootstrap.py准备构建树；
• 构建：--spanish-rom/--french-rom/--italian-rom一条命令完成校验、本地化与编译；
• 产物：build/upstream/3ds_port/emerald3ds.3dsx，放入SD:/3ds/emerald3ds/即可运行；
• 深入阅读：docs/SPANISH.md、docs/FRENCH.md、docs/ITALIAN.md、docs/DEVELOPMENT.md、docs/ASSET_PIPELINE.md。

祝你用母语重走丰缘，享受双屏与立体 3D 带来的全新冒险！