Wild Battle API

### [Please consider supporting me on ko-fi if you like the mod and can afford it, I appreciate even 1 dollar. ](https://ko-fi.com/raguto) --- _**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 ` - `/wildbattleapi debug on` - `/wildbattleapi debug off` - `/wildbattleapi debug status` Aliases: - `/wba ui` - `/wba difficulty ` - `/wba debug on|off|status` These commands require permission level `2`. Developer Usage ## 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`): ```json { "depends": { "wild_battle_api": "*" } } ``` NeoForge (`META-INF/neoforge.mods.toml`): ```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: ```gradle dependencies { modCompileOnly files("libs/wild_battle_api-fabric-1.0.0.jar") } ``` NeoForge example: ```gradle 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. ```java 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: ```java 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`. ```java 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.