v21.1 Advanced AI System 2.4

# Force a specific personality for a named trainer
AdvancedAI.set_personality("Cynthia", :aggressive)
AdvancedAI.set_personality("Brock", :defensive)

# Get current personality
personality = AdvancedAI.get_personality(battle, trainer_index)
# => :aggressive

# Each personality also affects switch thresholds:
# Aggressive: 55 (switches less, stays to attack)
# Defensive: 35 (switches more often for safety)
# Balanced: 45
# Hyper Offensive: 60 (almost never switches)

# The AI prevents infinite switching loops (Toxapex ↔ Blissey)
# - Won't switch if it just switched in (turn count < 2)
# - Tracks recent switches to detect ping-pong patterns
# - Stall archetypes are protected from unnecessary switches
#   (a Toxapex running Toxic Spikes + Recover STAYS in)

# The AI identifies the opponent's team strategy:
archetype = AdvancedAI.identify_opponent_archetype(battle, user_index)
# => { type: :rain, confidence: 0.85 }

# Recognized archetypes:
# :hyper_offense  — fast, fragile, setup-heavy
# :balance        — mixed roles
# :stall          — walls + status + recovery
# :rain / :sun / :sand / :hail — weather teams
# :trick_room     — slow heavy hitters
# :volt_turn      — pivot-based momentum

# Counter-play is automatic:
# vs. Stall: +30 for Taunt, +20 for wallbreaker moves
# vs. Hyper Offense: +20 for priority, +15 for defensive plays
# vs. Weather: +25 for weather override moves
# vs. Volt-Turn: +30 for Pursuit, +20 for trapping

# The AI identifies and pursues win conditions:
win_con = AdvancedAI.identify_win_condition(battle, user, skill)
# => :sweep (one mon can clean), :attrition, :stall,
#    :trade, :setup, :revenge, :speed_control

# Dynamic shifting: if your sweeper gets KO'd,
# the AI automatically shifts from :sweep to :attrition
# and adjusts all scoring accordingly.

# Finds types that the team can't handle
gaps = AdvancedAI.identify_coverage_gaps(battle, user_index)
# => [:GROUND, :FIGHTING] — we can't resist OR threaten these types

# The AI protects Pokémon that cover these gaps
# and avoids risky plays with them (recoil penalty, no sacking)

# Detects common defensive cores:
cores = AdvancedAI.identify_defensive_cores(battle, side_index)
# => [{ type: "Fire/Water/Grass", members: ["Heatran", "Toxapex", "Ferrothorn"] }]

# Known core patterns:
# Fire/Water/Grass (FWG), Steel/Fairy/Dragon, 
# Ground/Steel/Flying, Water/Grass/Electric,
# Poison/Steel, Dark/Fighting/Psychic

# Rewards moves that break cores (+15 to +25 bonus)

# The AI evaluates when sacrificing a Pokémon is strategically correct
should_sack = AdvancedAI.should_sack?(battle, user, target)

# Sacking criteria:
# - User will likely faint this turn anyway (< 25% HP, opponent outspeeds)
# - User has low remaining value (no useful moves for remaining opponents)
# - A teammate benefits greatly from a free switch-in
# If sacking: +40 for pivot moves, +20 for heavy damage, -30 for recovery

# Tracks team HP% advantage and adjusts playstyle
health = AdvancedAI.track_health(battle, user_index)
# => { our_percent: 72.5, opponent_percent: 45.0, advantage: 27.5 }

# Winning (advantage > 30): play safe, avoid recoil, favor healing
# Losing (advantage < -30): be aggressive, favor power moves, setup
# Even: no adjustment

# The AI checks what its partner is targeting
# to coordinate attacks and avoid waste
partner_targeting = partner_targets?(battle, partner, target)
# Checks battle.choices for partner's registered action
# Falls back to heuristic (low HP target likely shared)

# Joint target bonus adjusts score:
# - If partner can KO alone: -10 (redirect our attack elsewhere)
# - SE advantage on alternate target: +10 (focus fire correctly)

# Full hazard damage calculation
# Stealth Rock: type-based (6.25% to 50%)
# Spikes: layer-based (12.5% / 16.7% / 25%)
# Toxic Spikes: poison on grounded mons
# Sticky Web: -1 Speed on grounded mons

# The AI evaluates:
# - When to SET hazards (opponent switches a lot)
# - When to REMOVE hazards (Defog vs. Rapid Spin decision)
# - Court Change / Mortal Spin / Tidy Up alternatives
# - Heavy-Duty Boots negation

