Explain AI_* flags

1 files changed, 16 insertions, 11 deletions

diff --git a/Add-a-new-trainer-class.md b/Add-a-new-trainer-class.md
index 6c768da..9040c42 100644
--- a/Add-a-new-trainer-class.md
+++ b/Add-a-new-trainer-class.md
@@ -111,18 +111,23 @@ Edit [data/trainers/attributes.asm](../blob/master/data/trainers/attributes.asm)
 
 - **items:** Two items, each of which a trainer can use once. They may be the same item or `NO_ITEM`. The AI engine has to know how to use the items, as defined by `AI_Items` in [engine/battle/ai/items.asm](../blob/master/engine/battle/ai/items.asm).
 - **base reward:** The base monetary reward for beating a trainer. The reward amount is 4×*B*×*L*, where *B* is the base reward and *L* is the level of the last Pokémon they used.
-- **AI flags (move weights):** Bit flags that control how the trainer's AI chooses a move to use. Valid flags:
+- **AI flags (move weights):** Bit flags that control how the trainer's AI chooses a move to use. Valid flags, with descriptions from [engine/battle/ai/scoring.asm](../blob/master/engine/battle/ai/scoring.asm):
    - `NO_AI`:
-   - `AI_BASIC`:
-   - `AI_SETUP`:
-   - `AI_TYPES`:
-   - `AI_OFFENSIVE`:
-   - `AI_SMART`:
-   - `AI_OPPORTUNIST`:
-   - `AI_AGGRESSIVE`:
-   - `AI_CAUTIOUS`:
-   - `AI_STATUS`:
-   - `AI_RISKY`:
+   - `AI_BASIC`: Don't do anything redundant:
+      - Using status-only moves if the player can't be statused (see [data/battle/ai/status_only_effects.asm](../blob/master/data/battle/ai/status_only_effects.asm)
+      - Using moves that fail if they've already been used
+   - `AI_SETUP`: Use stat-modifying moves on turn 1:
+      - 50% chance to greatly encourage stat-up moves during the first turn of enemy's Pokémon
+      - 50% chance to greatly encourage stat-down moves during the first turn of player's Pokémon
+      - Almost 90% chance to greatly discourage stat-modifying moves otherwise
+   - `AI_TYPES`: Dismiss any move that the player is immune to. Encourage super-effective moves. Discourage not-very-effective moves unless all damaging moves are of the same type.
+   - `AI_OFFENSIVE`: Greatly discourage non-damaging moves.
+   - `AI_SMART`: Context-specific scoring. Special cases for many different move effects
+   - `AI_OPPORTUNIST`: Discourage stall moves when the enemy's HP is low (see [data/battle/ai/stall_moves.asm](../blob/master/data/battle/ai/stall_moves.asm)).
+   - `AI_AGGRESSIVE`: Discourage all damaging moves but the one that does the most damage. Reckless moves are not discouraged (see [data/battle/ai/reckless_moves.asm](../blob/master/data/battle/ai/reckless_moves.asm)).
+   - `AI_CAUTIOUS`: 90% chance to discourage moves with residual effects after the first turn (see [data/battle/ai/residual_moves.asm](../blob/master/data/battle/ai/residual_moves.asm)).
+   - `AI_STATUS`: Dismiss status moves that don't affect the player.
+   - `AI_RISKY`: Use any move that will KO the target. Risky moves will often be an exception (see [data/battle/ai/risky_effects.asm](../blob/master/data/battle/ai/risky_effects.asm)).
 - **AI flags (item/switch):** Bit flags that control how the trainer's AI chooses to use an item or switch Pokémon instead of attacking. Combine one `*_USE` flag and one `SWITCH_*` flag. Valid flags:
    - `CONTEXT_USE`:
    - `UNKNOWN_USE`: