Skip to content

Tournaments

Quick Start: Host a tournament.

A tournament is a special mode of a playlist:

  • Instead of isolated matches, one playlist runs a whole event (Best-of, single-elimination brackets, round-robin, or bracketed Best-of-N).
  • Parties join as a unit exactly like a normal queue, and every match of the event still looks and feels like a normal match.

Marking a playlist

playlists:
  ranked-bo5-bracket:
    tournament:
      enabled: true
      best-of: 5        # default 3; -1 disables
      use-round-robin: false
      use-brackets: true
      respect-role-weights: false
  • Round-robin only runs when best-of is -1 and use-brackets is false. Best-of and brackets may coexist. An even best-of below 3 warns at load and still runs.
  • Every event gets a stable integer id and a display name (Tournament 1, Tournament 2, ...). States run REGISTERING (queue open) to IN_PROGRESS, ending FINISHED or CANCELLED.

Queue size and the shown max

Tournaments have no player cap: the minimum is the playlist composition sum, and anyone past that keeps the queue open. The queue still shows an X / max figure, where the shown max rises to the next multiple of the recommended unit:

shown_max = max(unit, ceil(queued / unit) * unit)
  • The unit is 2 for any Best-of event, or the composition sum otherwise (8 for 4v4, 5 for 1v4). A 1v4 queue with 7 waiting shows 7/10; the 11th arrival moves it to 11/15. Display only: it never blocks joins.
  • Remainders past full brackets form an overflow bracket that keeps the composition ratio as balanced as possible, and those players get a notice naming it.

Leaving

  • Leaving works exactly like leaving a normal match: the same lobby-vs-spectator destination, the same flow. Ranked pools always pay out on leave (see below), so leaving never forfeits cached gains.
  • The spectator "back to lobby" button needs a double click: the first click warns (a neutral sound plus a message), and a second click within 5 seconds confirms the leave. After that the confirmation expires silently. The leave command goes through the same confirmation.

Match summary bullet

Every match of a tournament adds a Tournament bullet to the match summary with the series standing, for example 1-0 (best of 5) (own team wins first). Localisable under the tournament message keys.

Side balance

Tournament maps balance sides from occurrence counts: each player takes whichever side they have played less, hunter on ties. A 1v1 bracket of 16 (at most four maps) lands each player on hunter twice and runner twice, most preferably in alternating order.

With tournament.respect-role-weights (default off), first matches use role weights instead of a fresh draw: round 0 in brackets (both plain and elo legs; later rounds re-seed uniform), and the single starting fixture in symmetric round-robin. Later matches alternate as usual. See LuckPerms.

Round-robin passes

  • Round robin supports passes (default 1, recommend even values like 2 for balanced roles). Each pass replays the fixtures with opposite sides: the same players get opposite roles next time.
  • The first pass assigns sides fresh, the second pass forces opposites of the first, the third assigns fresh again, the fourth opposites of the third, and so on.
  • Asymmetric modes flip the fixture direction so the sides stay sensible.

Ranked seeding legs

Ranked tournaments support elo-bracketed-legs (default false, brackets only): parties sort by average elo descending, then snake into balanced legs so each leg carries similar strength. Ignored outside brackets.

Spectating

  • Spectator redirects always prefer the player's own tournament: live matches of the same event come first (closest neighbor bracket first, ties resolving to the lower bracket), and only when none exist does the normal redirect config apply. One entry point enforces this, so no path can skip it.
  • The spectator match browser shows a CHEST row named Tournament N ahead of the normal entries, with the format summary and the current leader (highest cumulative match score, ties broken alphabetically). Clicking it opens a panel of every match of the event, live and completed.

Match-to-match transitions

When a tournament match ends, its players never touch the lobby between rounds:

  • Players already assigned to the next match stay where they are, skipping the lobby teleport and the lobby toolbar, and the next match teleports them directly once it finishes preparing.
  • Players whose next match cannot start yet (a round robin waiting on other fixtures, a bracket waiting on other slots in the tier) spectate the best live match of their own tournament while they wait, then ride the same direct teleport when their match prepares.
  • Anything that fails along the way falls back to the lobby path with a console warning, so a routing fault can never strand a player.

