Developer Usage

Supported Public API

Use only these classes for third-party integrations:

• com.github.raguto.wildbattleapi.api.WildBattleAPI
• com.github.raguto.wildbattleapi.api.WildAIProvider
• com.github.raguto.wildbattleapi.api.WildAIContext

Do not depend on internal packages such as impl, mixin, config, or network.

Runtime Dependency

Install Wild Battle API anywhere your dependent mod loads. In normal modpacks, that means both client and server.

Mod ID:

• wild_battle_api

Also declare it as a dependency in your mod metadata.

Fabric (fabric.mod.json):

{
  "depends": {
    "wild_battle_api": "*"
  }
}

NeoForge (META-INF/neoforge.mods.toml):

[[dependencies.your_mod_id]]
modId = "wild_battle_api"
type = "required"
versionRange = "[1.0.0,)"
ordering = "AFTER"
side = "BOTH"

Adjust the minimum version to the first Wild Battle API version your mod supports.

Compile-Time Dependency

If you are not consuming a published Maven artifact, compile against the loader-specific jar directly.

Fabric example:

dependencies {
    modCompileOnly files("libs/wild_battle_api-fabric-1.0.0.jar")
}

NeoForge example:

dependencies {
    compileOnly files("libs/wild_battle_api-neoforge-1.0.0.jar")
}

Use the loader-appropriate jar for your environment.

Registering a Provider

Register your provider once during your mod's common initialization.

import com.github.raguto.wildbattleapi.api.WildBattleAPI;
import com.github.raguto.wildbattleapi.api.WildAIContext;

public final class MyWildAIRegistration {
    public static void init() {
        WildBattleAPI.registerProvider(150, context -> {
            if (shouldUseMyAI(context)) {
                return new MyCustomWildBattleAI();
            }
            return null;
        });
    }

    private static boolean shouldUseMyAI(WildAIContext context) {
        return context.getBattle() != null && context.getActor() != null;
    }
}

You can also register at the default priority:

WildBattleAPI.registerProvider(context -> null);

Priority Guidance

• 0: catch-all or default provider
• 50: standard override
• 100+: high-priority or boss-specific override
• 200+: hard override, use carefully

If your provider only handles specific cases, return null for everything else.

Implementing Your Own BattleAI

You may provide any class that implements Cobblemon's BattleAI.

import com.cobblemon.mod.common.api.battles.model.PokemonBattle;
import com.cobblemon.mod.common.api.battles.model.ai.BattleAI;
import com.cobblemon.mod.common.battles.ActiveBattlePokemon;
import com.cobblemon.mod.common.battles.BattleSide;
import com.cobblemon.mod.common.battles.PassActionResponse;
import com.cobblemon.mod.common.battles.ShowdownActionResponse;
import com.cobblemon.mod.common.battles.ShowdownMoveset;
import com.cobblemon.mod.common.net.messages.client.battle.BattleHealthChangePacket;
import org.jetbrains.annotations.Nullable;

public final class MyCustomWildBattleAI implements BattleAI {
    @Override
    public ShowdownActionResponse choose(
        ActiveBattlePokemon activeBattlePokemon,
        PokemonBattle battle,
        BattleSide side,
        @Nullable ShowdownMoveset moveset,
        boolean forceSwitch
    ) {
        if (forceSwitch || moveset == null) {
            return PassActionResponse.INSTANCE;
        }

        // Replace this with your own move or switch logic.
        return PassActionResponse.INSTANCE;
    }

    @Override
    public void onHealthChange(BattleHealthChangePacket packet) {
        // Optional state tracking.
    }
}

WildAIContext

WildAIContext gives providers the information needed to decide whether to claim a wild battle actor.

Always available:

• getActor()
• getPokemonList()
• getBattle()
• isForceSwitch()

Nullable depending on the current decision:

• getActiveBattlePokemon()
• getAiSide()
• getMoveset()

Guard nullable fields before using them.

Integration Notes

• Keep provider logic fast and predictable.
• Return null when your mod does not want to claim the current context.
• Avoid throwing exceptions from provider or AI logic.
• Test in both dedicated server and integrated singleplayer.
• If multiple mods register providers, higher numeric priority is checked first.