NBContest 🏆

NBContest is a lightweight, fast and highly customizable Minecraft plugin that allows you to host exciting server-wide contests such as farming, fishing, and mob hunting events. It encourages players to compete and earn configurable rewards with real-time visual feedback.

✨ Features

🎮 Contest Types

Farming Contest – Break random crops (wheat, carrots, potatoes, etc.)
Fishing Contest – Catch as many fish as possible!
Passive Mobs Contest – Kill cows, chickens, sheep and more!
Hostile Mobs Contest – Kill hostile mobs like zombies and skeletons!

📊 Real-time Display System

Boss Bar (can be enabled/disabled)
- Shows time remaining and global objective
- Customizable color (PINK, BLUE, GREEN, RED, YELLOW, PURPLE, WHITE)
- Full MiniMessage support for rich formatting
Scoreboard (can be enabled/disabled) - NEW! ✨
- Live display of contest information
- Event name with custom formatting
- Time remaining (MM:SS format)
- Objective progress (for farming events)
- Real-time Top 3 leaderboard
- Shows only active participants
- Fully customizable via messages.yml
Action Bar
- Individual player score display
- Updates in real-time
- Legacy color code support for compatibility

🎁 Rewards System

Top 3 players receive configurable rewards
Execute any console command as reward
Support for multiple commands per rank
Placeholder support (%player%)

⏰ Automatic Event Scheduler

Schedule multiple events per day
Supports multiple times per event type
Fully customizable timezone (e.g., Europe/Paris)
Runs automatically based on server clock
Enable/disable individual events

🎨 Customization

MiniMessage Support for rich text formatting
- Gradients, hex colors, formatting tags
- Hover and click events support
Fully translatable via messages.yml
Configurable objectives (fixed or random)
Custom material names for better localization
Organized configuration with detailed comments

🛠️ Technical Features

Lightweight and optimized for performance
Adventure API integration for modern text components
Paper/Purpur optimized
No dependencies required (standalone)
Automatic cleanup on server shutdown

⌨️ Commands

Command	Description	Permission
`/nbcontest start <event>`	Start a contest (`farming`, `fishing`, `hostiles_mobs`, `passive_mobs`)	`nbcontest.admin`
`/nbcontest stop`	Stop the current contest	`nbcontest.admin`
`/nbcontest reload`	Reload config, schedule and language	`nbcontest.admin`

Event Types

farming - Harvesting contest
fishing - Fishing contest
hostiles_mobs - Monster hunt
passive_mobs - Animal culling

🕒 Automatic Events

Auto-events can be scheduled using auto-events in the config. Each event can have multiple start times, and all times are based on the server's timezone.

Example:

auto-events:
  enabled: true
  farming:
    - "14:00"  # 2:00 PM
    - "18:30"  # 6:30 PM
  fishing:
    - "15:00"  # 3:00 PM

You can configure the timezone with timezone: "Europe/Paris" (or any supported timezone ID).

⚙️ Configuration (`config.yml`)

# ========================================
#        NBContest Configuration
# ========================================
# Plugin for managing competitive events on your Minecraft server
# Discord: https://discord.nb.studio/
# ========================================

# ========================================
# General Settings
# ========================================

# Duration of all events in seconds (default: 300 = 5 minutes)
duration: 300

# Timezone for auto-events scheduling
# Full list: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
# Examples: "Europe/Paris", "America/New_York", "Asia/Tokyo", "UTC"
timezone: "Europe/Paris"

# ========================================
# Display Settings
# ========================================

# Boss Bar Configuration
bossbar:
  # Enable/disable the boss bar during contests
  enabled: true
  
  # Color of the boss bar
  # Options: PINK, BLUE, GREEN, RED, YELLOW, PURPLE, WHITE
  color: YELLOW

# Scoreboard Configuration
scoreboard:
  # Enable/disable the live scoreboard during contests
  # Shows: event name, time remaining, top 3 players, objective progress
  enabled: true

# ========================================
# Contest Objective
# ========================================

objective:
  # If true, use the fixed 'amount' value
  # If false, use a random value between 'min' and 'max'
  fixed: false
  
  # Fixed objective amount (used when fixed: true)
  amount: 100
  
  # Random objective range (used when fixed: false)
  min: 50
  max: 500