# Detection
AdvancedAI.choice_locked?(battler)  # Has it used a move while Choice'd?
AdvancedAI.choice_item?(battler.item_id)  # Is it holding a Choice item?

# Behavior:
# - Choice-locked: score -100 for non-locked moves (they'll fail)
# - Before locking: favor broadest coverage move (+15)
# - Before locking: penalize status moves (-40)
# - Pivot moves get +25 (escape the lock)
# - Choice Scarf detected from turn order observations

# Life Orb (1.3x), Expert Belt (1.2x SE), Muscle Band, Wise Glasses
# Score bonus proportional to multiplier: (mult - 1.0) × 50
# Life Orb = +15, Expert Belt on SE = +10

# 18 type gems recognized (Normal Gem through Fairy Gem)
# Gem + matching move type = +15 score bonus
# Great for Fake Out + Normal Gem, Explosion + Normal Gem
AdvancedAI.has_type_gem?(battler, :NORMAL)  # => true/false

# Contact moves against Sticky Barb holder = risk inheriting it
# Score -10 for contact moves against Sticky Barb holders
AdvancedAI.has_sticky_barb?(target)  # => true/false

# Blocks Taunt/Encore/Disable/Torment ONCE
# Score -25 for those moves against Mental Herb holders
# (they'll cure it immediately, wasting your turn)
AdvancedAI.has_mental_herb?(target)  # => true/false

# Ignores weather effects — Thunder/Hurricane lose weather accuracy,
# Solar Beam doesn't skip charge, Weather Ball stays Normal
# Score -20 for weather-dependent moves against Utility Umbrella holders
AdvancedAI.has_utility_umbrella?(target)  # => true/false

# Heat Rock, Damp Rock, Smooth Rock, Icy Rock, Terrain Extender
# When holding extender + using matching weather move: +10 bonus
# (8 turns instead of 5 is a significant advantage)

# The AI predicts what you'll do next:

# Switch prediction — estimates chance you'll switch
switch_chance = predict_switch_chance(battle, target)
# Considers: type disadvantage, low HP, setup bait, known moves

# Switch target prediction — guesses WHO you'll switch to
predicted = predict_switch_target(battle, target)
# Considers: type matchup, role needs, bench condition

# Move prediction — estimates your likely next move
predicted_move = predict_next_move(battle, target)
# Uses: Move Memory, frequency tracking, situation analysis

# Prediction-based scoring:
# Pursuit vs. predicted switch = +30
# Setup move vs. predicted status = +20  
# Coverage move vs. predicted switch-in = +25

# Double Switch detection:
should_double_switch?(battle, user, target)
# If AI predicts you'll switch, it switches too to maintain advantage

# The AI learns your patterns during battle:

# Tracks your tendencies:
# - How often do you use Protect? (Protect prediction)
# - How often do you switch? (Switch habit tracking)
# - What's your most-used move? (Preferred move detection)
# - How predictable are you? (Predictability scoring)

# This affects scoring:
# If you Protect often → AI uses setup/status during your Protect turns
# If you switch often → AI uses Pursuit/hazards/prediction switches
# If you spam one move → AI predicts and counters it

# 6-factor decision system:
# 1. Timing     (0-35)  — early G-Max setters, mid-game sweepers
# 2. Offense    (0-40)  — move diversity, power, G-Max bonus
# 3. Sweep      (0-35)  — boosts, speed advantage, weak enemies left
# 4. Survival   (0-45)  — HP doubling urgency, OHKO prevention
# 5. Party Comp (0 to -25) — is a teammate a better Dynamax user?
# 6. Momentum   (0-30)  — current advantage, pressure

# Thresholds:
# Score ≥ 100: Dynamax immediately (excellent timing)
# Score ≥ 70:  Strong candidate
# Score ≥ 50:  Acceptable if ≤ 2 remaining

# 6-factor decision system:
# 1. Timing     — team state, battle phase
# 2. Type Adv   (0-40)  — STAB gain, SE coverage, weakness removal (+25)
# 3. Sweep      (0-35)  — boosts, HP%, win condition
# 4. Survival   (0-45)  — emergency HP, imminent KO prevention (+45!)
# 5. Party Comp (0 to -25) — better Tera candidates on bench?
# 6. Momentum   (0-25)  — pressure, finishing blow

# Thresholds:
# Score ≥ 80: Tera immediately (emergency or excellent)
# Score ≥ 60: Strong candidate
# Score ≥ 40: Acceptable if ≤ 2 remaining

# The AI plays differently in 1v1 and 2v2 endgame:

