Custom Ball Compat API: Custom Balls & Catch-Rate Modifiers

[Akkiruk]

Who this is for

Two situations:

• You made a custom Poké Ball for Cobblemon and want CatchRateDisplay to show the right number for it, instead of falling back to a generic 1x.
• You made a temporary catch rate boost (a food buff, a potion, an item effect) and want it to show up on the HUD.

As of 2.12.0 both of these are self-service. You don't need us to hardcode anything on our end.

Part 1: Custom Balls

Here's the minimum to get a ball recognized:

CatchRateBallRegistry.registerBall(
    ResourceLocation.fromNamespaceAndPath("mymod", "quantum_ball")
) { ctx ->
    BallApiResult(multiplier = 3.5F, conditionMet = true, reason = "Quantum resonance")
}

Call this once when your mod initializes. Once it's registered:

• the live catch rate HUD shows the real multiplier and your reason text while the ball is being thrown
• it shows up in the ball comparison panel automatically, no extra step
• if we ever hardcode support for the same ball ID on our side for some reason, your registration wins

com.catchrate.api has no runtime dependency on CatchRateDisplay, so you can depend on it as compileOnly (or modCompileOnly if you're on Fabric/NeoForge Loom) and your mod will work fine even if a player doesn't have CatchRateDisplay installed. The provider just never gets called.

CatchRateBallProvider

One method:

fun interface CatchRateBallProvider {
    fun evaluate(ctx: BallApiContext): BallApiResult?
}

Returning null tells us to fall back to whatever we'd normally do for that ball ID. You probably won't need this for a ball (unlike a buff, a ball doesn't really come and go) but it's there.

BallApiContext

What you get handed, describing the target Pokémon and the situation:

Field	Type	Notes
speciesId	String	e.g. "pikachu"
level	Int
primaryType	String	e.g. "electric"
secondaryType	String?
weight	Float
baseSpeed	Int
labels	List<String>	e.g. "legendary", "mythical"
statusPath	String?	e.g. "sleep", "paralysis", null if healthy
inBattle	Boolean	false means throwing at a wild overworld Pokémon
turnCount	Int	battle turn, if inBattle
pokemonAspects	Set<String>	form/aspect tags (shiny, regional forms, etc.)

BallApiResult

What you hand back:

Field	Type	Notes
multiplier	Float	your ball's catch rate multiplier
conditionMet	Boolean	is a conditional bonus currently active (this drives the checkmark/x shown next to the reason)
reason	String	short label on the HUD, e.g. "Quantum resonance"
isGuaranteed	Boolean	defaults to false, set true for a Master Ball style guaranteed catch

CatchRateBallRegistry

CatchRateBallRegistry.registerBall(id: ResourceLocation, provider: CatchRateBallProvider)
CatchRateBallRegistry.unregisterBall(id: ResourceLocation)

Use your ball item's actual full ResourceLocation (yourmodid:your_ball), not just the bare name. That's what stops two unrelated mods from colliding if they both happen to name a ball the same thing.

A few other things worth flagging: if your provider throws an exception, we log it once and quietly skip that ball going forward instead of spamming your log every frame. Also, this API only controls what number CatchRateDisplay shows, it doesn't make your item function as a ball. You still need to register it as an actual PokeBallItem through Cobblemon's own API for it to be throwable and catch anything, that part's entirely between you and Cobblemon.

Part 2: Catch Rate Modifiers

This one's for a temporary boost rather than a physical ball, things like a carrot that was eaten or a potion effect. Each active modifier gets its own row on the HUD and multiplies into the final percentage.

CatchRateModifierRegistry.registerModifier(
    ResourceLocation.fromNamespaceAndPath("mymod", "carrot_boost")
) { player ->
    if (player.hasEffect(MY_CARROT_EFFECT)) {
        CatchRateModifierResult(multiplier = 2F, description = "Carrot Boost")
    } else {
        null
    }
}

Register once at init like the ball API. The difference here is that returning null is the normal, expected case whenever your buff isn't active, not an error. When it is active, keep returning a result, this gets evaluated continuously rather than once.

CatchRateModifierProvider

fun interface CatchRateModifierProvider {
    fun evaluate(player: Player): CatchRateModifierResult?
}

This one gets the Player directly rather than a context object, since a modifier is about the player's state (an effect, a held item, whatever) rather than the target Pokémon.

CatchRateModifierResult

Field	Type	Notes
multiplier	Float	folded into the catch percentage along with ball/status/level bonuses
description	String	short label on its own HUD row, e.g. "Carrot Boost"

CatchRateModifierRegistry

CatchRateModifierRegistry.registerModifier(id: ResourceLocation, provider: CatchRateModifierProvider)
CatchRateModifierRegistry.unregisterModifier(id: ResourceLocation)

The ID just needs to be unique to you since there's no item backing it, unlike balls.

If multiple mods have an active modifier at the same time, they all show up as separate rows and all their multipliers get applied together. Same failure handling as the ball API too: a provider that throws gets logged once and skipped after that, not retried every frame.

Source

Both files are under common/src/main/kotlin/com/catchrate/api/ in this repo, CatchRateBallApi.kt for Part 1 and CatchRateModifierApi.kt for Part 2. The doc comments there have the same examples as above if you'd rather just read the source.

If either API is missing a field you need, reply here and let me know.