Skip to content

FishingFestival Guide

FishingFestival is a polished fishing tournament plugin for Paper/Purpur servers. It turns regular fishing into competitive events with custom fish, rarity tiers, live leaderboards, physical trophies, token rewards, and a full in-game admin GUI.

At a glance:

  • 5 tournament types — Biggest Fish, Smallest Fish, Most Fish, Total Score, and Rarest Fish.
  • Custom fish system — define unlimited species with rarities, weights, scores, biome/weather/time restrictions, and custom model data.
  • Live leaderboards — boss bars, action bars, and broadcast announcements.
  • Reward tables — command rewards + festival tokens for 1st, 2nd, 3rd, and participation.
  • Token shop — spend earned tokens on items configured by admins.
  • Trophies — physical winner trophies and rare-catch trophies.
  • Auto scheduling — start festivals automatically by day/time/timezone.
  • Anti-exploit — catch-rate limits, same-spot detection, and minimum catch intervals.
  • Crash recovery — active festivals survive server restarts.
  • Full admin GUI — manage festivals, fish, rewards, schedules, and shop items without touching files.

Install

  1. Put fishingfestival-1.0.0.jar into your server's plugins folder.
  2. Restart the Minecraft server.
  3. The plugin will create:
  4. plugins/FishingFestival/config.yml
  5. plugins/FishingFestival/festivals.yml
  6. plugins/FishingFestival/fish.yml
  7. plugins/FishingFestival/rewards.yml
  8. plugins/FishingFestival/schedules.yml
  9. plugins/FishingFestival/history.mv.db (H2 database)

Quick Start

Start a festival manually from a pre-made profile:

/fishfest start weekend

Players will immediately see a broadcast, a boss bar will appear, and catches will start scoring. When the timer runs out, winners are announced, rewards are given, and results are saved to the database.

Open the player GUI at any time:

/fishfest

Commands

Main command: /fishfest (aliases: /ff, /fishingfestival)

Player Commands

Command Description
/fishfest Open the player GUI.
/fishfest gui or menu Open the player GUI.
/fishfest me Show your current festival stats and rank.
/fishfest top Show the live leaderboard for the active festival.
/fishfest tokens or balance Show your festival token balance.
/fishfest shop Open the token shop.
/fishfest rewards View the active festival's reward table summary.
/fishfest history [player] View recent festival winners, or a specific player's history.
/fishfest alltime View all-time leader records (wins, catches, biggest fish, score, legendary catches).
/fishfest stats [player] View saved database stats for a player (defaults to you).

Admin Commands

Command Description
/fishfest start <profile> Start a festival from a profile in festivals.yml.
/fishfest stop End the active festival immediately and announce winners.
/fishfest pause Pause scoring (catches still happen but do not count).
/fishfest resume Resume paused scoring.
/fishfest reload Reload config.yml, festivals.yml, fish.yml, rewards.yml, and schedules.yml.
/fishfest admin Open the main admin GUI.
/fishfest admin festival or festivals Open the festival manager.
/fishfest admin fish or fishes Open the fish manager.
/fishfest admin rewards or reward Open the reward manager.
/fishfest admin schedules or schedule Open the schedule manager.
/fishfest admin shop Open the shop manager.
/fishfest schedule list List all configured schedules.
/fishfest schedule enable <id> Enable a schedule.
/fishfest schedule disable <id> Disable a schedule.

Permissions

Permission Default Description
fishingfestival.use true Basic festival commands (/fishfest, GUI, /me, /top).
fishingfestival.top true View leaderboards.
fishingfestival.shop true Open the token shop.
fishingfestival.tokens true View token balance.
fishingfestival.start op Start festivals.
fishingfestival.stop op Stop festivals.
fishingfestival.reload op Reload configuration.
fishingfestival.admin op Full admin access (pause, resume, admin GUI, schedule editing, debug).

Tournament Types

Set the scoring mode in each festival profile (festivals.yml):

Type How it scores
BIGGEST_FISH Highest single fish weight wins.
SMALLEST_FISH Lowest single fish weight wins.
MOST_FISH Most total catches wins.
TOTAL_SCORE Highest cumulative score across all catches wins.
RAREST_FISH Best rarity rank wins; ties broken by biggest weight.

