Commands: Battler Attributes
Section 4.B.5
These are keys which trigger something to happen to a battler, such as changing its attributes or effects, changing its stats, or manipulating its HP.
"battlerHP" => Integer or Array
Changes the HP of the battler. When set to a positive integer, the battler's HP will be restored by that percentage of its total HP. When set to a negative integer, the battler's HP will be reduced by that percentage instead.
For example, if this is set to 25, the battler will restore 25% of its total HP. If set to 100, the battler will restore 100% of its total HP. However, if you inverse these to negative numbers instead, the battler will have their HP reduced by 25% or 100%, respectively. If you set this to 0 instead of a positive or negative number, the battler's HP will always be set to 1 HP, regardless of whatever its current amount is.
If you set this as an array, you can include a string as the second argument of the array to display a custom battle message that occurs when the battler's HP is changed. You can use {1} in this string to refer to the specific battler's name.
"battlerHPCap" => Integer
This sets an HP threshold for the battler that will cap how much damage it can possibly take from direct attacks. For example, if this is set to 25, the battler's HP will be prevented from dropping below 25% of its max HP when it is struck by an attack, regardless of how strong the attack was. If set to 100, the battler will prevent any damage being taken by an attack at all. If you set this to 0, the battler will survive an attack with 1 HP. This can be used to design boss-like encounters who trigger certain actions when their HP reaches certain thresholds. Note however that this only affects damage taken by attacks, so any indirect damage may still reduce the battler's HP below the set damage cap.
"battlerStatus" => Symbol or Array
Changes the status condition of the battler. If set to a symbol, you may enter the ID of a specific status to inflict that status on the battler. For example, :BURN would inflict a burn on the battler. You can also use the symbols :TOXIC or :CONFUSION to apply toxic Poison or to make the battler confused, respectively. If you want to cure the battler of its status conditions, you can use the symbol :NONE to remove them. Note that this will also remove the confusion and infatuation conditions, too. If you want to set a random status condition, you can simply set an array of different status symbols, and a random one will be chosen out of that array.
Another way to use an array is to have the first item of the array be a status symbol (or array of status symbols), and the second item in the array may be set to true in order to display certain success/failure messages in applying that status condition.
"battlerForm" => Integer, Symbol, or Array
Changes the battler's form, if possible. If set to an integer, the battler will change to that form number, if one exists. You may also set this to :Random to change the battler into a random form out of all of its eligible forms, or you can set this to :Cycle for the battler to cycle through to its next form in order. For example, if the battler is Deoxys and :Cycle is set, Deoxys will shift from Normal form to Attack, Defense, then Speed, and then back to Normal again, each time its form is changed with :Cycle.
Note however that certain forms, such as Mega and Primal forms, are not considered eligible forms with this setting, and will be ignored. So you cannot force a Charizard to become Mega Charizard X with this setting. Pretty much everything else however is fair game.
You may also set this to an array if you'd like, and if you do, you may set the second item in this array as a string so that a custom message may appear when the battler changes form. If you set this second item to true instead, then a generic transform message will appear instead. Otherwise, no message will display.
Note that a battler cannot have its species changed if it's currently under the effects of a special form or state, such as Mega Evolution, Ultra Burst, Dynamax, or Terastallization. It also cannot change species if it's currently in a semi-invulnerable state due to moves like Fly or Dig, or lifted up in the air due to Sky Drop.
"battlerSpecies" => Symbol or Array
Changes a battler's species. Set this to a species ID such as :PIKACHU to change the species of that battler. Note that this is a permanent change, so the battler will not revert once switched out. In the case of the player's Pokemon, this means that their Pokemon will be permanently changed as well even once they leave battle, so be careful in how you apply this. NPC's Pokemon are re-generated from their PBS data whenever battle is initiated, so these effects won't persist out of battle for them.
If you set this as an array, you can include a string as the second argument of the array to display a custom battle message that occurs when the battler changes species. You can use {1} in this string to refer to the specific battler's name, {2} to refer to the new species name, and {3} to refer to the name of the trainer who owns that battler.
Note that a battler cannot have its species changed if it's currently under the effects of a special form or state, such as Mega Evolution, Ultra Burst, Dynamax, or Terastallization. It also cannot change species if it's currently in a semi-invulnerable state due to moves like Fly or Dig, or lifted up in the air due to Sky Drop.
"battlerEvolve" => Symbol or Array
Forces a battler to evolve during battle. Unlike normal evolution, battle evolutions cannot be cancelled and do not require any sort of evolution methods or criteria to be met; you can evolve any species at any point in battle. So for example, you can force Pikachu to evolve into Raichu without a Thunder Stone requirement.
You can set this to :Next to force the battler to evolve into the next evolutionary stage listed in that species' PBS data. If the species has multiple branches it can evolve into, such as Eevee, you can set this to :Random to choose a random evolution out of all possible branches. If the battler is already fully evolved and has no evolution data, nothing will happen when these symbols are set.
If you'd like to set a specific species for the battler to evolve into, you can set a specific species ID such as :PIKACHU, instead. Note that you can force a battler to evolve into any species if you set a specific species ID in this way, even if it's a species that would otherwise be impossible for that battler to evolve into. For example, if you set this to :MEWTWO, you can make the battler evolve into Mewtwo even though that would be impossible normally. However, if you set the species ID to the same species that the battler already is, then nothing will happen.
If you set this as an array, you can include a number as the second item in the array to set the form of the battler prior to evolution. This can be used to force a battler to evolve directly into a specific form of a species. For example, if set as [:RAICHU, 1], this will force the battler to evolve specifically into Alolan Raichu.
When a battler owned by the player evolves into a species that learns new moves upon evolving, it will be prompted to learn those moves like it normally would. However, if the battler is wild or owned by an NPC trainer, it will automatically have those evolution moves added to its moveset silently, without any prompts. A battler that evolves during battle will be considered a "new" battler once evolution is complete, meaning any effects the battler suffered from before evolution will be removed, similarly to how they would be they had been switched out of battle. However, any effects that would be carried over with the effects of Baton Pass (such as stat stages) will still be retained by the evolved battler.
Note that a battler cannot be forced to evolve if it's currently under the effects of a special form or state, such as Mega Evolution, Ultra Burst, Dynamax, or Terastallization. It also cannot evolve if it's currently in a semi-invulnerable state due to moves like Fly or Dig, or lifted up in the air due to Sky Drop.
"battlerAbility" => Symbol or Array
Changes the battler's ability. If set to an ability ID symbol, the battler's ability will be changed to that ability. This won't work however if the battler currently has an ability that cannot be removed, or if the ability you're attempting to give it is an ability that can only be utilized by a specific species. If you want to reset the battler's ability back to its original ability, you can use the symbol :Reset, instead.
If you want to assign a random ability to the battler out of a list, you can simply enter this as an array of ability ID's, and a random one will be chosen out of that array. If you want to alert the player of this ability change, you may enter this as an array where the first item in the array is the ability ID (or array of ability ID's), and the second item of this array may be set as either true, or a string containing a custom message. If neither are included, then the battler's ability will be changed silently, without alerting the player.
"battlerItem" => Symbol or Array
Changes the battler's held item. If set to an item ID symbol, the battler's held item will be changed to that item. This won't work however if the battler is currently holding an item that cannot be removed. If you want to remove a battler's held item without replacing it with another, you can use the symbol :Remove, instead.
If you want to assign a random held item to the battler out of a list, you can simply enter this as an array of item ID's, and a random one will be chosen out of that array. If you want to alert the player of this item change, you may enter this as an array where the first item in the array is the item ID (or array of item ID's), and the second item of this array may be set as either true, or a string containing a custom message. If neither are included, then the battler's item will be changed silently, without alerting the player.
"battlerMoves" => Symbol or Array
Changes the battler's moves. If set to a move ID, the battler will have that move added to their moveset. If their moveset is already full, their first move will be deleted and their moveset will shift up by one to make room for the new move. If you want to reset the battler's moveset back to the normal moves it would typically have at that level, you can use the symbol :Reset instead.
If you want to change multiple moves in a battler's moveset, you may instead enter this as an array of move IDs, and each move ID will replace the existing move located at that index in the battler's current moveset. If you want to simply delete a move in a battler's moveset instead of replacing it with anything, you can just enter nil at that index.
"battlerStats" => Array or Symbol
Changes the battler's stat stages. Set this to an array containing the ID of the stat you want to change, followed by the number of stages you want to change it by. For example, entering [:ATTACK, 2] would increase the battler's Attack stat by 2 stages. You can enter as many stats as you want in this array, as long as it follows this pattern of symbols and numbers. If you want to decrease the stage of a particular stat, then you would just enter a negative number instead. For example, [:DEFENSE, -3] would lower the battler's Defense by 3 stages.
If you would like a random stat to be altered, then you can use :Random in place of a stat ID. This randomized stat will never be a stat that already appears in the array, however. So for example, if your stat array looks like [:SPEED, 1, :Random, -1], the random stat will never be Speed, since that stat is already going to be altered.
If you would like to reset all of a battler's stat stages back to zero, you may do so by entering the symbol :Reset, instead of an array. If you only want to reset a battler's increased stat stages to zero, then you would use the symbol :ResetRaised. Alternatively, if you only want to reset a battler's negative stat stages to zero, then you would use the symbol :ResetLowered.
"battlerEffects" => Array
Changes the effects that are applied to the battler. This is entered as an array that must contain at least two items; the first item in the array must be the symbol of the specific effect you'd like to alter or apply, and the second item in the array must be the value you want to set this effect to. Optionally, you may enter a string as the third item in this array, which will display a custom message when applying this effect. For example, you may enter this as [:Endure, true] to silently apply the Endure effect on a battler, or you could set something like [:FocusEnergy, 2, "{1} is getting pumped!"] to set the battler's Focus Energy effect to 2 and announce it to the player.
You may even enter multiple different effects to be applied all at once if you want, by making an array of arrays, like this:
[[:Rage, true],
[:NoRetreat, true],
[:PerishSong, 3, "{1} will faint in three turns!"]]
Last updated