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" title:"Ranked 2v2" versus:"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 title:"Friday Night 3v3" versus:"3v3" team_formation:"Captains Draft" Creates a hosted lobby with captain's draft team selection
| 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.
/queue_versus headless queue_name:"ranked" versus:"2v2" match_result:"Ranked"/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" 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" 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.
Two vocabularies: the values below are the lobby modes used by /host and running lobbies. The /queue_* commands
use the queue vocabulary instead — balanced_teams, random_teams, players_choose, and the captains_* variants (highest/lowest Elo, random, volunteer, host picks).
Hosted launchers translate automatically when a lobby is created
(balanced_teams → balance_elo).
See the Settings Reference for both lists.
Players Choose
Default
Players select which team they want to join using buttons. First come, first served.
team_formation: "players_choose"Players Choose with Positions
For role-based games
Players choose both team and position (e.g., Tank, DPS, Support). Each position can only be filled once.
team_formation: "players_choose_positions"Random Teams
Quick and fair
Players are randomly assigned to teams. Simple and unbiased.
team_formation: "random"Random Teams (Anonymous)
Hidden during selection
Random assignment, but team compositions are hidden until the match starts.
team_formation: "random_anonymous"Random Teams with Positions
Random teams, specific roles
Teams are randomly assigned, then players choose positions within their team.
team_formation: "random_positions"Captains Draft
Traditional pick system
Two captains take turns picking players for their teams. Classic draft experience.
team_formation: "captains_host_picks"Balanced by Rating
Competitive fairness
Teams are automatically balanced based on player Elo ratings to create even matches.
team_formation: "balance_elo"No Teams (FFA/Co-op)
Individual or all together
No team assignment. Used for free-for-all or cooperative game modes.
team_formation: "no_teams"Match Result Options
Control how match outcomes are recorded and whether they affect player ratings.
Disabled
No result voting or recording. The match ends when players leave. Use this for casual games where ratings don't matter.
match_result: "disabled"Ranked
RecommendedPlayers vote on the outcome via consensus. Once all players agree, the match is recorded and ratings are updated automatically.
match_result: "ranked"Ranked (Admin Approval)
Same as Ranked, but an admin must approve the result before ratings are updated. Useful for preventing abuse in competitive environments.
match_result: "ranked_admin"Unranked
Match is recorded in history, but ratings are not affected. Good for practice matches or warm-up games.
match_result: "unranked"Unranked (Admin Approval)
Same as Unranked, but requires admin approval before recording.
match_result: "unranked_admin"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 there's a dispute, admins can intervene.
Competitive Formats
Choose how matches are structured for hosted lobbies.
Single Match
One game determines the winner. Lobby closes after result is recorded.
competitive_format: "Single Match"Best Of Series
First team to win majority wins. Available: Bo3, Bo5, Bo7.
competitive_format: "Best Of" matches: 3Endless Matches
Play continuous games without closing. Lobby stays open until players vote to close.
competitive_format: "Endless Matches"Cumulative Scoring
Total points across rounds determines winner. Teams submit and approve scores each round.
competitive_format: "Cumulative" matches: 3Map 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
/settings map_pool add pool_name:"competitive" map_name:"Dust 2" Add a map to the pool
/settings map_pool add pool_name:"competitive" map_name:"Mirage"/settings map_pool add pool_name:"competitive" map_name:"Inferno"Using a Map Pool in Queues
/queue_versus headless queue_name:"ranked" ... map_pool:"competitive" map_voting_strategy:"Simple" Players vote on maps from the "competitive" pool when a match is found
Temporary Channels
Automatically create temporary voice or text channels for each match. Channels are deleted when the match ends.
Setting Up Temporary Channels
/queue_versus headless ... category_for_temp_channel:#Match Lobbies Specify which category to create temporary channels in
/queue_versus headless ... create_shared_channel:"Text" Create a shared text channel for all players
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
The required description, match_start_channel,
and match_end_channel options are omitted from these examples for brevity —
Discord will prompt for them.
Ranked 1v1 Queue
Simple competitive 1v1 with Elo tracking
/queue_versus headless queue_name:"ranked-1v1" title:"Ranked 1v1" team_size:1 match_result:"Ranked" leaderboard:"default"Balanced 5v5 with Voice Channels
Automatic team balancing and temporary voice channels — after creating, enable team voice channels via Admin Actions → Configure Auto-Channels
/queue_versus headless queue_name:"5v5-comp" title:"5v5 Competitive" team_size:5 team_formation:"Balanced Teams" match_result:"Ranked" category_for_temp_channel:#MatchesHosted Captain's Draft
Manual lobby with traditional draft picking
/queue_versus hosted queue_name:"friday-draft" title:"Friday Night Draft" team_size:5 team_formation:"Captains (Host Picks)" match_result:"Ranked" leaderboard:"default"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:2 match_result:"Ranked" map_pool:"competitive" map_voting_strategy:"Simple"Casual FFA Battle Royale
8-player free-for-all with placement rankings
/queue_ffa headless queue_name:"battle-royale" title:"Battle Royale" min_players:8 match_result:"Unranked"Continue Learning
Explore more Team Up features