🤖 Discord

✅ Setup

You need:

• A Discord bot (Developer Portal) invited to your guild
• Enabled intents: GUILD_MEMBERS and MESSAGE_CONTENT
• Channels (recommended): chat, link, console, status, plus a ticket category

Minimal first-run checklist:

1. Edit config/voidium/discord.json
2. Set enableDiscord: true, botToken, guildId
3. Configure channel IDs:
   • chatChannelId (required for chat bridge)
   • linkChannelId (recommended; see note below)
4. Restart the server (for token changes), or try /voidium reload for small edits

⚙️ Configuration

Voidium uses two Discord-related config files:

• config/voidium/discord.json (bot, channels, whitelist, chat bridge, status/topic, ban sync)
• config/voidium/tickets.json (ticket system)

discord.json (key fields)

Basics

• enableDiscord, botToken, guildId

Channels

• chatChannelId — Discord ↔ MC chat bridge channel
• consoleChannelId — console log streaming target
• linkChannelId — channel where users can paste verification codes (messages are deleted)
• statusChannelId — status messages; if empty, Voidium uses chatChannelId

Whitelist & linking

• enableWhitelist
• kickMessage, verificationHintMessage
• linkSuccessMessage, alreadyLinkedMessage, maxAccountsPerDiscord

Chat bridge

• enableChatBridge
• minecraftToDiscordFormat, discordToMinecraftFormat
• chatWebhookUrl (optional; MC → Discord webhook with skin avatar)

Status / topic

• enableStatusMessages + status text fields
• enableTopicUpdate, channelTopicFormat, uptimeFormat

Ban sync

• syncBansDiscordToMc, syncBansMcToDiscord
• Ban sync uses Mixin injection (UserBanListMixin) for automatic detection — no polling

Bot responses

• invalidCodeMessage, notLinkedMessage
• alreadyLinkedSingleMessage (%uuid%), alreadyLinkedMultipleMessage (%count%)
• unlinkSuccessMessage, wrongGuildMessage
• ticketCreatedMessage, ticketClosingMessage, textChannelOnlyMessage

Roles & prefixes

• linkedRoleId — role assigned after successful linking (link-channel flow)
• rolePrefixes + useHexColors

tickets.json (TicketConfig)

File: config/voidium/tickets.json

• enableTickets
• ticketCategoryId, supportRoleId
• ticketChannelTopic (placeholders: %user%, %reason%)
• maxTicketsPerUser
• Messages: ticketCreatedMessage, ticketWelcomeMessage, ticketCloseMessage, noPermissionMessage, ticketLimitReachedMessage, ticketAlreadyClosedMessage
• Transcript: enableTranscript, transcriptFormat (TXT/JSON), transcriptFilename (supports %user%, %date%, %reason%)
• In-game messages (color codes via &): mcBotNotConnectedMessage, mcGuildNotFoundMessage, mcCategoryNotFoundMessage, mcTicketCreatedMessage, mcDiscordNotFoundMessage

🔗 Whitelist & Linking

In-game (whitelist flow)

When whitelist is enabled and a player is not linked:

1. The player joins and is frozen in place (not kicked).
2. They receive a 6-digit code in chat (kickMessage + verificationHintMessage).
3. The code expires after 10 minutes.
4. After linking, the player is unfrozen.

On Discord

• Slash commands:
  • /link code:<code>
  • /unlink
• Link channel:
  • User posts the code into linkChannelId
  • Bot deletes the message and replies (auto-deletes the reply after a few seconds)
  • Optional: assigns linkedRoleId

Data is stored in config/voidium/storage/links.json.

💬 Chat bridge

MC → Discord

• Triggered by normal chat + /say
• Sent into chatChannelId
• Uses minecraftToDiscordFormat
• If chatWebhookUrl is set, messages are sent via webhook (skin-based avatar)

Discord → MC

• Messages from chatChannelId are forwarded into Minecraft when chat bridge is enabled
• Basic Markdown is converted to MC formatting (bold/italic/underline/strike)
• Some Unicode emoji are converted to :aliases: for Voidium client rendering

Join / leave / death

When chat bridge is enabled, join/leave/death events are posted to Discord as colored embeds with the player’s skin thumbnail:

• Join — green embed
• Leave — red embed
• Death — gray embed

🎫 Tickets

Discord slash commands

• /ticket create reason:<reason>
• /ticket close

Ticket creation is rate-limited (global cooldown ~60 seconds) to avoid Discord 429 errors.

In-game

• /ticket <reason> <message...>
• /reply <message...>

See the full command reference here: Commands.

Transcripts

If transcripts are enabled:

• Voidium fetches up to the last ~100 messages
• Uploads a TXT/JSON transcript file into the ticket channel
• Then deletes the channel a few seconds after closing

🧯 Troubleshooting

Bot won’t start

• Verify botToken and guildId
• Check that the intents are enabled in Developer Portal

Discord → MC messages do not arrive

• Ensure enableDiscord and enableChatBridge are true
• Check chatChannelId
• Ensure MESSAGE_CONTENT intent is enabled

Linking doesn’t work

• Code is valid for ~10 minutes
• Check linkChannelId permissions (send + delete)

Ticket not created

• Check ticketCategoryId and bot permissions
• Remember the global ~60s cooldown between ticket creations

Related

• Configuration
• Commands