导入 Pokemon Essentials 项目
你有一个已经做了数月甚至数年的 Pokemon Essentials 项目吗？OpenMon 的 Essentials Importer 会把你的 PE v20、v21 和 v21.1 项目数据转换为 OpenMon 格式 —— 在保留你的成果的同时，让你获得 Unity 完整的平台支持和商业授权。
第二张截图是整个流水线的意义所在：667 / 667 Monsters，可 按物种、招式、特性、道具、属性和性格浏览，而这个项目一小时前还只是 Ruby 脚本和 PBS 文本文件。
适用于 Indie、Pro、Source 和 Studio 版本（Indie 和 Pro 为编译版）。
已在真实的 v21.1 项目上验证
该导入器曾在一个完整的 Pokemon Essentials v21.1 项目（2023-07-30 版本）上以无界面方式运行，端到端转换了每一份列表，零错误：
| 数据 | 结果 |
|---|---|
| 物种 | 898 / 898 已转换，0 错误 —— 应用了 335 个形态覆盖，链接了 422 个进化 |
| 招式 | 新创建 150 个 Move 资产，590 个与现有招式库匹配 |
| 特性 | 创建 72 个，匹配 195 个 |
| 道具 | 创建 315 个 Item 资产，匹配 378 个 |
| 训练师 | 20 位训练师，队伍已填充（处理了 72 种训练师类型） |
全部 898 个物种都转换成了真正的 MCE ScriptableObject —— 形态和进化链均已链接 —— 没有致命错误。这就是导入器的核心主张：**已针对完整的真实 v21.1 项目验证，而非合成的测试用例。**伴随这次运行出现的 227 条警告全都是诚实降级的通知（没有精确 MCE 模板的招式效果 —— 见下文招式），绝非悄悄丢失数据。
导入 的内容
Essentials Importer 处理以下数据类型：
| PE 数据 | OpenMon 对应项 | 状态 |
|---|---|---|
| PBS/pokemon.txt | MonsterEntry ScriptableObject | 已支持（真实 v21.1 上 898/898） |
| PBS/pokemon_forms.txt | Form 资产 + DataByFormEntry 覆盖 | 已支持（应用了 335 个覆盖） |
| PBS/moves.txt | Move ScriptableObject | 已支持，诚实的效果映射 |
| PBS/types.txt | MonsterType 资产 + 属性相克表 | 已支持 |
| PBS/abilities.txt | Ability ScriptableObject | 已支持（资产级别） |
| PBS/items.txt | Item ScriptableObject | 已支持（生成具体的 SO） |
| PBS/trainers.txt | TrainerDefinition + CharacterData + Roster + Bag | 已支持 |
| PBS/encounters.txt | WildEncountersSet ScriptableObject | 已支持 |
| 怪物精灵 | 战斗 Material + 图标 Sprite | 已支持（按形态 + 性别变体） |
| 地图文件 (.rxdata) | 带 GridController 的 Unity 场景 | 已支持（需要项目级验证） |
| 图块集图片 | Unity 精灵图集 | 已支持 |
| 地图事件命令 | CommandGraph 节点 | 已支持（训练师战斗已接线） |
| 音频文件 | 带 AudioManager 配置的 AudioClip | 直接复制 |
需要手动处理的内容
PE 的某些功能没有直接的自动转换。我们把这些记录为诚实的、有意为之的限制，而不是含糊其辞：
CommonEvents.rxdata—— 公共事件**按设计不在范围内。**它们不会被导入；请手动把共享事件逻辑移植到 CommandGraph 或 C#。- 特性行为 —— 特性资产会被创建或克隆，但导入的特性只能达到它所映射的 MCE 实现的丰富程度。自定义或插件特性需要对应的 MCE
Ability实现。 - 复杂的 Ruby 脚本 —— 超出标准事件命令的 PE 自定义脚本需要手动移植到 C# 或 CommandGraph。
- 插件特定数据 —— 第三方 PE 插件以非标准格式存储数据。
- 自定义 UI 布局 —— PE 的窗口系统与 Unity UI 有根本区别。
- 动画战斗精灵 —— PE 使用不同的动画格式；精灵会作为静态帧导入，你可以重新组装。
前提条件
导入之前，请确保你具备：
- 已安装 OpenMon（Indie 版本或更高） —— 参见安装指南
- 可在磁盘上访问的你的 PE 项目文件夹（包含
PBS/和Data/的那个） - **你的 Unity 项目的备份。**向导自己也这么说：导入器是实验性的，按原样提供，某些功能是部分实现（Items）或未实现（Common Events）。
你不需要选择 Essentials 版本（v20、v21 或 v21.1）：导入器在你扫描项目时会自动检测。
分步导入
步骤 1：打开导入器
在 Unity 中，打开 OpenMon Hub（Tools > MCE > OpenMon Hub）→ Importer 选项卡 → Import Wizard。
位于同一选项卡下方的 Starting Map Picker 是人们容易漏掉的一步：它决定玩家在主菜单之后出生在哪张地图。没有它，一次其他方面都成功的导入也无处开始。
向导窗口显示：
- PE Project Folder —— 你项目的根文件夹（包含
PBS/、Data/、Graphics/的那个），带有 Browse 按钮 - Project Name —— 这次导入的名称（例如
FRLG或Emerald）。它决定输 出文件夹的名称，因此多次导入可以并存 - Imported Projects —— 这个 Unity 项目中已有的导入
- Import Categories —— 每种数据类型的开关
- Map Display Mode —— 以 2D（平面，自上而下）或 2.5D（倾斜相机下）绘制导入的地图。之后可在 Display Mode per Map 中逐张地图更改
- Output Folder 和 Overwrite Existing Assets
步骤 2：选择并扫描你的 PE 项目
点击 Browse 并导航到你的 Pokemon Essentials 项目文件夹，然后按 Scan Project。导入器会验证文件夹结构，显示检测到的 Version，并报告它发现的内容：
PBS/pokemon.txt -- 898 species detected
PBS/moves.txt -- 740 moves detected
PBS/types.txt -- 19 types detected
PBS/abilities.txt -- 267 abilities detected
PBS/items.txt -- 693 items detected
PBS/pokemon_forms.txt -- 339 form overrides detected
PBS/trainers.txt -- 20 trainers detected
（所示数量来自用于验证导入器的真实 v21.1 2023-07-30 项目。）
扫描还会对项目的自动图块进行深度扫描。当某个图块集所指名的图像都在项目中时，扫描会以 [OK] Missing: 0 - All autotile images found! 结束。缺失的图像此时还不会被判定：判定发生在地图解析完成之后（参见命令行一节中关于退出码的说明，以及步骤 5 的日志图例）。
步骤 3：选择要导入的内容
Import Categories 为以下每一项都提供了开关：Species、Moves、Items、Abilities、Types、Trainers、Encounters、Maps、Sprites、Follower Sprites、Audio 和 Connections。
首次导入时，我们建议分阶段导入：
- **第一遍：**Types、Abilities、Moves、Species（仅数据，不含地图）
- **第二遍：**Items、Trainers、Encounters
- **第三遍：**Maps 和 Audio
- **第四遍：**检查事件和场景集成（见下文）
这种分阶段的方法让你在基于某一数据层继续构建之前先验证它。
步骤 4：运行导入
向导分阶段工作，每个阶段都有自己的按钮：
| 按钮 | 作用 |
|---|---|
| PARSE DATA | 阶段 1-2：根据检测到的 Essentials 版本读取 PBS 文本文件以及 .rxdata 地图和图块集。此时你的项目中尚未创建任何内容。 |
| CONVERT TO MCE | 阶段 3：把解析后的数据转换为输出文件夹下的 MCE ScriptableObject 和场景。解析成功后启用。 |
| FULL IMPORT (Parse + Convert) | 一次完成解析、转换和集成。 |
| INTEGRATE SCENES (Phase 6) | 把导入的场景接入 MCE 运行时：将它们注册到场景管理器，连接每个 SceneInfo，放置传送触发器，链接遭遇集合，并把场景添加到 Build Settings。请在导入之后运行（完整导入已包含此步）。 |
所有内容都写入 Assets/ImportedGames/<Project Name>/，并生成一份详细的导入日志，显示成功项、警告和需要关注的项目。
步骤 5：查看导入日志
日志对结果进行分类：
- [OK] —— 数据成功转换
- [WARN] —— 数据已转换，但带有假设（例如，没有精确 MCE 模板、按类别克隆的招式效果），或是不会造成任何损失的遗留项（某个图块集指名了项目没有附带的自动图块图像，但没有任何地图使用该图块集）
- [ERR] —— 无法自动转换的数据（包括被至少一张地图所使用的图块集指名、而项目没有附带的自动图块图像）
步骤 6：让游戏可玩
集成之后，如果想要不同的起始地图，请使用 Starting Map Picker。向导的 Restore MCE Original Demo 和 Restore Imported Demo 按钮用于在演示场景和导入场景之间切换 Build Settings。
DELETE ALL IMPORTED PROJECTS 会删除所有导入的项目文件夹和配置文件。按下之前请先备份。
步骤 7：为商业使用重命名
此步骤对商业发行至关重要。
你的 PE 项目很可能为怪物、角色和道具使用了宝可梦特有的名称。在出售你的游戏之前，必须把它们替换为原创名称。使用 Database Browser 查看并重命名导入的数据：
- 打开 OpenMon Hub（
Tools > MCE > OpenMon Hub）→ Database 选项卡 → Database Browser - 搜索你导入的物种数据库
- 把每个条目的显示名称改为你的原创名称
- 由于资产是通过对象引用来引用的，遭遇表、训练师队伍和进化链在重命名后依然有效
招式名称和特性名称通常可以保持原样（它们描述的是机制，而不是知识产权），但带有宝可梦特有品牌的怪物名称、角色名称和道具名称必须更改。
流水线逐步导入的内容
**Parse（阶段 1-2）**按顺序读取：属性、特性、招式、道具、物种、训练师、遭遇、地图连接、地图元数据、图块集和地图。
**Convert（阶段 3）**随后运行这些步骤（当某一类别关闭时，对应步骤会被跳过）：
- 扫描已存在的 MCE 资产，以便复用匹配项而不是重复创建。
- 通过克隆和配置创建缺失的招式和特性。
- 转换物种及其形态和进化（此时所有招式和特性都已存在）。
- 报告未匹配的引用。
- 链接 PE
Graphics/文件夹中的精灵，如果项目有跟随者精灵则一并链接。 - 重建中央怪物数据库；转换属性；确保 25 种性格存在；导出道具和训练师。
- 把图块集切分为 Unity 图块资产并烘焙自动图块。
- 把地图转换为 Unity 场景并连接它们的连接。
- 把遭遇转换为
WildEncountersSet资产。 - 导入音频（BGM、BGS、ME、SE）、世界角色精灵、战斗背景图片和训练师精灵。
- 提取传送点和事件数据，并把事件命令转换为 CommandGraph。
**Integrate（阶段 6）**按上表所述注册、连接并添加场景。
每种数据类型如何转换
精灵与战斗材质
真实的 Essentials 资源包按 INTERNALNAME 而不是图鉴编号来命名怪物精灵。SpriteLinker 按内部名称匹配精灵文件，按形态链接美术资源，并遵循性别变体：默认美术字段存放雌性/无性别精灵（{name}_female.png），另有一个雄性覆盖字段存放基础精灵。
关键在于，链接器会为四个面（Front、Back、Front-Shiny、Back-Shiny）各自生成战斗 Material，外加图标精灵。MCE 的战斗模型通过 Material（翻页动画着色器）引用精灵，所以没有这一步，导入的怪物在战斗中会不可见。当你在启用精灵的情况下 导入时，会运行精灵链接。
招式（诚实的效果映射）
招式效果来自 Essentials 的 FunctionCode。导入器把 307 个不同的 FunctionCode 映射到具体的 MCE 招式模板（已在 MoveConverter.FunctionCodeTemplates 中验证）—— 这一映射经过多个批次扩展，包括一次涵盖两回合/蓄力攻击和威力修正招式的补充遍历。
任何不在表中的 FunctionCode 都会诚实地降级：招式仍会被创建，按其伤害类别克隆，并记录一条可见的警告（unmapped FunctionCode '…'. Cloned by category only.）。这是有意为之 —— 降级绝不是静默的。当不存在忠实的 MCE 模板时，有些代码会被特意留空，因为诚实的回退好过错误的克隆。
道具
ItemConverter 为每个解析出的道具生成具体的 MCE Item ScriptableObject（为保证幂等性，会复用任何名称匹配的现有 MCE Item），并把 PE 原始数据以 JSON 形式导出以供参考。MCE 无法建模的道具效果会作为警告记录，道具仍会作为一个无效果的背包道具创建。
训练师
trainers.txt 中重复的 Pokemon = SPECIES,level 块会被正确解析（一个常见陷阱 —— 重复的键会被保留，而不是被合并）。TrainerConverter 为每位训练师创建一个 TrainerDefinition、CharacterType、CharacterData、Roster 和 Bag。调用 pbTrainerBattle(:TYPE, "Name") 的地图事件会被接线到匹配的已导入 TrainerDefinition，因此导入的训练师能进入真实的运行时战斗。
遭遇
EncounterConverter 构建 WildEncountersSet 资产，并按原始名称、大写名称和规范化名称解析物种 —— 包括名称中含有标点或性别符号的物种 —— 所以即使内部名称很古怪，遭遇表也能链接到正确的怪物。
形态与进化
形态覆盖会创建或复用 Form 资产和 DataByFormEntry 数据；缺失基础物种时会发出警告，且不计为成功。进化接线作为第二遍运行（在所有物种资产都存在之后），使目标能够被解析，并在重新导入时以幂等方式重建进化列表。转换器把 v21.1 完整的进化方式头部集合 —— 等级、时段、性别、道具、携带道具、交换、已学招式、队伍中存在以及暴击等变体 —— 映射为 MCE 的进化命令。
命令行导入
有两个 入口可以不打开向导就运行导入器。它们做的事情多少不同。
完整导入：ImportarCompletoDesdeCli
运行整个向导流水线 —— 数据、地图、遭遇、音频、精灵、传送点、事件和场景集成 —— 与 FULL IMPORT 按钮完全一致：
Unity.exe -batchmode -projectPath . \
-executeMethod OpenMon.MCE.EssentialsImporter.Editor.EssentialsImporterWizard.ImportarCompletoDesdeCli \
-essentialsProyecto "D:/Games/MyEssentialsProject" \
-essentialsNombre "MyGame" \
-essentialsModo 2.5D
| 参数 | 含义 |
|---|---|
-essentialsProyecto <文件夹> | Essentials 项目（必须包含 PBS/ 和 Data/） |
-essentialsNombre <名称> | 导入的名称。输出放入 Assets/ImportedGames/<名称>/ |
-essentialsModo <2D 或 2.5D> | 可选。地图的绘制方式；省略时为 2D |
它拒绝覆盖已存在的输出文件夹：流水线会在那里写入和重写，原有内容会丢失。请选择另一个 -essentialsNombre，或把旧文件夹移出项目。当项目文件夹不存在或缺少 PBS/ 或 Data/ 时，它也会拒绝。
编辑器会在生成了场景且没有记录任何 [ERR] 行时以退出码 0 自行结束，否则为 1，如果无法启动（缺少 参数、未知模式、找不到项目、输出文件夹已存在）则为 2。它的日志行以 [EssentialsCompleto] 开头。
如果某个图块集指名了项目没有附带的自动图块图像，则会在地图解析完成之后再做判定。只有在至少有一张地图使用该图块集时，它才是 [ERR]。如果没有任何地图使用它，它就是 [WARN]（"no map uses that tileset, so nothing is lost"），不会让导入失败。
仅数据导入：EssentialsHeadlessImport
用于 CI，或当你只需要数据库（物种、招式、道具等）而不需要地图时，EssentialsHeadlessImport 会不带窗口地运行数据流水线：
Unity.exe -batchmode -quit -projectPath . \
-executeMethod OpenMon.MCE.EssentialsImporter.Editor.EssentialsHeadlessImport.RunCli
RunCli 从环境变量读取其输入：
| 变量 | 含义 | 默认值 |
|---|---|---|
MCE_IMPORT_PROJECT | Essentials 项目根目录 | ./Pokemon Essentials v21.1 2023-07-30 |
MCE_IMPORT_OUTPUT | 相对于 Unity 的输出文件夹 | Assets/ImportedGames/_v21batch |
MCE_IMPORT_SPRITES | 链接精灵和跟随者（false、0、no 或 off 会跳过它们） | 开启 |
MCE_IMPORT_REBUILD_DB | 重建项目的 MonsterDatabaseInstance（false 则保持不变） | 开启 |
它首先清空之前的输出文件夹，使运行具有确定性，然后把每个分区一行的紧凑报告写入 Logs/v21-batchmode-summary.txt，成功时以 0 退出，失败时以 1 退出。
在 C# 中，你也可以改为调用 EssentialsHeadlessImport.Run(projectPath, outputPath, importSprites, rebuildDatabase)；它返回一个带有真实计数的 ImportSummary（创建、匹配和跳过的物种、招式、道具、特性和训练师）。
它导入属性、特性、招式、道具、带形态和度量的物种、精灵、跟随者、性格和训练师，并重建数据库。它有意跳过地图、场景、图块集、自动图块、遭遇场景、音频、世界/战斗背景/训练师媒体、事件命令图和场景集成 —— 每次跳过都会记录在摘要的 SkippedSteps 中。
带精灵生成的完整导入会执行持续数分钟的同步 AssetDatabase 工作。请在关闭编辑器的情况下以批处理模式运行，而不是交互式运行，这样漫长的资产处理就不会阻塞你的编辑器。交互式导入最适合分阶段、仅数据的遍历。
关于卡带转储（HeartGold / SoulSilver、FireRed、Black / White）及其游戏配置文件，参见导入的游戏与游戏配置文件。
导入后检查清单
导入之后，逐项完成此清单：
- 在 Monster Database Editor 中验证物种数据
- 在 Type Chart Editor 中抽查属性相克
- 用导入的怪物和招式测试几场战斗
- 走遍导入的地图并验证图块碰撞
- 测试 NPC 事件和对话流程
- 把所有宝可梦特有的名称替换为原创名称
- 为重命名后的怪物添加你自己的精灵
- 按你游戏的进度配置遭遇表
- 按你游戏的存档格式设置存档系统
常见导入问题
"Species X has an unknown ability"
PE 允许通过插件使用自定义特性。如果导入器不认识某个特性，会把它映射到占位符。请在 OpenMon 中创建一个自定义 Ability 资产来匹配其行为。
"Map tile Y has no matching collision type"
PE 使用了一些不能直接映射到 OpenMon 的 GridController 的图块属性。导入器会创建该图块，但会标记它需要手动指定碰撞。
"Evolution method Z not supported"
OpenMon 支持 37 种进化类型，但 PE 插件可能会添加自定义类型。这些会作为警告记录，等待手动实现。
为什么要迁移？
导入和重命名的投入是一次性成本。你将得到：
| 之前（PE） | 之后（OpenMon） |
|---|---|
| 仅 Windows | 7 个以上平台 |
| 仅限同人游戏 | 商业发行 |
| 没有多人游戏 | 可用 25 个在线服务类 |
| Ruby 脚本 | 拥有完整 IDE 支持的 C# |
| 没有自动化测试 | NUnit 测试框架 |
| 手动部署 | Unity 构建流水线 |
| 320x240 分辨率 | 任意分辨率 |
你多年的创作成果 —— 你构建的世界、你设计的怪物、你写下的故事 —— 值得以最好的技术触达尽可能广泛的受众。
获取帮助
- Discord：加入 OpenMon 社区 —— #essentials-import 频道有专门的支持
- **文档：**浏览完整的指南库，了解 OpenMon 特有的工作流程
- **Issues：**在 GitHub 上报告导入错误