Hypixel Mayor Discord Bot

A Discord bot that checks the Hypixel SkyBlock election API, pings a configured role for election and mayor changes, and keeps a single status embed updated with the current mayor and active perks.

Detailed project documentation lives in docs/BOT_DOCUMENTATION.md.

Features

• Polls https://api.hypixel.net/v2/resources/skyblock/election on a fixed interval.
• Detects the currently active SkyBlock mayor.
• Can ping a configured role when the Election Booth opens.
• Can ping a configured role when a new mayor becomes active.
• Posts a status embed with the current mayor and perks.
• Replaces the previous ping message whenever a new alert is sent.
• Edits the existing status embed instead of sending a new one every time.
• Includes an in-Discord /setup hub with sections for mayor alerts, mod update tracking with optional role pings, reaction roles, and shitter permissions.
• Sends cake reminders into a dedicated configured channel on a fixed 124-hour cycle.
• Supports Discord-configurable reaction roles via /reactionrole.
• Includes /help for a grouped command overview with examples.
• Includes /cata and /catacombs for a quick dungeon overview lookup, with linked-account fallback when no player is provided.
• Includes /trophyfishing for a Trophy Fish overview with per-fish info about location and catch chance, with linked-account fallback when no player is provided.
• Includes /trophyfrogs for a Trophy Frog overview with unlocked-tier progress and per-frog requirement info, with linked-account fallback when no player is provided.
• Includes /itememoji to post SkyBlock item emojis from Altpapier's emoji dataset.
• Includes /uuid to fetch a player's Minecraft UUID from their IGN, with linked-account fallback when no player is provided.
• Includes /namehistory to show a player's known Minecraft name history, with linked-account fallback when no player is provided.
• Includes /link to verify Minecraft usernames through the Hypixel Discord social link.
• Includes /gif to convert an uploaded image into a GIF.
• Includes /shitter add, /shitter query, /shitter remove, and /shitter list for a guild-local IGN watchlist with reasons and optional screenshots, with linked-account fallback when no IGN is provided.
• Persists booth state and the status message ID in data/state.json.
• Stores server configuration in data/config.json.
• Stores shitter list entries in data/shitter-list.json.
• Can optionally expose a built-in HTTP IRC bridge server for the Fabric client mod.

Setup

1. Create a bot in the Discord Developer Portal.
2. Make sure the bot can send messages in your target channel.
3. Invite the bot to your server.
4. Copy .env.example to .env.
5. Fill in your token and optional defaults.
6. In Discord, run /setup, open Discord -> Mayor Alerts, and enter the target channel ID and role ID.
7. Open Discord -> Mod Updates to manage tracked GitHub repos. New servers start with https://github.com/odtheking/Odin prefilled.
8. Use the Mayor Alerts toggle buttons to choose whether Election Booth and mayor change alerts should ping the role in that server.
9. Use Discord -> Mayor Alerts -> Reload Status any time you want to force-refresh the current mayor embed.

Configuration

