Trainer battles¶
GreatNPC runs trainer battles through Cobblemon's native NPC battle system. A trainer combines an NPC entity, a preset containing battle rules, and a Pokémon party. The NPC's appearance species is separate from its party: a Pikachu-shaped NPC can command any valid trainer team.
Create a working trainer¶
- Install the required server and client dependencies listed in Installation.
- Create a party file in
config/greatnpc/trainer_team/and a preset file inconfig/greatnpc/trainer_preset/. See Teams and AI for a complete example. - Run
/gnpc reload, then/gnpc validate. Correct missing species, moves, items, or team references before continuing. - Run
/gnpc spawn tutorial/brockto spawn that preset at your location. - Look at the NPC and run
/gnpc edit. Set its interaction mode tobattlefor direct challenges, or use a dialogue action of typebattle. - Check a normal battle with an ordinary player account.
/gnpc testis an administrator preview that deliberately bypasses progression restrictions and rewards.
A trainer preset must reference an existing team file to load. After loading, per-NPC changes can override the party and settings. Editing a shared file can affect several NPCs; inspect the editor's source and write-to-file controls.
What happens when challenged¶
For a normal challenge, GreatNPC checks whether the trainer is enabled, the player's permission and tags, prerequisite victories, existing battles and introductions, the one-battle rule, rematches, the victory limit, and cooldown. It then validates the player's party, optionally heals it, creates the trainer party, and checks the effective battle format.
When enabled and supported by the player's client, the introduction appears before the battle starts. Important access, progression, and party checks run again after the introduction. An introduction alone does not consume the one-battle attempt: the attempt is recorded after Cobblemon successfully starts the battle.
A player who disconnects during the introduction loses the pending introduction. Duplicate requests cannot reserve another introduction for the same player, and a reserved NPC cannot accept a second introduction.
Battle settings¶
| JSON field | Default | Meaning |
|---|---|---|
enabled |
true |
Accept normal challenges. |
interaction_mode |
"battle" |
Direct battle, dialogue, trade, or another supported interaction. |
battle_format |
"single" |
single, double, or triple. |
allow_format_downgrade |
false |
Allow a smaller format when the trainer does not have enough Pokémon. |
battle_ai |
"generation5" |
AI selector; see Teams and AI. |
battle_theme |
"cobblemon:battle.pvn.default" |
Registered battle sound ID. |
battle_intro |
true |
Show the client introduction. |
battle_intro_seconds |
4 |
Introduction duration; the service bounds it to 1–15 seconds. |
battle_intro_reveal |
"team" |
team reveals the trainer party; none sends no party entries; other values produce hidden party entries. |
heal_player_before |
false |
Heal the player's party after its rule checks and before the battle. |
heal_player_after |
false |
Heal the player's party after a recorded battle result, including a loss. |
shuffle_team |
false |
Shuffle the trainer party before creating the battle. |
Single, double, and triple battles require one, two, and three usable player Pokémon respectively. Downgrade is based on trainer party size; it does not turn a large-format challenge into a smaller one merely because the player's party is too small. The configured party-size rules also apply.
Troubleshooting¶
| Symptom | Check |
|---|---|
Preset is missing from /gnpc list |
Its JSON, referenced team, and server log; run /gnpc validate. |
| NPC does not challenge on click | interaction_mode, enabled, dialogue actions, and whether an administration tool is held. |
| Player cannot rematch after losing | one_battle_per_player: it counts successful battle starts, including losses. |
| Player is blocked after a victory | Rematches: cooldown, is_rematch_allowed, and max_victories. |
| Battle will not start in doubles/triples | Party count, healthy Pokémon count, and allow_format_downgrade. |
| Preset edits do not affect one NPC | It may have per-NPC overrides or be detached from its preset. Review its source; /gnpc reload force also reapplies to edited NPCs. |
| Need server diagnostics | /gnpc debug true, reproduce, inspect the server log, then /gnpc debug false. |
For result auditing, see Battle log. For progression gates, see Party and access requirements.