# 1v1 Endgame:
# - Calculates exact KO potential
# - Detects "winning move" (OHKO available = +100 score)
# - Speed tier comparison for priority decisions
# - Desperation plays when losing (Destiny Bond, Endeavor + Quick Attack)
# - Will NOT waste turns on setup when they can KO

# 2v2 Endgame:
# - Similar KO detection with expanded bench options
# - Sacrifice evaluation (lose one to set up another)
# - Priority becomes critical (Mach Punch the weakened target)

# Dynamic mode:
# Winning → play safe, use priority, avoid risks
# Losing → gamble on high variance (crit moves, OHKO, Destiny Bond)

# Effective speed calculation includes:
# - Base Speed stat
# - Choice Scarf detection (from observed turn order)
# - Paralysis (25% speed)
# - Tailwind (2x)
# - Trick Room (inverted)
# - Abilities: Swift Swim, Chlorophyll, Sand Rush, Slush Rush
# - Unburden (2x after item consumed)
# - Items: Quick Claw, Lagging Tail, Iron Ball

# Speed-control move evaluation:
# Tailwind: calculates how many mons benefit
# Trick Room: counts slow mons on our side vs. theirs
# Sticky Web: evaluates opponent's grounded mons
# Icy Wind, Electroweb: speed-dropping attack value

# Priority Tier Classification:
# +5: Helping Hand
# +4: Protect, Detect
# +3: Fake Out, Quick Guard, Wide Guard
# +2: Extreme Speed, First Impression
# +1: Aqua Jet, Bullet Punch, Ice Shard, Mach Punch, Shadow Sneak, Sucker Punch
# 0:  Normal moves
# -1: Vital Throw
# -5: Trick Room
# -6: Counter, Mirror Coat
# -7: Roar, Dragon Tail, Circle Throw

module AdvancedAI
  # Master switch — disable the entire system
  ENABLED = true

  # Minimum skill level to activate advanced AI
  MIN_SKILL_FOR_AUTO_ACTIVATION = 70

  # Debug output
  DEBUG_MODE = false                 # Verbose console logging
  DEBUG_SWITCH_INTELLIGENCE = false  # Extra switch decision logging
  LOG_TO_CONSOLE = false             # Print to console
  LOG_TO_FILE = false                # Write to Logs/ai_log.txt

  # Show AI decision reasoning in battle text
  SHOW_MOVE_EXPLANATIONS = true

  # Wild Pokemon AI
  ENABLE_WILD_POKEMON_AI = true
  WILD_POKEMON_SKILL_LEVEL = 100

  # Auto-detect personality from team composition
  AUTO_DETECT_PERSONALITY = true

  # Prevent ace from switching in early
  RESPECT_RESERVE_LAST_POKEMON = true

  # Game Variable for mode override (0 = auto)
  AI_MODE_VARIABLE = 100

  # Gen 9 Pack compatibility
  GEN9_PACK_COMPAT = true

  # DBK Plugin toggles
  DBK_PLUGINS = {
    mega_evolution:    true,
    dynamax:           true,
    terastallization:  true,
    z_moves:           true,
    raid_battles:      true,
    sos_battles:       true,
  }
end

AdvancedAI.active?                              # Is system enabled?
AdvancedAI.activate! / AdvancedAI.deactivate!   # Toggle at runtime
AdvancedAI.qualifies_for_advanced_ai?(skill)    # Does this skill qualify?
AdvancedAI.get_ai_tier(skill)                   # :beginner / :mid / :pro / :extreme
AdvancedAI.feature_enabled?(:prediction, skill) # Is this feature on at this skill?
AdvancedAI.get_setting(key, default)            # Read config value
AdvancedAI.dbk_enabled?(:dynamax)              # Is DBK plugin available?
AdvancedAI.log("message", "Source")             # Write to AI log

AdvancedAI.type_mod(:FIRE, defender)                     # Type multiplier
AdvancedAI.type_absorbing_immunity?(user, target, :WATER) # Flash Fire, etc.
AdvancedAI.bulletproof_immune?(user, target, move)        # Ball/Bomb moves
AdvancedAI.soundproof_immune?(user, target, move)         # Sound moves
AdvancedAI.status_immune?(atk, target, :BURN, battle)     # Can status land?
AdvancedAI.grounded?(battler, battle)                     # On the ground?

AdvancedAI.get_memory(battle, battler)           # Full memory hash
AdvancedAI.knows_move?(battle, battler, :EQ)     # Have we seen this move?
AdvancedAI.has_priority_move?(battle, battler)    # Any priority observed?
AdvancedAI.has_healing_move?(battle, battler)     # Any recovery observed?
AdvancedAI.has_setup_move?(battle, battler)       # Any boost observed?
AdvancedAI.strongest_known_move(battle, battler)  # Highest power seen
AdvancedAI.max_known_damage(battle, atk, def)     # Damage estimate
AdvancedAI.last_move(battle, battler)             # Last used move
AdvancedAI.move_frequency(battle, battler, :EQ)   # Times move was used

