Synccord

🇬🇧 English

Synccord is an all-in-one integration plugin that connects your Paper/Spigot server with a Discord guild:

✅ Account linking via codes (MC ↔ Discord) with SQLite storage

🔁 Role sync between Discord roles and LuckPerms groups

💬 Full chat bridge (Minecraft ↔ Discord) + join/leave/death embeds

🧾 Ticket system with buttons, modals, LiteBans hook & transcripts

📊 Live server status embed (TPS, MSPT, players, IPs) with offline detection

👥 Online player list embed that updates automatically

📜 Rule acceptance flow with code word & auto-role

🧩 PlaceholderAPI expansion (synccord_…) for stats, link state & Discord info

⚙️ Everything configurable via config.yml, lang/de.yml, rules.yml

🪲 Debug mode with detailed log messages

📈 bStats support

Features in detail 🔗 Account linking (MC ↔ Discord)

Code-based linking:

On the Minecraft side a code is generated.

On Discord you confirm the code via Slash-/Button flow.

Links are stored in SQLite (linked_users table) – no YAML spam.

Commands:

/dcfind – show linked Discord ID + tag for a Minecraft player

/unlinkdiscord – remove an existing link (Minecraft, admin)

/linkmc … & /unlinkmc … – Discord slash commands to link/unlink from Discord

Placeholders & Lang-keys show link status, last link time, remaining code time, etc.

🎭 RoleSync (Discord ↔ LuckPerms)

Discord → Minecraft:

role-link: in config.yml maps Discord role IDs → LuckPerms groups.

On player join, Synccord looks up the linked Discord member and syncs groups.

Groups are added/removed so that Discord role setup and in-game groups always match.

Extensive debug logs: which role/group combination is checked, added, removed, or unchanged.

Errors (missing guild id / role / member) are localized via lang/de.yml.

(LuckPerms is a hard dependency.)

💬 Chat bridge & Join/Leave/Death embeds

Minecraft → Discord:

All chat messages go into the configured discord.chat-channel-id.

Uses PlaceholderAPI to format player name, prefix, status, etc.

Configurable format in config.yml (chat.format-to-discord).

Discord → Minecraft:

Messages from the configured channel are sent into the Minecraft chat.

Supports placeholder replacement and color codes.

Can block mentions and ignore bot messages.

Join/Leave/Death forwarding:

Randomizable messages for join/leave/death (discord.join-messages, discord.leave-messages, discord.death-messages).

Embedded messages with color and player name.

Features toggleable via features.send-join, features.send-leave, features.send-death.

🧾 Ticket system (Discord-only, but Minecraft-aware)

Multiple ticket types in config.yml under tickets: (e.g. support, entbannung, bugreport, teamapply, vorschlag, kriegsanfrage …)

Each type has:

Name, description, button label

Support roles (supporter_roles)

Ticket category (Discord category ID)

Optional LiteBans hook to attach ban info to unban tickets

A list of questions with max input length (modal form)

Slash command /ticket setup … (Discord) to post ticket panels.

When a ticket is created:

A private ticket channel is created in the configured category.

Supporters get permissions, the user sees only their own ticket.

Transcripts:

On closing a ticket, all messages are collected and uploaded as transcript.txt in the log channel, with an informative embed.

Minecraft integration:

When a staff member joins the server and there are open tickets, they receive an in-game reminder (configurable Lang key).

📊 Live server status embed

Slash command /setup info sends a server info panel to a Discord channel:

TPS, MSPT, uptime

Online player count

Java & Bedrock IP from config

tps-monitor automatically updates the embed every X seconds.

Synccord remembers channel + message ID in a small YAML file and restores them after restart.

If the server is offline, InfoUpdaterOffline replaces the panel with an “offline” embed and a button, so users always see a valid status.

👥 Online player list embed

Separate player list embed:

Shows current online players with rank & aliases (playerlist.rank-aliases).

Config options: show rank, alias, name; line format per player.

Updates automatically on player join / quit.

Stores channel + message ID and reuses them after restart.

📜 Rules & code-word acceptance

File rules.yml holds your server rules in multiple sections.

Discord slash command /setup regel:

Sends the rules into a channel (split into multiple embeds if needed).

Adds a “Accept rules” button that opens a modal with a code word.

If the user enters the correct codeword from config.yml (rules.keyword):

They receive the configured accept role (rules.accept-role-id).

Errors, success, and debug messages are fully localized via Lang.

🧩 PlaceholderAPI: %synccord_*%

Synccord registers a PlaceholderAPI expansion synccord with many placeholders, for example:

Global:

%synccord_tps%, %synccord_mspt%

%synccord_online_count%, %synccord_max_players%