# ========================================
# Auto-Events Scheduler
# ========================================

auto-events:
  # Enable/disable automatic event scheduling
  enabled: true
  
  # Schedule for each event type (24-hour format: "HH:MM")
  # You can add multiple times for the same event
  farming:
    - "14:00"
    - "18:30"
  
  fishing:
    - "15:00"
  
  hostiles_mobs:
    - "16:00"
  
  passive_mobs:
    - "17:00"

# ========================================
# Event-Specific Settings
# ========================================

# Farming Contest
farming:
  # Block types that can be harvested during farming contests
  block-types:
    - WHEAT
    - POTATOES
    - CARROTS
    - BEETROOTS
    - PUMPKIN
    - MELON
    - SUGAR_CANE
    - COCOA_BEANS
    - NETHER_WART

# ========================================
# Rewards Configuration
# ========================================
# Rewards are given to the top 3 players at the end of each contest
# You can use any console command with %player% placeholder
# Supports single command (string) or multiple commands (list)

rewards:
  # Farming Contest Rewards
  farming:
    top1:
      - "give %player% minecraft:diamond 5"
      - "eco give %player% 250"
      - "say Congratulations %player%, you won the Farming Contest!"
    top2:
      - "give %player% minecraft:emerald 10"
      - "eco give %player% 150"
    top3:
      - "give %player% minecraft:bread 32"
      - "say Good job %player%!"

  # Fishing Contest Rewards
  fishing:
    top1:
      - "give %player% minecraft:trident 1"
      - "eco give %player% 200"
      - "say %player% caught the biggest fish!"
    top2:
      - "give %player% minecraft:cod 16"
      - "eco give %player% 100"
    top3:
      - "give %player% minecraft:salmon 16"

  # Hostile Mobs Contest Rewards
  hostiles_mobs:
    top1:
      - "give %player% minecraft:netherite_ingot 1"
      - "effect give %player% strength 30 1"
      - "say %player% dominated the Monster Hunt!"
    top2:
      - "give %player% minecraft:iron_sword 1"
      - "eco give %player% 100"
    top3:
      - "give %player% minecraft:shield 1"

  # Passive Mobs Contest Rewards
  passive_mobs:
    top1:
      - "give %player% minecraft:golden_apple 3"
      - "eco give %player% 200"
      - "say %player% is the best farmer!"
    top2:
      - "give %player% minecraft:cooked_beef 32"
      - "eco give %player% 120"
    top3:
      - "give %player% minecraft:leather 16"

💬 Messages (`messages.yml`)

All messages support MiniMessage format for rich text formatting!

Available MiniMessage Tags

Colors: <red>, <green>, <blue>, <yellow>, <gold>, <aqua>, <white>, <gray>, <dark_gray>, etc.
Formatting: <bold>, <italic>, <underlined>, <strikethrough>
Gradients: <gradient:color1:color2>text</gradient>
Hex colors: <#FF5555>text</#FF5555>

Example Configuration

# ========================================
# Contest Messages
# ========================================
contest-started: "<green>[NBContest] <yellow>The %event% <yellow>contest has started!"
contest-ended: "<red>[NBContest] The contest has ended!"
no-participants: "<gray>No players participated in this contest."
farming-objective: "<gold>Goal: <yellow>Break %amount% %material%"

# ========================================
# Display (Boss Bar, Action Bar, Scoreboard)
# ========================================

# Boss Bar
bossbar.farming: "<gold>Time: <white>%time%s <green>- <white>%remaining% %material% left"
bossbar.generic: "<gold>Time: <white>%time%s"

# Action Bar
# Note: Action bar uses legacy color codes (&) because Minecraft action bar
# has limitations with Adventure components. Do not use MiniMessage here.
actionbar.farming: "&e%score% &f%material% harvested"
actionbar.fishing: "&e%score% &ffish caught"
actionbar.mobs: "&e%score% &fmobs killed"

