Item AI: Handlers

Section 7.G.1

The AI for each individual item is implemented modularly, similar to how the AI for individual moves is implemented in base Essentials. You can create your own AI item handler for any item you want that is usable in battle. However, the type of handler you need to use varies based on that specific item's BattleUse property, which is set in the items.txt PBS file.

There are three different types of handlers that can be set for specific items, and a fourth handler which can be set for more general application. I will outline the specifics of each handler type below.

Note that the AI skill level of a particular trainer can significantly change the performance of each handler.

Handler: PokemonItemEffectScore

This is the handler used for items that have BattleUse = OnPokemon set in their PBS data. Items with this type of battle use can be used on both active battlers and party Pokemon in reserve. This is the most common way an item can be used in battle, so this is the most commonly used handler.

Below are all of the items that use this handler, and a general description of how the AI is scripted to use them. If you want to see specific examples of this type of AI item handler, they can be found in the plugin file named [002] OnPokemon Handlers.

HP Healing Items

This includes all items included in the HP_HEAL_ITEMS hash located in AI_UseItem in base Essentials. The AI will typically not care to use these items if the Pokemon in their party are still healthy and have roughly 55% of their HP or more remaining. Otherwise, the AI will score the value of using any particular healing item by calculating how much HP the item would recover vs how much wasted healing the item would do.

For example, if a Pokemon's HP is at 40/100, using a Hyper Potion would be wasteful since Hyper Potions heal 120 HP, meaning that 60 points of healing would be wasted on healing this Pokemon. If the AI has access to something like a Super Potion in their inventory, then they will be more incentivized to use that item instead, since it only heals 50-60 HP which would not result in any waste.

Generally, healing will be prioritized more on active battlers if any are predicted to faint this turn due to indirect damage such as through statuses like Poison, or other effects. Depending on the AI's skill level, it will also prioritize healing if the only valid target to heal is their final remaining Pokemon in their party.

Pokemon that have any attributes that would prefer higher HP will also cause the AI to be more likely to heal them. These attributes include things like having moves that deal more damage based on how high the user's HP is (Water Spout, Eruption, Final Gambit, etc), held items that only trigger at full HP (Focus Sash), abilities that only trigger at full HP (Multiscale, Sturdy, etc), or if the Pokemon is below half HP and they have an ability that can re-trigger each time their HP falls below half (Berserk, Anger Shell) or an an ability like Defeatist that weakens them if their HP is low.

Here's a list of every item that uses this AI:

  • Potion

  • Super Potion

  • Hyper Potion

  • Max Potion

  • Full Restore

  • Berry Juice

  • Sweet Heart

  • Fresh Water

  • Soda Pop

  • Lemonade

  • Moomoo Milk

  • Oran Berry

  • Sitrus Berry

  • Energy Powder

  • Energy Root

  • Rage Candy Bar (depending on Generation)

Note that for the Full Restore in particular, this item is treated as a combination of a Max Potion and a Full Heal. So the AI calculations for both of these items are combined when determining whether or not to use one. If using a Full Restore would both recover HP and also heal a status condition at the same time, then it will be more highly prioritized. If using a Full Restore would only heal HP, then it will be less prioritized compared to the other items on this list.

Single Status Cure Items

This includes all items included in the ONE_STATUS_CURE_ITEMS array located in AI_UseItem in base Essentials. The AI for these items will differ based on which status condition is being healed.

Generally speaking, the AI will not waste using these items on a Pokemon who is already holding an item that will trigger to cure their current status condition (such as status cure berries), or if they have an ability that may do the same. It will also not waste these items if the Pokemon would actually prefer to keep its status condition for some reason, such as if it's powered up by an ability like Guts or Toxic Boost, or receives passive benefits from it through abilities like Poison Heal. If the status condition deals indirect damage, but the Pokemon is immune to indirect damage thanks to the Magic Guard ability, then the AI will not waste the items healing the condition. The AI will also be less incentivized to use these items if the battler or its ally partner has an ability that may prematurely end its status condition, such as Shed Skin, Healer, or Natural Cure, or if the battler has the Hydration ability in the rain. This is also true if the Pokemon is an active battler and already has moves that can cure its status condition (Refresh, Rest, Heal Bell, etc.), or has a move that actually prefers to keep its condition (Facade).

Finally, if the Pokemon is a battler with low HP or is predicted to faint this round due to the indirect damage of a status condition, then the AI will be more likely to want to cure the condition. If the status condition affects one of the battler's stats, such as Burn does with Attack or Paralysis does with Speed, then the AI is more likely to want to cure this condition if that stat is worthwhile to the battler.

