Skip to content

Teams, levels, and AI

File layout and IDs

A preset named tutorial/brock uses config/greatnpc/trainer_preset/tutorial/brock.json. Its team value points to a JSON array in config/greatnpc/trainer_team/. A bare ID such as tutorial/brock uses the compatibility namespace cobblemontrainerbattle; the fully qualified ID is cobblemontrainerbattle:tutorial/brock.

Create the following party file at config/greatnpc/trainer_team/tutorial/rock.json:

[
  {
    "species": "geodude",
    "level": 12,
    "ability": "rockhead",
    "nature": "impish",
    "moves": ["tackle", "defensecurl", "rockthrow"],
    "ivs": {"hp": 20, "atk": 20, "def": 20, "spa": 20, "spd": 20, "spe": 20},
    "evs": {}
  },
  {
    "species": "onix",
    "level": 14,
    "ability": "sturdy",
    "nature": "careful",
    "moves": ["tackle", "bind", "rockthrow"]
  }
]

Create the preset at config/greatnpc/trainer_preset/tutorial/brock.json:

{
  "team": "tutorial/rock",
  "display_name": "Brock",
  "interaction_mode": "battle",
  "enabled": true,
  "battle_format": "single",
  "battle_ai": "strong5",
  "level_mode": "normal",
  "cooldown_in_seconds": 1800,
  "one_battle_per_player": false,
  "is_rematch_allowed": true
}

Then run:

/gnpc reload
/gnpc validate
/gnpc spawn tutorial/brock

Names of species, forms, abilities, moves, and items must exist in the installed Cobblemon version and data packs. Validation checks identifiers; it is not a competitive ruleset or a guarantee of legal move acquisition.

Pokémon fields

Field Meaning
species Species ID/name accepted by the species resolver. Required for a usable entry.
name Optional nickname.
form Optional form; form availability depends on the species.
level Level in normal mode, or offset from the player's highest level in relative mode. Default 100.
shiny Shiny appearance; default false.
item Held item; use an explicit ID such as minecraft:air only when intended. Leave empty for no item.
ability, nature, gender Optional attributes. Gender values are male, female, or genderless.
moves Up to four move IDs. An empty list allows the normal creation behavior.
ivs Stat map. Missing IV entries default to 31.
evs Stat map. Missing EV entries default to 0. Keep individual EVs at most 252 and the total at most 510.
aspects Optional aspects, separated by spaces or commas.
teraType Optional Tera type. Aliases tera_type and tera are accepted.
dynamaxLevel Dynamax level. Aliases dmax_level and dynamax_level are accepted.
gigantamax Gigantamax factor. Aliases include gmax, gmax_factor, and gmaxFactor.

Common stat keys are hp, atk, def, spa, spd, and spe. Use the team editor's controls when working with less common species-specific aspects or forms.

The normal editor limits a party to six entries. Prefer that limit in files as well; /gnpc validate reports oversized parties.

Level modes

level_mode Trainer creation level
normal Each entry's level plus level_offset.
relative The highest level in the player's current party, plus the entry's level, plus level_offset.
flat A level-50 battle format; trainer creation starts from 50 plus level_offset.

Created trainer levels are bounded to 1–100. In relative mode, level: 0 means matching the player's highest level before level_offset; level: -3 means three levels below it. Do not reuse a normal-mode party whose entries say level: 100 as a relative-mode party unless that very large offset is intentional.

minimum_party_level and maximum_party_level restrict the player's party. They are not the trainer's level settings.

Team editor

Open the NPC editor and its team section. You can add, copy, remove, and reorder entries, edit Pokémon attributes and moves, import a Showdown team from the clipboard, export JSON, and copy your current party.

The source indicator distinguishes a shared team file from a party stored on one NPC. With greatnpc.edit.files, the Write to file option can update the shared party file. Saving only to the NPC keeps the change local to that NPC. Confirm which source is selected before applying a shared change.

Artificial intelligence

battle_ai Implementation
random Cobblemon's random AI.
strong0 … strong5 Cobblemon's strong AI at the corresponding level.
rct RCT API battle AI.
generation5 Legacy/default selector currently resolved by the factory to strong5.

Unknown selectors also fall back to strong5; validate presets to catch typos. The skill field defaults to -1, which derives the NPC battle actor skill from the selected AI. An explicit nonnegative value is capped at 5. skill and the selected AI implementation are separate settings.

The dedicated-server startup currently requires RCT API. The AI factory also has a strong5 fallback when RCT is unavailable, but that fallback does not remove the dedicated-server dependency check.

Battle mechanics

allow_mega, allow_tera, allow_dynamax, and allow_zmove default to true and control the NPC battle AI's use of those mechanics. A toggle does not supply the necessary held item, move, form, factor, or other Cobblemon prerequisites. Prepare the party appropriately and test the actual mechanic in battle.