SyncCord 🚀

Seamless Discord <-> Minecraft Integration Plugin for Paper & Purpur

SyncCord is a powerful, modern, and lightweight Minecraft-to-Discord bridge plugin specifically designed for Paper, Purpur, and Spigot servers (1.20 - 1.21+). It features real-time chat synchronization, secure account linking, role synchronization with LuckPerms, bi-directional console relays with interactive command outputs, and deep integration with the wapeB moderation suite.

📋 Version 1.1 (Recent Updates)

✨ wapeB v1.0.8 Integration & Staff History Sync

• Full Staff History Tracking: Sanctions executed from Discord (e.g. ?mute, ?ban, ?kick, ?warn) are now completely registered and tracked in wapeB's staff history database!
• (Console) Tagging: When inspecting records using /staffhistory <staff>, sanctions executed through Discord are clearly formatted with the (Console) tag on the target player:
  • In-game sanction: TEMPMUTE ywxlol for: spam (2026-09-04 22:16:34)
  • Discord console sanction: TEMPMUTE ywxlol (Console) for: spam (2026-09-04 22:16:34)
• Linked Staff Executor Override: Sanctions issued via Discord automatically map to the staff member's linked Minecraft username instead of anonymous "Console" or raw Discord handles.
• Upgraded API: Updated to the latest wapeB v1.0.8 API for maximum stability and compatibility across both SQLite and YAML data storage managers.
• Customizable Format: Configurable wapeBExecutorFormat setting (default: {executor} (Console)).

⚡ Dual Engine Command Output Capture

• Adventure & Spigot Support: Enhanced console capture engine supporting both Paper's modern Adventure Component format (net.kyori.adventure) and legacy Spigot format (net.md_5.bungee / org.bukkit.ChatColor).
• Zero Output Loss: Moderation and administrative commands that output formatted components in Paper 1.21+ now correctly display in Discord command response embeds.

🔍 Real-Time Diagnostic & Debug System

• Deep Diagnostic Logging: Full tracking of Discord events, channel verifications, command parsing, role permission evaluations, and wapeB event triggers.
• Toggleable On the Fly: Enable or disable verbose debug logging via /synccord debug or directly in config.yml without server restarts.

🛡️ Reliability & Reload Stability

• Safe Shutdown & Reloads: Improved JDA lifecycle management and OkHttp dispatcher shutdown to prevent ZipFile closed exceptions during /plugman reload or server stops.
• Safe Post-Processing: Thread-safe task scheduling to guarantee database integrity during rapid command execution.

🌟 Core Features

• 💬 Bi-directional Chat Synchronization:

  • Real-time bridge between Minecraft server chat and Discord channels.
  • Markdown and formatting support.
  • In-game Discord reply tags showing who replied to whom.
  • Rich muted player embed notifications when a muted player attempts to talk.

• 🔗 Secure Account Linking:

  • Easy two-step verification (/discord link in-game and ?dclink <code> on Discord).
  • Expirable verification codes with customizable validity length.
  • Discord unlink support (?dcunlink).

• 🛡️ Interactive Discord Console & Moderation:

  • Execute server commands directly from Discord channels using custom prefixes (e.g. ?ban, ?mute, ?kick).
  • Console outputs are captured and returned in styled Discord embeds.
  • Granular role permissions (assign specific commands to specific Discord roles or admin roles).
  • Automatic chunking for long console outputs exceeding Discord's character limit.

• 📊 Live Channel Topic Status:

  • Automatically updates Discord channel topics with live online/max player counts (🟢 Online: 12/100).
  • Displays server offline status automatically upon shutdown.

• ⚔️ LuckPerms & wapeB Integration:

  • Real-time rank synchronization with LuckPerms.
  • Native punishment hooks for wapeB mute notifications and staff history auditing.

⚙️ Configuration (config.yml)

# SyncCord - Minecraft-Discord Integration Plugin
# Created by KAGA

# ----------------------------------
# BOT SETTINGS
# ----------------------------------
BotToken: ""
Debug: false  # Detailed console logging for all events (chat, commands, linking, sanctions)
BotStatus:
  enabled: true
  activityType: "WATCHING"
  activityText: "the server"

# ----------------------------------
# CHANNEL SETTINGS
# ----------------------------------
Channels:
  chat: ""      # Primary channel for Minecraft chat & player events
  console: ""   # Console log / command channel

# ----------------------------------
# CHANNEL TOPIC UPDATER
# ----------------------------------
ChannelTopicUpdater:
  enabled: true
  channelId: ""
  updateIntervalSeconds: 60
  format: "🟢 Online: {online}/{max}"
  offlineFormat: "🔴 Server Offline"

