Chat Bridge

Chat Bridge

The chat bridge relays messages between a Minecraft server chat and a Discord text channel in real time — in both directions.

---

How It Works

Minecraft → Discord

1. A player sends a chat message in Minecraft.
2. The AsyncChatEvent listener captures the message.
3. The plugin formats it using the configured template.
4. The formatted message is sent to the configured Discord channel via webhook or bot message.

Discord → Minecraft

1. A user sends a message in the configured Discord channel.
2. The MessageReceivedEvent listener captures the message (bot messages are ignored).
3. The plugin formats it using the configured template with MiniMessage support.
4. The formatted message is broadcast to all online Minecraft players.

---

Configuration

Chat bridge settings live in config.yml:

chat-bridge:
  enabled: true
  channel-id: "DISCORD_CHANNEL_ID"

  # How Minecraft messages appear in Discord
  minecraft-to-discord:
    format: "**%player_name%**: %message%"
    use-webhook: true
    webhook-url: "https://discord.com/api/webhooks/..."
    webhook-name: "%player_name%"          # Webhook display name
    webhook-avatar: true                    # Use player's skin as webhook avatar

  # How Discord messages appear in Minecraft
  discord-to-minecraft:
    enabled: true
    format: "<gray>[Discord]</gray> <white>%discord_name%</white>: <gray>%message%</gray>"
    # Format uses MiniMessage tags: <color>, <bold>, <italic>, <gradient:...>, etc.

---

Placeholders

Minecraft → Discord Format

Placeholder	Description
%player_name%	Minecraft username
%player_uuid%	Minecraft UUID
%message%	The chat message content
%server_name%	Server name from config
%world%	World the player is in

Discord → Minecraft Format

Placeholder	Description
%discord_name%	Discord display name
%discord_tag%	Discord username (with discriminator)
%message%	The Discord message content
%channel_name%	Discord channel name

---

Webhook Mode

When use-webhook: true, messages are sent through a Discord webhook. This allows the bot to impersonate the player's name and skin as the webhook avatar, making the chat look more natural in Discord.

To set up:

1. In Discord, go to the bridge channel → Edit Channel → Integrations → Webhooks → New Webhook.
2. Copy the webhook URL.
3. Paste it as webhook-url in the config.

When webhook-avatar: true, the plugin fetches the player's skin head from Crafatar and uses it as the webhook's avatar for each message.

---

MiniMessage Formatting (Discord → Minecraft)

The discord-to-minecraft.format field supports MiniMessage tags for rich text in Minecraft:

<red>text</red>
<bold>text</bold>
<italic>text</italic>
<gradient:red:blue>text</gradient>
<hover:show_text:'Tooltip'>text</hover>
<click:run_command:/help>text</click>

Example format with colors:

format: "<dark_gray>[<aqua>Discord</aqua>]</dark_gray> <white>%discord_name%</white> <dark_gray>»</dark_gray> %message%"

---

Filtering

To prevent the bridge from relaying certain messages, configure prefixes to ignore:

chat-bridge:
  ignore-prefixes:
    - "!"    # Ignore bot commands that start with !
    - "/"    # Ignore slash commands typed in chat

Players with the uxmdiscordsync.chat.bypass permission can be excluded from the bridge entirely.

---

Rate Limiting

To prevent spam flooding Discord:

chat-bridge:
  rate-limit:
    enabled: true
    max-messages-per-minute: 60

Messages beyond the limit are silently dropped. Increase this if your server has a very active chat.