Here's a list of every item that uses this AI:

  • Awakening

  • Chesto Berry

  • Blue Flute

  • Antidote

  • Pecha Berry

  • Burn Heal

  • Rawst Berry

  • Paralyze Heal

  • Cheri Berry

  • Ice Heal

  • Aspear Berry

Note that when the Blue Flute in particular is used on an active battler, there is an additional check to see if the battler has the Soundproof ability. If so, the AI will be unable to use this item to cure the Sleep condition.

Full Status Cure Items

This includes all items included in the ALL_STATUS_CURE_ITEMS array located in AI_UseItem in base Essentials. The AI for these items are identical to the single status cure items in the above section, except it will change based on the specific status condition.

Additionally, full status cure items may also heal confusion, which is also calculated by the AI when factoring in the total score. Typically, the AI will be less incentivized to use a full status cure item if they already have a single status cure item that can be used to cure the specific status instead. However, if the Pokemon is a battler who suffers from both a status condition and confusion at the same time, then the full status cure item will be prioritized more.

Here's a list of every item that uses this AI:

  • Full Heal

  • Full Restore

  • Lava Cookie

  • Old Gateau

  • Castelia Cone

  • Lumiose Galette

  • Shalour Sable

  • Big Malasada

  • Pewter Crunchies

  • Lum Berry

  • Heal Powder

  • Rage Candy Bar (depending on Generation)

Note that for the Full Restore in particular, this item is treated as a combination of a Max Potion and a Full Heal. So the AI calculations for both of these items are combined when determining whether or not to use one. If using a Full Restore would both recover HP and also heal a status condition at the same time, then it will be more highly prioritized. If using a Full Restore would only cure a status condition, then it will be less prioritized compared to the other items on this list.

Revival Items

This includes all items included in the REVIVE_ITEMS hash located in AI_UseItem in base Essentials. The AI behind using these items are comparatively simple compared to other items, as they will never be used unless the trainer has fainted Pokemon to revive. If so, they will have a high likelihood to use a revival item, especially if they're down to their last Pokemon, or the opponent has more remaining Pokemon than they do. Max Revive-like items that fully revive a Pokemon tend to be more highly prioritized.

If the AI has a relatively high skill and have multiple fainted Pokemon to revive, it will score each fainted Pokemon to revive based on how useful their moves would be versus the current opponents. For example, if there are two possible Pokemon to revive but one of them have moves that would deal Super Effective damage against the current opposing battlers, then that Pokemon is more likely to be revived than the other.

Here's a list of every item that uses this AI:

  • Revive

  • Max Revive

  • Revival Herb

  • Max Honey

PP Recovery Items

This includes all items included in the PP_HEAL_ITEMS and ALL_MOVE_PP_HEAL_ITEMS hashs located in [001] Battle_AI in this plugin's files. The AI will typically not care to use these items unless one of their Pokemon's moves have ran out of PP. If so, the AI will score the value of restoring PP to that move based on how much overall PP this would restore. If a Pokemon has multiple moves with PP worth restoring, it'll score each move individually to consider which is most worth restoring PP to.

Depending on the AI's skill level, status moves will generally be less desirable to restore PP to than damage-dealing moves. Also, the AI will be less incentivized to restore PP to Pokemon who have low HP, especially if their are HP healing items that could be used instead. If the Pokemon is an active battler and is predicted to faint this round anyway due to indirect damage, then the AI will not bother using PP recovery items at all.

Here's a list of every item that uses this AI:

  • Ether

  • Max Ether

  • Leppa Berry

  • Hopo Berry (Gen 9 Pack)

  • Elixir

  • Max Elixir

Handler: BattlerItemEffectScore

This is the handler used for items that have BattleUse = OnBattler set in their PBS data. Items with this type of battle use can only be used on an active battler owned by the trainer. This is used almost exclusively by X Items that boost a battler's stats, though there are a few other oddball items that also use this.

Below are all of the items that use this handler, and a general description of how the AI is scripted to use them. If you want to see specific examples of this type of AI item handler, they can be found in the plugin file named [003] OnBattler Handlers.

Stat Boosting Items

This includes all items included in both the ONE_STAT_RAISE_ITEMS and ALL_STATS_RAISE_ITEMS hashes located in AI_UseItem in base Essentials. The AI will generally want to use these items if the stat boost they grant would be relevant and useful to one of their active battlers. If the stat boost wouldn't be of any use, such as an Attack boost on a battler with only special moves, then the AI won't waste the item. The battler's current HP is also factored in when deciding to use a stat boosting item, as it would be pointless to use one on a battler who is unlikely to survive another hit, or is predicted to faint this turn anyway due to indirect damage.