Config Files

config.yml

The main settings file.

config-version: 2
prefix: "&b&lFishingFestival &8» &r"
leaderboard-size: 10

messages:
  no-permission: "&cYou do not have permission."
  no-active-festival: "No festival is active. Admins can run &f/fishfest start weekend&r."
  festival-started: "&a{festival} has started! Fish now to compete."
  festival-ended: "&e{festival} has ended!"
  catch: "You caught {rarity_color}{fish} &7({weight}kg, +{score} score)&r"
  catch-token-bonus: "Catch bonus: &f{tokens} &bfestival tokens&r."
  tokens-balance: "You have &f{tokens} &bfestival tokens&r."
  rare-catch-broadcast: "{player} caught {rarity_color}{fish} &7({weight}kg)&r"
  # ... (and more)

formats:
  leaderboard-title: "&b&l{festival} Leaderboard"
  trophy-title-winner: "#{place} Festival Winner"
  trophy-title-rare: "Rare Catch"

anti-exploit:
  min-catch-seconds: 2
  same-spot-check: false
  min-same-spot-distance: 0
  max-catches-per-minute:
    enabled: true
    warning-threshold: 20
    block-threshold: 30

display:
  bossbar: true
  actionbar: true
  rare-sounds: true
  titles: true
  particles: true

gui:
  filler:
    enabled: false
    material: "BLACK_STAINED_GLASS_PANE"
    name: " "
  titles:
    player: "&bFishingFestival"
    admin: "&bFishingFestival Admin"
  buttons:
    back: "&7Back"
    next-page: "&aNext Page"
    previous-page: "&cPrevious Page"

festival-display:
  bossbar-color: "BLUE"
  bossbar-style: "SOLID"

recovery:
  restore-active-festival: true

trophies:
  enabled: true
  winner-trophies: true
  rare-catch-trophies: true
  rare-catch-minimum-rarity: "LEGENDARY"
  material: "NAUTILUS_SHELL"

storage:
  database-file: "history"

tokens:
  enabled: true
  per-catch:
    enabled: true
    rarity:
      COMMON: 0
      UNCOMMON: 0.1
      RARE: 0.2
      EPIC: 0.5
      LEGENDARY: 1.0

shop:
  enabled: true
  title: "&bFestival Token Shop"
  size: 27
  confirm-purchases: true
  filler:
    enabled: false
    material: "GRAY_STAINED_GLASS_PANE"
    name: " "
  items:
    diamonds:
      slot: 10
      material: "DIAMOND"
      name: "&bDiamond Pack"
      lore:
        - "&7Costs &f25 &7tokens"
        - "&7Gives 3 diamonds."
      cost: 25
      commands:
        - "give {player} diamond 3"

Key sections explained:

  • prefix — the plugin's chat prefix. Use & color codes.
  • messages — almost every player-facing message is editable here.
  • anti-exploit — prevents auto-fishing and macro abuse.
  • display — toggles boss bars, action bars, sounds, particles.
  • trophies — configure physical trophies given to winners and rare-catch anglers.
  • tokens — enable/disable tokens and set per-catch token rewards by rarity.
  • shop — define items players can buy with tokens. {player} is replaced in commands.

festivals.yml

Define reusable festival profiles.

config-version: 2
festivals:
  weekend:
    display-name: "Weekend Fishing Derby"
    duration-minutes: 30
    tournament-type: "BIGGEST_FISH"
    worlds:
      - "world"
    auto-join: true
    bossbar: true
    catch-pool: "default"
    rewards: "weekend-rewards"
  • display-name — shown in broadcasts and the boss bar.
  • duration-minutes — how long the festival lasts.
  • tournament-type — BIGGEST_FISH, SMALLEST_FISH, MOST_FISH, TOTAL_SCORE, or RAREST_FISH.
  • worlds — restrict to specific world names. Empty list = all worlds.
  • bossbar — show a server-wide boss bar timer.
  • catch-pool — which fish pool to use (matches pools in fish.yml).
  • rewards — which reward table from rewards.yml to use.

fish.yml

Define custom fish species and rarity tiers.

