Full reference guide for config.yml, advanced calendar scheduling, reward execution, and internal anti-exploit mechanics.

Configuration (`config.yml`)

The config.yml file is generated inside the plugins/NBContest/ folder. It controls the game rules, worlds, interface components, automatic calendar scheduling, and reward command tables.

Default Configuration File

Here is the exact default structure of the config.yml generated on startup:

# ========================================
#        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"

# List of worlds where events are active
# Players can only earn points in these worlds
active-worlds:
  - "world"
  - "world_nether"
  - "world_the_end"

# ========================================
# 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

# Action Bar Configuration
actionbar:
  # Enable/disable the action bar display during contests
  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
  # Format : Specific days (DAILY, MONDAY, TUESDAY, etc.)
  # You can use a simple time string (random type) or an object with 'time' and 'type' (specific type, ONLY for farming)
  farming:
    DAILY:
      - "18:30"
    SATURDAY:
      - time: "14:00"
        type: POTATOES
      - time: "16:00"
        type: CARROTS
    SUNDAY:
      - time: "21:10"
        type: WHEAT
      - "18:00"
  
  fishing:
    DAILY:
      - "15:00"
  
  hostiles_mobs:
    DAILY:
      - "21:00"
    FRIDAY:
      - "16:00"
  
  passive_mobs:
    DAILY:
      - "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"

Detailed Option Breakdown

General Settings

duration : The length of active contests (in seconds). Default is 300 (5 minutes).
timezone : The reference clock used by the automatic scheduler (e.g. Europe/Paris, America/New_York, UTC).
active-worlds : List the exact string names of the worlds where players can gain points. In other worlds, breaking blocks, fishing, or killing mobs will be ignored. Leave it empty to activate the contest globally in all worlds.

Display Settings

bossbar.enabled : Enable/disable the linear Boss Bar showing at the top center of the screen during events.
bossbar.color : Accepts PINK, BLUE, GREEN, RED, YELLOW, PURPLE, WHITE.
scoreboard.enabled : Renders the live top 3 score sidebar during events.
actionbar.enabled : Shows real-time points popups above the player's hotbar.

Contest Objectives

objective.fixed : If true, the target objective score (needed to instantly win a farming contest early) is exactly the amount value. If false, the goal is randomized between min and max on contest launch.

Advanced Scheduler Configuration

The automatic event engine parses times at 10-second intervals. You can configure times in three different structural modes depending on your scheduling requirements.

1. Daily Simple Time Lists

Runs the event every single day at the given times. For farming events, the crop is selected randomly from farming.block-types.

auto-events:
  enabled: true
  fishing:
    - "15:00"
    - "20:00"

2. Day-Specific Scheduling

Run contests only on specific days of the week (DAILY, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY).

auto-events:
  enabled: true
  hostiles_mobs:
    DAILY:
      - "21:00"
    FRIDAY:
      - "16:00"
      - "23:30"

3. Targeted Crop Schedules (Farming Only)

For farming events, instead of a random crop selection, you can enforce a specific target material on specific times using map parameters (time and type):

auto-events:
  enabled: true
  farming:
    DAILY:
      - "18:30" # Picked randomly
    SATURDAY:
      - time: "14:00"
        type: POTATOES # Forces potato harvesting at 14:00
      - time: "16:00"
        type: CARROTS   # Forces carrot harvesting at 16:00
    SUNDAY:
      - time: "21:10"
        type: WHEAT    # Forces wheat harvesting at 21:10
      - "18:00"        # Picked randomly

Under the Hood: Safe Play & Exploit Prevention

NBContest has custom listeners written into its core logic to prevent players from exploiting scoreboard points and to keep events balanced.

1. Block Placement Anti-Cheat

In many farming plugins, players can bypass mechanics by simply placing a crop block and breaking it repeatedly.

Mechanism: When a contest starts, the plugin tracks every block placed by players inside active worlds (stored as physical locations in memory). If a player breaks a block that was placed by a player during the event, no points are awarded.
Memory Management: Placed block coordinates are automatically cleared when chunks unload from memory to keep the server lightweight and avoid RAM leaks.

2. Crop Growth Validation

Players cannot cheat by breaking freshly planted seeds.

Mechanism: For any crop containing age properties (WHEAT, POTATOES, CARROTS, BEETROOTS), the block-break listener checks the crop age. Points are only credited if the plant is fully mature (reaches its maximum possible growth age).

3. Stacked Sugar Cane Support

Mining tall crops like Sugar Cane block-by-block can be tedious.

Mechanism: If SUGAR_CANE is broken, the plugin instantly scans up to 2 blocks directly above the broken block. If they are also Sugar Canes, the listener awards points for every block in the stack broken in that single action.

For Mob Hunting (hostiles_mobs) and Culling (passive_mobs), points are only added if the mob was personally slain by a player (i.e. event.getEntity().getKiller() is not empty). Deaths from natural fires, fall damage, cacti, or mob-grinder lava pits do not reward any points.

Configuration