Migrate existing NPCs and battle history¶
GreatNPC has separate migration paths for Easy NPC entities, legacy Cobblemon Trainer Battle entities, and legacy player battle-history files. Entity conversion and history import are separate operations.
Before conversion¶
- Stop the server and create a restorable backup of the world and
config/greatnpc/. Include any old-mod configuration required to recreate the trainers. - Work on a copy first. Keep the source mod installed while loading its saved entities for conversion.
- For legacy trainer entities, prepare matching GreatNPC presets and teams.
/gnpc listmust contain the trainer IDs referenced by the old entities. - Start the server and load the chunks containing the entities to migrate.
- Use a dry run and inspect the report before converting.
Migration does not scan every saved region or force-load the entire world. Counts apply to currently loaded entities across server worlds. A real entity conversion spawns a native NPC and discards the old entity after successful creation; restore the backup to undo an unsuitable conversion.
Easy NPC¶
Supported source entities include Easy NPC humanoids (humanoid, humanoid_slim) and supported Cobblemon/Pokémon render types.
dump writes diagnostic source NBT to config/greatnpc/easynpc_dump and uses the dry-run path. It does not perform the real conversion.
To handle one model family at a time:
/gnpc migrate easynpc humanoid dry-run
/gnpc migrate easynpc humanoid
/gnpc migrate easynpc pokemon dry-run
/gnpc migrate easynpc pokemon
The converter attempts to carry supported names, skin/model information, equipment, selected poses, dialogue, actions, and trade offers into GreatNPC. Conversion is not lossless for every Easy NPC capability. Unsupported model types are reported/skipped. Actions or conditions without an equivalent can be omitted and counted as lossy conversions, including some scoreboard, advancement, and damage-trigger features.
After converting, test each NPC's actual dialogue choices, trade costs/results, equipment, skin/model, interaction mode, and actions. Use the editor to replace omitted behavior with supported actions.
Main Config exposes automatic Easy NPC migration and a Migrate Easy NPC now action. Automatic Easy NPC migration is disabled by default and operates when eligible entities load. It is separate from /gnpc migrate auto, which controls legacy trainer conversion.
Legacy Cobblemon Trainer Battle entities¶
The legacy entity namespace is cobblemontrainerbattle. The normal converter recognizes trainer, neutral_trainer, and mannequin. static_trainer requires the explicit include-static branch.
The source entity's stored Trainer ID must resolve to a loaded GreatNPC trainer preset. Entities with missing configuration are reported and kept. Prepare the missing preset/team, reload, and repeat the conversion after checking the report.
To also convert legacy static trainers:
That command performs real conversion. There is currently no include-static dry-run combination in the command tree. The report lists legacy static trainers separately so they can be reviewed first.
Successful conversion uses the trainer preset at the old entity's position/yaw and carries compatible command tags. It does not imply full support for every source-mod implementation detail.
To enable subsequent conversion as chunks load:
Automatic legacy migration defaults to off. It handles eligible legacy battle trainers as they load; it does not automatically include static trainers. Disable it with /gnpc migrate auto false when manual control is preferred.
Import battle history¶
Legacy compressed .dat histories are read from the current world's:
Import them with:
Each old trainer entry contributes its timestamp, victory, defeat, and kill values. The importer takes the maximum of each imported and existing value; it does not add the counters. Old files are read rather than deleted. Check records with /gnpc history <online-player> [trainer] after import.
A legacy timestamp can affect current cooldown availability. Legacy victory/defeat counters can also make the one-battle-per-player rule consider the trainer already attempted. Review those settings before enabling the rule on an existing server.
GreatNPC's file-backed history lives under <world>/greatnpc/battle_history/. When MySQL is enabled and available, history is saved through the configured history backend. Back up the active backend before resets or further imports.
Final verification¶
Run /gnpc validate, inspect the server log, and test ordinary player challenges. Check the converted NPC's trainer ID with /gnpc info; verify that prerequisites, first-victory rewards, one-battle attempts, rematch cooldown, dialogue, and trade rules still produce the intended experience. A successful conversion count means an entity was converted, not that all source behavior has a one-to-one equivalent.
All migration command branches require greatnpc.migrate. See Commands for exact syntax and Permissions for access defaults.