Complete Guide to Pixelmon Battle Settings

The Battle section contains the options Pixelmon uses for this part of the server. Configure battle AI, experience, weather, catching, turn behavior, clauses, and other core combat mechanics.

Pixelmon Battle Settings

The settings below are listed in the same order as they appear in battle.yml. The table preserves each default and identifies the accepted value type. The Setting column shows a reader-friendly name first, followed by the matching battle.yml key for reference.

Setting and Config Key	Default and Accepted Values	Description
Battle A I Wild Type battle-a-i-wild-type	Default: pixelmon:random Values: text value	The type of battle AI that the wild Pokemon will use. The options are: - 'pixelmon:random' - The pokemon will use moves randomly - 'pixelmon:aggressive' - The pokemon will use the move that will deal the most damage, and avoid status moves - 'pixelmon:tactical' - The pokemon will know how to use status moves with offensive moves - 'pixelmon:advanced' - The pokemon will do everything from tactical and also know when to switch
Battle A I Boss Type battle-a-i-boss-type	Default: pixelmon:aggressive Values: text value	The type of battle AI that the boss pokemon will use. The options are: - 'pixelmon:random' - The pokemon will use moves randomly - 'pixelmon:aggressive' - The pokemon will use the move that will deal the most damage, and avoid status moves - 'pixelmon:tactical' - The pokemon will know how to use status moves with offensive moves - 'pixelmon:advanced' - The pokemon will do everything from tactical and also know when to switch
Multiple Photos Of Same Pokémon multiple-photos-of-same-pokemon	Default: true Values: true or false	Determines if the player can take multiple photos of a single pokemon
Relaxed Battle Gimmick Rules relaxed-battle-gimmick-rules	Default: true Values: true or false	Whether which battle gimmick can be used is determined purely by band chosen
Battle Music Volume battle-music-volume	Default: 1.0 Values: decimal number	Volume of the music that is played during battles
Allow P V P Experience allow-p-v-p-experience	Default: true Values: true or false	Whether or not Pokémon can gain experience when battling other players
Allow Trainer Experience allow-trainer-experience	Default: true Values: true or false	Whether or not NPC Trainers' Pokémon award experience upon defeat
Return Held Items return-held-items	Default: true Values: true or false	If enabled, consumable held items used up during player vs. player battles will be restored when the battle ends
Return Held Items P V E return-held-items-p-v-e	Default: true Values: true or false	If enabled, consumable held items used up during player vs. player battles will be restored when the battle ends for PVE battles (e.g., wild Pokémon, NPC Trainers).
Force End Battle Result force-end-battle-result	Default: WINNER Values: text value	This setting determines what will occur if a battle is ended without a proper conclusion (e.g., too many errors in battle, player death while in battle). Determining an official winner and loser only matters for certain aspects, such as the /pokestats command, NPC Trainers that give items upon defeat, or Pixelmon sidemods that manipulate battle wins and losses. The Different Modes are as Follows: - WINNER - A winner will be chosen based on which battler has more pokemon remaining, of which has the most HP remaining on their team - DRAW - The battle gets declared as a draw - ABNORMAL - The battle is considered to have ended abnormally
EXP Modifier exp-modifier	Default: 1.0 Values: decimal number	Multiplier for experience gained in Pokémon battles
Synchronize Chance synchronize-chance	Default: 1.0 Values: decimal number	Chance for Synchronize to sync nature on battle start. (1 is 100% chance, 0.5 is 50% chance)
Allow Happy Hour allow-happy-hour	Default: true Values: true or false	Whether Happy Hour will award PokéDollars when used
Happy Hour Multiplier happy-hour-multiplier	Default: 2 Values: whole number	The multiplier for how many PokéDollars will be awarded by using Happy Hour (2.0 = 2x Multiplier)
Allow Pay Day allow-pay-day	Default: true Values: true or false	Whether Pay Day will award extra PokéDollars when used
Pay Day Multiplier pay-day-multiplier	Default: 5.0 Values: decimal number	The multiplier for how many PokéDollars will be awarded by using Pay Day (5.0 = 5x Multiplier)
Allow G Max Gold Rush allow-g-max-gold-rush	Default: true Values: true or false	If G-Max Gold Rush will award extra PokéDollars when used.
G Max Gold Rush Multiplier g-max-gold-rush-multiplier	Default: 100.0 Values: decimal number	The multiplier for how many PokéDollars will be awarded by using G-Max Gold Rush
Allow Amulet Coin allow-amulet-coin	Default: true Values: true or false	Whether Amulet Coin will award double PokéDollars when used.
Amulet Coin Multiplier amulet-coin-multiplier	Default: 2 Values: whole number	The multiplier for how many PokéDollars will be awarded by using Amulet Coin (2.0 = 2x Multiplier)
Pickup Rate pickup-rate	Default: 10 Values: whole number	The rate (1/x) that Pickup will collect special drops at. 0 disables this.
Allow Catch Combo allow-catch-combo	Default: true Values: true or false	Allows chaining catches to get bonus exp, higher shiny and perfect iv rates. If false, all captures use the first threshold listed.
Catch Combo Thresholds catch-combo-thresholds	Default: [0, 10, 20, 30, 40] Values: list	Catch Combos count thresholds at which the effects of the combo change. Default values give the combo ranges 0, 1-10, 11-20, 21-30, 31-40, and 41+.
Catch Combo EXP Bonuses catch-combo-exp-bonuses	Default: [1.0, 1.100000023841858, 1.5, 2.0, 2.5, 3.0] Values: list	Catch Combos exp bonuses per threshold.
Catch Combo Shiny Modifiers catch-combo-shiny-modifiers	Default: [1.0, 1.0, 1.399999976158142, 1.7999999523162842, 2.200000047683716, 2.200000047683716] Values: list	Catch Combos shiny modifiers per threshold.
Catch Combo Perfect I Vs catch-combo-perfect-i-vs	Default: [0, 0, 2, 3, 4, 4] Values: list	Catch Combos perfect IVs per threshold.
Scale Grass Battles scale-grass-battles	Default: false Values: true or false	Whether or not the levels Pokémon found in Pixelmon grass will scale to the level of the player's highest-leveled Pokémon.
Overworld Weather Affects Wild Battle Weather overworld-weather-affects-wild-battle-weather	Default: true Values: true or false	Whether a battle with a wild Pokémon should start with its weather reflecting the weather of Minecraft's Overworld.
Overworld Weather Affects Trainer Battle Weather overworld-weather-affects-trainer-battle-weather	Default: true Values: true or false	Whether a battle with a NPC Trainer should start with its weather reflecting the weather of Minecraft's Overworld.
Overworld Weather Affects Pv P Battle Weather overworld-weather-affects-pv-p-battle-weather	Default: false Values: true or false	Whether a PvP battle should start with its weather reflecting the weather of Minecraft's Overworld.
Overworld Weather Affects Raid Battle Weather overworld-weather-affects-raid-battle-weather	Default: false Values: true or false	Whether a raid battle should start with its weather reflecting the weather of Minecraft's Overworld.
Overworld Weather Can Change Battle Weather During Battle overworld-weather-can-change-battle-weather-during-battle	Default: true Values: true or false	Whether Minecraft's weather in the Overworld should change battle weather during the battle, not just at the beginning of the battle. This shouldn't change battle weather that is created by players via an ability or move.
Players Can Move During Pv P Battles players-can-move-during-pv-p-battles	Default: true Values: true or false	Whether players can escape the battle menu during a PvP match to walk around and do other actions without having to forfeit or win their battle. This option must also match the battle rule of the battle being entered (defaults to false) (`pixelmon:exitable`)
Players Can Move During Wild Battles players-can-move-during-wild-battles	Default: true Values: true or false	Whether players can escape the battle menu during a wild Pokémon encounter to walk around and do other actions without having to forfeit or win their battle. This option must also match the battle rule of the battle being entered (defaults to false) (`pixelmon:exitable`)
Players Can Move During Trainer Battles players-can-move-during-trainer-battles	Default: true Values: true or false	Whether players can escape the battle menu during a battle with an NPC trainer to walk around and do other actions without having to forfeit or win their battle. This option must also match the battle rule of the battle being entered (defaults to false) (`pixelmon:exitable`)
Players Can Move During Raid Battles players-can-move-during-raid-battles	Default: false Values: true or false	Whether players can escape the battle menu during a Raid battle to walk around and do other actions without having to forfeit or win their battle. This option must also match the battle rule of the battle being entered (defaults to false) (`pixelmon:exitable`)
Max Distance Players Can Move Away From Battles max-distance-players-can-move-away-from-battles	Default: 30 Values: whole number	The maximum distance away from the (furthest) of the Pokémon on the battlefield a player may travel before the battle is ended.
Min Distance Before Warning Vignette min-distance-before-warning-vignette	Default: 20 Values: whole number	The minimum distance away from any of the battle Pokémon the player must be before the warning vignette is shown.
Store Last Battle store-last-battle	Default: false Values: true or false	This setting determines if the player's party will store the log for the last battle they were in. This is incredibly useful for testing battles where you might forget to log the battle before it ends. It is set to false by default as for servers this will use incredibly large amounts of RAM.

Important Battle Setting Notes

Defaults and Value Types

Boolean toggles, numeric rates, timers, lists, and mappings use different value formats. Preserve the value type shown in the table and keep collection syntax intact when changing battle.yml.

Settings That Work Together

Several battle options can affect the same outcome. Review related rates, limits, timers, and lists together before deciding that one value is responsible for a result.

Testing Changes

Change one related group of settings at a time so its effect is easy to measure.
Test the result under the conditions affected by the setting, including relevant dimensions, player states, or encounter types.
Keep a copy of the previous values so unexpected balance or performance changes can be reversed quickly.

Final Thoughts

Battle settings are easier to balance when changes are deliberate and documented. Start with the defaults, adjust only what the server needs, and verify the result before moving on to the next group.

Need Help?

If you have questions or run into any issues, our support team is here to help! Reach out using the support widget on our website or visit our support center for further assistance.