Skip to content

Configuration

Aridro Chatterjee edited this page Nov 15, 2026 · 1 revision

Configuration Guide

MineBridge provides a flexible YAML-based configuration system that allows server administrators to customize Discord integration, chat synchronization, player notifications, death messages, achievements and gameplay events.

All configuration options are managed through config.yml, which is generated when MineBridge starts for the first time.


Table of Contents

  1. Discord Connection
  2. Message Formatting
  3. Feature Toggles
  4. Death Messages
  5. Achievements and Challenges
  6. Discord Events
  7. Placeholder Reference
  8. Security Best Practices

1. Discord Connection

The discord section contains the credentials and default channel used for Discord integration.

Configuration

discord:
  bot-token: ""
  channel-id: ""
Option Description
bot-token Discord bot authentication token
channel-id Default Discord text channel ID

Bot Token Configuration

MineBridge supports the MINEBRIDGE_BOT_TOKEN environment variable.

We recommend using an environment variable instead of storing your bot token directly in config.yml.

Example:

export MINEBRIDGE_BOT_TOKEN="YOUR_BOT_TOKEN"

Important: Never share your Discord bot token or commit it to a public repository.

Channel ID

The channel-id option specifies the default Discord channel used by MineBridge.

Individual event systems can also define their own channel IDs.


2. Message Formatting

MineBridge allows administrators to customize messages exchanged between Minecraft and Discord.

All message templates are configurable through the messages section.

2.1 Minecraft to Discord

Controls how Minecraft chat messages appear in Discord.

minecraft-to-discord: "**{player}**: {message}"

Available placeholders:

Placeholder Description
{player} Minecraft player name
{message} Chat message
{timestamp} UTC ISO-8601 timestamp

2.2 Discord to Minecraft

Controls how Discord messages appear inside Minecraft.

discord-to-minecraft: "&9[Discord] &f{player}: {message}"

Available placeholders:

Placeholder Description
{player} Player display name
{display_name} Discord display name
{username} Discord username
{message} Message content
{timestamp} UTC ISO-8601 timestamp

2.3 Player Join and Leave Messages

Customize player activity notifications.

player-join: "🟢 **{player}** joined the server."
player-leave: "🔴 **{player}** left the server."

Available placeholders:

  • {player} — Player name.
  • {timestamp} — UTC ISO-8601 timestamp.

2.4 Server Status and Player List

server-status: "&7Server &8| &a{online}&7/&f{max} players online"
player-list: "&7Online players (&f{online}&7/&f{max}&7): {players}"

Available placeholders:

Placeholder Description
{online} Number of online players
{max} Maximum player capacity
{players} List of online players

3. Feature Toggles

The features section controls the main MineBridge functionality.

features:
  chat-relay: true
  join-leave-notifications: true
  server-status: true
  player-list: true
Option Description
chat-relay Controls chat synchronization
join-leave-notifications Controls player join and leave notifications
server-status Controls server status functionality
player-list Controls player list functionality

Enabling and Disabling Features

Use true to enable a feature and false to disable it.

Example:

features:
  chat-relay: false
  join-leave-notifications: true
  server-status: true
  player-list: false

4. Death Messages

MineBridge provides configurable death notifications for Minecraft and Discord.

The death-messages section controls death detection, message broadcasting, Discord embeds and individual death categories.

4.1 Main Settings

death-messages:
  enabled: true
Option Description
enabled Enables or disables the death message system

4.2 Minecraft Notifications

minecraft:
  enabled: true
  broadcast: true
Option Description
enabled Enables Minecraft death notifications
broadcast Controls death message broadcasting

4.3 Discord Notifications

discord:
  enabled: true
  channel-id: ""
  embed: true
  title: "☠ Player death"
  description: "{message}\nCategory: {category}\nCause: {cause}"
  color: "#D32F2F"
Option Description
enabled Enables Discord death notifications
channel-id Dedicated Discord channel ID
embed Enables embed formatting
title Discord embed title
description Discord embed description
color Embed color in hexadecimal format

Leave channel-id empty to use the default discord.channel-id.

4.4 Death Categories

MineBridge supports individual death category controls.

categories:
  player-kill: true
  mob-kill: true
  fall: true
  lava: true
  fire: true
  drowning: true
  void: true
  explosion: true
  environmental: true
  other: true

Supported categories:

Category Description
player-kill Death caused by another player
mob-kill Death caused by a mob
fall Fall damage
lava Lava-related death
fire Fire-related death
drowning Drowning
void Falling into the void
explosion Explosion-related death
environmental Environmental damage
other Other death causes

4.5 Custom Death Messages

Administrators can customize individual death messages.

