📜Configuration
Message strings use the MiniMessage format (<gold>, <red>, …). Titles and legacy nametags still accept § colour codes.
Configuration File
# Logic behind the matches in case one or both players are offline
# at the time of the duel: if only one of the two players is offline,
# the other wins directly if both are offline, a lot draws a winner
settings:
general:
# If activated, teleports the player to the "exit" position
teleport_after_duel: true
# If activated, it saves the player's inventory before the duel and restores it after the duel
save_and_restore_inventories: true
# Require empty inventory before duel
require_empty_inventory: false
# If the player quit loses the duel, otherwise the duel ends when he dies (recommended default)
handle_quit: true
# The integration with placeholder api is automatic, therefore, it is advisable to leave the default value
hook_in_papi: true
starting_gamemode: SURVIVAL
disable_hunger: true
use_death_event: true
no_team_name: "BYE"
# Set this to enable the live online bracket (leave empty to disable)
api_key: ""
# Maximum minutes a live match can run before the higher-health player wins (0 = no limit)
match_timeout_minutes: 10
# Whether to run a 3rd-place match between the two semifinal losers
third_place_match: true
# How many matches may be fought at the same time, across different arenas
max_parallel_matches: 1
# This server's name on the website (leave empty to have one generated)
server_id: ""
# How the tournament is drawn
format:
# SINGLE_ELIMINATION - lose once and you are out (the default)
# DOUBLE_ELIMINATION - you are out after two defeats; beaten teams drop into a
# losers bracket and can fight their way back to the final
# ROUND_ROBIN - everyone plays everyone, and the table decides it
# GROUPS_PLAYOFF - a group stage, then a knockout between whoever came top
type: SINGLE_ELIMINATION
# DOUBLE_ELIMINATION only: play a decider if the unbeaten finalist loses the grand final
grand_final_reset: true
# GROUPS_PLAYOFF only. groups x qualify_per_group must be a power of two
groups: 2
qualify_per_group: 2
# Games per match. Must be odd
best_of: 1
# Games in the last round, if you want a longer final than the rest
best_of_final: 1
nametag:
team1: "§7[§cR§7] §c"
team2: "§7[§9B§7] §9"
messages:
# %tournament% Name of the tournament
# %rounds% Number of rounds
# %max_teams% Maximum number of teams
# %max_players_per_team% Maximum number of players per team
# %uuid% (WEB Only) UUID of the tournament
# %url% (WEB Only) URL of the tournament
# Examples:
# "§7(%max_teams% teams, %max_players_per_team% players per team)"
# "§7Bracket: §a%url%"
tournament_starting: "<gold>The tournament is starting! <gray>(%tournament%) <gray>(%rounds% rounds)"
# %player% Name of the player involved (winner)
opponent_offline: "<red>The opponent is offline! %player% won by forfeit."
# %player% Name of the player involved (winner)
both_opponents_offline: "<red>Both players are offline. Random drawing of the winner..."
# %player% Name of the player involved (winner)
match_timeout: "<gold>Match timed out! <green>%player% <gray>wins by health advantage."
# %player% Name of the player involved (winner)
match_victory: "<red>%loser% <gray>lost against <green>%winner% <gray>(<red>%health%❤) <gray>in the duel."
titles:
# %round% Group number
round_presentation:
title: "§6§l%round%° Round"
subtitle: ""
fadeIn: 500
stay: 2000
fadeOut: 500
# %player1% Name of the first player involved
# %player2% Name of the second player involved
match_presentation:
title: "§6§lDuel"
subtitle: "§c%player1% §7vs §9%player2%"
fadeIn: 500
stay: 2000
fadeOut: 500
match_starting:
title: "§6§lStarting in"
subtitle: "%seconds%"
fadeIn: 200
stay: 800
fadeOut: 200
# %player% Name of the player involved (winner)
match_victory:
title: "§b§l%player% §7won"
subtitle: ""
fadeIn: 500
stay: 2000
fadeOut: 500
# %player% Name of the player involved (winner)
third_place:
title: "§6§l3° Place"
subtitle: ""
fadeIn: 500
stay: 2000
fadeOut: 500
# %player% Name of the player involved (winner)
tournament_victory:
title: "§d§l%player%"
subtitle: "§fwon the tournament"
fadeIn: 500
stay: 2000
fadeOut: 500
sounds:
arena_join: "ENTITY_EXPERIENCE_ORB_PICKUP"
arena_leave: "ENTITY_EXPERIENCE_ORB_PICKUP"
match_starting: "ENTITY_EXPERIENCE_ORB_PICKUP"
match_victory: "ENTITY_PLAYER_LEVELUP"
tournament_victory: "ENTITY_ENDER_DRAGON_GROWL"
events:
# When a player enters the arena for his duel
# %player% Name of the player involved
arena_join:
commands: [ ]
# When a player leaves the arena for his duel
# %player% Name of the player involved
arena_leave:
commands: [ ]
commands:
invite:
not_supported: "<red>This command is not supported in this tournament</red>"
player_not_found: "<red>Player not found</red>"
invite_self: "<red>You can't invite yourself</red>"
no_team: "<red>You are not in a team</red>"
not_leader: "<red>You are not the leader of the team</red>"
team_full: "<red>The team is already full</red>"
already_in_team: "<red>Player is already in the team</red>"
invite_error: "<red>An error occurred while inviting the player</red>"
already_sent: "<red>Player %player% has already been invited</red>"
invite_sent: "<green>Player %player% has been invited to the team</green>"
invite_received: "<green>You have been invited to the team of %player%</green>"
join:
not_invited: "<red>No one has invited you in this team</red>"
success: "<green>You signed up for the tournament</green>"
success_team: "<green>You joined the team %team%</green>"
leader: "<green>Player %player% joined your team</green>"
no_team: "<red>Team not found</red>"
full: "<red>The team is already full</red>"
tournament_full: "<red>The tournament is already full</red>"
already_participant: "<red>You are already registered for the tournament</red>"
status_error: "<red>The tournament doesn't accept new registrations</red>"
leave:
not_participant: "<red>You are not registered for the tournament</red>"
unsubscribe: "<green>You have unsubscribed from the tournament</green>"Formats
settings.format.type decides how the tournament is drawn. The setting is sent to the website when the tournament starts, so both ends draw the same one — change it before you start, not after.
SINGLE_ELIMINATION
Lose once and you are out. The default, and what every previous version played.
DOUBLE_ELIMINATION
You are out after two defeats. A beaten team drops into a losers bracket and can fight its way back to the grand final.
ROUND_ROBIN
Everyone plays everyone once, and the table decides it. There is no final.
GROUPS_PLAYOFF
A group stage, then a knockout bracket between whoever came top of each group.
grand_final_reset (double elimination only). The team that reaches the grand final through the winners bracket has not lost yet. If it loses there, both teams have one defeat each, and with this on a decider is played to settle it. Turn it off to end the tournament on the first grand final instead.
groups and qualify_per_group (groups → playoffs only). Their product must be a power of two, because the qualifiers go into a knockout bracket: 2 groups of 2 qualifiers, or 4 groups of 2, or 2 groups of 4. Teams are drawn into groups in a snake — the top seed to the first group, the second to the second, and back again — so the strongest are spread out rather than landing together. Qualifiers are placed so that the winner of one group never meets the runner-up of its own group in the first playoff round.
A group table is ordered by matches won, then game difference, then games won, and finally by seeding, so the order is total. Head-to-head is deliberately not used: it is ambiguous in a three-way tie, and a rule nobody can predict is worse than a blunt one everybody can.
Best-of-N
best_of is the number of games a match takes, and best_of_final the number the last round takes if you want a longer final than the rest. Both must be odd — an even best-of can be drawn, and a drawn match has nowhere to send its two teams.
The same two teams play until one of them has won a majority, and it is the majority, not the last game, that advances. Each game is reported to the website as it finishes, so the online bracket shows the score as it stands rather than jumping at the end.
A game nobody turns up for settles the whole match rather than just that game. A best-of-five against a team that is offline would otherwise be three forfeits in a row, and a quarter of an hour of countdowns, to reach an answer already known at the first.
Parallel matches
max_parallel_matches is how many matches may be fought at the same time. 1 is the old behaviour: one duel at a time, with every other arena standing idle while a 32-team tournament works through thirty-one of them in single file.
Raise it and every match that is ready to be played is dispatched at once, up to this many, each into its own arena. The same tournament becomes five rounds. You need at least that many arenas configured for it to make a difference — a match with no free arena waits for one, so the setting is a cap on concurrency rather than a promise of it. The tournament's own arena is always used first, so a server with one arena behaves exactly as it always did whatever this is set to.
Bracket sync
The website owns the bracket. It draws one when a tournament starts and stores it; the plugin reads it and plays it. Every match has a fixed place — its round and its position in that round — that both ends agree on because only one of them decides it.
That was not always so. The plugin and the website each used to work out a bracket of their own, and the plugin then told the website the result of each match by its position in its copy. The two could come apart — a result that never arrived, a player added after the draw — and nothing noticed. Both implementations are gone; there is one.
What it means in practice:
A result the bracket cannot justify is refused instead of stored. Reporting a winner who was not in the match, or a second, different winner for a match that already has one, fails loudly rather than quietly corrupting the bracket.
Sending the same result twice is safe, so a retry after a timeout cannot duplicate or contradict anything.
Byes are decided by the website when it draws the bracket, so both ends agree about who got a walkover.
Adding or removing a player, or reshuffling the seeding, is refused once a tournament has started — the bracket is drawn from the entrant list at that moment, and changing it afterwards would describe a tournament nobody is playing.
Results survive an outage or a restart. Each one is written to disk before it is sent and retried until the website confirms it, rather than being logged and dropped.
A tournament is executed by one server, which claims it on start. If that server crashes, the match it was running is reopened when it comes back — and a server that has since been superseded is refused if it tries to report an old result.
server_id is the name the website records as the owner, so an operator who cannot start a tournament can see which machine is holding it. Leave it empty and one is generated and stored in the plugin folder; set it to something recognisable if you run more than one server.
If a tournament is held by a server that is gone for good, take it over deliberately rather than starting a second server on the same bracket.
This is v3 of the sync protocol, and it is the only one. A 2.x plugin cannot talk to the current website, and a current plugin cannot talk to an older one — they need upgrading together. The plugin reports the protocol version it speaks when it connects, and says so plainly in the log if the two do not match.
Last updated