Imported Games and Game Profiles

Besides Pokémon Essentials projects (see Import from Pokémon Essentials), the importer can bring in whole games from a dump of a cartridge that you own: HeartGold / SoulSilver, FireRed and Black / White. The result is a complete project under Assets/ImportedGames/<Game>/ -- world, characters, species, moves, items, trainers, music, scripted NPCs -- that you can then play inside the engine.

Importing and playing are two separate steps on purpose:

1. Import only writes under Assets/ImportedGames/<Game>/. It touches nothing of the engine.
2. Apply the game profile ("Play ...") makes the engine start that game. It does edit engine assets, so it keeps a backup and can be undone ("Restore the demo").

Available in Source tier. Everything in the Hub lives in the Importer tab.

What You Need

Game	Folder the importer reads	Node.js	Maps are drawn
HeartGold / SoulSilver	salida/, the output of the HGSS extractor	for the extractor	2.5D like the cartridge, or 2D (you choose when importing)
FireRed	salida-rom/, read from the cartridge	for the extractor	2D
Black / White (and Black 2 / White 2)	Your .nds ROM, read by the Hub itself	18 or newer	-- (species and battle data)

The readers that turn a cartridge dump into those folders are small Node.js scripts that ship with the importer in Assets/OpenMon/Importer/Tools~/ (the folders hgss/, firered/ and bw/; the trailing ~ keeps Unity from importing them as assets). They read your dump and write to a folder of your choice; nothing of the game is distributed with MCE.

The Node tools recognise which game and platform a dump comes from by the signature in its header (Game Boy Advance or Nintendo DS), and the generation of the game decides how the world is drawn: FireRed imports in 2D, HeartGold / SoulSilver offers 2.5D and 2D.

Step 1: Import

In the Hub (Tools > MCE > OpenMon Hub → Importer tab), scroll to the section of your game and press its import button. It asks for the folder, and HeartGold / SoulSilver also asks whether the maps are drawn in 2.5D (as the cartridge draws them) or 2D (flat, from above). You can change that per map later with Display Mode per Map.

The importers run in a fixed order -- the order matters, because each step builds on the previous ones, and the world step rebuilds every scene from scratch, so the NPCs always come last:

HeartGold / SoulSilver (HgssImportador):

1. The world: maps, warps and outdoor neighbours.
2. The 3D models of the maps (2.5D).
3. The battle moves of the cartridge, then the items, then the shops (each machine teaches its cartridge move; each shop sells the cartridge items).
4. The badges and regions.
5. The species, with evolutions, then their battle sprites and icons.
6. The audio: music, sound effects and cries.
7. The wild encounters and the battle backgrounds.
8. The characters and the followers, with what the follower says, and the game's emotion balloons.
9. The trainers, then their battle figures (the trainer's front and the player's back, see Trainer Back Sprites).
10. The NPCs with their scripts, translated into CommandGraphs.

FireRed (FireRedImportador): the world and characters first, then the data of the cartridge (moves, items, species, sprites, trainers, battle figures, badges, encounters), then audio, battle backgrounds, emotion balloons and finally the NPCs with their scripts.

Black / White (BwDesdeLaRom): reads the ROM with the extractor in Tools~/bw and imports the species, their moves, their cries, their icons and their animated battle sprites. The data read from the ROM stays in Library/OpenMon/BW; the imported assets go under Assets/ImportedGames/BW.

Anything an importer meets and cannot map is counted and reported in the summary dialog and the console (for example "commands without support yet" or "moves without a template"). Nothing is dropped silently.

Folder names

Each importer writes only inside its own folder: Assets/ImportedGames/HGSS, Assets/ImportedGames/FireRed or Assets/ImportedGames/BW.

Step 2: Play It -- the Game Profile

An imported game is not part of the engine until you apply its profile. In the Hub, the same section has two more buttons:

Button	What it does
Play HGSS / Play FireRed (apply its game profile)	Registers the imported scenes where the engine looks for them, starts a new game in the player's room, offers the hero and heroine of that game as the playable characters, seeds the new-game flags, registers the game's species, items, music, regions and followers, and switches the engine's online layer off (these games are single-player)
Restore the demo	Undoes the profile, byte for byte, leaving the engine as it was

What the profile touches are engine assets that live in the repository -- the new-game initializer, the character-selection scene, the scene registry, the Build Settings, the savegame and world databases, the monster database, the audio library, the battle launcher's music, the follower and emotion-balloon sets in MCESettings, the global game data and the online configuration. Because of that, the profile is never applied by importing; you always apply it on purpose. And it behaves like this:

• A backup first. Before it changes anything the profile saves what was there into perfil-original.json and a perfil-original~/ folder inside the game's Assets/ImportedGames/<Game>/ folder. It is made once: applying the profile again never overwrites the backup with values that were already changed. The profile is idempotent.
• One profile at a time. Applying FireRed while the HGSS profile is applied restores HGSS first (and the other way round), so a backup never records the engine with another game already in it.
• Exports are blocked. While a profile is applied the package exporter refuses to run, because the engine would ship pointing at the ignored ImportedGames folder. Press Restore the demo first.
• The balloons and the back sprites come along. The profile assigns the game's emotion-balloon set (Emotion Balloons and Emotes), and the imported player characters carry the cartridge's own back sprites and throw timing (Trainer Back Sprites). Also, when the online layer is in the project, the importer stamps a grant id on every NPC that gives you a monster (Monster Gifts).