If there are other scenarios where boosting a stat would be pointless or detrimental, such as if the foe has the Unaware ability or the user has the Contrary ability, then the AI will also not consider using the item. The AI will generally be less incentivized to use a stat boosting item if any of the opposing battlers have a move that could negate, steal, or invert the stat boost (Haze, Topsy Turvey, Psych Up, etc.), or have a move that will become more threatening with heightened stats (Punishment). If the user is under some effect or has some item/ability that prevents stat loss however (Mist, Clear Body, Clear Amulet, etc.), the AI will be more incentivized to use a stat boosting item since the battler is less likely to have it lowered again.

Generally speaking, if the battler already has a move in that can raise a particular stat, then the AI will be less incentivized to use an item on them that boosts that stat. This is especially true if the battler has a move that raises multiple stats at once.

Here's a list of every item that uses this AI:

  • X Attack

  • X Defense

  • X Sp. Atk

  • X Sp. Def

  • X Speed

  • X Accuracy

  • Max Mushrooms

Note that the improved versions of each X item that boost stats by 2, 3, or 6 stages also use this same AI. The number of stages the items boost by are factored in when deciding which to use. More stages are always better, unless the user is already nearly at the stat cap and any additional stages would be wasted.

The Max Mushrooms item uses this same AI too, but it runs the calculation 5 times for each of the main battle stats. It then combines the value of raising each worthwhile stat to determine its overall value.

Critical Hit Boosting Items

The AI will generally want to use these items on a battler if that battler is capable of utilizing a heightened critical hit ratio. This means that if the battler has no usable damage-dealing moves, then the AI won't bother using the item on them. This is also true if the battler would gain no benefit from the heightened crit ratio due to already stacking effects that guarantee a critical hit (Super Luck ability, critical hit boosting item, etc.).

The battler's current HP is also factored in when deciding to use a critical hit boosting item, as it would be pointless to use one on a battler who is unlikely to survive another hit, or is predicted to faint this turn anyway due to indirect damage. The AI will be incentivized to use the item on a battler if that battler's offensive stats have been lowered, as a critical hit would allow them to bypass those stat drops. The AI will also be more incentivized to use the item if the battler has moves or effects that can benefit from the heightened critical hit chance, such as the Sniper ability.

However, if the AI sees that the opposing Pokemon have an effect or ability that negates critical hits altogether (Lucky Chant, Battle Armor), or an ability that benefits them when critically hit (Anger Point), then the AI will be less incentivized to use the item. If the battler already has a move that can boost their own critical hit ratio, the AI will also be less incentivized to use the item. This is also true if the battler already has access to a move that is guaranteed to deal critical hits anyway (Frost Breath, Storm Throw), or if they have moves that deal fixed damage and cannot ever deal a critical hit.

Here's a list of every item that uses this AI:

  • Dire Hit

  • Dire Hit 2

  • Dire Hit 3

Note that the number of stages these items boost the battler's critical hit ratio by are factored in when deciding which to use. More stages are always better, unless the user is already nearly +3 and any additional stages would be wasted.

Confusion Curing Items

The AI will generally want to use these items on a battler if that battler is confused. However, the AI won't bother if the battler is holding an item or has an ability that will already cure their confusion. This is also true if the battler is predicted to faint this round anyway due to indirect damage.

Generally speaking, the more remaining turns of confusion the battler has left, the more incentivized the AI will be to cure it with these items. This is even more likely if the battler's Attack stat has been raised, since this means it may suffer even more self-inflicted damage from confusion. The AI will also be more incentivized to use these items if the battler is suffering additional conditions that may prevent it from acting, such as Paralysis or infatuation. The AI will be slightly less incentivized to cure confusion if the battler has an ability that prefers that the user is confused, such as the Tangled Feet ability.

Here's a list of every item that uses this AI:

  • Persim Berry

  • Yellow Flute

Note that when the Yellow Flute in particular is used on an active battler, there is an additional check to see if the battler has the Soundproof ability. If so, the AI will be unable to use this item to cure confusion.

Red Flute

The AI will generally want to use this item on a battler if that battler is infatuated. However, the AI won't bother if the battler is holding an item or has an ability that will already cure their infatuation. This is also true if the battler is predicted to faint this round anyway due to indirect damage. The AI will be more incentivized to use these items if the battler is suffering additional conditions that may prevent it from acting, such as Paralysis or confusion.

If the selected battler has the Soundproof ability, this item will be unable to be used on them, and thus the AI will disregard using it.

Handler: ItemEffectScore

This is the handler used for items that have BattleUse = Direct set in their PBS data. Items with this type of battle use don't target any Pokemon at all, and are instead just applied generally. These types of items have the widest potential of effects due to this, although very few items that function in this way are present in the series.

