Tournament System

Comprehensive automated tournament system featuring single-elimination brackets, persistent countdown timers across reboots, wave arena scheduling, live visual bracket GUIs with auto-pagination, Nexo custom items, and spectator integrations.

Feature Highlights

• Automatic Periodic Scheduling: Configure tournaments to run every X hours or days (e.g. interval: "24h").
• Persistent Schedule Across Restarts: If the server reboots with 45 minutes remaining on the countdown, it resumes at 45 minutes rather than resetting.
• Interactive Live Visual Bracket: Dynamic GUI rendering round matchups, player heads, fight statuses, and winners.
• Auto-Pagination: Brackets exceeding 16 players automatically split across pages with previous/next controls.
• Non-Strict Wave Execution: Tournaments can run smoothly even when fewer arenas exist than concurrent matches. Waiting players receive interactive 1-click spectator prompts.
• Full Nexo & CustomModelData Support: Borders, navigation buttons, and overview menu items fully support CustomModelData and Nexo custom items.
• Automated Prize Distribution: Execute custom console commands, send titles, and give rewards to 1st, 2nd, and 3rd place winners.

Commands Reference

All tournament admin subcommands accept either shyamduels.tournament.admin or the global shyamduels.admin permission. /tournament stop is aliased as /tournament cancel, and /tournament forcestart as /tournament force-start.

Configuration Overview (tournament.yml)

yaml# Master toggle: disables all tournaments, commands, and schedulers when false
enabled: false

schedule:
  enabled: true
  interval: "24h"
  initial-delay: "30m"
  persist-schedule-across-restarts: true

players:
  minimum: 4
  maximum: 16
  require-even: true
  odd-player-handling: "BYE" # "BYE", "WAIT", or "CANCEL"
  wait-extension-seconds: 60 # Used when odd-player-handling is "WAIT"

kit:
  default-kit: "Nethpot"
  random-kit: false
  kit-pool:
    - "axe"
    - "cartpvp"
    - "crystal"
    - "BuildUHC"

match:
  time-limit: "5m"
  timeout-behavior: "DISQUALIFY_BOTH" # "DISQUALIFY_BOTH" (default/fallback), "HIGHEST_HEALTH", or "RANDOM_WINNER". Any other value falls back to double disqualification.
  rounds: 1
  round-system: "BEST_OF" # "BEST_OF" (win majority e.g. Best of 3) or "FIRST_TO" (e.g. First to 3 wins)
  affect-elo: false
  record-stats: false

countdown:
  registration-seconds: 120      # Registration countdown when a tournament is announced
  match-start-seconds: 5         # Countdown before players can move/fight
  round-transition-seconds: 10   # Pause between rounds
  broadcast-intervals: [120, 60, 30, 15, 10, 5, 3, 2, 1]

arenas:
  reserve-before: "5m"
  strict-mode: false
  force-reserve: true
  minimum-required: 1

rules:
  allow-join: true
  allow-leave: true
  block-parties: true            # Players must leave their party to join
  block-queues: true             # Participants cannot join normal queues or FFA
  broadcast-replacements: true   # Announce open slots when someone leaves during registration
  return-to-previous-location: true

spectator:
  enabled: true
  # Automatically spectate when eliminated
  auto-spectate-on-elimination: false
  # Auto-teleport waiting players to spectate the active match (non-strict mode)
  # They exit spectator automatically when their own match is ready
  auto-spectate-waiting-players: false
  # When auto-spectate is false, send a 1-click [CLICK TO SPECTATE] chat prompt
  notify-waiting-players: true

rewards:
  first-place:
    enabled: true
    title: "<gradient:#37F699:#55FFFF><bold>CHAMPION!</bold></gradient>"
    subtitle: "<gray>You won the <aqua>%kit%</aqua> tournament!</gray>"
    commands:
      - "eco give %player% 10000"
      - "give %player% diamond 10"
  # second-place / third-place / participation blocks follow the same layout
  # (participation has no title/subtitle, only enabled + commands)

Bracket GUI: Navigation & Pagination

The live bracket viewer GUI supports full Nexo / CustomModelData items and auto-paginates brackets with more than 16 players.

Messages: Waiting Player Notification

When spectator.notify-waiting-players is true, waiting participants receive a clickable chat prompt. Customise the text in tournament.yml under messages.waiting-match-running.

PlaceholderAPI Placeholders