Build a Discord Faction Leaderboard From Message XP

Before you start

• A running bot connected to your Discord server, with Pro access and Faction XP enabled.
• Existing Discord roles to represent factions, with each participant assigned exactly one of those roles.
• Manage Server permission or the configured manager role to add, remove or reset factions. The bot must be able to view channels where you expect messages to count.

1. Enable scoring and set a member cooldown

   Open your bot’s Modules area, enable Faction XP and open Settings. Select the intended Discord server, turn on Enable in this server and save. Scoring is off by default for each server. Optionally choose a manager role for people who should manage factions without Manage Server.

   Set XP per eligible message from 1 to 100 and the member cooldown from 15 to 3600 seconds. Defaults are 10 XP and 60 seconds. The cooldown applies to a member across all factions in this Discord server, so switching faction roles does not bypass it. Explain your participation rules before inviting members to compete.

2. Register existing roles as factions

   Use /faction add and select the role option for each faction. You can register up to 10 roles per server. Each newly registered faction begins at zero XP. The module rejects @everyone, integration-managed roles and roles that are not valid for this server; registering the same role again does not reset its score.

   Adding a faction registers the role for scoring. It does not create a role or assign members to it. Give participants their faction role through Discord’s role tools or your existing role workflow. A member with no registered faction role earns nothing; a member with multiple registered faction roles also earns nothing. Keep your test participant in exactly one faction.

3. Check which messages earn points

   With the bot running, send a new message from a human test account in a channel the bot can view. Check /faction leaderboard to see the faction total. Send another message during the member cooldown; it should not add points. After the cooldown expires, a new eligible message can add the configured XP amount.

   Bot messages, webhooks and system messages do not earn XP. The module also rejects stale message events and does not backfill messages sent while offline. It reads role membership rather than message content. Sending longer messages does not increase the per-message award.

   Only the faction total increases; the module does not keep an individual contribution leaderboard. Already-earned points stay with the faction if the member changes teams or leaves. Scores and per-member cooldowns are saved, so restarting the bot does not reset them.

4. Read the server’s saved leaderboard

   Any member can use /faction leaderboard while the module is enabled. The private reply shows registered factions, XP totals and role IDs, sorted by highest score first. Equal scores are ordered by role ID, not by a separate competition tie-break. The reply suppresses role pings.

   Keep an eye on role membership when a score does not change. Confirm the member has exactly one registered faction role, the cooldown has expired, the bot can see the channel and both module switches are enabled. There is also a cap of 1 billion XP per faction. Turning off the module pauses scoring and commands while retaining scores.

5. Remove a faction or start a manual reset

   Use /faction remove with id set to the faction’s role ID from the leaderboard. This permanently removes that faction’s saved score, even if the Discord role has already been deleted. It leaves Discord roles and memberships unchanged. Re-registering the role starts a new score at zero; member cooldowns remain.

   For a deliberate fresh start, a manager can use /faction reset with confirm set to true. This permanently sets every registered faction’s score in the server to zero. It keeps the registrations and member cooldowns. There is no undo for cumulative resets. Optional monthly competitions keep separate monthly scores and saved results; resetting cumulative scores does not erase them.

   For monthly results, register all faction roles first, then enable Monthly competitions in settings and use /faction monthly or /faction history. Tracking starts at the first eligible message or monthly command and fixes that month’s roster. Later registrations join next month. Months end on the first at 00:00 UTC and roll over on the next eligible message or monthly command. The last 12 completed months are saved; there is no offline backfill. Handle any rewards separately. Individual Leveling XP remains a separate module and is not converted into faction points.