Skip to content

Concepts and data ownership

Understanding the difference between an NPC, a trainer preset, and a history record prevents accidental changes to player progression.

Four identities to keep separate

Concept Example What it identifies
Placed NPC entity UUID A UUID shown by the editor One character in a world
Trainer preset ID town/first_trainer A reusable trainer configuration and its progression identity
Team reference town/first_trainer in a preset's team property A file under trainer_team
Player UUID The player's Minecraft UUID The player whose progress/state is recorded

The short trainer ID town/first_trainer resolves to the namespace cobblemontrainerbattle internally. A filename under trainer_preset supplies its relative path; omit .json in commands. This namespace is retained for compatibility and does not mean that a separate Trainer Battle NPCs installation is required.

Two NPC entities can share one trainer ID. They are different world objects but can share the player's trainer battle history, cooldown, and attempt limit. Moving an existing NPC does not intentionally create a new trainer progression identity.

Visual appearance versus battle party

A humanoid or Pokémon character can be a trainer, trader, dialogue character, healer, or decorative NPC. On Interaction decides the main behavior. The appearance species of a Pokémon NPC is independent from the Pokémon used in its battle party.

Dialogue portraits are another independent visual configuration. A portrait can show the NPC itself, a different Pokémon, a human skin, or nothing. It does not configure the world model or a minimap icon.

Presets versus local edits

A trainer preset is a reusable server file. A placed NPC can follow that preset or keep locally edited values.

  • Source Preset identifies the reusable configuration.
  • Follow Preset reapplies source settings when the preset is loaded/reloaded.
  • Editing a local setting switches Follow Preset off for that character.
  • Home and world placement describe the placed NPC, not a universal location for every copy.

A local NPC can hold an inline team through its entity configuration. A referenced team file can be shared by several presets. Editing a shared team file changes everyone who uses it; applying a local team change is a different operation.

The current file-based preset loader requires a valid external team reference. A team_inline property alone does not make a reusable JSON preset loadable. This requirement also affects shop/dialogue/decorative presets; they can reference a team file containing [] when they do not battle. See Preset team requirements.

What lives where?

Data Location/owner
Trainer presets config/greatnpc/trainer_preset/ on the server
Shared teams config/greatnpc/trainer_team/ on the server
Server-wide settings config/greatnpc/settings.json
Saved preset-item snapshots config/greatnpc/item_presets/
Preset-manager backups config/greatnpc/backups/
Placed NPCs and local entity variables The Minecraft world/entity save
Player battle history, trade/action state, and known NPC locations World-scoped saved data; battle history can optionally use MySQL
Battle audit results logs/greatnpc/battles/
Interface translations assets/greatnpc/lang/<locale>.json in the mod or a resource pack

Back up the complete world and config/greatnpc, plus any external database. Copying only trainer_preset is not a complete server migration.

settings.json is a separate server-settings format. Its persisted properties use camelCase; trainer preset properties generally use snake_case. The editor/network field names are not a reason to rename raw settings-file properties. Use the documented format for the file you are editing.

Attempts, victories, and cooldowns

One Battle per Player records whether an attempt was used. It is different from requiring a player victory. A loss can consume the single attempt. The dedicated reset-battle command can reopen that attempt without treating it as a new NPC entity.

Victory-based rematch cooldowns begin when the player defeats the trainer. A defeat against the trainer does not start that victory cooldown. Other access rules and limits still apply.

The command accepting an NPC UUID looks up that NPC's trainer identity; it does not imply that all underlying history is stored per entity UUID. Give independent encounters separate trainer IDs when their progress must stay separate.

Configuration content versus translation

The mod's interface labels and built-in messages belong in Minecraft language resources. Server-authored names, dialogue, descriptions, commands, item IDs, species IDs, and custom resource identifiers are content chosen by the server owner.

Translating an editor label does not translate or rename the serialized ID it edits. Keep identifiers such as minecraft:diamond, pikachu, ground_idle, and your trainer IDs intact. Resource packs can override the interface language entries without changing server configuration.