Skip to content

Trainer presets and reusable teams

A trainer preset is a server-side configuration reused by placed NPCs. Its trainer identity is used by commands, the trainer menu, and player battle history.

Files and IDs

config/greatnpc/
├── trainer_preset/
│   └── town/
│       └── first_trainer.json
├── trainer_team/
│   └── town/
│       └── first_trainer.json
├── item_presets/
└── backups/

The preset above has the short ID town/first_trainer. Omit .json in commands:

/gnpc spawn town/first_trainer

Short IDs resolve to the internal cobblemontrainerbattle namespace. This namespace is retained for compatibility; it is not a requirement to install a separate Trainer Battle NPCs mod.

Keep export names lowercase, using letters, digits, _, and -; / creates a folder hierarchy. Do not use spaces, absolute paths, or .. path traversal segments.

Export an existing character

Build and test a character in the editor. Stand within 8 blocks, look at it, and run:

/gnpc export town/first_trainer

Export copies its effective configuration to trainer_preset/town/first_trainer.json. A nonempty inline team is written to trainer_team/town/first_trainer.json, and the preset references that team. Export clears a fixed exported entity UUID, reloads configurations, and assigns the placed NPC to the exported trainer ID.

If the effective preset already references a shared team instead of containing an inline team, export keeps that reference; it does not necessarily create another team file.

Existing destination files stop export by default. Replace them only when intended:

/gnpc export town/first_trainer overwrite

Keep a backup before overwriting. Preset and team files use safe replacement but remain separate files, so a whole-server backup is still valuable.

Understand team ownership

Team form Meaning
Local/inline team Pokémon definitions stored with the effective NPC/preset configuration
Shared team reference The preset's team value references a file under trainer_team

The team editor's file-writing option is different from applying a team only to the current NPC. File editing needs permission and changes a shared resource. Check the displayed team origin before saving.

This property references config/greatnpc/trainer_team/town/first_trainer.json:

{
  "team": "town/first_trainer"
}

This is a property fragment, not a complete battle-ready trainer preset. Export produces a configuration matching your actual character and team.

File-based presets require an external team file

The current file loader resolves every preset's team reference in trainer_team before accepting the preset. A team_inline property by itself does not make a file-based preset loadable. Local egg-created NPCs can hold inline teams through their entity settings; this is a different path from loading a reusable JSON file.

For a battle trainer, provide a valid referenced team file. Exporting a nonempty local inline team performs this separation for you.

A reusable shopkeeper, dialogue character, or decorative preset still needs a valid team reference under the current loader, even if it never battles. For example, create:

config/greatnpc/trainer_team/shops/empty.json

with the complete file content:

[]

Then use this property in its preset:

{
  "team": "shops/empty"
}

An empty referenced list allows the preset to load but supplies no battle Pokémon. Do not use it for a trainer that is expected to start battles. If a preset does not appear after reload, check the team reference first, even when you put team_inline in its JSON.

Follow Preset and local overrides

Set Source Preset to a reusable ID and enable Follow Preset when the placed NPC should inherit updates. Editing an individual setting locally switches Follow Preset off.

Before changing a shared preset, decide which NPCs should inherit it and which should stay local variants. Placement and home position belong to each placed NPC; two copies can stand in different places while sharing trainer progression.

Open the preset manager

/gnpc presets

The manager requires the client mod and editing access. You can also open Manage Presets from the NPC editor. Opening it from an NPC supplies context for adding that character as a preset or applying a preset to it.

The manager supports preset/category selection, editing, application, creating/renaming categories, removing presets/categories, and history resets. File operations require greatnpc.edit.files; history resets check greatnpc.reset.

A category here is a folder under trainer_preset. This differs from the custom menu_category label used to group trainers in /trainers.

Rename and remove

The manager records supported category renames in config/greatnpc/preset_renames.json. A manual operating-system rename does not by itself update every reference.

Removing a preset creates a backup before deleting its file. An associated team file can also be backed up and removed when it belongs to that preset and is not shared by another loaded preset. Category removal can affect all presets below that folder.

Deleting a reusable preset is not the same as Remove Wand on a placed entity. Discarding a placed NPC does not delete its shared trainer preset file.

The manager's history-reset actions operate on the executing player's selected trainer/category scope. They change progression; they do not rename or copy the character.

Item presets are separate

Blank Preset creates an item snapshot under item_presets. The resulting item can spawn copies or apply the snapshot to a matching humanoid/Pokémon NPC. It is not simply an inventory representation of a trainer_preset file.

See Administrative tools for that workflow and its backup requirements.

Check file changes

/gnpc reload
/gnpc validate

Read errors before spawning more copies. A preset with a missing/invalid team can fail to load. The manager and spawn commands use loaded presets, not arbitrary filenames on disk.

See Concepts for the identity/progression relationship.