• DISCORD_TOKEN - bot token from the Discord Developer Portal
• IRC_BRIDGE_ENABLED - enable the built-in HTTP IRC bridge server for the Fabric mod
• IRC_BRIDGE_HOST / IRC_BRIDGE_PORT - listen address for the IRC bridge server
• IRC_BRIDGE_AUTH_TOKEN - shared secret used by the Minecraft mod
• IRC_BRIDGE_CHANNEL_ID - Discord channel used for the bridge
• IRC_BRIDGE_MAX_BUFFERED_MESSAGES - how many recent Discord/IRC messages the backend keeps for clients
• MOD_BACKEND_URL - standalone Xclipsen Mod backend URL, defaults to https://api.xclipsen.de
• MOD_BACKEND_AUTH_TOKEN - token used by the bot when reading/writing mod backend links
• GITHUB_TOKEN - optional GitHub token for higher rate limits on mod update checks
• HYPIXEL_API_KEY - required for /cata and /catacombs using the official Hypixel API
• DISCORD_CHANNEL_ID - optional legacy default channel for first-time setup
• DISCORD_ROLE_ID - optional legacy default role for first-time setup
• ADMIN_USER_IDS - optional comma-separated Discord user IDs that can always use admin bot commands
• CHECK_INTERVAL_MINUTES - interval for election and mayor checks
• MOD_UPDATE_CHECK_MINUTES - interval for GitHub mod update checks
• STATUS_UPDATE_MINUTES - interval for status embed updates
• SKYBLOCK_ITEM_EMOJIS_ENABLED - set to false to disable the SkyBlock item emoji lookup feature
• SKYBLOCK_ITEM_EMOJI_HASH_URL / SKYBLOCK_ITEM_EMOJI_DATA_URL - optional override URLs for the Altpapier emoji mapping files
• MOCK_MODE - if true, the bot always loads data/mock-election.json instead of the live API
• EMOJI_* - optional custom emojis for mayors, for example <:diaz:123...>
• VOTE_BAR_FILLED_EMOJI / VOTE_BAR_EMPTY_EMOJI - optional custom emojis for the mayor vote bar chart
• Mod update tracking reads public GitHub release data for repos you add in /setup -> Discord -> Mod Updates and can post new releases into a configured channel with an optional role ping
• Cake reminders use their own configured channel and optional ping role.
• If your server already has emojis named like diaz, cole, or mayor_diaz, the bot can detect them automatically.
• The bot now needs permission to manage roles if you use reaction roles.

DISCORD_TOKEN=your_discord_bot_token
IRC_BRIDGE_ENABLED=true
IRC_BRIDGE_HOST=0.0.0.0
IRC_BRIDGE_PORT=8765
IRC_BRIDGE_AUTH_TOKEN=change-me
IRC_BRIDGE_CHANNEL_ID=123456789012345678
IRC_BRIDGE_MAX_BUFFERED_MESSAGES=250
GITHUB_TOKEN=your_github_token
HYPIXEL_API_KEY=your_hypixel_api_key
DISCORD_CHANNEL_ID=123456789012345678
DISCORD_ROLE_ID=123456789012345678
ADMIN_USER_IDS=885542911511515146
CHECK_INTERVAL_MINUTES=5
MOD_UPDATE_CHECK_MINUTES=60
STATUS_UPDATE_MINUTES=30
SKYBLOCK_ITEM_EMOJIS_ENABLED=true
MOCK_MODE=false
EMOJI_DIAZ=<:diaz:123456789012345678>
VOTE_BAR_FILLED_EMOJI=<:barfill:123456789012345678>
VOTE_BAR_EMPTY_EMOJI=<:barempty:123456789012345678>

Run Locally

npm install
npm start

• Use /help in Discord for a quick overview of public commands and examples.
• If you enable the IRC bridge, the bot also needs the GuildMessages and MessageContent intents.

Project Structure

• src/index.js wires the client and events together.
• src/config/ contains environment loading, slash commands, and interaction IDs.
• src/features/ contains setup, mayor alerts, access control, reaction roles, simulation, and shitter logic.
• The shitter list is stored per guild in data/shitter-list.json.
• src/storage/ contains the config/state store helpers.
• src/utils/ contains shared SkyBlock time formatting helpers.

After the bot is online, run /setup in your Discord server and fill in:

• the channel ID where updates should be posted
• the role ID that should be pinged for election and mayor changes
• whether election-open alerts and mayor-change alerts should ping that role

Only members with Manage Server or a whitelisted ADMIN_USER_IDS entry can use the setup hub.

Reaction Roles

