Commands: Battle Mechanics

Section 4.B.4

These are keys which trigger certain actions to take place during battle, such as forcing a trainer to use an item or switch out, or toggling the availability of the player's Poke Balls.

"useItem" => Symbol or Array

Forces a trainer (or a wild Pokemon) to use an item on the battler. The item does not have to be in the trainer's inventory to be used, nor will it be removed from their inventory if it is. If the set item doesn't have any in-battle use, or if the item wouldn't have any effect, then nothing will happen.

If the set item is any type of Poke Ball, then the ball will always be used by the player and thrown at the opposing Pokemon, even if the battler who triggered the item to be used is an opposing Pokemon. This is because only the player can use and throw Poke Balls, so this will always default to the player's item, regardless of who triggers the item to be used.

If a PP-restoring item is used that would normally require a move to be selected to be used, such as an Ether or Leppa Berry, then these items will just automatically select the move with the lowest PP to use itself on. If you want to select a random item to be used 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.

"useMove" => Integer, Symbol, String, or Array

Forces a battler to use a specific move in their moveset during their turn, regardless of whatever their actual selected move was going to be this turn. This won't work if the battler has already moved this turn, or if a different action has been chosen besides using a move, such as switching or using an item. This also won't work if the battler is under some condition that would prevent it from using a different move, such as being in the charging turn of a different attack, having zero PP for the selected move, or being under the effects of things like Encore, Disable, or Choice Band. Lastly, this also will fail to work if the battler's naturally selected move is a Z-Move or a Dynamax move, as those cannot be overridden by a normal move. If this is set as an integer, then the move that the battler will be forced to use will be whatever move appears at the index of that integer. For example, if set to 1, then the battler will be forced to use whatever move appears second in its moveset (since the first index counted would be 0). Alternatively, you can set this to a move ID symbol instead, and the battler will be forced to use that move as long as it appears in their moveset. If you set this as an array, you may also include an integer as the second argument of the array to specify a particular target for the move. This isn't necessary if the move is a self-targeting move, or doesn't specifically target anyone. If the specified target cannot be found, or isn't eligible, then the first eligible target that can be found will be set instead. If you don't want to specify which specific move the battler should use, but want to apply a more general rule for which kinds of moves it should use, you may do so by setting a string instead of using indexes or move ID's. If it has multiple moves that fit the inputted criteria, it will select a random one to use among those moves. Here are the possible strings you can use to narrow down the kinds of moves that should be used:

• "Damage" This will force the battler to select only damage-dealing moves to use, if able. If you use "Damage_foe" instead, this will specify further that it should only pick damage-dealing moves that will damage opponents, or you can use "Damage_ally" to specify that it should only pick damage-dealing moves that will damage an ally.

• "Heal" This will force the battler to select only healing moves to use, if able. A healing move is any move where healingMove? returns true. If you use "Heal_self", this will specify further that it should only pick healing moves that target the user, like Recover. If you use "Heal_ally", this will specify that only healing moves that are capable of targeting an ally should be picked, like Heal Pulse. If you use "Heal_foe", this will specify that only healing moves that are capable of targeting a foe should be picked, like Leech Life.

• "Status" This will force the battler to select only non-healing status moves, if able. If you use "Status_self", this will specify further that it should only pick status moves that target the user, like Swords Dance. If you use "Status_ally", this will specify that only status moves that are capable of targeting an ally should be picked, like Helping Hand. If you used "Status_foe", this will specify that only status moves that are capable of targeting a foe should be picked, like Thunder Wave.

"switchOut" => Integer, Symbol, or Array

Forces the battler to switch out with another one in the party. This key doesn't do anything if there are no other eligible Pokemon to switch to in the battler's party, or if the battler is unable to switch out for some reason. When set to an integer, the new Pokemon that will be sent out will be the one that matches the party index of that integer. For example, if set to 2, then the trainer will send out the Pokemon that appears third in their party line up (since the first index counted would be 0).

Alternatively, you may set this to a species ID symbol, and the trainer will send out the first Pokemon in their party line up that matches that species. For example, if you set this to :PIKACHU, the trainer will always send out a Pikachu, if they have one in their party. If they have multiple Pokemon of the same species, then the first able one in their party will be the one that gets sent out. 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 is switched out. You can use {1} in this string to refer to the specific battler's name. If you don't want to specify which Pokemon the trainer will switch to, there are alternate symbols you may use for this purpose instead of using indexes or species ID's:

• :Choose This will allow the trainer to decide for themselves what the next Pokemon sent out should be. If this is the player, then they will manually choose a Pokemon from the party menu. If this is an AI trainer, then they will select the best Pokemon to send out based on their skill level.

• :Random This will choose a totally random Pokemon from the trainer's party to send out.

• :Forced This functions identically to :Random, except the messages that display will indicate that the trainer is being forced to make this switch, instead of by choice (similar to how moves like Roar and Whirlwind work).

"megaEvolve" => Boolean or String

Forces the battler to Mega Evolve when set to true, as long as they are able to. If set to a string instead, you can customize a message that will display upon this Mega Evolution triggering. Note that this can even be used to force a wild Pokemon to Mega Evolve, as long as they are holding the appropriate Mega Stone, or has the required Mega Move. Unlike natural Mega Evolution, you can use this to force Mega Evolution to happen at any point in battle, even at the end of the turn or after the battler has already attacked. This cannot happen if a different action with this battler has been chosen however, such as switching it out or using an item.

"disableMegas" => Boolean

Toggles the availability of Mega Evolution for the owner of the battler. If set to true, Mega Evolution will be disabled for this trainer. If set to false, Mega Evolution will no longer be disabled, allowing this trainer to use it again even if they've already used Mega Evolution prior in this battle.

"disableBalls" => Boolean

Toggles the player's ability to throw Poke Balls during this battle. If set to true, Poke Balls will be disabled. When set to false, this flag is removed, allowing the trainer to throw Poke Balls again.

"disableItems" => Boolean

Toggles the ability of all trainers participating in this battle to use items from their inventory during this battle. If set to true, item usage will be disabled. When set to false, this flag is removed, allowing all trainers to use items again.

"disableControl" => Boolean

Toggles the player's ability to input controls. If set to true, the player's control will be disabled and the AI will control the inputs of the player's character. When set to false, this flag is removed, allowing controls to return to the player.

"endBattle" => Integer

Prematurely ends the battle. This can be used to end a battle early, and manually set its outcome. This is done by setting this to one of the following integers:

• 1: Ends the battle as if the player won.

• 2: Ends the battle as if the player lost.

• 3: Ends the battle as if the player ran/forfeited.

• 4: Ends the battle as if the player won (identical to 1).

• 5: Ends the battle as if it ended in a draw (identical to 2 in most cases).

"wildFlee" => Boolean or String

This wont do anything unless the battler is a wild Pokemon. Setting this to true will force the wild Pokemon to flee, prematurely ending the battle. If you set this to a string instead, whatever text you enter will be displayed as the flee message for the wild Pokemon. You can use {1} in this string to refer to the wild Pokemon by name.