Restore before you commit

The profile edits assets that belong to the engine. If your project is under source control, press Restore the demo before committing, or you will commit a project that points at a folder nobody else has.

Command Line

Every Hub button has a static method you can run from Unity's batchmode (-batchmode -quit -projectPath . -executeMethod <method>). All of them end the editor with an exit code: 0 on success and 1 on failure. The HeartGold / SoulSilver import and the Black / White import use 2 when they could not even start (a missing or invalid argument; for Black / White, no ROM or no Node.js).

Game	Method	Arguments
HGSS	OpenMon.MCE.EssentialsImporter.Editor.HGSS.HgssImportador.ImportarTodoDesdeCli	-hgssSalida <salida folder> (required), -hgssModo <2D or 2.5D> (optional, 2.5D if omitted)
HGSS profile	OpenMon.MCE.EssentialsImporter.Editor.HGSS.HgssPerfil.AplicarDesdeCli	-hgssSalida <salida folder> (optional: the last output is used)
HGSS restore	OpenMon.MCE.EssentialsImporter.Editor.HGSS.HgssPerfil.RestaurarDesdeCli	--
FireRed	OpenMon.MCE.EssentialsImporter.Editor.FireRed.FireRedImportador.ImportarTodoDesdeCli	-fireredSalida <salida-rom folder> (optional)
FireRed profile	OpenMon.MCE.EssentialsImporter.Editor.FireRed.FireRedImportador.AplicarPerfilDesdeCli	-fireredSalida <salida-rom folder> (optional)
FireRed restore	OpenMon.MCE.EssentialsImporter.Editor.FireRed.FireRedImportador.RestaurarPerfilDesdeCli	--
Black / White	OpenMon.MCE.EssentialsImporter.Editor.BW.BwDesdeLaRom.DesdeLaRomDesdeCli	-bwRom <rom.nds> (or MCE_BW_ROM)

FireRed also has methods for single parts (ImportarDatosDesdeCli, ImportarFondosDesdeCli, ImportarAudioDesdeCli, ImportarEncuentrosDesdeCli), and Black / White has BwImportador.ImportarTodoDesdeCli and ImportarDatosDesdeCli (with -bwSalida).

Where an argument is optional, the entry point looks for the folder (or ROM) elsewhere, and each one does it its own way:

Entry point	Without its argument
HGSS import (HgssImportador.ImportarTodoDesdeCli)	-hgssSalida is required: there is no environment variable and no last folder. It logs falta -hgssSalida <ruta a salida/> and exits with 2.
HGSS profile (HgssPerfil.AplicarDesdeCli)	MCE_HGSS_SALIDA, else the last HeartGold / SoulSilver output imported in this editor.
FireRed: the full import, its partial imports and the profile	MCE_FIRERED_SALIDA, else the last FireRed output imported in this editor. If there is none, the import fails (exit code 1) because the folder does not exist.
Black / White from the ROM (BwDesdeLaRom.DesdeLaRomDesdeCli)	MCE_BW_ROM. There is no last-folder fallback: without a ROM (or without Node.js) it exits with 2.
Black / White from an output folder (BwImportador)	MCE_BW_SALIDA, else the last Black / White output imported in this editor.

An example of a complete, scripted HeartGold run:

# 1. import
Unity.exe -batchmode -quit -projectPath . \
  -executeMethod OpenMon.MCE.EssentialsImporter.Editor.HGSS.HgssImportador.ImportarTodoDesdeCli \
  -hgssSalida D:/dumps/hgss/salida -hgssModo 2D

# 2. apply the profile so the engine starts that game
Unity.exe -batchmode -quit -projectPath . \
  -executeMethod OpenMon.MCE.EssentialsImporter.Editor.HGSS.HgssPerfil.AplicarDesdeCli \
  -hgssSalida D:/dumps/hgss/salida

# 3. ... later, give the engine back
Unity.exe -batchmode -quit -projectPath . \
  -executeMethod OpenMon.MCE.EssentialsImporter.Editor.HGSS.HgssPerfil.RestaurarDesdeCli

For plain Pokémon Essentials projects the equivalent entry points are in Import from Pokémon Essentials.

Where the Importers Live

Folder	Content
Assets/OpenMon/Importer/Editor/HGSS/	The HeartGold / SoulSilver importers and HgssPerfil, the profile (it serves FireRed too)
Assets/OpenMon/Importer/Editor/FireRed/	The FireRed importers and FireRedImportador
Assets/OpenMon/Importer/Editor/BW/	The Black / White importers
Assets/OpenMon/Importer/Tools~/	The Node.js readers that turn a cartridge dump into the folders above