Skip to content

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

  1. Stop the server and create a restorable backup of the world and config/greatnpc/. Include any old-mod configuration required to recreate the trainers.
  2. Work on a copy first. Keep the source mod installed while loading its saved entities for conversion.
  3. For legacy trainer entities, prepare matching GreatNPC presets and teams. /gnpc list must contain the trainer IDs referenced by the old entities.
  4. Start the server and load the chunks containing the entities to migrate.
  5. 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.

/gnpc migrate easynpc dry-run
/gnpc migrate easynpc dump
/gnpc migrate easynpc

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.

/gnpc reload
/gnpc migrate report
/gnpc migrate entities dry-run
/gnpc migrate entities

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:

/gnpc migrate entities include-static

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:

/gnpc migrate auto true

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:

<world>/cobblemontrainerbattle/battle_history/<player-uuid>.dat

Import them with:

/gnpc migrate history

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.