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:
busybee
https://repo.busybeedev.net/public-releases
net.busybee.busyfishing
busyfishing-api
VERSION
provided
*
*
Gradle:
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:
depend: [BusyFishing] # or softdepend, if your plugin also runs without it
Getting the API
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:
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.
@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.