# Scoreboard (Live Display)
# The scoreboard shows real-time contest information
# Can be enabled/disabled in config.yml
scoreboard.title: "<gold><bold>CONTEST"
scoreboard.event: "<yellow>Event: <white>%event%"
scoreboard.time: "<aqua>Time: <white>%minutes%:%seconds%"
scoreboard.remaining: "<green>Remaining: <white>%remaining% %material%"
scoreboard.top-title: "<gold>Top Players:"
scoreboard.top-line: "<gray>#%rank% <green>%player%<dark_gray>: <yellow>%score%"
scoreboard.top-empty: "<gray>#%rank% <dark_gray>---"

# Leaderboard (End of Contest)
top-title: "<gold>Top 5 Players:"
top-line: "<gray>#%rank% <green>%player% <dark_gray>- <yellow>%score% %unit%"

# ========================================
# Event Names
# ========================================
event:
  farming: "<aqua>Harvesting"
  fishing: "<blue>Fishing"
  hostiles_mobs: "<dark_red>Monster Hunt"
  passive_mobs: "<dark_green>Culling"

# ========================================
# Units (for final leaderboard)
# ========================================
unit:
  fishing: fish caught
  hostiles_mobs: mobs killed
  passive_mobs: mobs killed

# ========================================
# Material Names
# ========================================
# Customize how materials are displayed in messages
materials:
  WHEAT: wheat
  POTATOES: potatoes
  CARROTS: carrots
  BEETROOTS: beetroot
  PUMPKIN: pumpkins
  MELON: melons
  SUGAR_CANE: sugar cane
  COCOA_BEANS: cocoa beans
  NETHER_WART: nether wart

# ========================================
# Command Messages
# ========================================
command.no-permission: "<red>You do not have permission to use this command."
command.start.already-running: "<red>A contest is already running."
command.start.unknown-event: "<red>Unknown event: <gold>%event%"
command.start.success: "<green>Contest started: <gold>%event%"
command.stop.not-running: "<red>No contest is currently running."
command.stop.success: "<red>Contest stopped."
command.reload.success: "<green>NBContest configuration and messages reloaded."

🧩 Placeholder Usage

These placeholders are used across messages and rewards:

Placeholder	Description	Example
`%event%`	Event name (translated)	"Harvesting"
`%material%`	Target material	"wheat"
`%amount%`	Objective amount	"100"
`%score%`	Player score	"45"
`%player%`	Player name	"Steve"
`%unit%`	Display unit	"mobs killed"
`%time%`	Time left (seconds)	"180"
`%minutes%`	Minutes remaining	"3"
`%seconds%`	Seconds remaining	"00"
`%remaining%`	Items remaining to goal	"55"
`%rank%`	Player's rank	"1"

🎨 Customization Examples

Gradient Titles

scoreboard.title: "<gradient:gold:yellow>⚔ CONTEST ⚔</gradient>"

Hex Colors

scoreboard.top-line: "<#FFD700>#%rank% <#00FF00>%player% <#FFFF00>%score%"

Emoji Support

scoreboard.title: "<gold>🏆 CONTEST 🏆"
scoreboard.time: "⏱️ %minutes%:%seconds%"
scoreboard.remaining: "🎯 %remaining% %material%"

📊 Display Options

You can enable/disable each display element independently:

Element	Config Option	Description
Boss Bar	`bossbar.enabled: true`	Shows time and objective at the top
Scoreboard	`scoreboard.enabled: true`	Shows live leaderboard on the side
Action Bar	Always enabled	Shows personal score above hotbar

Example configurations:

Minimal (Action Bar only)

bossbar:
  enabled: false
scoreboard:
  enabled: false

Full Display (All enabled)

bossbar:
  enabled: true
scoreboard:
  enabled: true

📸 Screenshots

Contest starting with boss bar and scoreboard

Live Scoreboard
Real-time scoreboard showing top 3 players

Scoreboard Detail
Scoreboard with live updates and player rankings

Performance

Lightweight design with minimal overhead
Efficient scoreboard updates (1 per second)
Optimized player score tracking
Automatic cleanup on contest end

🐛 Known Issues

Action Bar: Due to Minecraft limitations, action bar only supports legacy color codes (&e, &f, etc.) instead of MiniMessage format.
Scoreboard: Text is limited to 40 characters per line (Minecraft limitation).

❤️ Credits

Created with ❤️ by 6rius
Join our Discord for support, suggestions, or questions.

NBContest

📖About NBContest