EloPulse Documentation

Overview

EloPulse is a ranked matchmaking Discord bot. Players queue up, get matched into balanced lobbies based on their skill rank, and win or lose ELO based on the outcome. On top of that core ladder, EloPulse adds parties (queue with friends as a group), full bracket tournaments, and a web dashboard for moderators to manage everything without needing to run commands in Discord.

Quick summary: /queue to find a match, /profile to check your stats, /party invite to team up with friends, and the web dashboard for anything a moderator needs to configure or control.

Setting Up (Moderators)

Before players can queue, a moderator needs to configure the server once:

Run /setup - a guided wizard that configures the game name, player ID label, mod role, channels (queue, mod-log, mod-verify, match-log, scrim-ping, tournament), rank tiers, and queue modes (1v1, 2v2, etc.).
Run /settierrole to link each rank tier to a Discord role, so players get auto-assigned roles as they climb or fall.
Run /viewconfig anytime to see the server's current configuration.
Everything from /setup can also be edited afterward from the web dashboard's Settings tab - including live dropdowns for channels and roles pulled straight from Discord, so you never have to paste an ID by hand.

Two permission tiers

The Mod Role (or Manage Server permission) covers regular day-to-day moderation - suspending players, resolving matches, managing reports and tournaments. A separate, higher Admin Role is required for genuinely destructive or bulk actions: season resets, backup restores, bulk player reset/suspend, and role-sync "fix all." If you don't configure an Admin Role, those actions fall back to requiring Manage Server permission specifically - so nothing is ever accidentally locked out. Both tiers apply identically whether the action is taken on Discord or through the dashboard.

Ranked Matchmaking

Players run /queue and pick a mode. The first person to queue gets a private confirmation - nothing is posted publicly yet, aside from a ping naming who's searching, so nobody can pick and choose opponents by peeking at who's already in a lobby. Once a second player joins, the full team-selection embed goes public.

Rank-bracketed lobbies

A single queue mode can have several lobbies open at once. If your rank is too far from whoever's already queued, you're not blocked - you're placed into (or start) a separate lobby for players closer to your own rank, so a Bronze and a Master player never end up forced together.

Exact tolerance: in 1v1 queues, you can only share a lobby with players within ±1 rank tier of whoever's already there. Every other queue mode (2v2, 3v3, etc.) allows ±2 rank tiers. If nobody currently queued falls within that range, a brand new lobby opens for you instead of blocking you outright.

Other timing defaults worth knowing: there's a 30 second cooldown between uses of /queue per player, and a queue that never fills up times out and clears automatically after 1 hour with no new joins.

ELO & ranks

Winning gains ELO, losing costs ELO, weighted by how your rank compares to your opponents' average. Climb far enough and you cross into the next rank tier, which comes with an auto-assigned Discord role. The very top of the ladder gets special Champion status, which decays over time if you go inactive - so it has to be defended, not just earned once. Full formulas and exact numbers: ELO & Ranking Math and Champion Defence below.

Parties

Team up with friends so you're placed on the same side every match:

Command	What it does
`/party invite @user`	Invite a player to your party. You become the leader.
`/party accept`	Accept a pending invite. Prompts you to register your in-game ID first if you haven't already.
`/party leave`	Leave your party, decline an invite, or - if you're the leader - disband the whole party.
`/party info`	See your current party's leader, members, and pending invites.

Only the party leader can run /queue for the group - other members get redirected if they try. When the leader queues, the whole party is placed on the same team together, as long as there's room.

Tournaments

EloPulse supports full single- or double-elimination bracket tournaments, run by moderators and joined by players through a Discord button.

Running one (moderators)

Command	What it does
`/tournament start`	Opens enlistment - posts an Enlist button, with team size, max players, and single/double elimination format.
`/tournament begin`	Locks enlistment, randomly teams up remaining solo players, and generates the bracket.
`/tournament pause` / `resume`	Pause or resume match reporting without losing tournament state.
`/tournament stop`	Cancels and clears the tournament entirely.
`/tournament restart`	Cancels the current one and immediately reopens enlistment with the same settings.
`/tournament status`	Shows the current tournament's status, team count, and matches remaining.

Joining (players)

Click Enlist on the tournament announcement. If you're in a party, your whole party joins together as one team. If not, you're teamed up randomly with other solo players once the moderator runs /tournament begin.

Match verification flow