• Use /reactionrole add with a channel, message ID, role, and emoji.
• Or open /setup -> Discord -> Reaction Roles and manage bindings from the interactive panel.
• You can optionally set required_role so only members with that role can use the reaction to get the target role.
• Use /reactionrole remove to delete a binding.
• Use /reactionrole list to see all current bindings for the server.
• When someone adds the configured reaction, the bot gives the role.
• When they remove the reaction, the bot removes the role.
• The bot needs Manage Roles, and the target role must be lower than the bot's top role.

Linked Minecraft Accounts

• Use /link username:<ign> to verify a Minecraft account through Hypixel Social Media and receive a short-lived code for /irc link <code> in Minecraft.
• The player's Hypixel Discord social link must match the Discord username running the command.
• This feature requires HYPIXEL_API_KEY.
• Links created by the old Minecraft code flow are treated as legacy and must be re-verified with /link username:<ign>.
• If you leave the name field empty on supported commands, the bot uses your linked Minecraft username.

Shitter List

• Use /shitter add [name:<ign>] reason:<text> to add or update an entry.
• /shitter add also accepts up to 5 optional screenshot image attachments.
• IGNs are validated like Minecraft names: 3-16 characters, letters, numbers, and _ only.
• Multiple active entries can be stored for the same IGN, and /shitter query lets you select which one to view.
• The bot automatically stores the current date and time for each entry.
• Use /shitter query [name:<ign>] to check whether an IGN is listed.
• Use /shitter remove [name:<ign>] to mark all active entries for that IGN as removed while keeping history.
• Use /shitter list to show unique names for the server and select one from a menu.
• In /setup -> Discord -> Shitter List, you can block specific Discord user IDs, block roles, or require allowed roles for adding/removing shitter entries.

Minecraft UUID Lookup

• Use /uuid [player:<ign>] to fetch a player's current Mojang UUID.
• The bot returns both the raw UUID and dashed UUID form.
• /uuid also shows a Stuffy-style UUID percentile and leaderboard position.
• This command uses the official Mojang API and does not require a Hypixel API key.

SkyBlock Item Emojis

• Use /itememoji item:<SKYBLOCK_ID> to post a mapped item emoji in the current channel.
• Add enchanted:true if you want the enchanted variant when one exists.
• The command posts a normal channel message instead of a slash-command response because the upstream emoji dataset no longer works reliably inside interaction responses.
• By default the bot loads the mapping data from Altpapier/Skyblock-Item-Emojis version 3 on demand.
• Credit for the dataset stays with Altpapier/Skyblock-Item-Emojis.

Minecraft Name History

• Use /namehistory [player:<ign>] to show a player's known username history.
• The bot shows the current name, UUID, and each known previous name.
• This command uses Mojang for the current profile and scrapes the name history directly from NameMC over HTTPS.

Media Tools

• Use /gif media:<image> to convert an uploaded image into a GIF file.

Help

• Use /help to open the full command guide.
• Use /help section:<name> to jump straight to Getting Started, Player Tools, Moderation, or Admin Tools.

Testing Scenarios

• Use /simulate custom mayor:<name> perk_count:<number> to generate a random perk set for a selected mayor.
• /simulate custom also accepts booth_open:true/false.
• /simulate clear switches the bot back to the live API.
• If you want the whole bot to stay in local test mode after restart, set MOCK_MODE=true and edit data/mock-election.json.

Docker Compose

docker compose up -d --build

• The bot loads its token and optional legacy defaults from .env.
• ./data is mounted to /app/data so server config, the stored status message ID, and booth state survive restarts.
• View logs with docker compose logs -f.
• Stop the bot with docker compose down.

Notes

• This election endpoint currently does not require a Hypixel API key.
• If you want to use other Hypixel endpoints later, you can extend the bot with an API key.
• The bot only needs the Guilds intent because it does not read messages.
• The /setup command is registered per server when the bot starts or joins a new guild.
• For custom emojis, upload them to your Discord server and paste the full emoji tag into .env.
• As an alternative, you can simply name your server emojis diaz, cole, foxy, or mayor_diaz and the bot will try to resolve them automatically.