Essentials Docs Wiki
For when the AI is used, see Battle round.

This page describes the battle AI (artificial intelligence). That is, how computer-controlled opponents in battle (both wild Pokémon and enemy/ally trainers) choose which moves to use and which items to use when. This page assumes the AI controlling an enemy trainer, although it applies for wild Pokémon and partner trainers too.

This is a complicated topic, and unnecessary for most users. Do not attempt to modify the AI unless you have decent scripting knowledge.

Levels of AI

The basic principle of AI in Essentials is that better trainers should be cleverer than worse trainers. A cleverer AI has access to more information about the battle and is more informed about various effects of moves/abilities/items/other effects.

When defining a trainer type, one of the properties that can be defined is a skill level. This is usually the same as the trainer type's base money payout. A higher skill level represents a better AI.

By default, there are 5 tiers of AI in Essentials:

  • Wild Pokémon - If the Pokémon the AI is controlling is a wild Pokémon, it will have an equal chance of choosing each move they know. It will not do any other calculations. It has no special name.
  • Skill level 1-31 - The lowest tier for trainers. It has no special name.
  • Skill level 32-47 - Known as PBTrainerAI.mediumSkill.
  • Skill level 48-99 - Known as PBTrainerAI.highSkill.
  • Skill level 100+ - Known as PBTrainerAI.bestSkill.

There is also the value PBTrainerAI.minimumSkill, which is the lowest skill level a trainer can have. If a trainer's skill level is lower than this, it is raised to this, which may put it in a different tier if it is high enough. This is 1 by default.

All trainer types within a given tier will behave exactly the same. The only differences are between different AI tiers, where higher tiers have access to more information and improved calculations.

AI overview

The first thing the AI needs to do each turn is decide whether to use an attack, use an item, or switch their Pokémon with another one. This decision starts in the script section Battle_AI, in def pbDefaultChooseEnemyCommand.

Firstly, the AI decides whether it should use an item (AI_Itemdef pbEnemyItemToUse). This method goes through each item the AI has, and decides whether to use it. There are separate clauses in this decision for each type of item the AI has been programmed to recognise - it can recognise (and therefore use) only healing items, status-curing items and X items (e.g. X Attack). Some types of item take preference over others, e.g. if the Pokémon is poisoned, the AI will prefer using an Antidote over a Full Heal if it has one.

If the AI decides not to use an item, then it decides whether it can/should withdraw the Pokémon instead (AI_Switchdef pbEnemyShouldWithdrawEx?). This method looks at several factors in turn, including how good the opposing Pokémon's moves will do against it, whether it can use any moves itself, whether it is about to faint because of toxic poisoning or Perish Song, and so forth. This decision can flip-flop as it runs through each factor. Finally, if it has decided to switch Pokémon, the method decides which other Pokémon in the AI trainer's party is the best choice to switch in with, and does so.

If the AI won't switch Pokémon either, then it needs to choose a move to use (AI_Movedef pbChooseMoves). For each known move in turn, it calculates a score depending on various factors, including the function code and effectiveness of that move, the currently active abilities, move effects and weather, the user's held item and status, and how many Pokémon the player has left. It then compares the scores for each move, and chooses which move to use depending on these scores. If there are no good moves to choose from, there is another opportunity to switch the Pokémon out instead.

Just before it chooses a move to use, the AI will decide if it should Mega Evolve their Pokémon. By default, it will always choose to do so if possible.

Item recognition and effects

The AI needs to be programmed to recognise particular items. Currently it only recognises the basic Potions, Heal items and X stat raisers. This recognition is done in the script section AI_Item, in def pbEnemyItemToUse, where the items are listed in various hashes/arrays, some of which include descriptions of their effects (other items' effects are determined in other ways).

An item used by an AI uses the same code as the same item being used by the player. Only the decision of whether the AI can/should use the item is different.