Punishment Sync

Punishment Sync

Punishment sync bridges bans and mutes between your Minecraft server and Discord — punishments on one platform are automatically mirrored to the other.

---

Supported Punishment Plugins

The plugin auto-detects which punishment system is installed and hooks into it:

Plugin	Detection
LiteBans	Detected if the LiteBans API is present
AdvancedBan	Detected if the AdvancedBan API is present
Vanilla	Fallback — uses the built-in Minecraft ban system

Only one system is used at a time. Priority: LiteBans → AdvancedBan → Vanilla.

---

Sync Directions

Direction	Description
Minecraft → Discord	A Minecraft ban/mute triggers a Discord action
Discord → Minecraft	A Discord ban/timeout triggers a Minecraft action

---

Configuration

All punishment sync settings live in punishment-sync.yml:

punishment-sync:
  enabled: false       # Disabled by default; enable when ready

  # Sync Minecraft punishments to Discord
  minecraft-to-discord:
    enabled: true
    on-ban:
      action: ban          # "ban", "kick", or "timeout"
      reason: "Banned on Minecraft: %reason%"
    on-tempban:
      action: timeout      # Discord timeout (max 28 days)
      duration: "%duration%"
    on-mute:
      action: timeout
      duration: "%duration%"
    on-kick:
      action: kick

  # Sync Discord punishments to Minecraft
  discord-to-minecraft:
    enabled: true
    on-ban:
      action: ban
      reason: "Banned on Discord: %reason%"
    on-timeout:
      action: mute         # Mute via the detected punishment plugin
      reason: "Discord timeout: %reason%"
    on-unban:
      action: unban

  # Users/roles exempt from punishment sync
  bypass:
    # Discord role IDs whose members are never synced
    role-ids:
      - "STAFF_ROLE_ID"
      - "ADMIN_ROLE_ID"
    # Discord user IDs that are always exempt
    user-ids:
      - "BOT_USER_ID"

---

Actions Reference

Discord Actions (Minecraft → Discord)

Action	Description	Notes
ban	Permanently ban the Discord member	Bot needs Ban Members permission
kick	Kick the Discord member	Bot needs Kick Members permission
timeout	Apply a Discord timeout (mute)	Max 28 days; bot needs Moderate Members

Minecraft Actions (Discord → Minecraft)

Action	Description
ban	Permanently ban the player via the detected plugin
tempban	Temporary ban (duration from the Discord event)
mute	Mute via LiteBans / AdvancedBan
kick	Kick the player if online
unban	Remove a Minecraft ban

---

Discord Timeout Limit

Discord timeouts have a maximum duration of 28 days. If a Minecraft tempban exceeds 28 days, the plugin automatically caps the timeout at 28 days and logs a warning.

For permanent Minecraft bans, the plugin uses a Discord ban instead of a timeout.

---

Bypass Lists

Staff members should be exempt from punishment sync to prevent accidental cross-platform punishments during moderation.

Role bypass: Any Discord member with one of the listed roles is skipped entirely.

User bypass: Specific Discord user IDs (useful for other bots) are always exempt.

---

Reason Placeholders

Placeholder	Description
%reason%	The punishment reason
%player_name%	Minecraft username
%discord_name%	Discord username
%duration%	Punishment duration
%moderator%	Who issued the punishment

---

Requirements

• The bot needs Ban Members, Kick Members, and Moderate Members permissions.
• Players must have linked accounts for cross-platform sync to work. Unlinked players cannot be synced.
• For LiteBans / AdvancedBan: the respective plugin must be installed and loaded before uxmDiscordSync.

---

Important Notes

• Test carefully before enabling in production. An accidental ban loop could occur if a moderation action on one platform triggers a sync that triggers another action. The bypass lists exist specifically to prevent this.
• Discord permanent bans are irreversible via the plugin. Only a manual Discord unban by an admin restores access.
• Timeout duration from Discord is in seconds; the plugin converts this when creating Minecraft tempbans.