Battle AI

MCE uses a pluggable strategy pattern for battle AI. The AI system is built around the BattleAI base class and a collection of BattleAction components that can be composed to create different difficulty levels and behavior styles.

Architecture

The AI pipeline works in two layers:

1. BattleAI -- The entry point that receives the current battle state and returns a BattleAction.
2. BattleAction Components -- Individual decision-making units that evaluate one aspect of battle (e.g., "should I use a super effective move?" or "should I switch to a resistant monster?").

A BattleAI instance holds an ordered list of BattleAction components. It evaluates them in priority order, and the first one that produces a valid action wins.

Built-In AI Strategies

MCE ships with several AI strategies that can be mixed and matched:

RandomBattleAI

The simplest AI. Picks a random valid move each turn.

• Difficulty: Very Easy
• Use Case: Wild encounters, early-game trainers
• Behavior: Randomly selects from available moves. No strategic thinking.

PerformEffectiveMove

Picks the move that deals the most effective damage against the current target.

• Difficulty: Medium
• Use Case: Mid-game trainers, gym leaders
• Behavior: Calculates type effectiveness for each available move and picks the best one. Does not account for stat changes or status moves.

PerformRandomMove

Similar to RandomBattleAI but with weighted move selection.

• Difficulty: Easy
• Use Case: Low-level trainers
• Behavior: Randomly selects a move, with slight preference for damaging moves over status moves.

Built-In Action Components

These components can be composed into custom AI strategies:

Component	Description
PerformEffectiveMove	Use the move with best type effectiveness
PerformRandomMove	Use a random move
MegaOrGigaIfCan	Activate Mega Evolution or Gigantamax if available
SwitchToEffectiveMonster	Switch to a party member with type advantage
UseBattleItems	Use healing or status items when HP is low
IfWildWithRunChanceRun	Wild monsters may attempt to flee

Configuring AI per Trainer

Each trainer NPC can have a different AI configuration:

1. On the trainer's Actor or encounter data, find the AI Configuration field.
2. Assign a BattleAI ScriptableObject.
3. Configure the action component list and their priority order.

Example configurations:

Easy Trainer (Route 1)

1. PerformRandomMove

Medium Trainer (Gym Puzzle)

1. MegaOrGigaIfCan
2. PerformEffectiveMove
3. PerformRandomMove (fallback)

Hard Trainer (Champion)

1. MegaOrGigaIfCan
2. SwitchToEffectiveMonster (when at disadvantage)
3. UseBattleItems (when HP < 25%)
4. PerformEffectiveMove
5. PerformRandomMove (fallback)

The IBattleAI Interface

For DLL-tier users, the AI system is accessed through the BattleAI base class. While you cannot modify the internal implementation without source code, you can:

1. Create new BattleAI ScriptableObjects in the editor.
2. Configure the action component list via the Inspector.
3. Assign them to trainers.

The key interface:

public abstract class BattleAI : ScriptableObject
{
    // List of BattleAction components evaluated in order
    public List<BattleAction> Actions;
}

public abstract class BattleAction : ScriptableObject
{
    // Evaluate whether this action should be taken
    // Returns null if this action does not apply
    public abstract BattleActionResult Evaluate(BattleContext context);
}

ML-Agents Integration

MCE includes experimental ML-Agents-based AI for advanced difficulty:

MLBattleAI

Uses Unity ML-Agents to make decisions based on a trained neural network.

• Difficulty: Variable (depends on training)
• Use Case: End-game trainers, competitive AI, research
• Setup: Requires ML-Agents package and a trained model

Training the AI

1. Install ML-Agents dependencies: .\MLAgentsInstall.ps1
2. Configure training parameters in MLAgentsConfig/OpenMonAgent.yaml
3. Start training: .\RunMLTraining.ps1
4. Monitor with TensorBoard: .\ViewMLResults.ps1
5. Export the trained model (.onnx file)
6. Assign the model to the MLBattleAI component

The MCEBattleAgent class defines the observation and action spaces:

Observations (what the AI sees):

• Own monster's HP %, types, stat stages, status conditions.
• Opponent monster's HP %, types, stat stages, status conditions.
• Available moves and their types.
• Party status (remaining monsters, HP percentages).

Actions (what the AI can do):

• Use move 1-4.
• Switch to party member 1-5.
• Use an item.

ML-Agents Dependency

ML-Agents is a separate package with its own Python dependencies. The core MCE battle system works without it. Only install ML-Agents if you plan to use neural network-based AI.

Creating Custom AI (Source Tier)

With source code access, you can create entirely new AI strategies:

Custom BattleAction

[CreateAssetMenu(menuName = "OpenMon/AI/Actions/Use Status Move If No Status")]
public class UseStatusMoveIfNoStatus : BattleAction
{
    public override BattleActionResult Evaluate(BattleContext context)
    {
        // Check if opponent has no status condition
        if (context.OpponentBattler.StatusCondition != StatusCondition.None)
            return null; // Skip this action

        // Find a status-inflicting move
        foreach (var moveSlot in context.OwnBattler.MoveSlots)
        {
            if (moveSlot.Move.Category == MoveCategory.Status
                && moveSlot.CurrentPP > 0
                && moveSlot.Move.InflictsStatus)
            {
                return new BattleActionResult
                {
                    ActionType = BattleActionType.UseMove,
                    MoveIndex = moveSlot.Index
                };
            }
        }

        return null; // No applicable status move found
    }
}

Custom BattleAI

[CreateAssetMenu(menuName = "OpenMon/AI/Strategies/Expert AI")]
public class ExpertBattleAI : BattleAI
{
    // Override the decision pipeline if needed
    public override BattleActionResult DecideAction(BattleContext context)
    {
        // Custom logic that goes beyond simple action composition
        // e.g., look-ahead prediction, team synergy analysis
        return base.DecideAction(context);
    }
}

AI Difficulty Guidelines

Difficulty	AI Components	Where to Use
Very Easy	Random move only	Wild encounters
Easy	Random with weighted moves	Early routes, youngsters
Medium	Type effectiveness aware	Gym trainers, rivals
Hard	Effectiveness + switching + items	Gym leaders, Elite Four
Expert	Full composition + prediction	Champion, post-game
Neural	ML-trained model	Competitive, challenge modes

Best Practices

1. Match AI to narrative context. A random bug catcher should not play like the Champion.
2. Test AI against player teams of similar level. Unbalanced AI feels unfair.
3. Use the action component pattern. It is easier to maintain than monolithic AI scripts.
4. Provide fallbacks. Always include PerformRandomMove as the last action to prevent the AI from getting stuck.
5. Do not over-optimize AI for early trainers. Players need to learn the system before facing smart opponents.