config-version: 2
rarities:
  COMMON:
    color: "&f"
    multiplier: 1.0
    broadcast: false
  UNCOMMON:
    color: "&a"
    multiplier: 1.25
    broadcast: false
  RARE:
    color: "&9"
    multiplier: 1.75
    broadcast: false
  EPIC:
    color: "&5"
    multiplier: 2.5
    broadcast: true
  LEGENDARY:
    color: "&6"
    multiplier: 4.0
    broadcast: true
fish:
  common_carp:
    name: "&fCommon Carp"
    rarity: "COMMON"
    weight-min: 0.5
    weight-max: 4.0
    score: 10
    chance: 60
    material: "COD"
    pools: ["default"]
    worlds: []
    biomes: []
    weather: []
    times: []
    custom-model-data: 0
  golden_trout:
    name: "&6Golden Trout"
    rarity: "LEGENDARY"
    weight-min: 4.0
    weight-max: 22.0
    score: 500
    chance: 2
    material: "TROPICAL_FISH"
    pools: ["default"]
    broadcast: true
  • color — the Minecraft color code prefix for that rarity.
  • multiplier — multiplies the fish's base score.
  • broadcast — if true, server sees a chat broadcast when caught.
  • chance — relative weight in the roll pool. Higher = more common.
  • material — the Bukkit material the caught item becomes.
  • pools — which catch pools this fish belongs to.
  • worlds / biomes / weather / times — optional restrictions. Empty = no restriction.
  • weather: CLEAR, RAIN, THUNDER
  • times: DAY, NIGHT
  • custom-model-data — resource pack support for custom item models.
  • broadcast (per-fish) — overrides rarity broadcast for this species.

rewards.yml

Define command + token reward tables.

config-version: 2
reward-tables:
  weekend-rewards:
    first:
      tokens: 40
      commands:
        - "give {player} diamond 8"
        - "xp add {player} 10 levels"
    second:
      tokens: 25
      commands:
        - "give {player} emerald 16"
    third:
      tokens: 15
      commands:
        - "give {player} gold_ingot 16"
    participation:
      tokens: 5
      commands:
        - "xp add {player} 3 levels"
  • {player} is replaced with the winner's name in commands.
  • tokens are added to the player's festival token balance.

schedules.yml

Configure automatic festival starts.

config-version: 2
schedules:
  saturday-derby:
    enabled: false
    festival: "weekend"
    timezone: "UTC"
    days: ["SATURDAY"]
    time: "19:00"
  • enabled — must be true for the schedule to run.
  • festival — the profile ID from festivals.yml.
  • timezone — any valid Java ZoneId (e.g. UTC, America/New_York).
  • days — list of MONDAY through SUNDAY.
  • time — 24-hour format HH:MM.

Token System & Shop

Players earn tokens in two ways:

  1. Per-catch tokens — configured in config.yml under tokens.per-catch.rarity.
  2. Placement tokens — configured in rewards.yml under each reward table.

Spend tokens in the shop:

/fishfest shop

Shop items are configured in config.yml under shop.items. Each item needs:

  • slot — inventory slot (0–26 for a 27-slot shop).
  • material — Bukkit material name.
  • name — display name with & color codes.
  • lore — item description lines.
  • cost — token price.
  • commands — list of console commands to run on purchase. Use {player}.
  • permission (optional) — restrict purchase to players with this permission.

If shop.confirm-purchases is true, players see a confirmation GUI before buying.

Trophies

When a festival ends, top 3 winners receive a Winner Trophy item (default: Nautilus Shell). The trophy lore includes:

  • Player name
  • Festival name
  • Placement rank
  • Biggest fish species and weight

If rare-catch trophies are enabled, catching a fish at or above the configured minimum rarity (default: LEGENDARY) also awards a Rare Catch Trophy.

Trophy settings are in config.yml under trophies.

Admin GUI

Admins can manage almost everything in-game without editing files.

Open the main admin menu:

/fishfest admin

