Nexal Fishing

Nexal Fishing replaces vanilla fishing loot with configurable custom fish across five rarity tiers (Common, Uncommon, Rare, Epic, Legendary). Every catch pays money through Vault and experience, plays rarity-specific particles, sounds, titles or action bar messages, and is recorded in the player's collection and statistics. Players browse their discoveries in a collection GUI and compete on a leaderboard and in timed tournaments with boss bar tracking and automatic prizes. Admins manage everything from an in-game admin menu, and data is stored in JSON or MySQL/MariaDB with export and import.

Features

Five Rarity Tiers - Common, Uncommon, Rare, Epic and Legendary fish, each with its own particles and catch sound.
Custom Fish - Every fish sets its rarity, catch weight, display name, money, XP, quantity range, permission, display item, dropped item, custom model data, lore and console commands.
Catch Feedback - Rare and better catches show a title, Common and Uncommon an action bar, both with what the catch paid. Text, sounds and timings are set per rarity in messages.yml.
Display and Dropped Items - The floating catch shows the display item; whatever collects it (the player, a mob or a hopper) receives the dropped item, so a display item is never handed out. The fish's commands run as soon as it is caught.
Economy and XP Rewards - Vault money and experience per catch (replacing vanilla fishing XP), tracked as lifetime totals.
Fish Collection GUI - Paginated menu of every fish sorted by rarity; caught fish show their catch count and value, undiscovered fish show as gray glass.
Player Statistics - Total catches, collection progress, rarest catch, money and XP earned, for yourself or any player.
Leaderboard GUI - Top fishers with player heads, ranked by total catches, unique fish or money earned.
Fishing Tournaments - Timed competitions with a boss bar showing the leader and time left, the top places announced at the end, and console prize commands for the top players.
Bite Timing and Pull - Configurable wait range before a fish bites, and an optional pull toward the bobber on each catch.
Admin Menu - /fishing admin opens a hub with settings, tournament control, the fish list, player data with resets, reload, export and import.
PlaceholderAPI Support - Catches, collection, rarest fish, leaderboard positions and tournament status.
Dual Storage - JSON for single servers or MySQL/MariaDB for networks, written in the background so catches never wait on storage.

Technologies

Paper API 1.20.1+ - Minecraft server API (Spigot compatible)
Utilizer - Configuration, messages, items, tasks, GUIs
ACF - Command framework
nexal-core - JSON and SQL persistence (MariaDB/MySQL), help menus
Vault - Economy rewards (optional)
PlaceholderAPI - Placeholder integration (optional)

Commands

Aliases: /fishing, /fish, /nexalfishing.

Player Commands

Command	Description	Permission
`/fishing`	Open the fish collection (help from the console)	`nexalfishing.use`
`/fishing collection`	Open the fish collection (alias `gui`)	`nexalfishing.use`
`/fishing stats [player]`	View fishing statistics	`nexalfishing.use`
`/fishing leaderboard`	Open the leaderboard (aliases `lb`, `top`)	`nexalfishing.use`
`/fishing help [page]`	Show help	None

Admin Commands

Command	Description	Permission
`/fishing admin`	Open the admin menu (admin help from the console)	`nexalfishing.admin`
`/fishing admin help [page]`	Show admin help	`nexalfishing.admin`
`/fishing admin reload`	Reload the fish from config.yml	`nexalfishing.admin`
`/fishing admin stats \<player>`	View a player's statistics	`nexalfishing.admin`
`/fishing admin reset \<player>`	Reset a player's fishing data	`nexalfishing.admin`
`/fishing admin tournament start [seconds]`	Start a tournament (default duration from config, at least 1 second)	`nexalfishing.admin`
`/fishing admin tournament stop`	Stop the tournament and award prizes	`nexalfishing.admin`
`/fishing admin export`	Export data to `export/fishing_users.json`	`nexalfishing.admin`
`/fishing admin import`	Import data from `export/fishing_users.json`	`nexalfishing.admin`

/fishing tournament start and /fishing tournament stop from earlier versions still work.

Configuration - bite wait range, pull force, default tournament duration, boss bar color and style, saved to config.yml.
Tournament - left click to start with the default duration, right click to stop.
Fish - every configured fish with its chance, rewards, quantity, permission and model data.
Player Data - every player with catches; shift right click resets one.
Reload, Export, and Import (shift right click).

Permissions

Permission	Description	Default
`nexalfishing.*`	All fishing permissions	op
`nexalfishing.use`	Collection, stats and leaderboard commands	true
`nexalfishing.admin`	Admin menu and admin commands	op

A fish with a permission set in config.yml is only caught by players who have it.

Placeholders

Requires PlaceholderAPI.

