Developer API

Other plugins can read and change fishing progress, react to catches, change them before they happen and add their own catch rules. The API is published on its own as busyfishing-api: the net.busybee.busyfishing.api package and its event subpackage, plus the types they use (FishData, FishTier, CatchHook, CatchContext, FishingSpeedCalculator, Stat, AugmentType, FishingSkill, TournamentType). You build against the API; the server needs the BusyFishing plugin itself to run it.

Setup

Maven:

xml

    busybee
    https://repo.busybeedev.net/public-releases



    net.busybee.busyfishing
    busyfishing-api
    VERSION
    provided
    
        
            *
            *
        
    

Gradle:

kotlin
repositories {
    maven("https://repo.busybeedev.net/public-releases")
}

dependencies {
    compileOnly("net.busybee.busyfishing:busyfishing-api:VERSION") {
        isTransitive = false
    }
}

Use the BusyFishing version your server runs for VERSION. Don't shade the API into your plugin: BusyFishing provides it at runtime.

Add BusyFishing to your plugin.yml so it loads first:

yaml
depend: [BusyFishing]      # or softdepend, if your plugin also runs without it

Getting the API

java
BusyFishingAPI api = BusyFishingAPI.get(); // null while BusyFishing is not enabled

It is registered with Bukkit's services manager, so Bukkit.getServicesManager().load(BusyFishingAPI.class) works too.

Threads

Anything that takes a Player reads or changes that player's live data. On Folia, call it on the player's own thread: inside an event about that player, or through player.getScheduler(). Methods that need a module return a neutral value (0, null, false) while that module is off.

Methods

Method What it does
getVersion() BusyFishing's version
isModuleEnabled(String) Whether a module ("fish", "augments", ...) is on
getLevel(Player), getXp(Player), getXpToNextLevel(Player), getSkillPoints(Player) Progress
giveXp(Player, long) Gives XP, with level-ups and a PlayerXpGainEvent (reason API)
getEntropy(Player) Entropy balance
giveEntropy(Player, long) Gives entropy, with an EntropyGainEvent (reason API)
takeEntropy(Player, long) Takes entropy if the player has enough; false otherwise
getStat(Player, Stat) One stat, e.g. Stat.FISH_CAUGHT, Stat.MONEY_MADE
getAllFish(), getFish(FishTier, int) Fish from fish.yml
getFish(ItemStack) Which fish an item is, or null
createFishItem(FishData, int) A new fish item
registerCatchHook(Plugin, CatchHook), unregisterCatchHook(CatchHook) Take part in every catch
isPyroCompat() Whether the server runs in PyroFishingPro compatibility mode

Catch hooks

A CatchHook runs inside every catch. Override only the steps you need:

java
api.registerCatchHook(this, new CatchHook() {
    @Override
    public void beforeRoll(CatchContext ctx) {
        // +1% Gold for players with a permission
        if (ctx.player().hasPermission("myplugin.goldluck")) {
            ctx.addTierBonus(FishTier.GOLD, 100);
        }
    }

    @Override
    public boolean allows(CatchContext ctx, FishData fish) {
        // keep one fish out of a world
        return !(fish.tier() == FishTier.MYTHICAL && fish.number() == 1
                && ctx.location().getWorld().getName().equals("lobby"));
    }
});
Step When
casting(Player, FishingSpeedCalculator) The line is cast: change how long the bite takes
blocksCustomFish(Player, Location) Return true to leave this catch vanilla
beforeRoll(CatchContext) Before the tier roll: addTierBonus, multiplyTier, rollRange
afterTier(CatchContext) The tier is rolled; ctx.tier can still change
allows(CatchContext, FishData) Whether this fish may be picked
rewards(CatchContext) Add to entropyBonus, xpBonus or amount
caught(CatchContext) The catch is final

Your hooks run after BusyFishing's own, stay through /fish reload, and are removed when your plugin is disabled.

Events

All in net.busybee.busyfishing.api.event.

Event When Cancellable
FishPreCatchEvent A fish is picked, before anything is paid. setFish, setAmount yes
FishCatchEvent After the catch, with the fish, amount, item and location
PlayerXpGainEvent Before XP is added. setAmount, getReason() yes
PlayerLevelUpEvent After one or more levels were gained
EntropyGainEvent Before entropy is added. setAmount, getReason() yes
FishSellEvent After a player sold fish and was paid
SkillUpgradeEvent Before a skill is unlocked or upgraded yes
AugmentApplyEvent Before augments go on a rod yes
DeliveryCompleteEvent After a delivery was collected
CodexDiscoverEvent A player is the first on the server to catch a fish
BossSpawnEvent / BossDefeatEvent A fishing boss spawns / is killed
TournamentStartEvent / TournamentEndEvent A tournament starts / ends, with the standings
PyroDataMigratedEvent A player's PyroFishingPro progress was moved. Async

Reasons for XP are CATCH, BOSS, API, OTHER; for entropy CATCH, GUTTING, DELIVERY, SKILL, BOSS, API, OTHER. Admin commands (/fish addxp, /fish addentropy) change data directly and don't fire them.

java
@EventHandler
public void onCatch(FishCatchEvent event) {
    if (event.getTier() == FishTier.MYTHICAL) {
        Bukkit.broadcast(Component.text(event.getPlayer().getName() + " caught " + event.getFish().name()));
    }
}

Addons written for PyroFishingPro

BusyFishing ships its own versions of the three events PyroFishingPro offered (me.arsmagica.API.PyroFishCatchEvent, TournamentStartEvent, TournamentEndEvent) and answers to the plugin name PyroFishingPro, so an addon built for Pyro loads and keeps working. They fire only while pyro-compat is on. PyroFishCatchEvent.isHotspot() is always false. New addons should use the events above.