Main Admin Menu

  • Tournament Type — cycle between the 5 scoring modes.
  • Duration — left click +60s, right click -60s, shift click to type exact seconds in chat.
  • Reward Table — cycle available reward tables.
  • Catch Pool — cycle available fish pools.
  • Bossbar — toggle boss bar display.
  • Reward Builder — create/edit a reward table via chat prompts.
  • Fish Builder — create/edit a custom fish via chat prompts.
  • Fish Manager — list, clone, and delete fish entries.
  • Shop Manager — list configured shop items.
  • Festival Manager — list, start, clone, and delete festival profiles.
  • Schedule Manager — create, toggle, and delete schedules.
  • Reward Manager — list, clone, and delete reward tables.
  • Save Custom Festival — save the current draft to festivals.yml.
  • Save And Start — save the draft, reload profiles, and start the festival.

Festival Manager

Click any festival to edit it. You can:

  • Start it immediately.
  • Adjust duration, type, reward table, and catch pool.
  • Clone it (creates a copy prefixed with clone_).
  • Delete it (only custom/clone entries can be deleted from GUI).

Fish Manager

Click any fish to edit it. You can:

  • Change rarity.
  • Adjust chance.
  • Toggle broadcast.
  • Clone or delete (only custom/clone fish).

Builders (Chat Prompts)

When you use the Reward Builder or Fish Builder, the GUI closes and the plugin waits for you to type values in chat:

  • Reward tokens: type first,second,third,participation (e.g. 40,25,15,5).
  • Reward command: type a console command using {player}.
  • Fish name: type the display name with & color codes.
  • Fish numbers: type minWeight,maxWeight,score,chance (e.g. 1,10,100,5).
  • Fish material: type a Bukkit material name (e.g. TROPICAL_FISH).

Scheduling

Instead of starting festivals manually, create schedules in schedules.yml:

schedules:
  saturday-derby:
    enabled: true
    festival: "weekend"
    timezone: "UTC"
    days: ["SATURDAY"]
    time: "19:00"

The plugin checks every minute. When the current day/time/timezone match, the scheduled festival starts automatically. Each schedule only fires once per minute.

Enable or disable schedules in-game:

/fishfest schedule enable saturday-derby
/fishfest schedule disable saturday-derby

Anti-Exploit

FishingFestival includes built-in protections against auto-fishing and macro abuse:

Setting Default What it does
min-catch-seconds 2 Minimum seconds between qualifying catches.
same-spot-check false Require the player to move between catches.
min-same-spot-distance 0 Minimum distance (blocks) the player must move.
max-catches-per-minute.enabled true Limit catches per minute.
warning-threshold 20 Console warning when a player hits this many catches in 60 seconds.
block-threshold 30 Blocks catches beyond this rate per minute.

If a catch is blocked, the player sees the ignored-catch message.

Crash Recovery

If recovery.restore-active-festival is true (default), the plugin saves the active festival state to plugins/FishingFestival/active-festival.yml every minute.

If the server restarts while a festival is running, it will:

  1. Reload the festival profile.
  2. Restore all player stats and catches.
  3. Resume the timer from where it left off.
  4. Announce the restored festival to the server.

If the festival had already ended during downtime, it is discarded.

Database & History

All completed festival results are stored in plugins/FishingFestival/history.mv.db (H2).

Stored data includes:

  • Festival name, profile, start/end times.
  • Player placements, catches, biggest weight, and total score.
  • Individual catch records (species, rarity, weight, score).
  • Token balances.

Players can query this history with:

/fishfest history
/fishfest history <player>
/fishfest stats <player>
/fishfest alltime

Troubleshooting

  • No festival active message: Admins must start one with /fishfest start <profile> or set up a schedule.
  • Fish not appearing: Check the catch-pool in the festival profile matches a pools entry in fish.yml. Also verify world/biome/weather/time restrictions.
  • Custom model data not showing: Ensure your resource pack is loaded and the custom-model-data value matches.
  • Shop item not working: Verify the material is a valid Bukkit material name. Check console for command errors.
  • Schedule not firing: Make sure enabled: true, the timezone is valid, and the day/time strings are correct.
  • Config changes not applying: Use /fishfest reload or restart the server. Some changes (like shop size) may need a restart.
  • GUI items stuck on cursor: This is prevented automatically, but if it happens, pressing Esc or clicking an empty slot clears it.
  • Leaderboard looks wrong: Remember that each tournament type scores differently. MOST_FISH ranks by catch count, not weight.