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

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:

🎨 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:

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

Real-time scoreboard showing top 3 players

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.