# ----------------------------------
# ACCOUNT LINKING
# ----------------------------------
AccountLinking:
  database: "yaml"
  codeValidityMinutes: 5
  codeLength: 6
  deleteCommandAfterUse: true

  MinecraftMessages:
    alreadyLinked: "&cYour account is already linked!"
    notLinked: "&cYou do not have a linked account."
    linkCodeGenerated: "&aYour code: &e{code}&a. Type on Discord: &e{prefix}dclink {code}"
    linkSuccess: "&aSuccessfully linked your account to Discord user &e{discordName}&a!"
    unlinkSuccess: "&aSuccessfully unlinked your account."

  DiscordMessages:
    linkSuccess: "✅ Account linked successfully!"
    linkInvalidCode: "❌ Invalid code."
    linkExpiredCode: "⌛ Expired code."
    unlinkSuccess: "✅ Successfully unlinked your account."
    unlinkNotLinked: "❌ Your account is not linked."

# ----------------------------------
# ROLE SYNCHRONIZATION (LuckPerms)
# ----------------------------------
RoleSync:
  enabled: false
  roles:
    default: ""

# ----------------------------------
# CONSOLE RELAY & COMMANDS
# ----------------------------------
ConsoleRelay:
  enabled: true
  prefix: "?"
  levels: ["INFO", "WARN", "ERROR"]
  commands:
    enabled: true
    requireLinkedAccount: true

    # When enabled, sanctions issued from Discord override the executor to the linked Minecraft account
    overrideWapeBExecutor: true

    # Format of the executor name (default: "{executor} (Console)")
    wapeBExecutorFormat: "{executor} (Console)"

    # Global roles that can run all allowed moderation commands
    allowedRoles:
      - "ADMIN_ROLE_ID"

    # Allowed moderation commands
    moderationCommands: ["kick", "ban", "mute", "tempban", "warn", "banip", "muteip", "tempbanip", "unmute", "unban", "unbanip"]

    # Role-based command permissions:
    roles:
      mute:
        id: "MUTE_ROLE_ID"
        commands: ["mute", "muteip", "unmute"]
      ban:
        id: "BAN_ROLE_ID"
        commands: ["ban", "banip", "unban"]

    broadcastPermission: "synccord.seeconsolecommands"

# ----------------------------------
# MESSAGE FORMATS
# ----------------------------------
MessageFormats:
  minecraftToDiscord:
    plainTextFormat: "**{rank}** {playerName}: {message}"

  discordToMinecraft: "&9[Discord] &7({topRole}) &b{userNick}&f: &7{message}"

  mutedPlayerToDiscord:
    enabled: true
    color: "#FF0000"
    title: "🔇 Muted Player Message"
    description: "**Player attempted to speak while muted:**"
    author:
      name: "{playerName} ({rank})"
      iconUrl: "https://cravatar.eu/helmavatar/{playerUuid}/128.png"
    footer:
      text: "SyncCord • wapeB Punish"
      includeTimestamp: true
    fields:
      message:
        enabled: true
        name: "💬 Message"
        value: "{message}"
        inline: false
      player:
        enabled: true
        name: "👤 Player"
        value: "{playerName}"
        inline: true
      rank:
        enabled: true
        name: "🛡️ Rank"
        value: "{rank}"
        inline: true
      executor:
        enabled: true
        name: "🔨 Punished By"
        value: "{executor}"
        inline: true
      reason:
        enabled: true
        name: "📋 Reason"
        value: "{reason}"
        inline: true
      duration:
        enabled: true
        name: "⏱️ Remaining"
        value: "{duration}"
        inline: true

  consoleCommandExecuted: "&e[!] Command '{command}' executed by: &c{executorName} (Discord)"
  commandNotAllowed: "{userMention}, this command is not allowed from Discord: `{command}`"
  noPermissionCommand: "{userMention}, you do not have permission to use `{command}`!"

  serverStart:
    description: "✅ Server has started!"
    color: "#00FF00"
  serverStop:
    description: "❌ Server has stopped!"
    color: "#FF0000"
  playerJoin:
    description: "➡️ {playerName} joined the server."
    color: "#FFFF00"
  playerLeave:
    description: "⬅️ {playerName} left the server."
    color: "#FFA500"

  discordReplyFormat: " &8(reply: {repliedTo})"

⌨️ Commands & Permissions

Discord Commands:

• ?dclink <code>: Enters the link code on Discord to finalize account pairing.
• ?dcunlink: Unlinks your Discord account.
• ?<command>: Runs a permitted server moderation command (e.g. ?mute Steve 1h spam).