Below are all of the items that use this handler, and a general description of how the AI is scripted to use them. If you want to see specific examples of this type of AI item handler, they can be found in the plugin file named [004] Direct Handlers.

Guard Spec.

The AI will generally have a slight desire to use this item whenever it's available. However, the AI won't bother using it at all if the Mist effect is already in play on their side of the field.

The AI will generally be less incentivized to use this item if any of their active battlers have the Defiant or Competitive abilities, as this item would prevent them from triggering. However, the AI will be more incentivized to use this item if it detects any moves on the opponent's active battlers that could lower stats, or if any of the AI's active battlers have had any of their stats changed previously.

Poke Flute

This item uses the exact same AI as the status cure AI used for the Blue Flute. However, the Poke Flute calculates this score for each active battler on the field, including foes. It then calculates what the total value would be for waking up each sleeping Pokemon and combines the total score to determine the value of using this item.

Waking up ally battlers is almost always considered beneficial, unless the battler would prefer to stay asleep for some reason. While waking up foes is almost always considered detrimental, unless the foe would prefer to stay asleep for some reason.

Plugin Exclusive Items

This plugin includes AI handlers for several items added by other add-on plugins. These include:

  • Z-Booster (Z-Power add-on)

  • Wishing Star (Dynamax add-on)

  • Radiant Tera Jewel (Terastallization add-on)

If any of the above items are available in your game, AI trainers will now be capable of using them, too. Generally speaking, the AI will not bother to use any of these items if they are incapable of using the specific mechanic linked to each item for some reason. They will be incentivized to use them however, if their are remaining Pokemon in their party who would be capable of utilizing the mechanic linked to that item.

Handler: GeneralItemScore

This handler is different from the ones listed above in that this isn't used for any one particular item. Instead, this handler is applied more generally and tweaks the AI's calculation for each item it scores after running one of the other handlers above. You can use these types of handlers to influence how the specific AI trainer behaves more generally when it comes to items.

By default, this plugin only contains one such handler, which uses the ID :inventory_count. This handler incentivizes the AI's used of an item based on how many copies of that item they have left in their inventory. More copies means the AI is more encouraged to use that item, while less copies means it'll be encouraged to use them more conservatively.

There's no real limit in how this handler can be used, though. For instance, if you wanted to make a specific trainer type have a certain type of behavior that you want reflected in how they use items, you can use this handler to accomplish this.

Below are just some basic examples of ideas you could incorporate using this handler.

Example 1

Let's say you wanted to make it so that a certain type of "rich kid" trainer type would be more likely to use items in battle, because you wanted to express that they're wealthy and don't care about wasting money. Here's a basic example of a handler you could make to emphasize this:

Battle::AI::Handlers::GeneralItemScore.add(:rich_trainer,
  proc { |score, item, ai, battle|
    next score if score <= Battle::AI::ITEM_USELESS_SCORE
    trainers = (ai.trainer.side == 0) ? battle.player : battle.opponent
    trainer = trainers[ai.trainer.trainer_index]
    base_money = trainer.base_money
    if base_money >= 160
      old_score = score
      score += 20 
      PBDebug.log_score_change(score - old_score, "prefers to use item because trainer is rich")
    end
    next score
  }
)

Now, with this :rich_trainer handler, any trainer type who has a BaseMoney value of 160 or higher in the trainer_type.txt PBS file will have 20 points added to their overall item scores for all items in their inventory. This means that these trainers will be more encouraged to use items generally when compared to others.

Example 2

Let's say you want to make a trainer that has healing items in their inventory, but you want them to behave in a way where they will save all of their healing items for their final Pokemon. One way you could do that is by giving that trainer type a flag that you can later check with this handler.

Battle::AI::Handlers::GeneralItemScore.add(:reserve_healing_items,
  proc { |score, item, ai, battle|
    next score if !battle.pbItemHealsHP?(item)
    if ai.trainer.has_skill_flag?("ReserveHealingItems")
      remaining_count = battle.pbTeamAbleNonActiveCount(ai.user.index)
      if remaining_count > 0
        old_score = score
        score = Battle::AI::ITEM_FAIL_SCORE
        PBDebug.log_score_change(score - old_score, "fails because of trainer's flag (ReserveHealingItems)")
      end		
    end
    next score
  }
)

Now, with this :reserve_healing_items handler, whenever the AI wants to use a healing item, it will check if the trainer has the "ReserveHealingItems" flag. If so, the AI will disregard using those healing items unless it's down to its last Pokemon.

PreviousImproved Item AINextWonder Launcher

Last updated