Docs Queues & Lobbies
Documentation
Matchmaking & Queues
Create automated matchmaking queues or hosted lobbies for your gaming community
Overview
Team Up provides a powerful matchmaking system that lets you create queues for your gaming community. Players can join queues and get automatically matched, or hosts can create lobbies with manual control over team formation and match flow.
Queue Commands
/queue_versus- Standard versus (1v1, 2v2, etc.)/queue_anonymous- Hidden random teams/queue_ffa- Free-for-all/queue_coop- Cooperative/queue_team- Team-based
Two Operating Modes
- Headless - Automatic matchmaking
- Hosted - Manual lobby control
Each queue command supports both modes as subcommands.
Which Queue Type Should I Use?
Team vs Team? → Use /queue_versus
1v1, 2v2, 3v3, 5v5, etc.
Hidden teams? → Use /queue_anonymous
Random teams, hidden — you know your own team, not your teammates
Everyone for themselves? → Use /queue_ffa
Battle royale, racing, individual placements
Players vs AI/game? → Use /queue_coop
Raids, dungeons, cooperative challenges
Pre-made teams? → Use /queue_team
Teams queue together as a unit
Headless vs Hosted Modes
Headless Mode
Automatic matchmaking queue. Players join the queue, and when enough players are waiting, the system automatically creates a match and notifies everyone.
Best For
- • High-traffic servers with active players
- • Casual pickup games
- • 24/7 matchmaking availability
- • Minimal moderation needed
Features
- • Auto-match when queue fills
- • Rating-based team balancing
- • Join notifications
- • Map pool voting
/queue_versus headless queue_name:"ranked-2v2" team_size:2 title:"Ranked 2v2" Creates an automatic 2v2 matchmaking queue
Hosted Mode
Manual lobby system. A host creates a lobby, players join, and the host controls when to start, how teams are formed, and when to record results.
Best For
- • Organized events and tournaments
- • Custom game setups
- • Captain's draft games
- • Private matches with specific players
Host Controls
- • Start/close lobby
- • Kick players
- • Randomize/balance teams
- • Share invite codes
/queue_versus hosted queue_name:"friday-3v3" team_size:3 title:"Friday Night 3v3" Creates a hosted 3v3 lobby launcher. For a captain's draft, set Team Formation to one of the Captains modes from Admin Actions → Configure Match Rules & Voting on the queue message, or on the dashboard's Matchmaking page (all team settings).
| Feature | Headless | Hosted |
|---|---|---|
| Match Creation | Automatic when queue fills | Manual by host |
| Team Formation | Automatic (balanced/random) | Host controlled |
| Player Management | Self-service join/leave | Host can kick players |
| Persistence | Queue persists indefinitely | Lobby closes after match |
| Best Use Case | Casual pickup games | Organized events |
Queue Types
/queue_versus
Standard competitive matchmaking
The most common queue type. Creates matches where two teams or individuals compete against each other.
Supports any versus format: 1v1, 2v2, 3v3, 4v4, etc. An automatic queue can also have more than two
teams (up to 8, e.g. teams:6 for 2v2v2v2v2v2); those matches are reported by placement.
/queue_versus headless queue_name:"ranked" team_size:"2"Playing with chosen teammates (party queueing)
Turn it on in Admin Actions → Configure → Configure Party Queue on Discord, or in the queue's settings on the web dashboard (the size fields appear once Party Queue is Enabled). Players get a 👥 Join as Party button and pick their teammates; a party always plays on the same team, and solo players are still matched alongside parties.
- Max Party Size is the largest party allowed. 2 in a 5v5 means solos and duos, no trios. It doesn't stop solo players.
- Min Party Size (automatic queues) is the smallest party allowed. 2 means nobody queues alone: the solo Join Queue button disappears and everyone joins as a party.
- Max Party Rating Difference limits the Elo gap inside one party.
Duos only, six teams of two: create /queue_versus headless team_size:2 teams:6, enable Party Queue
and set Min Party Size to 2.
Min Players and Max Players are different: they are player counts for free-for-all and co-op queues, letting a match start anywhere in a range (e.g. 4 to 8 players) after a short wait for more to join.
/queue_anonymous
Hidden-team matchmaking
Players are split into two randomly assigned teams that stay hidden. Each player can privately check which team they're on — but not who their teammates are. The full rosters stay secret until the teams are revealed. Built for social-deduction games like Among Us, where you know your side but not your allies.
/queue_anonymous headless queue_name:"hidden-5v5" team_1_size:"5" team_2_size:"5"Teams are randomly assigned and hidden — players see only their own team until the teams are revealed
/queue_ffa
Free-for-all matchmaking
Every player competes individually. Results are recorded as placements (1st, 2nd, 3rd, etc.). Perfect for battle royale style games or racing.
/queue_ffa headless queue_name:"battle-royale" min_players:8/queue_coop
Cooperative matchmaking
Players team up together against the game or AI. All players share the same outcome (win or lose together).
/queue_coop headless queue_name:"raid-finder" min_players:4/queue_team
Pre-formed team matchmaking
For players who want to queue as a pre-formed team rather than being randomly assigned teammates. Teams queue together and get matched against other teams.
/queue_team headless queue_name:"team-ranked" team_size:3Team Formation Strategies
When a match starts, how should teams be formed? Team Up offers 8 different strategies to fit your community's needs.
Where to pick it: the team_formation option of /host, or, for a queue, Team Formation under Admin Actions → Configure Match Rules & Voting on the queue message (also in the
queue editor on the dashboard).
Queues name a few of these differently — Balanced Teams for Balanced by Rating — and add captain variants that pick the captains by highest or lowest Elo, at random, or from volunteers. A hosted lobby launched from a queue carries the queue's choice over. The Settings Reference lists both, with the values stored in exports and the API.
Players Choose
Default for /host
Players select which team they want to join using buttons. First come, first served.
Random Teams
Quick and fair
Players are randomly assigned to teams. Simple and unbiased.
Random Teams (Anonymous)
For social deduction
Random assignment, kept hidden. A player can check which side they're on but not who else is on it, and the rosters stay secret until the teams are revealed — normally after the match. Built for games like Among Us.
Captains Draft
Traditional pick system
Two captains take turns picking players for their teams. Classic draft experience.
Balanced by Rating
Competitive fairness
Teams are automatically balanced based on player Elo ratings to create even matches.
No Teams (FFA/Co-op)
Individual or all together
No team assignment. Used for free-for-all or cooperative game modes.
Role-based games (lanes, roles, factions): lobby team formation has no role support — use a headless queue instead. Assign an Option Set (e.g. Lane → Exp, Jungle, Mid, Gold, Roam) to the queue's leaderboard, then set Unique Choice Matchmaking to Balanced per team under Configure Matchmaking Rules. Players pick their role as they join, and the queue only fires a match once it can field one of each per team. See Unique Choice Matchmaking in the Settings Reference.
Match Result Options
Control how match outcomes are recorded and whether they affect player ratings. Pick one with the match_result option of /host, or, for a
queue, Ranking & Voting Mode under Admin Actions → Configure Match Rules & Voting.
Disabled
No result voting or recording. The match ends when players leave. Use this for casual games where ratings don't matter.
Ranked
RecommendedPlayers vote on the outcome via consensus. Once all players agree, the match is recorded and ratings are updated automatically.
Ranked (Admin Approval)
Same as Ranked, but an admin must approve the result before ratings are updated. Useful for preventing abuse in competitive environments.
Unranked
Match is recorded in history, but ratings are not affected. Good for practice matches or warm-up games.
Unranked (Admin Approval)
Same as Unranked, but requires admin approval before recording.
How Consensus Voting Works
When match results are enabled, players see voting buttons at the end of the match:
The result is recorded when a majority of players agree on the outcome. If the teams disagree, any admin — including one playing in the match — can pick 🛠️ Admin: Report Result from the match message's More Actions… dropdown to record the result directly.
Competitive Formats
Choose how matches are structured for hosted lobbies. On a queue it is Match Format (with Matches/Rounds for best-of and cumulative) under Configure Match Rules & Voting;
the competitive_format option of /host offers Single Match and Endless.
Single Match
One game determines the winner. Lobby closes after result is recorded.
Best Of Series
First team to win majority wins. Available: Bo3, Bo5, Bo7.
Endless Matches
Play continuous games without closing. Lobby stays open until players vote to close.
Cumulative Scoring
Total points across rounds determines winner. Teams submit and approve scores each round.
Map Pools & Voting
Create map pools and let players vote on which map to play. Maps are selected randomly or through player voting when a match is created.
Creating a Map Pool
Add a map to the pool
Using a Map Pool in Queues
After creating the queue, pick the pool and the voting strategy from Admin Actions → Configure Map Voting on the queue message, or on the dashboard's Matchmaking page.
Players then vote on maps from that pool when a match is found. All map settings
Temporary Channels
Automatically create temporary voice or text channels for each match. Channels are deleted when the match ends.
Setting Up Temporary Channels
After creating the queue, open Admin Actions → Configure Auto-Channels on the queue message, or the dashboard's Matchmaking page.
Set the Temp Channel Category the channels are created in, and turn on Shared Channels (text, voice, or both) for all players. All channel settings
Channel Types
- • Text - Shared text chat for all players
- • Voice - Shared voice channel
- • Team Voice - Separate voice per team
Requirements
- • Bot needs "Manage Channels" permission
- • Category must exist beforehand
- • Channels auto-delete after match
Queue Settings
After creating a queue, open the Admin Actions dropdown on the queue message to access the Configure … modals, or edit the queue from the web dashboard.
Full Settings Reference →
Every queue setting — defaults, valid ranges, and enum values — filterable by queue type, mode, and where it's set.
Password Protection
Restrict queue access with passwords. Set a queue password for players joining, or a host password for creating hosted lobbies.
Great for private tournaments or subscriber-only queues.
Rematch Cooldown
Prevent the same players from matching up again for a set period. Set to minutes (e.g., 60) or 0 for permanent cooldown.
Ensures variety and prevents farming the same opponent.
Dispute Handling
Configure channels for dispute notifications, screenshot evidence, and audit logging. Optionally ping a role when disputes occur.
Essential for competitive integrity and moderation.
Match Announcements
Post automatic announcements when matches start and end. Shows team rosters, ratings, and final results.
Perfect for streaming events or spectator channels.
Competitive Formats
Choose match structure: Single Match, Best Of series, Endless sessions, or Cumulative scoring.
Cumulative is great for point-based games like racing.
Auto-Channels
Automatically create voice/text channels and threads when matches start. Supports shared channels and private team channels.
Channels are deleted when the match ends.
Need Help Configuring?
Use our AI support chat on the Support page for step-by-step guidance on setting up these features.
Common Examples
Each example is the command that creates the queue, then the settings to change afterwards from the
queue message's Admin Actions menu (the same settings are in the
queue editor on the dashboard). Options left out, such as description,
are optional.
Ranked 1v1 Queue
Simple competitive 1v1 with Elo tracking
/queue_versus headless queue_name:"ranked-1v1" title:"Ranked 1v1" team_size:1 leaderboard:"default"Nothing else to set: a new queue is already Ranked (Consensus), so players vote on the result and it moves their Elo.
Balanced 5v5 with Voice Channels
Rating-balanced teams and a voice channel for each team
/queue_versus headless queue_name:"5v5-comp" title:"5v5 Competitive" team_size:5Then set
- Configure Auto-Channels → Temp Channel Category: #Matches
- Configure Auto-Channels → Team Channels: Private — Voice
Team Formation is already Balanced Teams on a new queue.
Hosted Captain's Draft
Manual lobby with traditional draft picking
/queue_versus hosted queue_name:"friday-draft" title:"Friday Night Draft" team_size:5 leaderboard:"default"Then set
- Queue editor on the dashboard → Team Formation: Captains (Host Picks)
Captains (Host Picks) is set from the dashboard; Discord's Configure Match Rules & Voting offers the other captain modes.
Anonymous 2v2 with Map Voting
Hidden teams and map selection
/queue_anonymous headless queue_name:"blind-2v2" title:"Anonymous 2v2" team_1_size:2 team_2_size:2Then set
- Configure Map Voting → Map Pool Name: competitive
- Configure Map Voting → Map Voting Strategy: Simple Vote
Casual FFA Battle Royale
8-player free-for-all with placement rankings
/queue_ffa headless queue_name:"battle-royale" title:"Battle Royale" min_players:8Then set
- Configure Match Rules & Voting → Ranking & Voting Mode: Unranked (Consensus)
Continue Learning
Explore more Team Up features