messages:
  player-kill: "&c☠ {victim} was slain by {killer}"
  mob-kill: "&c☠ {victim} was slain by {killer}"
  fall: "&c☠ {victim} fell to their death"
  lava: "&c☠ {victim} tried to swim in lava"
  fire: "&c☠ {victim} burned to death"
  drowning: "&c☠ {victim} drowned"
  void: "&c☠ {victim} fell out of the world"
  explosion: "&c☠ {victim} died in an explosion"
  environmental: "&c☠ {victim} died from {cause}"
  other: "&c☠ {victim} died"

Available placeholders:

  • {victim} — Player who died.
  • {killer} — Killer name.
  • {cause} — Death cause.
  • {category} — Death category.

5. Achievements and Challenges

MineBridge supports Minecraft advancement and challenge notifications.

Administrators can configure Minecraft announcements, Discord notifications, categories and custom messages.

5.1 Main Settings

achievements:
  enabled: true

Enables or disables the achievement notification system.

5.2 Minecraft Notifications

minecraft:
  enabled: true

Controls achievement notifications in Minecraft.

5.3 Discord Notifications

discord:
  enabled: true
  channel-id: ""
  title: "ADVANCEMENT UNLOCKED"
  description: "{player} has unlocked {title}.\n{description}"
  challenge-title: "CHALLENGE COMPLETED"
  challenge-description: "{player} has completed {title}!\n{description}"
  color: "#2196F3"
Option Description
enabled Enables Discord achievement notifications
channel-id Dedicated Discord channel
title Advancement embed title
description Advancement embed description
challenge-title Challenge embed title
challenge-description Challenge embed description
color Embed color in hexadecimal format

Leave the channel ID empty to use the default Discord channel.

5.4 Challenge Settings

challenges:
  enabled: true

Controls challenge completion notifications.

5.5 Advancement Categories

categories:
  story: true
  nether: true
  end: true
  adventure: true
  husbandry: true
  other: true
Category Description
story Story advancements
nether Nether advancements
end End advancements
adventure Adventure advancements
husbandry Husbandry advancements
other Other advancements

5.6 Custom Achievement Messages

messages:
  normal: "&a✦ {player} has made the advancement [{title}]!"
  challenge: "&6🏆 {player} has completed the challenge [{title}]!"

Available placeholders:

  • {player} — Player name.
  • {title} — Advancement title.
  • {description} — Advancement description.
  • {category} — Advancement category.
  • {challenge} — Challenge information.

6. Discord Events

The discord-events section provides additional controls for Minecraft event notifications sent to Discord.

6.1 Main Settings

discord-events:
  enabled: true

Enables or disables the Discord event notification system.

6.2 Embed Settings

embeds:
  enabled: true
  footer: "MineBridge | Minecraft Events"
Option Description
enabled Controls event embeds
footer Custom embed footer

6.3 Player Events

player-events:
  enabled: true
  channel-id: ""
  join: true
  leave: true
  first-join: true

Available controls:

Option Description
enabled Enables player event notifications
channel-id Dedicated notification channel
join Player join notifications
leave Player leave notifications
first-join First-time join notifications

6.4 Achievement Events

achievements:
  enabled: true
  channel-id: ""
  story: true
  nether: true
  end: true
  adventure: true
  husbandry: true
  challenges: true

Controls Discord notifications for advancement categories and challenges.

6.5 Death Events

deaths:
  enabled: true
  channel-id: ""
  player-kill: true
  mob-kill: true
  environmental: true

Controls Discord death event notifications.

Supported options:

  • enabled
  • channel-id
  • player-kill
  • mob-kill
  • environmental

7. Placeholder Reference

MineBridge supports placeholders in different message templates.

Placeholder Description
{player} Player name
{display_name} Display name
{username} Username
{message} Message content
{timestamp} UTC ISO-8601 timestamp
{online} Online player count
{max} Maximum player capacity
{players} Online player list
{victim} Player who died
{killer} Killer name
{cause} Death cause
{category} Event category
{title} Advancement title
{description} Advancement description
{challenge} Challenge information

Note: Placeholder availability depends on the specific configuration field. Only use placeholders supported by that field.


8. Security Best Practices

Follow these recommendations when configuring MineBridge:

  1. Never share your Discord bot token.
  2. Prefer the MINEBRIDGE_BOT_TOKEN environment variable.
  3. Keep your configuration file private.
  4. Avoid committing credentials to public repositories.
  5. Use valid Discord channel IDs.
  6. Review your bot permissions and restrict access appropriately.

Need Help?

If you experience configuration problems:

  • Check your YAML indentation.
  • Verify that configuration values use the correct data types.
  • Check your Minecraft server console for errors.
  • Verify your Discord bot credentials and channel IDs.

For further assistance, visit the Troubleshooting page.


MineBridge Documentation Minecraft × Discord Integration GitHub Repository · Modrinth

Clone this wiki locally