AdvancedAI.priority_move?(:BULLETPUNCH)   # true
AdvancedAI.setup_move?(:SWORDSDANCE)      # true
AdvancedAI.hazard_move?(:STEALTHROCK)     # true
AdvancedAI.healing_move?(:RECOVER)        # true
AdvancedAI.ohko_move?(:FISSURE)           # true
AdvancedAI.spread_move?(:EARTHQUAKE)      # true
AdvancedAI.protect_move?(:PROTECT)        # true
AdvancedAI.screen_move?(:REFLECT)         # true
AdvancedAI.status_move?(:THUNDERWAVE)     # true
AdvancedAI.pivot_move?(:UTURN)            # true
AdvancedAI.stall_move?(:TOXIC)            # true
AdvancedAI.categorize_move(:EARTHQUAKE)   # => :spread (or array of categories)
AdvancedAI.get_setup_data(:SWORDSDANCE)   # => { stat: :ATTACK, stages: 2, ... }

AdvancedAI.detect_roles(battler)                    # => [:sweeper, :pivot]
AdvancedAI.has_role?(battler, :wall)                # => false
AdvancedAI.best_for_role(battle, side, :wall)       # Best wall on team
AdvancedAI.recommend_role_for_situation(...)         # What role to send?

AdvancedAI.detect_personality(battle, trainer_idx)   # => :aggressive
AdvancedAI.set_personality("Cynthia", :aggressive)   # Override per trainer
AdvancedAI.get_personality(battle, trainer_idx)       # Read personality
AdvancedAI.get_personality_switch_threshold(:aggressive) # => 55

AdvancedAI.identify_opponent_archetype(battle, idx) # => { type: :stall, confidence: 0.8 }
AdvancedAI.identify_coverage_gaps(battle, idx)      # => [:GROUND, :FIGHTING]
AdvancedAI.identify_critical_pokemon(battle, idx)   # Pokemon we can't lose
AdvancedAI.identify_defensive_cores(battle, side)   # => [{ type: "FWG", ... }]
AdvancedAI.track_health(battle, idx)                # Team HP% comparison
AdvancedAI.update_threats(battle, idx)              # Threat tracking
AdvancedAI.should_sack?(battle, user, target)       # Strategic sacrifice?
AdvancedAI.strategic_score(battle, user, mv, tgt, skill)  # Combined score

AdvancedAI.choice_item?(:CHOICEBAND)            # => true
AdvancedAI.choice_locked?(battler)              # => true/false
AdvancedAI.blocks_status_moves?(battler)        # Assault Vest check
AdvancedAI.calculate_item_multiplier(btl, move) # => 1.3 (Life Orb)
AdvancedAI.get_item_threat_modifier(battler)    # Item threat factor
AdvancedAI.recommend_item_for_role(pkmn, :sweeper) # => :LIFEORB
AdvancedAI.has_utility_umbrella?(battler)        # Weather negation
AdvancedAI.has_type_gem?(battler, :NORMAL)       # Gem check
AdvancedAI.has_sticky_barb?(battler)             # Contact transfer
AdvancedAI.has_mental_herb?(battler)             # Anti-Taunt once
AdvancedAI.gem_damage_bonus(battler, move)       # +15 if matching
AdvancedAI.mental_herb_penalty(target, move)     # -25 vs Mental Herb
AdvancedAI.utility_umbrella_penalty(target, move) # -20 weather moves

AdvancedAI.assess_threat(battle, target, user, skill) # => 0.0 to 10.0
AdvancedAI.get_ability_threat(:HUGEPOWER)             # => 3.0
AdvancedAI.defensive_ability?(:FURCOAT)               # => true
AdvancedAI.offensive_ability?(:ADAPTABILITY)          # => true
AdvancedAI.categorize_ability(:SPEEDBOOST)            # => :speed
AdvancedAI.benefits_from_weather?(battler, :Sun)      # Chlorophyll?
AdvancedAI.benefits_from_terrain?(battler, :Electric) # Surge Surfer?
AdvancedAI.contact_punishment(attacker, defender, move) # Rocky Helmet etc.
AdvancedAI.expected_multi_hits(attacker, move)         # Skill Link = 5

AdvancedAI.identify_win_condition(battle, user, skill)
# => :sweep | :attrition | :stall | :trade | :setup | :revenge | :speed_control