Byes

  • When a bracket has no opponent (the whole opposing side left), its players are not eliminated: they carry into the next round and spectate the closest neighbor bracket while they wait.
  • A bye still counts as a loss in match history, stats, and tournament score, and it settles the ranked pool against a virtual opponent rated at the round's mean effective elo (see below). Byes are recomputed every round.

Commands

  • /mh tournament history <id> shows the bracket tree or final standings of a live or finished event, with pooled elo gains, applied loss, and net change for ranked events. It replays your own run's TOURNAMENT SUMMARY lines when you left early. Permission: jmanhunt.command.tournament.
  • /mh tournament start <playlist> [lobby] force-starts the registering event. /mh tournament cancel <playlist> [lobby] cancels it. Both need jmanhunt.admin.

Ranked elo: the pool

Ranked tournaments never pay per match. Each participant has a pool ledger:

  • Every match caches its win and loss deltas at start, from effective elo (current elo + pooled gains). Cached values are immutable: later tuner updates never touch them.
  • A win banks the cached win delta into the pool. Nothing touches real elo yet.
  • The pool settles into one net change when the run ends (elimination, title, leave, disconnect) or at a bye: net = pooled gains + loss delta. The net can be positive. Settlement respects the ranked floor and rounding rules and is persisted, so a crash cannot lose gains or double-apply.
  • The champion settles the full pool with no loss component.

Example: wins caching +20 and +15, then an elimination with a cached -18 pays 20 + 15 - 18 = +17.

Format notes:

  • Best-of: only the series result counts. The delta cached when the series opens (game one) represents the whole series: a series win banks it, a series loss settles it.
  • Brackets: same pool math per round; matchmaking and later deltas use effective elo.
  • Round-robin: no elimination, so both wins and losses feed one running sum that settles at tournament end (or on leave). Per-match deltas scale by round-robin-elo-scale (default auto: ceil(log2(entries)) / fixtures per entry, clamped to 0.05-1.0, so a perfect run pays about the same as a bracket title of the same size). Leaving forfeits each unplayed match with a delta computed at that moment. Standings ties never affect elo.
  • The auto-weights tuner samples finished individual maps and never mutates a cached delta.

API event and TOURNAMENT SUMMARY

  • When a run ends, the API fires TournamentRunEndEvent once per player, after settlement, carrying a TournamentRunResult with placement, match and series records, byes, tournament score, the elo breakdown (ranked only), and whether the player left early. The result is WIN for the champion, LOSE otherwise. See the API page.
  • The same result object feeds the TOURNAMENT SUMMARY shown to every participant still online at tournament end: placement, record, score over max, the ranked elo breakdown, and the champion name. The champion hears tournament.champion; everyone else hears the neutral summary sound.

Placeholders

Mode-agnostic keys that work for every format:

  • Score: %jmanhunt_tournament_score%, %jmanhunt_tournament_score_<name>%, %jmanhunt_tournament_max_score%.
  • Queue and state: %jmanhunt_tournament_queue_unit%, %jmanhunt_tournament_id%, %jmanhunt_tournament_state%, %jmanhunt_tournament_round%, %jmanhunt_tournament_remaining%.
  • Standing: %jmanhunt_tournament_standing%, %jmanhunt_tournament_leader%, %jmanhunt_tournament_record%, %jmanhunt_tournament_pool%, and %jmanhunt_playlist_max_<id>% for the rising shown max.
  • Best-of-5 reads series wins over a max of 3; round-robin reads points over the theoretical max; brackets read wins over the wins needed for the title. Full table: placeholders.

Messages and sounds

All tournament text lives in the tournament message section; new sounds are tournament.bracket_advance, tournament.series_point, tournament.elimination, tournament.champion, and the neutral tournament.leave_warning.