---
title: Complete Guide to Pixelmon Battle Settings
description: Fine-tune Pokémon battles on your Pixelmon server with the settings in battle.yml. This guide explains how to customize core battle mechanics, including AI behavior, experience gains, weather effects, catching rules, turn handling, battle clauses, and more.
source: "https://nodecraft.com/support/games/minecraft/mods/pixelmon/complete-guide-to-pixelmon-battle-settings"
image: "https://dynamic-assets.nodecraft.com/signedurl/w7vokBAexMnVlnMZ1Q/image.jpg?modifications=W3sibmFtZSI6ImdhbWVfYmciLCJpbWFnZV91cmwiOiJodHRwczovL2Ntcy1hLm5vZGVjcmFmdC5jb20vZi8xMzM5MzIvMjAwMHg1NTAvZGNiMGFkNjkzOC9jYXZlcy1hbmQtY2xpZmZzLXB0LTItMS0yLTAucG5nL20vIn0seyJuYW1lIjoiZ2FtZV9sb2dvIiwiaW1hZ2VfdXJsIjoiaHR0cHM6Ly9jbXMtYS5ub2RlY3JhZnQuY29tL2YvMTMzOTMyLzM3NXgxNTAvM2MxZGIyYmFiNS9taW5lY3JhZnQucG5nL20vIn0seyJuYW1lIjoiY3RhX3RleHQiLCJ0ZXh0IjoiQ3JlYXRlIHlvdXIgb3duIHNlcnZlciEifSx7Im5hbWUiOiJ0ZXh0IiwidGV4dCI6IkNvbXBsZXRlIEd1aWRlIHRvIFBpeGVsbW9uIEJhdHRsZSBTZXR0aW5ncyJ9XQ&s=e5e1405a4f0bc52adc1608a64d743fcd11d176a23fdd9310cb3a23715a909f6e"
published: "2026-08-16T23:26:01.799Z"
updated: "2026-08-16T23:26:01.799Z"
---

# Complete Guide to Pixelmon Battle Settings

Fine-tune Pokémon battles on your Pixelmon server with the settings in battle.yml. This guide explains how to customize core battle mechanics, including AI behavior, experience gains, weather effects, catching rules, turn handling, battle clauses, and more.

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.