Duels

Duels is a fully GUI-driven duels plugin. Every feature is reachable from the in-game menu, so no chat commands are required to play, though full command equivalents are provided for convenience and automation.

Dueling

• Challenge a player by clicking their head in a menu, or with /duel <player>
• Fight with your own inventory, an admin-published kit, or your own saved personal kit
• Toggleable arena mode: teleport, countdown, fight - or leave it off and hunt each other down in the open world with a compass tracker and live distance indicator
• A clear VICTORY! / DEFEAT title and sound the instant a fight ends - no more guessing from a silent gear swap
• Forfeit, disconnect-safe auto-forfeit, and a safety-net draw timeout all handled automatically

Wagers & Payouts

• Stakes are optional by default - duel for free, or wager currency on yourself and take the pot
• Admins can flip one switch to require a real wager on every duel server-wide
• The winner is handed a trophy head of the loser, with hover text noting the duel and the wager
• Multi-currency support, per-currency min/max stakes, and an optional tax on winnings only (never on a refund)
• Stake real items too, not just currency - drag them into a stake area and confirm; the winner takes everything staked by both sides, no tax

Duel Rules & Final Confirmation

• RuneScape Duel Arena-style rule toggles, adapted to Minecraft combat: No Ranged, No Potions, No Food, No Forfeit, No Movement - set per duel or open challenge
• Before any own-items or item-staked duel begins, both players get a final confirmation screen - an own-items duel mirrors exactly what the opponent is currently wearing/carrying, an item-staked duel lays out both sides' staked items side by side
• Both must click Ready before the fight starts; either can cancel, returning any staked items instantly

Spectating & Betting

• Open Fights board: every live duel on the server, one click to teleport in and watch
• Open Challenges board: post an un-targeted challenge - no need to pick an opponent, anyone online can accept it, coinflip-board style
• Parimutuel spectator betting on either fighter, completely separate from the duelists' own stake - no house bankroll, the pool only ever pays out what was put in

Kits

• Admin kits and personal kits (up to a configurable cap per player), built in a real drag-and-drop in-game editor with a fill-from-current-inventory shortcut
• Admin kits also ship in a hand-editable YAML format for spreadsheet-style bulk editing outside the game
• Both duelists always get an identical copy of whichever kit is picked - fully fair by construction

Fairness & Anti-Cheat

• Nobody outside a duel can hit a duelist, and a duelist can't hit anyone outside their own fight - enforced in both directions
• A duel supersedes land-claim/region PvP protection for hits between the two duelists specifically, so a PvP-disabled claim can't stall a fight either side agreed to
• Containers are locked for the whole duel (crafting tables excepted) and items can't be dropped, so gear can't be stashed and retrieved after the match
• Real inventories are snapshotted and safely restored the instant a duel ends, however it ends - including across a server restart mid-duel
• An item held on your cursor the instant a duel starts is folded into your inventory first, so it can't ride into a supposedly identical kit loadout untouched by the wipe

Statistics & Leaderboards

• Lifetime wins, losses, kills, deaths, and streaks with an in-game leaderboard
• YAML storage out of the box, or MySQL to share one leaderboard across a whole network
• Fully cached in memory - stats never block the main thread on a disk or database round-trip

Integrations

None of these are required to load - Duels works standalone with friendly (no-stakes) duels and no leaderboard placeholders. Each one activates automatically the moment it's detected; nothing to configure beyond config.yml.

A currency configured for a backend that isn't installed is simply hidden from menus (with a startup warning) until it becomes available - safe to leave in config.yml either way.

Commands

• /duel - open the hub menu
• /duel <player> [currency] [amount] - challenge a player, optionally pre-filling a stake
• /duel accept, /duel deny - respond to a pending duel request
• /duel forfeit - concede your current duel
• /duel kits - manage your personal kits
• /duel fights - open the Open Fights board
• /duel challenges - post or accept an open challenge
• /duel stats [player] - view a stats card
• /duel top [wins|kills|streak] - open the leaderboard
• /duel arena - manage arenas (administrator)
• /duel kitadmin - manage server kits (administrator)
• /duel reload - reload the configuration (administrator)

Permissions

• duels.use - challenge, accept, save personal kits, and forfeit
• duels.bet - place spectator bets on other players' duels
• duels.admin - manage arenas, manage server kits, and reload the configuration

Configuration options (config.yml)

settings:
  request-expire-seconds: 60          # how long a sent duel request stays pending
  open-challenge-expire-seconds: 300  # how long a posted open challenge stays on the board

  find-timeout-seconds: 120           # free-roam mode: time to find & engage before cancel
  actionbar-tracker: true             # live "Xm away | Ys left" action bar (free-roam only)
  give-compass: true                  # tracking compass (free-roam only)
  same-world-required: false          # restrict duels to same-world opponents only

  isolate-duel-combat: true           # no hits in/out of a duel from outside it, in either direction
  reset-health-on-start: true         # heal both duelists to full at start and end

  broadcast-new-duel: true            # global chat announcement when a duel/open challenge starts
  broadcast-result: true              # global chat announcement of the winner

  require-stake: false                # force every duel/challenge to carry a real wager

  sounds:
    enabled: true
    request: BLOCK_NOTE_BLOCK_PLING
    accept: UI_BUTTON_CLICK
    countdown: BLOCK_NOTE_BLOCK_HAT
    start: ENTITY_ENDER_DRAGON_GROWL
    win: ENTITY_PLAYER_LEVELUP
    lose: ENTITY_VILLAGER_NO

arena:
  enabled: true
  countdown-seconds: 5                # movement-frozen countdown before a fight starts
  fight-timeout-seconds: 300          # safety-net draw timeout, 0 disables it

betting:
  enabled: true
  lock-on-fight-start: true           # false allows betting for the whole fight

kits:
  max-player-kits: 3                  # personal kits a player may save at once

tax:
  stake: { enabled: true, percent: 5.0 }   # taken from duel winnings only, never a refund
  bet:   { enabled: true, percent: 5.0 }   # taken from spectator bet payouts only

statistics:
  storage-type: YAML                  # or MYSQL, to share one leaderboard across a network
  leaderboard-refresh-seconds: 60
  mysql: { host: localhost, port: 3306, database: duels, username: root, password: '', use-ssl: false, pool-size: 4 }

currencies:
  money:
    enabled: true
    display-name: "Money"
    provider: VAULT                   # or EXCELLENTECONOMY (+ currency-id)
    icon: SUNFLOWER
    min-stake: 10.0
    max-stake: 100000.0                # 0 = unlimited
    quick-amounts: [10, 100, 1000, 10000]   # +buttons in the amount picker

Every player-facing chat message, GUI title, and broadcast also lives in a separate messages.yml (MiniMessage formatting, %placeholder% support) - fully customizable without a restart, just /duel reload.