%synccord_uptime%

%synccord_ip_java%, %synccord_ip_bedrock%

%synccord_synccord_version%

%synccord_status_embed_active%, %synccord_playerlist_embed_active%

%synccord_discord_online%, %synccord_linked_online%

%synccord_tickets_open%

Per-player (needs player context & link):

Basic: %synccord_player%, %synccord_uuid%, %synccord_x%, %synccord_y%, %synccord_z%

Link state: %synccord_discord_id%, %synccord_discord_linked%, %synccord_discord_status%

Discord info: %synccord_discord_tag%, %synccord_discord_username%, %synccord_discord_avatar%

Roles: %synccord_discord_roles%, %synccord_role_count%, %synccord_highest_role%

Linking info: %synccord_last_linked%, %synccord_code_expire%, %synccord_sync_fail_reason%

Tickets: %synccord_tickets_user%, %synccord_ticket_support_role%, %synccord_last_ticket_time%

Perfect for Scoreboards, MOTDs, TAB, or other chat plugins.

🛠 Language, debug & metrics

All user-visible text is in lang/de.yml:

Normal messages, error messages, debug logs, ticket texts, rule messages, etc.

Missing keys get a clear “missing key” message so you can fix them.

debug: true in config.yml enables very detailed debug logging:

Linking, Slash commands, role sync, tickets, embeds, Playerlist, InfoUpdater, etc.

bStats is integrated (ID is configured in the plugin) to provide anonymous statistics.

📦 Requirements

Server: Paper / Purpur / Spigot (tested with 1.21)

Java: modern LTS (e.g. Java 17+; plugin is built for Java 21)

Dependencies:

Required: LuckPerms

Optional but supported:

LiteBans – for unban ticket integration

PlaceholderAPI – for placeholders & chat formatting

🇩🇪 Deutsch

Synccord ist ein umfangreiches Discord-↔-Minecraft-Plugin:

✅ Account-Verknüpfung (MC ↔ Discord) mit Codes & SQLite

🔁 Rollen-Sync zwischen Discord-Rollen und LuckPerms-Gruppen

💬 Chat-Bridge (Minecraft ↔ Discord) inkl. Join/Leave/Tod-Embeds

🧾 Ticketsystem mit Buttons, Modals, LiteBans-Anbindung & Transkript

📊 Serverstatus-Embed (TPS, MSPT, Spieler, IPs) mit Offline-Erkennung

👥 Spielerliste-Embed, das sich automatisch aktualisiert

📜 Regel-System mit Codewort-Abfrage & Auto-Rolle

🧩 PlaceholderAPI-Expansion (synccord_…) für Stats, Linkstatus & Discord-Infos

⚙️ Voll konfigurierbar über config.yml, lang/de.yml, rules.yml

🪲 Debug-Modus mit ausführlichen Logs

📈 bStats-Unterstützung

Funktionsübersicht 🔗 Account-Verknüpfung (Minecraft ↔ Discord)

Spieler erhalten im Minecraft einen Code, den sie auf Discord bestätigen.

Die Verknüpfung wird in einer SQLite-Datenbank gespeichert – dauerhaft und sauber.

Befehle:

/dcfind – zeigt die verknüpfte Discord-ID + Tag eines Spielers

/unlinkdiscord – entfernt eine Verknüpfung (Minecraft, Admin)

/linkmc … / /unlinkmc … – Slash-Commands auf Discord

Placeholders & Langtexte liefern Infos zu Linkstatus, letztem Link, Restlaufzeit des Codes usw.

🎭 Rollen-Synchronisation

Discord → Minecraft (LuckPerms):

In config.yml unter role-link: werden Discord-Rollen-IDs → LuckPerms-Gruppen gemappt.

Beim Join eines verknüpften Spielers werden die Gruppen in LuckPerms angepasst.

Gruppen werden hinzugefügt/entfernt, bis sie zu den vorhandenen Discord-Rollen passen.

Umfangreiche Debug-Ausgaben: welche Rolle/Gruppe geprüft, hinzugefügt, entfernt oder ignoriert wurde.

Fehler (fehlende Guild-ID, Rolle, Member) laufen komplett über die Sprachdatei.

💬 Chat-Bridge & Join/Leave/Tod

Minecraft → Discord:

Chat aus Minecraft geht in den konfigurierten Discord-Channel (discord.chat-channel-id).

PlaceholderAPI kann benutzt werden, um Namen, Prefix, Status usw. einzubauen.

Format konfigurierbar in config.yml (chat.format-to-discord).

Discord → Minecraft:

Nachrichten aus dem Chat-Channel werden in Minecraft angezeigt.

Mentions können geblockt werden, Bots ignoriert werden.

