Wild Battle API

---

I grant permission to anyone seeking to add my mod to a modpack

---

Wild Battle API

Wild Battle API is a shared wild battle AI framework for Cobblemon.

For players and pack authors, it provides configurable smarter wild battle behavior with built-in presets and admin tools. For developers, it exposes a supported public API for registering custom wild BattleAI implementations without replacing Cobblemon internals directly.

Wild Battle API installs a delegating AI on wild battle actors at battle start. On each AI decision:

• Higher-priority providers are checked first.
• The first provider that returns a non-null BattleAI is used.
• Returning null defers to lower-priority providers.
• If no provider claims the context, the actor's original Cobblemon AI is used as fallback.

This lets multiple mods cooperate safely while keeping a reliable fallback path when no custom provider applies.

Included Features

• Shared API for wild battle AI extensions
• Priority-based provider resolution
• Safe fallback to the actor's original Cobblemon AI
• Built-in configurable smart wild AI behavior
• Difficulty presets from easy to extreme
• Admin UI and debug commands
• Fabric and NeoForge support for Minecraft 1.21.1

Admin Commands

Wild Battle API includes operator/admin commands for testing and configuration.

Commands:

• /wildbattleapi ui
• /wildbattleapi difficulty <easy|medium|hard|extreme>
• /wildbattleapi debug on
• /wildbattleapi debug off
• /wildbattleapi debug status

Aliases:

• /wba ui
• /wba difficulty <easy|medium|hard|extreme>
• /wba debug on|off|status

These commands require permission level 2.

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.

Licensing

Wild Battle API code and binaries are All Rights Reserved.

Third-party usage and distribution permissions are defined by the author policy on the mod page.