Placeholder	Description
`%nexalfishing_catches%`	Player's total catches
`%nexalfishing_catches_\<fish>%`	Player's catches of one fish (fish ID from config.yml)
`%nexalfishing_unique%`	Number of different fish the player has caught
`%nexalfishing_rarest%`	Name of the player's rarest catch, or `None`
`%nexalfishing_top_\<position>_name%`	Name at a leaderboard position (1 to 100), or `-`
`%nexalfishing_top_\<position>_catches%`	Total catches at a leaderboard position, or `0`
`%nexalfishing_tournament_active%`	`yes` or `no`
`%nexalfishing_tournament_remaining%`	Time left in the tournament
`%nexalfishing_tournament_leader%`	Name of the tournament leader, or `Nobody`
`%nexalfishing_tournament_score%`	Player's catches in the current tournament

The leaderboard placeholders refresh every 30 seconds. Where there is no player (a global hologram), the player placeholders read as empty stats (0, None).

Configuration

config.yml

storage:
  type: json  # json or sql
  sql:
    host: localhost
    port: 3306
    database: minecraft
    username: root
    password: ""

fishing-options:
  # Wait before a fish bites, in ticks (20 ticks = 1 second)
  min-wait-ticks: 50
  max-wait-ticks: 150
  # Pull toward the bobber on catch (0 to disable)
  pull-force: 0.5

# How money is shown in messages and menus (%money%)
economy:
  price-format: "$%amount%"
  number-format: "#,##0.00"
  hide-zero-decimals: true

tournament:
  # Default duration in seconds (at least 1)
  default-duration: 300
  # Placeholders: %leader%, %leader_score%, %time%. MiniMessage and legacy & colours both work
  bossbar-title: "<gradient:#3498DB:#5DADE2>\<bold>FISHING TOURNAMENT\</bold>\</gradient> \<gray>|\</gray> <gradient:#FFC107:#FFCD38>%leader%\</gradient> \<gray>|\</gray> \<white>%time%\</white>"
  bossbar-color: YELLOW
  bossbar-style: SOLID
  # Top places announced at the end (every place with a prize is announced too)
  announce-top: 3
  # One console command per position, top first. Placeholders: %player%, %position%, %catches%
  prizes:
    - "eco give %player% 5000"
    - "eco give %player% 2500"
    - "eco give %player% 1000"

fish:
  diamond_catch:
    rarity: LEGENDARY          # COMMON, UNCOMMON, RARE, EPIC, LEGENDARY
    chance: 0.2                # weight against the other fish
    display-name: "Sea Diamond"     # shown in the rarity's colour
    money: 3000.0              # requires Vault
    xp: 120
    quantity:                  # amount of the dropped item
      min: 1
      max: 3
    # permission: "vip.fish"   # optional: only players with it catch this fish
    model-data: 0              # custom model data for resource packs, 0 for none
    display-item:              # shown while the catch floats
      material: DIAMOND_BLOCK
    dropped-item:              # what the catch turns into when collected
      material: DIAMOND
    lore:                      # MiniMessage or legacy & colours
      - "<gradient:#F39C12:#F7DC6F>\<bold>A flawless diamond from the deep!\</bold>\</gradient>"
    commands:                  # console commands when caught, %player% = who caught it
      - "say %player% found a legendary Sea Diamond!"

The default config ships 12 fish across all five rarities.

messages.yml

All messages are customizable with MiniMessage colors, sounds, titles and action bars. The catch feedback is set per rarity under catch: with the placeholders %fish%, %rarity%, %money%, %xp% and %rewards%. Keys missing from an older messages.yml fall back to the built-in text.

Database Schema

When using SQL storage, the plugin creates the following table. With JSON storage the same records live under fishing_users in data.json.

`fishing_users`

Column	Type	Key	Description
`id`	VARCHAR(36)	PK	Player UUID
`total_catches`	INT		Lifetime catches
`money_earned`	DOUBLE		Lifetime money from catches
`xp_earned`	INT		Lifetime XP from catches
`rarest_catch`	VARCHAR(64)		Fish ID of the rarest catch
`rarest_rarity_ordinal`	INT		Rarity of the rarest catch (0 Common to 4 Legendary)
`fishCatches`	TEXT		JSON map of fish ID to catch count

Key Legend: PK = Primary Key

Installation

Download the plugin JAR
Place it in the /plugins folder, with Vault and an economy plugin for money rewards
Start or restart the server
Configure config.yml (or use /fishing admin)
Reload the fish with /fishing admin reload; other changes apply when the file is saved

To move from JSON to SQL: /fishing admin export, set storage.type: sql, restart, then /fishing admin import.

Features​

Technologies​

Commands​

Player Commands​

Admin Commands​

Admin Menu​

Permissions​

Placeholders​

Configuration​

config.yml​

messages.yml​

Database Schema​

fishing_users​

Installation​