Join/Leave/Tod-Weiterleitung:

Zufällige Join-/Leave-/Death-Texte (discord.join-messages, discord.leave-messages, discord.death-messages).

Darstellung als Embed mit Farbe & Spielernamen.

Über features.send-join, features.send-leave, features.send-death einzeln deaktivierbar.

🧾 Ticketsystem

Tickets werden komplett über Discord erstellt, sind aber Minecraft-aware.

Mehrere Tickettypen unter tickets: in config.yml:

z. B. support, entbannung, bugreport, teamapply, vorschlag, kriegsanfrage …

Pro Typ:

Name, Beschreibung, Button-Text

Supporter-Rollen (supporter_roles)

Ticket-Kategorie (Channel-Kategorie)

Optional LiteBans-Hook (z. B. für Entbannungs-Tickets)

Fragen mit maximaler Zeichenzahl (Modal-Formular)

Slash-Command /ticket setup … zum Posten der Ticket-Embeds.

Beim Erstellen:

Private Ticket-Channel mit passenden Rechten für User & Supporter.

Transkript:

Beim Schließen werden alle Nachrichten gesammelt, als transcript.txt in den Logchannel geladen + Embed mit Metadaten.

Minecraft-Integration:

Join-Hinweis im Spiel, wenn offene Tickets existieren (für berechtigte Spieler).

📊 Live-Serverstatus

/setup info postet einen Status-Embed:

TPS, MSPT, Uptime

Spieleranzahl

Java- & Bedrock-IP aus der Config

tps-monitor aktualisiert den Embed automatisch in einem Intervall.

Synccord speichert Channel + Message-ID und belebt alles nach einem Restart wieder.

Wenn der Server nicht erreichbar ist, wird ein Offline-Embed gesendet, sodass der Status nie “veraltet” wirkt.

👥 Spielerliste-Embed

Eigenes Playerlist-Panel:

Zeigt alle online Spieler mit Gruppe und Alias (playerlist.rank-aliases).

Anzeige pro Spieler über ein Format ({alias} {name} etc.) definierbar.

Wird bei Join/Quit automatisch aktualisiert.

Channel + Nachricht werden persistent gespeichert und nach Neustart wiederverwendet.

📜 Regeln & Codewort-System

rules.yml enthält deine Serverregeln in Kategorien.

/setup regel auf Discord:

Postet die Regeln als mehrere Embeds.

Fügt einen Button hinzu, der ein Modal mit Codewort-Eingabe öffnet.

Korrektes Codewort (rules.keyword):

Benutzer bekommt die definierte Rolle (rules.accept-role-id).

Alle Texte (Fehler, Erfolg, Debug) laufen über lang/de.yml.

🧩 PlaceholderAPI-Expansion synccord

Synccord bringt eine große Anzahl an Placeholders mit:

Global:

%synccord_tps%, %synccord_mspt%

%synccord_online_count%, %synccord_max_players%

%synccord_uptime%

%synccord_ip_java%, %synccord_ip_bedrock%

%synccord_synccord_version%

%synccord_status_embed_active%, %synccord_playerlist_embed_active%

%synccord_discord_online%, %synccord_linked_online%

%synccord_tickets_open%

Spielerbezogen:

Basis: %synccord_player%, %synccord_uuid%, %synccord_x%, %synccord_y%, %synccord_z%

Link: %synccord_discord_id%, %synccord_discord_linked%, %synccord_discord_status%

Discord-Infos: %synccord_discord_tag%, %synccord_discord_username%, %synccord_discord_avatar%

Rollen: %synccord_discord_roles%, %synccord_role_count%, %synccord_highest_role%

Linking: %synccord_last_linked%, %synccord_code_expire%, %synccord_sync_fail_reason%

Tickets: %synccord_tickets_user%, %synccord_ticket_support_role%, %synccord_last_ticket_time%

Ideal für Scoreboards, TAB, Chat-Plugins, MOTD usw.

🛠 Sprache, Debug & Statistiken

Alle Texte im Plugin sind über lang/de.yml anpassbar.

Fehlende Keys werden klar gekennzeichnet, damit du sie schnell ergänzen kannst.

debug: true in der Config aktiviert umfangreiche Debug-Ausgaben für:

Linking, RoleSync, Ticketsystem, Status-Panel, Playerlist, Chat-Bridge usw.

bStats ist integriert.

📦 Voraussetzungen

Server: Paper / Purpur / Spigot (getestet mit 1.21)

Java: moderne Java-Version (empfohlen: Java 17+ / 21)

Abhängigkeiten:

Pflicht: LuckPerms

Optional: LiteBans, PlaceholderAPI