# 🌌 Synix: Ultimate Minecraft-Discord Synchronization Plugin ![mc](https://cdn.modrinth.com/data/cached_images/f58d5e86015c71fa9bc9d418cf61a7c33f8d0b13.png) Synix bridges your Minecraft server (Spigot/Paper) and Discord guild with a secure, feature-rich, high-performance embedded JDA bot. Experience seamless chat bridging, robust in-game and Discord moderation, an advanced item/currency trading system, AuthMe-secured linking flows, and mini-games. Main = 🎰 Integrated Economy Games, Smart Chat Bridge, 🤝 Interactive Peer-to-Peer Trading --- ## 🚀 Key Features * **🎙️ Smart Chat Bridge**: Bi-directional chat with clean Markdown formatting, attachment support, and server status updates. * **🔒 AuthMe Secure Linking**: Account verification via DM with dynamic Captchas and direct AuthMe API validation—no plaintext password storage. * **🤝 Interactive Peer-to-Peer Trading**: Secure trades via private Discord DMs featuring item swaps (supporting NBT, offline inventories) and secure Vault currency transfers using JDA Modals. * **🎰 Integrated Economy Games**: Play Coinflip, Coinflip, Slots, Blackjack, and Lottery with Vault integration and animated slot emojis. * **🛡️ Comprehensive Moderation**: Full punishment synchronizations (`ban`, `tempban`, `mute`, `warn`, `kick`, `jail`) with Discord logs. * **🛏️ Geyser & Floodgate Aware**: Built-in Bedrock player handling and independent account linking. --- ## 🛠️ Step 1: Discord Bot Setup Before installing the plugin, you must register your bot application on the Discord Developer Portal: 1. **Create Application**: * Go to [Discord Developer Portal](https://discord.com/developers/applications). * Click **New Application** at the top right, name it (e.g., `MineSync Bot`), and accept the Terms of Service. ![dc](https://cdn.modrinth.com/data/cached_images/3a74c8392d4fcc05fabaafd85616272b12ac098f_0.webp) 2. **Generate Bot Token**: * Navigate to the **Bot** tab on the left sidebar. * Click **Add Bot** and confirm. * Under **Token**, click __**Reset Token**__ and copy the generated token. **Keep this secret!** 3. **Enable Gateway Intents**: * Scroll down on the **Bot** page to the **Privileged Gateway Intents** section. * **Enable** the following intents (required for commands, linking, and bridging to function): * `PRESENCE INTENT` * `SERVER MEMBERS INTENT` * `MESSAGE CONTENT INTENT` * Click **Save Changes**. ![dc](https://cdn.modrinth.com/data/cached_images/09adebddc74d11a9efa97ddb2ecd6169470dfeba.png) 4. **Generate Invite Link**: * Navigate to the **OAuth2** tab, then select **URL Generator**. * Under **Scopes**, check: * `bot` * `applications.commands` * Under **Bot Permissions**, check: * `Manage Webhooks` (if webhook formatting is enabled) * `Read Messages/View Channels` * `Send Messages` * `Send Messages in Threads` * `Create Public Threads` * `Embed Links` * `Attach Files` * `Read Message History` * `Use External Emojis` * `Add Reactions` * `Manage Messages` (for moderation/cleaning) * Copy the URL at the bottom and open it in a browser to invite the bot to your Discord Server. ![dc](https://cdn.modrinth.com/data/cached_images/41183212cb6229416bdbb60eb5eed34655a47707.png) ![dc](https://cdn.modrinth.com/data/cached_images/f1bab06f1cab9bfac8fd2c5c7b1fef9e18ddb847.png) --- ## 📥 Step 2: Installation 1. Ensure you have **Java 21+** and a **Paper/Spigot 1.20+** server. 2. Install the following required dependency plugins in your `plugins/` directory: * [Vault](https://www.spigotmc.org/resources/vault.34315/) (along with an economy provider like *EssentialsX*) * [AuthMeReloaded](https://www.spigotmc.org/resources/authmereloaded.6269/) (Highly recommended for secure player linking) * [Floodgate / Geyser](https://geysermc.org/) (Optional, if you wish to support Bedrock players) 3. Download or build the latest `synix-0.1.0-SNAPSHOT.jar` and place it into the `plugins/` directory. 4. Start the server once to generate the default configuration files, then stop it. --- ## ⚙️ Step 3: Configuration Guide Open the generated `plugins/Synix/config.yml` and configure the settings. Below is the full breakdown of the configuration options: ```yaml bot: token: "YOUR_DISCORD_BOT_TOKEN_HERE" # Put the token copied from Discord Portal prefix: "!" # Prefix used for text/legacy commands (Guild only) enabled: true # Enable/Disable the entire Discord integration slash-commands: true # Register modern Discord Slash Commands (/link, etc.) status-text: "Watching the server" # The bot's playing/watching status message linked-role-id: "987654321012345678" # (Optional) Role automatically given to linked players chat: channel-id: "123456789012345678" # ID of the text channel for Minecraft <-> Discord bridging mention-filter: true # Replaces Discord @mentions with plain-text on Minecraft allow-attachments: true # Notifies Minecraft players when attachments are sent minecraft-format: "&8[Discord]&r {user}: {message}" # In-game appearance of Discord messages discord-format: "**[{server}]** {user}: {message}" # Discord appearance of in-game chat messages webhook-style-formatting: false # Use webhooks to show custom player avatars in Discord economy: max-bet: 25000 # Maximum bet allowed in blackjack, coinflip, slots, etc. daily-reward: 1000 # Coins awarded daily via /daily enable-gambling: true # Toggle gambling mini-games lottery-multiplier: 4.0 # Payout multiplier for the lottery coinflip-multiplier: 1.95 # Payout multiplier for coinflip slots-jackpot-multiplier: 6.0 # Payout multiplier for hitting a slots jackpot logs: enabled: true # Keep SQLite/MySQL audit logs for in-game activities send-to-discord: true # Direct game logs (joins, linkings, commands) to Discord log channel send-ip: false # Whether to include IP addresses in admin logs (Security Risk) keep-days: 30 # Auto-purge logs older than X days database: type: sqlite # DB Engine: 'sqlite' (local file) or 'mysql' (external) sqlite-file: "minesync.db" mysql: host: localhost port: 3306 name: minesync username: root password: "" ssl: false security: use-verification-code: true code-length: 5 code-expiry-seconds: 300 # Linking code validity duration password-hash: bcrypt max-login-attempts: 5 login-cooldown-seconds: 10 lockout-seconds: 300 session-duration-minutes: 30 captcha-expiry-seconds: 300 allow-bedrock: true # Allow Bedrock players to link via Geyser/Floodgate allow-java: true # Allow Java players to link auth: provider: authme # Account validation engine manage-minecraft-auth: false require-authme-for-linking: true # Ensure players register & log into AuthMe before linking import-authme: false staff: role-ids: ["888888888888888888"] # Discord Role IDs that can run staff-level command suites owner-role-ids: ["777777777777777777"] admin-role-ids: ["666666666666666666"] moderator-role-ids: ["555555555555555555"] log-channel-id: "444444444444444444" # Channel where moderation actions & admin logs are posted verification-channel-id: "" moderation: sync-to-discord: true # Auto-punish Discord user when Minecraft account is banned default-tempban-minutes: 60 # Default fallback duration for tempbans features: whitelist-discord-management: true # Toggle server maintenance mode via /maintenance maintenance-whitelist-bypass-permission: "minesync.maintenance.bypass" ``` Save the file and **restart your server** or run `/synix reload` to apply! --- ## 🔗 Step 4: The Account Linking Flow To verify players, Synix utilizes a secure double-ended verification system that prevents unauthorized linking and protects account passwords. ![dc](https://cdn.modrinth.com/data/cached_images/0eda19e6fea0233a1a3022bab12aaeae1144f90f.png) ![dc](https://cdn.modrinth.com/data/cached_images/5db30fb9bc4b267bb725c51b9a784027acb34394.png) ### Java Players 1. Join the Minecraft server. 2. Log in via AuthMe using `/login `. 3. Type `/link` in-game. A 5-digit verification code will print in-game (expires in 5 minutes). 4. In the Discord Server, use `/link` or type `!link` in a public guild channel. 5. The bot will send you a **Private Message (DM)** containing a dynamic Captcha challenge. 6. Complete the Captcha and enter your **Minecraft Username**, **AuthMe Password**, and **5-digit Code** securely. 7. Once verified, the bot grants you the configured **Linked Role**! ### Bedrock Players (Geyser/Floodgate) 1. Join the server via Geyser. 2. Type `/linkdc` (or `/link`) in-game to obtain your verification code. 3. Use `/link` on the Discord server, select **Bedrock Player**, complete the Captcha, and enter the code to finish. No password required for Bedrock linking if utilizing Floodgate autologin. ![dc](https://cdn.modrinth.com/data/cached_images/2e18b1f6baec4c17a056eacb0377a5044d5fb5a0.png) --- ## 🎮 Command Reference Synix provides matching **In-game (Slash)** commands and **Discord (Slash/Prefix)** commands. Prefix commands do not work in Discord DMs for safety. ### 👥 Player Commands | Minecraft | Discord | Description | | :--- | :--- | :--- | | `/link` | `/link` or `!link` | Starts account linking flow. | | `/unlink` | `/unlink` or `!unlink` | Decouples Discord account from Minecraft account. | | `/profile [player]` | `/profile` or `!profile` | View player profile card featuring Minecraft skin embeds. | | `/bal [player]` | `/bal` or `!bal` | Checks current in-game coin/economy balance. | | `/daily` | `/daily` or `!daily` | Claims daily coin reward. | | `/serverstatus` | `/serverstatus` | Views server TPS, RAM usage, and online time. | | `/players` | `/players` | Lists all online players. | ### 🎰 Gambling & Trade Commands | Command | Options | Description | | :--- | :--- | :--- | | `/coinflip` | ` ` | Flip a coin to double your bet! | | `/blackjack` | `` | Play dynamic Blackjack against the dealer. | | `/slots` | `` | Spin the slots with stunning animated emojis! | | `/lottery` | `` | Purchase lottery tickets for a grand prize draw. | | `/trade` | `[discord_user] [mc_username]` | Initiates an interactive DM-based trade session. | | `/sell` | ` ` | Sell server items directly from inventory for coins. | ### 🛡️ Admin & Moderation Commands *These commands require configured Role IDs in `config.yml` or specific Minecraft OP permissions.* | Minecraft | Discord | Role Required | Description | | :--- | :--- | :--- | :--- | | `/ban ` | `/ban` | Moderator | Permabans player in-game + syncs to Discord. | | `/tempban ` | `/tempban` | Moderator | Tempbans player (e.g. `1d`, `12h`). | | `/mute ` | `/mute` | Moderator | Mutes player in Minecraft chat. | | `/warn ` | `/warn` | Moderator | Warns a player. | | `/kick ` | `/kick` | Moderator | Kicks player from the server. | | `/maintenance ` | `/maintenance` | Admin | Toggles server whitelist mode. | | `/logmc [event]` | `/logmc` | Admin | Queries database logs for auditing. | | `/eco give ` | `/eco give` | Owner | Grants currency to player balance. | | `/giveaway ` | `/giveaway` | Staff | Starts an interactive Discord giveaway. | --- ## 🎨 Emoji Setup for Animated Slots To make the `/slots` or `!slots` games visually stunning, add these custom emojis to your Discord Server. The bot will automatically render them during spins: * `8311skeletonjugglehearts` * `Happy` * `blackfire` * `dogeburger1` * `AS_brow` --- ## 💡 Troubleshooting * **Bot isn't responding in Discord DMs**: Ensure you have enabled **Message Content Intent** and **Server Members Intent** in the Discord Developer Portal under the bot section. Also check if the user has "Allow direct messages from server members" enabled. * **Linking issues**: Make sure the player is registered and logged into **AuthMe** before executing `/link`. * **Chat bridge not working**: Verify that `chat.channel-id` in your `config.yml` is an exact match for your Discord text channel ID. Ensure the bot has `Send Messages` and `Embed Links` permissions in that channel.

ShDevx