Skip to content

Rewards, messages, and battle events

Victory and defeat are described from the player's perspective in reward command settings. on_victory_commands runs when the player defeats the NPC; on_defeat_commands runs when the player loses.

Command rewards

Field Trigger
first_victory_commands The player's recorded victory counter becomes 1.
on_victory_commands Every recorded player victory, including the first.
on_defeat_commands Every recorded player defeat.

Commands run from the server command source. Write one command per JSON-array entry, without a leading /. %player% is replaced with the player's account name and %trainer% with the trainer display name.

{
  "first_victory_commands": [
    "give %player% cobblemon:rare_candy 3",
    "tag %player% add rock_badge"
  ],
  "on_victory_commands": [
    "give %player% greatnpc:coin_gold 2"
  ],
  "on_defeat_commands": [
    "tellraw %player% {\"text\":\"Train your party and try again!\",\"color\":\"yellow\"}"
  ]
}

This is a preset settings fragment; retain a valid team reference in the full file. Confirm item IDs against the installed registry. Commands may call other installed mods when those mods expose server commands.

First-victory commands run before the normal victory commands. Reward commands are executed after the history update. A command failure is logged; it does not roll back the recorded victory or prevent an already-executed earlier command from having an effect. Keep rewards simple and test them on a staging world.

Resetting the victory counter with /gnpc resetfirst can make first-victory rewards available again. Resetting only the one-battle attempt with /gnpc resetbattle does not reset first-victory rewards.

Player messages

Field Trigger
intro_message After the battle has successfully started; it can also supply the default dialogue greeting.
victory_message Player wins.
defeat_message Player loses.
broadcast_victory Broadcast after a player victory.

These are server-authored content strings and support the mod's text formatting/parser and placeholders. Built-in interface labels belong in resource-pack language files; authored dialogue and custom reward text are content you choose for that NPC.

{
  "intro_message": "<gold>Let's see what your team can do!</gold>",
  "victory_message": "<green>Well played, %player%!</green>",
  "defeat_message": "<yellow>There is always another strategy.</yellow>",
  "broadcast_victory": "<gold>%player% defeated %trainer%!</gold>"
}

Healing and animations

heal_player_before heals before battle after access and party rules pass. heal_player_after heals after a recorded result, whether the player won or lost.

anim_battle_start is the NPC's start animation. anim_defeat plays when the NPC loses (the player wins), while anim_victory plays when the NPC wins. Animation names depend on the selected model and its assets.

The interaction action system receives battle_start, battle_win, and battle_lose events; the win/lose event names here use the player's perspective. Use supported actions in the editor rather than assuming a missing animation or command creates a new mechanic.

Test battles

/gnpc test, while looking at an NPC within eight blocks, starts an administrator test battle. Test battles bypass progression restrictions and do not generate normal recorded rewards or result-history changes. They also skip the normal introduction. Test reward commands through a normal challenge, then reset the test account's history if needed.

For the separate audit trail, see Battle log.