When two teams are matched, a name-only announcement (no IGNs) posts publicly, both teams get a DM to warm up, and moderators get a "Ready to Spectate" button. Clicking it DMs both teams each other's registered ID plus the moderator's own ID, and only then can the match be reported as won.

ELO & Ranking Math

EloPulse uses a modified ELO system - the same family of rating math used by chess and most competitive ladders, with extra tuning so climbing doesn't just become a coin-flip grind once you're already highly rated.

The core formula

Every match calculates an "expected win probability" from the rating gap between you and the opposing team's average ELO:

expected = 1 / (1 + 10^((opponent_avg_elo - your_elo) / 400))

Your ELO change is then K × (actual_result - expected), rounded to the nearest whole number, where actual_result is 1 for a win or 0 for a loss, and K (the "K-factor") controls how many points are on the line. A bigger K-factor means bigger swings.

K-factors (how much is on the line)

Situation	K-factor	Floor / Ceiling
Below 1200 ELO (any result)	32	none - standard formula applies directly
1200+ ELO, win as the favorite (your ELO > opponents')	6	minimum +1 ELO
1200+ ELO, win as the underdog (your ELO ≤ opponents')	24	minimum +5 ELO
1200+ ELO, loss as the favorite	64	maximum -15 ELO
1200+ ELO, loss as the underdog	24	maximum -5 ELO

Why the asymmetry: below 1200 ELO, everyone uses the same K-factor of 32 - fast, simple, and it gets new/lower-ranked players to their real rank quickly. Above 1200, the system deliberately punishes upset losses hard (K=64, capped at losing at least 15) and rewards upset wins generously (K=24, at least +5) - beating someone better than you should matter more than beating someone worse. Meanwhile, farming wins against weaker opponents barely moves your rating (K=6, capped at just +1), which stops high-ELO players from padding their rank against easy lobbies instead of playing real competition.

Your ELO is always clamped between 0 and the server's configured Max ELO (2000 by default, editable in the dashboard's Settings tab) - it can never go negative or above the ceiling.

Win streak bonus

On top of the base ELO change, winning multiple matches in a row adds a bonus:

bonus = min((streak - 1) × 6, 24) - so your 2nd win in a row adds +6, 3rd adds +12, 4th adds +18, capping out at +24 from your 5th consecutive win onward. Losing a match resets your streak to 0.

Once your ELO reaches 1200 ("Master threshold"), that bonus is scaled down to 34% of its normal value - streaking is a strong tool for climbing out of lower ranks, but it stops being a major factor once you're already highly rated, where the per-match K-factor swings (above) do most of the work instead.

Promotion & demotion

Rank tiers are purely ELO thresholds - promotion is instant: the moment your ELO crosses into the next tier's range, your rank and Discord role update immediately, no extra requirement.

Demotion has a 3-strike grace window. If a loss drops your ELO below your current tier's threshold, you don't lose the rank immediately - you get a demotion strike instead. Win your next match before accumulating 3 strikes and the counter resets to zero (this also counts as a "shield save" toward the Unbreakable achievement). Only after 3 losses in a row while sitting below your tier's threshold do you actually get demoted to your natural (ELO-matching) rank.

Champion Defence

Champion Defence is special status for the very top of the ladder - designed so the #1 spot has to be actively defended by continuing to play, rather than won once and then camped forever.

How you enter it

You gain Champion status the moment both of these are true:

You're in the server's Top 5 by ELO (configurable - "Champion Count")
Your ELO is at least 800 (configurable - "Champion Min ELO")

Losing either condition - falling out of the Top 5, or your ELO dropping below the minimum - immediately ends Champion status.

The grace period

The moment you become a Champion, a 12-hour grace period starts before any decay can begin. This resets every time you re-enter Champion status.

Decay - and why it pauses

Once the grace period expires, if you're still a Champion and currently inactive, your ELO decays by 10 points every 6 hours. But decay only progresses while you're genuinely idle - it automatically pauses the entire time you're in an active queue lobby or an active disputed match, and the paused duration gets added back onto your decay timer once you stop. In other words: decay measures time spent not playing, not just raw clock time. You can hold the throne indefinitely as long as you keep showing up.

Why it's designed this way: without decay, the #1 spot would go to whoever got there first and then simply stopped playing to avoid risking it. Pausing decay during active queueing (rather than decaying on a flat timer regardless of activity) means the system is specifically targeting inactivity, not punishing people for the time it takes to actually find and play a match.

If decay ever drops your ELO below the Champion Min ELO (800 by default), Champion status ends there and then - even mid-decay.

Achievements

24 base achievements, plus one automatically-generated "Reach [Tier Name]" achievement for every rank tier your server has configured above the lowest one.

Achievement	How to unlock it
⚔️ First Blood	Win your first ranked match.
🏆 Battle-Tested / Seasoned Fighter / Veteran Duelist / Centurion	Win 10 / 25 / 50 / 100 ranked matches.
💀 Welcome to the Grind	Suffer your first ranked defeat.
📈 Getting Started / Regular Combatant / Ladder Grinder	Play 10 / 50 / 100 ranked matches.
🔥 Heating Up / On Fire / Unstoppable	Reach a 3 / 5 / 10 win streak.
🏅 Podium Finish	Reach the server's Top 3.
🌟 Apex Predator	Reach the #1 leaderboard spot.
🛡️ Top 3 Defender	Hold a Top 3 spot for 24 hours straight.
🛡️ Reigning Champion	Hold the #1 spot for 24 hours straight.
👑 All Hail the Champion	Enter Champion Defence status.
🏰 Fortress	Hold Champion Defence for 7 straight days.
🧱 Unbreakable	Save your rank from demotion by winning while a demotion strike was active.
🎯 All-Rounder	Play a ranked match in every game mode the server offers.
🪪 Identified	Register your in-game ID with the bot.
🏛️ Hall of Famer	Finish a season in the Top 5.
🏆 Season Champion	Finish a season ranked #1.
🏔️ Reach [Tier]	One per configured rank tier - reach that rank at least once.

Custom Achievements Premium

Beyond the built-in list, servers can define their own achievements around anything the bot already tracks. This is a premium feature - support the bot with a $2+ donation, and the operator can grant you premium access from the admin panel. Once granted, it applies to any server you moderate.

Build one from either surface - they stay in sync automatically:

Discord: /customachievement create, list, delete
Dashboard: the Custom Achievements tab

Available trigger conditions:

Trigger	Needs a value?
Total wins at least...	A number
Total losses at least...	A number
Total matches played at least...	A number
Win streak of at least...	A number
ELO reaches at least...	A number
Reach this rank tier...	One of your server's configured tiers
Currently holds Champion status	No
Demotion saves at least...	A number
Season Top 5 finishes at least...	A number
Season #1 finishes at least...	A number

Each server can have up to 25 custom achievements. They're evaluated at the exact same moments as built-in achievements (after every match, queue join, etc.), so there's no delay or separate check to run - they unlock and DM the player automatically, identically to a built-in one.

Bracket Engine Internals

For anyone curious how the tournament bracket actually works under the hood:

Seeding is random, not ELO-based - every team has an equal chance of any matchup, including facing the strongest team in round 1.
Uneven team counts get padded with byes up to the next power of two (e.g. 5 teams gets padded to 8). Byes are deliberately never paired against each other - each bye is matched with a distinct real team, which auto-advances without playing.
Double elimination gives every team a trip to the losers bracket before being eliminated. The losers bracket is built dynamically as the winners bracket progresses, correctly handling bye cascades even when a bye-advanced team's "phantom" loss would otherwise leave a losers-bracket match with no real opponent.
The Grand Final is a single match between the winners-bracket champion and the losers-bracket champion - there's no "bracket reset" second match if the losers-bracket team wins it, which is a common simplification versus tournament software like Challonge.
One tournament per server at a time.

Player Commands

Command	What it does
`/queue`	Enter a matchmaking queue.
`/profile`	View your (or someone else's) ELO, rank, W/L, and achievements.
`/achievements`	View unlocked and locked achievements.
`/setmyid`	Set or update your own registered in-game player ID.
`/notifications`	Toggle your personal DM notification preferences.
`/halloffame`	View the Season Archive - Top 5 finishers of past seasons.
`/reportplayer`	Report a player for griefing, scripting/cheating, or breaking scrim rules.
`/help`	View a list of available commands.
`/party ...`	See Parties above.

Moderator Commands

Command	What it does
`/setup`	Configure the bot for this server and game.
`/viewconfig`	View this server's current bot configuration.
`/settierrole`	Link a rank tier to a Discord role.
`/sync`	Instantly refresh this server's slash commands.
`/backup`	List this server's available backups (full data + config).
`/backupnow`	Take an on-demand backup of this server's full data + config right now.
`/restorebackup`	Restore this server's full data + config from a backup.
`/adjustelo`	Manually set a player's ELO rating.
`/cancelmatch`	Cancel a stuck active match without applying any ELO changes.
`/clearqueue`	Clear a stuck matchmaking queue lobby.
`/forceresolve`	Manually resolve an active match's outcome.
`/resetplayer`	Reset a single player's stats back to Unranked.
`/suspendplayer`	Temporarily suspend a player from queueing.
`/unsuspendplayer`	Lift an active suspension early.
`/setstreak`	Manually set a player's win streak counter.
`/clearstrikes`	Clear a player's demotion protection strikes.
`/setid`	Manually set a player's registered in-game ID.
`/activedisputes`	List all currently unresolved match disputes.
`/refreshleaderboard`	Force an immediate leaderboard refresh.
`/restart-season`	Wipe all ELO/stats and start a fresh season (archives Top 5 to Hall of Fame first).
`/matchhistory`	View a player's recent recorded match history.
`/viewmatch`	View full info for a match by its Match ID (active or resolved).
`/tournament ...`	See Tournaments above.
`/support`	Request direct help from the bot developer - DMs every configured support contact with your server name, an invite, and who asked.
`/customachievement create/list/delete`	Premium. Build custom achievements around any tracked stat - see below.

Backup retention scales with server size: daily automatic backups are kept for 3 days on servers with 50 members or fewer, 7 days for servers with 51-299 members, and 14 days for servers with 300+ members - bigger communities generate more matches (and more to lose) between backups, so they get a longer recovery window. This is checked live against the server's current member count each time old backups are cleaned up, not fixed at setup time.

Backups cover the whole server, not just ELO/stats: every backup includes the full configuration too - which channels are assigned to what, the Mod and Admin roles, rank tiers, queue modes, and settings. If a server's channels or roles ever get wiped out or the bot needs re-setting-up from scratch, restoring a backup brings all of that back too, not just player data.

Web Dashboard

Everything a moderator can do in Discord can also be done from the web dashboard - log in with Discord, pick a server, and use any of these tabs:

Overview - at-a-glance stats and a Top 5 leaderboard preview.
Leaderboard - full sortable ranking; click a player to edit ELO, streak, ID, reset stats, or suspend/unsuspend.
Matches - resolve or cancel active matches.
Queues - see every open lobby live and clear stuck ones.
Parties - see every active party, its leader, members, and pending invites.
Tournaments - start, begin, pause, resume, stop, or restart a tournament, with a full visual bracket and one-click match reporting.
Reports & Disputes - review player reports and active match disputes.
Season & Backups - trigger a season reset, or create/restore backups.
Audit Log - every moderator action, from Discord or the dashboard, in one place.
Settings - everything /setup configures, with live Discord channel/role dropdowns instead of pasting IDs. Also shows your server's Public Leaderboard Link.

Public leaderboard page

Every server gets its own public, read-only leaderboard page - no Discord login required. It's linked from the persistent leaderboard message posted in Discord, and from the Settings tab (where a moderator can copy the link, or regenerate it to invalidate the old one). If a tournament is currently running, the page also gets a toggle at the top to switch between the leaderboard and a live view of the bracket. There are no admin controls on this page at all - viewing it never requires or grants any access to actually manage the server; that still only happens through the real dashboard.

FAQ

Why did my rank-mismatched opponent not get blocked?

They weren't blocked - they were placed in a separate rank-bracketed lobby instead. See Ranked Matchmaking.

Can I be in more than one party?

No - leave your current party first with /party leave.

Can two tournaments run at once?

No, one active tournament per server at a time.

How is the tournament bracket seeded?

Randomly, not by ELO. Uneven team counts are padded with byes, which auto-advance.

Who can resolve a tournament match?

Moderators only, via the "Ready to Spectate" verification flow - not self-reported by players.

Why did my last win barely move my ELO?

You're probably above 1200 ELO and beat someone rated lower than you (K-factor 6, capped at just +1). Beating someone higher-rated than you moves your ELO much more. See ELO & Ranking Math.

Why did I lose Champion status without losing a match?

Either someone else's ELO pushed you out of the Top 5, or your ELO decayed below the Champion minimum from being inactive too long. See Champion Defence.

Does queueing up pause Champion decay?

Yes - decay only counts time spent inactive. Being in an active queue lobby or an active disputed match pauses the decay timer entirely.

I lost a match and didn't get demoted - why?

Demotion needs 3 losses in a row while below your tier's ELO threshold. A single bad loss gives you a demotion strike, not an instant demotion - win your next match and the strike clears. See Promotion & demotion.