Welcome to the Custom Battle Ai Documentation for Pokemon Garbage Gold Deluxe!
Here, you’ll find a complete breakdown of the brand-new, fully customized AI system built just for this game. We’ve reworked how the AI thinks, plans, and battles—making every opponent smarter, more strategic, and a lot more challenging. Whether you’re curious about the inner workings or looking to tweak the AI yourself, this page has everything you need to dive deep into how it all works!
Pokemon Garbage Gold Deluxe Custom Battle Ai
sauceyaTTa’s Custom hg-engine Battle AI
In about two months of work, I have created an original battle AI for my upcoming ROM hacks Pokémon Garbage Gold Deluxe and Pokémon Iridium version. This battle AI is written in C and can be used by anyone who forks my hg-engine repository on GitHub:
https://github.com/MichaelFacci/hg-engine/tree/gg-plus-dev (most updated version at the time of writing)
The main decision making can be found in https://github.com/MichaelFacci/hg-engine/blob/gg-plus-dev/src/trainerai/main.c
Design Philosophy
It is really hard to create an AI that can act like a human VGC player with thousands of hours of experience, and probably a bad idea anyway. A good battle AI is one that is mostly predictable and makes the optimal play on each turn, with very few (but not zero) exceptions. Crafting a good battle AI boils down to trying to accomplish one major end goal: knocking out all of your opponents Pokémon. There are nearly infinite ways to accomplish this, but each way can be categorized into a broader, far more basic strategies:
- Inflict lots of damage (for KOs)
- Do the damage first
- Make it hard for the opponent (the player) to do damage
This is the main structure for this AI. It’s straightforward to understand at a basic level, but also threatening to the player.
The Decision Process
Here’s how the decision making works. On each turn there are at most four options (four moves) for the AI to pick from, and up to three targets (in the case of a double battle). Use of AI trainer items is prohibited because I disable the bag for the player(potions, revives) in these ROM hacks. Also, the AI will not switch out unless it uses a move like Volt Switch, U-turn, or Flip Turn. There are two reasons for this. First, it is unclear when switching is a good idea, since it is extremely conditional on the field state, and can lead to the AI throwing a battle just by trying to get out of a bad situation. The second reason is that the current structures for damage calculations for PartyPokemon as opposed to Battlemons in hg-engine are a little more difficult to work with, and require a separate function entirely which can deviate from the in-battle calc in certain edge cases. For the sake of consistency, I have chosen to remove hard switching from the decision process.
Unusual Damage Calculations:
There are a ton of strange damage calcs that are typically mis-calculated in vanilla AI, such as multihit moves. Here is a list of moves that are explicitly calculated by different rules:
- Multi-Hit moves (2-5 times): Computed at x3 the damage, since the average number of hits is 3.1. Skill link changes this to x5 and loaded dice changes this to x4.
- Multi-Hit fixed hits: Twineedle & Double Hit both have damage x2
- Flat Damage moves: Night Shade, Seismic Toss, Psywave all use the user’s level. Dragon Rage and Sonic Boom always return 40 and 20.
- Super Fang / Nature’s Madness: Damage seen by AI is = to 1/2 the target’s HP
- Endeavor: Computes the difference in HP
- Hex: Takes into account the x2 multiplier from statused opponents
- Rollout: Damage is multiplied by 1.5, since the next 2 turns average to 1.5 the base power.
Unusual Base Powers:
- Magnitude: computed as 71 base power, the average power of all outcomes
- Reversal / Flail: computed base power depending on HP
Double Battles are handled a bit differently than single battles. The normal scoring process happens for each potential defender (including partner, although this is scored extremely low (-30) except in some extreme circumstances like volt absorb / lightningrod). Once each potential defender has their scores computed for each move, the highest score is selected (for instance a slow kill at +11). Any defender whose corresponding score is equal to the high score is then added to a pool of potential targets (for example, both targets (player’s Pokemon) can be slow killed, and are both scored at +11). From that pool, a random target is chosen. If one target has a higher score than all others, that target is always picked.
IMPORTANT:
The AI knows the exact field state condition at the beginning of each turn. This includes your exact stats, held item, moves, ability, who moves first, number of Pokémon remaining, etc. The AI knows whether you have levitate or heatproof on a Bronzong, for instance. Think of this as an open-teamsheet format. Since each trainer is documented in the game’s docs, they also get to know what you have. It begins each turn by loading the field state into different variables, and computes the damage each of it’s moves can do to you. It also computes the damage of the strongest move that the player can deal to it.
IMPORTANT:
The AI will predictively calculate all damages, both incoming and outgoing, as the median roll, rounded down (92% of the max roll). After a lot of testing, this made for the most consistent and intuitive AI. Mathematically, it makes sense since it is the expected outcome (damage roll is picked from a uniform distribution of 85% to 100% of the computed move damage).
TLDR:
If you don’t want to read the rest of this doc with all the AI details, the outline for move scoring most of the time follows this rule:
- Priority Move if AI is KO’d by Defender & AI is slower
- Fast Pursuit Kill
- Slow Pursuit Kill or Priority Move Kill
- Fast Kill
- Slow Kill
- Fake Out
- Speed Control Damaging Moves if Slower (bulldoze / flame charge)
- Setup Moves for a 2HKO (e.g. Swords Dance -> OHKO)
- 2HKO moves (e.g. move damage > half defender’s remaining HP)
- Various Disruptive Setup Moves, Stat Boosts,
- Damaging Moves (move damage < half defender’s remaining HP, ranked by relative damage output to other known moves)
(There are couple of exceptions to the status rule, such as if the user is holding Light Clay, Weather Rocks, has prankster, etc…)
Each of the 4 moves is scored by three AI flags: Basic, Evaluate Attack, and Expert. Flag scores are additive between the 3 flags.
This means that damaging moves in both Evaluate Attack and Expert Flag STACK WITH EACH OTHER!
BASIC FLAG
This flag is extremely important from the development side of things, but way less important for the player to understand. It has exactly one job: avoid useless plays and score them very low. For instance, using a normal type move on a ghost type or a priority move on a grounded Pokémon on psychic terrain. There are a lot of conditionals here, particularly for different status conditions like leech seed, confusion, aqua ring, weather, terrains, etc. Basically what you need to know is that if the Basic Flag detects a bad decision, it will score it somewhere between -15 and -20 (-40 in some very rare cases). This score more than offsets any positive scoring from other flags.
EVALUATE ATTACK
This flag is the most important to understand from a player’s perspective, especially a nuzlocker. This flag has exactly one job: rank attacking (damaging) moves based on their damage, priority, and potential to get a KO. The purpose of this flag is to go for KOs or 2 hit KOs if it can. Prioritize damage if we can do a lot of it! The 2 hit KO is only a +4 score because there are numerous better options, and it avoids weird decisions when certain conditions stack with the Expert Flag.
This flag ignores all status moves and explosion-type moves (self-destruct, misty explosion, explosion) and returns 0.
If the move can kill{
If: The AI sees that the player can KO it and player would move first, then it will use a priority move
+12 score
Else if: The move is pursuit, it can kill, and AI is faster
+15 score
Else if: The move is pursuit, can kill, and AI is slower OR the move is a priority move, can kill, and AI is slower
+14 score
Else if: The move kills, and AI is faster
+12 score
Otherwise if the move would kill (slow kill or speed tie):
+10 score
}
Else if: the move does not KO, check if the move does more than half the opponents remaining HP (2 hit KO)
+4 score
Lastly, if the move is not Fake Out and the MOVE DOES NOT KO, rank the move relative to the Pokémon’s other damaging moves. (strongest move -0, second strongest move -1, third -2, fourth, -3). This avoids bugs if you the AI cannot use its most powerful move (i.e. is disabled, runs out of PP, etc)
EXPERT FLAG
This flag is the biggest one, and focuses mainly on status moves. Keep in mind that any damaging moves it scores WILL STACK with the scores from the evaluate attack flag.
STATUS-INDUCING MOVES:
If the move applies SLEEP or YAWN:
If: The move causes sleep immediately
and the move is 100% accurate,
or the attacker has Compound Eyes,
+5 score (same value as a 2HKO setup move)
Else if: The move causes sleep immediately
and the above is not true,
50% chance to add +2 score
Else if: The move is Yawn (sleep next turn),
50% chance to add +2 score
If the move causes BURN:
If: The defender’s Attack stat is higher than their Sp. Atk stat,
+2 score
If: The attacker has a move effect that deals double damage to statused targets,
+2 score (this stacks with the previous one)
If: The attacker’s minimum damage roll is less than one-third of the defender’s HP,
+1 score
If the move causes POISON or TOXIC POISON (BADLY POISONED):
If: Either the attacker or the defender is below 50% HP,
−1 score (don’t poison low-HP targets)
Else if: The attacker can’t deal more than one-third of the defender’s HP with its average damage roll,
+3 score (we expect a long fight—status is valuable)
Else if: The attacker can’t deal more than half the defender’s HP with average damage roll,
+2 score (still a decent opportunity for damage over time)
If the move causes PARALYSIS:
If: The defender moves first and Trick Room is not active,
+3 score (speed control is valuable)
If: The attacker is below or at 70% HP,
−1 score
If the move causes CONFUSION (including Swagger and Flatter):
If: The defender is already Paralyzed,
+2 score
If: The attacker has been on the field for more than 1 turn,
−2 score
50% chance for +2 additional score
METEOR BEAM
If: The attacker holds a Power Herb
+2 score
Else
−2 score
ELECTRO SHOT
If: The weather is any kind of rain, or the attacker holds a Power Herb
+2 score
Else
−2 score
GEOMANCY
If: The attacker holds a Power Herb
+8 score
Else
−2 score
SPEED CONTROL DAMAGING MOVES
If the move is a damaging attack that also either raises the attacker’s speed, lowers the defender’s speed,
or causes paralysis (Nuzzle), and the attacker does not have Sheer Force, and the secondary effect chance is 100%,
and the move cannot KO the defender:
If: Trick Room is inactive and the defender moves first
Return score 6 (priority above 2HKO and setup into OHKO, but below slow kills)
Else if: Trick Room is active
−2 score
SPEED DROPPING STATUS MOVES
If: The attacker is at risk of being KO’d this turn or has been on the field for more than 2 turns
Return score −3
If: The defender moves first or there is a speed tie, and Trick Room is inactive
+2 score
Else if: The attacker moves first
−3 score
SETUP MOVES THAT BOOST MULTIPLE DIFFERENT STATS
If the move boosts speed and another stat (e.g., Shell Smash, Quiver Dance, Dragon Dance, Tidy Up, Shift Gear):
If: The attacker is at risk of being KO’d this turn,
or has been on the field more than 2 turns,
or Trick Room is active and the attacker moves first,
then return −3 (avoid boosting)
Else if: The attacker’s Attack and Special Attack boosts are both less than +2 stages,
and the move cannot KO the defender,
and the defender has neither taunted nor encore, then:
- If: The defender needs at least 4 attacks to KO the attacker,
return 5 (setup encouraged)
- If: The attacker moves first, then:
- If: After factoring in defense drops for Shell Smash,
the attacker can survive the defender’s hits, then:
- If: The boosted move can KO the defender in the same number of turns as without boost,
return 5 (setup encouraged)
- Else if: The attacker just switched in (turns on field == 0),
return 3 (setup somewhat encouraged, but less than 2hko)
- Else
return −1 (setup discouraged)
- Else if: The attacker moves second, then:
- If: The boosted move can KO the defender faster,
return 6 (speed setup)
- Else
return 5 (setup encouraged)
STAT BOOSTING MOVES THAT RAISE USER ATTACK OR SPECIAL ATTACK
(INCLUDES POWER-UP PUNCH)
If: The attacker is at risk of being KO’d this turn,
or has been on the field more than 2 turns,
then return −3 (avoid boosting)
Else if: The attacker’s Attack/SpAtk boost is less than +2 stages,
and the move cannot KO the defender,
and the defender is neither taunted nor encored, then:
- If: The defender cannot KO the attacker within 3 hits,
return 5 (setup encouraged)
- If: The attacker moves first, then:
- If: The attacker can survive the defender’s hits, then:
- If: The boosted move can KO the defender in the same number of turns (as a 2hko),
return 5 (setup encouraged)
- Else if: The attacker just switched in (turns on field == 0),
return 1 (setup weakly encouraged)
- Else
return −1 (setup discouraged)
- Else if: The attacker moves second, then:
- If: The attacker can survive at least 2 hits, then:
- If: The boosted move can KO the defender in the same number of turns (as a 2hko),
return 5 (setup encouraged)
- Else if: The attacker just switched in,
return 1 (setup weakly encouraged)
- Else
return −1 (setup discouraged)
TERRAINS
If the move is Grassy Terrain:
If: The attacker has a damaging Grass-type move,
or the attacker has the ability Grass Pelt and the defender’s Attack is higher than Special Attack,
or the attacker knows Grassy Glide,
then +2 score
Else if: The attacker holds a Terrain Extender item
then +2 score
If the move is Psychic Terrain:
If: The attacker has a damaging Psychic-type move
then +2 score
Else if: The attacker holds a Terrain Extender item
then +2 score
If the move is Electric Terrain:
If: The attacker has a damaging Electric-type move
then +2 score
Else if: The attacker holds a Terrain Extender item
then +2 score
STATUS MOVES THAT DROP OPPONENTS STATS
(e.g., Growl, Leer, Charm)
If: The attacker is at risk of being KO’d this turn,
or has been on the field more than 2 turns,
then return −3 (avoid using)
Else if: The defender’s Attack is higher than their Special Attack, then:
- If: The defender’s Attack is raised by +0 or more stages
+2 score
- Else if: The defender’s Attack is -1 or more stages
+1 score
- Else
−1 score
Else:
−3 score
(same exactly logic applies to special attack dropping moves)
STATUS MOVES THAT DROP OPPONENT’S DEFENSE
If the move lowers the defender’s Defense (including guaranteed 100% secondary effect moves):
If: The attacker is at risk of being KO’d this turn,
or has been on the field more than 2 turns,
then return −3
Else:
- If: The defender’s Defense is +0 or more stages
+2 score
- Else if: The defender’s Defense is -1 stages
+1 score
- Else
−1 score
(same exactly logic applies to special defense dropping moves)
STATUS MOVES THAT BOOST DEFENSE/SPDEF BY AT LEAST 2 STAGES
(Iron Defense, Cotton Guard, Amnesia)
If: The defender’s Special Attack is less than their Attack, then:
- If: The attacker’s Defense is less than or equal to +0 stages
+3 score
- Else if: The attacker’s Defense is raised by +2 or more stages
−2 score
- Else
+1 score
Else
−3 score
(same logic applies for SpDef)
DESTINY BOND
If: The attacker will be KO’d this turn and moves first,
50% chance to add +6 score
Else if: The attacker will be KO’d but moves second,
50% chance to add +6 score
Else:
−3 score (avoid if not in danger)
INGRAIN / AQUA RING
If: The attacker can survive at least 3 hits (max damage received is less than half attacker’s HP)
+2 score
STATUS MOVES THAT RAISE EVASION OR DROP OPPONENT’S ACCURACY
If: The attacker’s evasion is at or below +0 stages,
or the defender’s accuracy is at or above +0 stages,
then +3 score
Else if: The defender’s evasion is at or below +2 stages,
or the defender’s accuracy is at or above -2 stage,
then +1 score
Else:
−4 score
EXPLOSION MOVES
If attacker’s HP ≥ 88%: 1 in 20 chance to add +8 score, else −4 score
If attacker’s HP ≥ 76%: 2 in 20 chance to add +8 score, else −4 score
If attacker’s HP ≥ 64%: 4 in 20 chance to add +8 score, else −4 score
If attacker’s HP ≥ 52%: 6 in 20 chance to add +8 score, else −4 score
If attacker’s HP ≥ 40%: 10 in 20 chance to add +8 score, else −4 score
If attacker’s HP ≥ 28%: 13 in 20 chance to add +8 score, else −4 score
If attacker’s HP ≥ 16%: 17 in 20 chance to add +8 score, else −4 score
If attacker’s HP < 16%: 19 in 20 chance to add +8 score, else −4 score
SPEED BOOSTING STATUS MOVES
(e.g. Agility)
If the attacker has been on the field more than 2 turns:
−3 score
Else:
- If the attacker moves first:
−3 score
- Else if the defender moves first and Trick Room is inactive:
+5 score
RECOVERY MOVES (Recover, Slack Off, Roost, Moonlight, etc…)
If attacker’s HP ≥ 80%:
−3 score
If attacker moves first:
- If the attacker would be KO’d but recovers more HP than lost (max damage received < half max HP and > current HP):
+3 score
Else if defender moves first:
- If the attacker would not be KO’d and recovers more HP than lost (max damage received < half max HP and < current HP):
+3 score
If the move heals more in sun:
- If the weather is Sandstorm, Rain, Hail, or Snow:
−2 score
LEECH SEED
If the attacker can survive at least 2 hits (max damage received ≤ half attacker’s HP):
- If the attacker just switched in (turns on field = 0):
+3 score
- Else:
+1 score
LIGHT SCREEN / REFLECT
If Light Screen is already active on the attacker’s side:
return −10
If the attacker holds Light Clay:
+5 score
Else if the defender’s Special Attack is higher than their Attack:
+3 score
If the attacker has Prankster ability:
+1 score
(logic is exactly the same but in reverse for Reflect)
FAKE OUT
If the defender does not have Inner Focus,
and does not have Steadfast unless Trick Room is active,
and does not have Shield Dust,
and is not holding Covert Cloak,
+7 score (fake out receives a -25 score from basic flag if not first turn out)
BINDING MOVES
(e.g. Whirlpool, Sand Tomb, Fire Spin, Infestation, etc…)
If the defender is badly poisoned, cursed, under Perish Song, or attracted:
+3 score
Else:
+2 score
If the defender is already bound:
no score change
ENDURE
If the attacker already used a protect-like move last turn:
−5 score
Else if the attacker is at risk of being KO’d this turn:
+7 score
Else:
−4 score
WEATHER SETTING MOVES
(e.g. Rain Dance, Sandstorm, Snowscape/Hail, Sunny Day)
RAIN DANCE
If the attacker holds Damp Rock:
+5 score
If the attacker has Swift Swim, moves second, and Trick Room is inactive:
+4 score
Else:
+3 score
SANDSTORM
If the attacker holds Smooth Rock:
+5 score
If the attacker has Sand Rush, moves second, and Trick Room is inactive:
+4 score
Else if the attacker has Sand Veil:
+3 score
Else:
+2 score
SUNNY DAY
If the attacker holds Heat Rock:
+5 score
If the attacker has Chlorophyll, moves second, and Trick Room is inactive:
+4 score
Else if the attacker has Solar Power or Harvest:
+3 score
Else:
+2 score
VOLT SWITCH / FLIP TURN / U-TURN
If the attacker has more than 1 remaining team member
and is below 33% HP:
If the attacker can’t 2HKO the defender:
And the defender moves first
And the attacker survives the hit
+5 score
Else if the attacker would be KO’d this turn and moves first:
+5 score
HAZARDS
(Spikes, Toxic Spikes, Stealth Rock)
If the attacker is about to be KO’d:
−3 score
Else if the attacker just switched in (0 turns on field):
+3 score
Else if on field 1 turn:
+1 score
Else if on field 2 turns:
0 score
Else (more than 2 turns on field):
−5 score
MAGNET RISE
If the defender has a Ground-type damaging move:
+5 score
Else:
−15 score
TRICK ROOM
If the battle is a multi, double, or tag battle:
0 score (handled in Tag Strategy Flag)
Else if the defender moves first:
+6 score
TAG STRATEGY FLAG (DOUBLE BATTLES)
Every double battle is hard coded to always have this flag enabled. It does a number of things, but the most relevant are two things.
First is protect. This is mainly relevant in the tag battle with Cynthia in the Plasma hideout. Protect is prioritized if the user is threatened by a kill by an opponent:
If the target could kill the AI’s Pokemon, AND the target is fast, AND the user has a protect counter of 0 consecutive turns:
+13 score
Second is spread moves. Moves that hit multiple targets (like muddy water or surf) get an extra +1 score boost on top of all the other scores in other flags if the move would kill. This basically covers for protect and also allows for extra chip damage on the partner.
The exact C code is:
if(ctx->moveTbl[ai->attackerMove].split != SPLIT_STATUS &&
ai->attackerAvgRollMoveDamages[i] >= ai->defenderHP &&
(ctx->moveTbl[ai->attackerMove].target == RANGE_ALL_ADJACENT || ctx->moveTbl[ai->attackerMove].target == RANGE_ADJACENT_OPPONENTS)){
moveScore += 1;
}
TARGETING
Last is targeting in double battles. Not only does the user need to decide on a move, but also a target. This is simply done by looping over all other battlers (including the partner, if alive), and computing the max score over all of the users moves against each other battler, and then selecting the target with the highest score (Ties are broken randomly).
For example, if a Marshtomp sees a Water Pulse slow kill against a Talonflame and a fast kill against a Magcargo, it will use the move against the Magcargo.
Note:
Anything not mentioned here is by default vanilla AI behavior.