modl

# modl – support & moderation reimagined
Streamline administrative duties with AI, dynamic punishments, and a slick web-interface.

### Description
modl is a modern solution to completely streamline moderation and support for your Minecraft server. The system is fully customizable, free to use, and open-sourced under the AGPL-3.0 license. Stay in control of your server from anywhere with our web-interface at https://modl.gg. Use AI to automatically handle chat reports. Simplify punishments through dynamic punishment types powered by points and severities.

**Free forever** and completely branded for your server – your players and staff will not see any modl.gg branding (assuming you enable custom domain).

modl can run natively on **Spigot, PaperSpigot, Folia, BungeeCord, and Velocity**, without feature degradation on any platform.

[Fully free & source repositories](http://github.com/modl-gg) | [Support Discord Server](https://modl.gg/discord) | [Locale File](https://github.com/modl-gg/minecraft/blob/main/core/src/main/resources/locale/en_US.yml) | [Config File](https://github.com/modl-gg/minecraft/blob/main/core/src/main/resources/config.yml)

## Features
#### 3rd Iteration Punishment System
Designed to fairly and consistently sanction players whilst maintaining moderator discretion.

– Fully customizable **point system** to designate low, medium, and habitual designations for both Gameplay and Social offenses
– Fully customizable punishment durations for each **severity** (lenient, normal, severe) and each **offender status** (low, medium, habitual)
– Issue punishments for bad usernames and skins that **automatically pardon** when a player changes his/her skin/username.
– Ability to make a ban “stat-wiping” that issues a command on the server upon _expiration_ to reset stats (not executed when pardoned or cancelled)
– Full modification system for **changing durations** and **pardoning** (remove points)
– Full evidence system for **uploading files** and linking to other sites (YouTube, Imgur, etc)
– 8-char alphanumeric ID system for streamlined appeal system, staff see all punishment details and can pardon/change duration without leaving the page. **Customize** the appeal page for each different punishment type
– Bans on offline players wait until a successful login to start the expiration countdown.
– Stack multiple bans/mute that execute **consecutively** (one after the other becomes inactive) – start time is when the player attempts to login unimpeded by other bans/mutes.
– Traditional, manual punishments also exist (ban, tempban, mute, tempmute, kick, blacklist)
– Import all bans, mutes, and player data (IPs) from **LiteBans** seamlessly

![Punish GUI gif](https://i.imgur.com/jOJAeO2.gif)
![Image 8](https://cdn.modl.gg/assets/modl-image-8.png)

#### Full Player Profiles and Smart Alt-account Linking

– See player info (playtime, session details, country), notes, history, alts, reports in sleek in-game and web UIs (windows for many open players on web).
– **Link accounts** that have the same non-proxy IP logins OR have the shared proxy logins within 2 hours of each other. This system tracks logins even if denied by a banned screen, allowing you to link accounts whenever a **bad actor** screws up and attempts to login on a banned account (to check) before logging into their ban evading account.
– Handle each linked ban **independently**- was there a mistake? Public internet or sibling? Easily handle the linked ban on a specific account without changing the initial ban.
– Linked bans expire when the original ban expire automatically.

![Inspect GUI gif](https://i.imgur.com/4Qmt2wt.gif)
![Image 9](https://cdn.modl.gg/assets/modl-image-9.png)

#### Elegant, Efficient Player Reporting

– Automatically **snapshot** full context chat-logs when someone is chat-reported.
– Allow players to **upload files** or link external evidence to all reports.
– Issue punishments from reports without leaving the ticket page.
– Link tickets to punishments that will auto-close the ticket and send a response letting the reporter know the offender was punished. Also can be used as evidence when hooked up to [modl-anticheat-bridge](https://github.com/modl-gg/minecraft-anticheat-bridge/releases) (Anti-cheat automatically creates reports based on flags)
– You can sort online players by number of reports to identify potential rule breakers across your network.

![Report GUI gif](https://i.imgur.com/ODXHpjC.gif)
![Image 10](https://cdn.modl.gg/assets/modl-image-10.png)

#### Full Audit and Analytics System

– Audit and **rollback** any staff punishment actions.
– See statistics on average ticket response times and **staff activity** (ticket responses, punishments issued, etc)
– See **trends** for different types of punishments and ticket data.
– Manage all files uploaded (evidence, ticket attachments): easily view, search, filter, delete, and download all files.

![Staff GUI gif](https://i.imgur.com/gj49NbH.gif)
![Image 6](https://cdn.modl.gg/assets/modl-image-6.png)

#### Smart AI Chat Moderation

– To not pester players and use excessive tokens, AI chat moderation **only scans messages that are chat-reported**. This is the most effective way of moderating chat as current systems that analyse all messages issuing auto-mutes are incredibly annoying for players and expensive.
– Constantly evolving system prompts to improve **accuracy** of AI auto-mod, is context-aware of Minecraft (e.g: “i’m going to kill you with a fireball” is a game term, not an IRL death threat).
– Configure AI to look for specific things and execute punishments **automatically** or make suggestions for staff approval.

![Image 11](https://cdn.modl.gg/assets/modl-image-11.png)

#### Support One-Stop-Shop: Use **your own domain** (recommended: support.yourserver.com)

– **Fully customizable** knowledgebase homepage with logo, external link, and sections
– Searchable markdown article support, write **your** rules, guidelines, and support articles with ease.
– Create fully **custom forms** for bug reports, support tickets, and staff applications: reveal hidden sections based on answer to multiple-choice questions.
– Customizable **quick-response buttons** to significantly streamline efficiency and keep responses consistent.
– Send in-game and email **notifications** for when staff respond to a player’s ticket.
– We use browser cookies to verify that responses in tickets are the same as the initial responder.
– Staff members are automatically **subscribed** to tickets they respond in and can easily track updates to those tickets in their home feed.

![Image 7](https://cdn.modl.gg/assets/modl-image-7.png)

#### Professional Interface

– Invite your staff team and fully customize their **roles** and permissions (permission nodes for each punishment type)
– Set each staff member’s Minecraft account so that permissions and punishments are **synced** between panel and in-game.
– Make modl yours: upload a custom logo, favicon, homepage image, and set your custom domain.
– Everything is fully **customizable**, from Minecraft plugin locale to ticket forms and punishment types.

![Image 2](https://cdn.modl.gg/assets/modl-image-2.png)

### Requirements
1. Java 8+
2. Working internet connection
3. Any version Spigot, PaperSpigot, Folia, BungeeCord, or Velocity

### Installation
1. Register your server at https://modl.gg
2. Go to your panel’s settings and find your API key under “Server & Billing” **>** “Server Config”.
3. Drop **modl-(version).jar** into your /plugins directory (Install on all Spigot servers and your proxy if you run a network. Run Spigot modl instances in bridge mode if so.)
4. Restart your server and wait for **/plugins/modl/config.yml** to generate, once it does input your API key and panel URL then restart
5. Done!

**Showcase & Installation Video (outdated – view docs installation guide):**

**Requirements & Installation Steps:**
https://docs.modl.gg/installation

**For support, please join our [discord server](https://modl.gg/discord) or open an [issue on GitHub](https://github.com/modl-gg/issue-tracker/issues). If you encounter any issues or bugs, please report them :)**

MiraiMC

[![GitHub release](https://img.shields.io/github/v/release/DreamVoid/MiraiMC?style=flat-square
)](https://github.com/DreamVoid/MiraiMC/releases/latest)
[![CodeFactor](https://www.codefactor.io/Content/badges/A.svg)](https://www.codefactor.io/repository/github/dreamvoid/miraimc)
[![GitHub Actions CI](https://img.shields.io/github/actions/workflow/status/DreamVoid/MiraiMC/maven.yml?style=flat-square)](https://github.com/DreamVoid/MiraiMC/actions/workflows/maven.yml?query=is%3Asuccess)
![GitHub all releases](https://img.shields.io/github/downloads/DreamVoid/MiraiMC/total?style=flat-square)

—

MiraiMC is a [mirai](https://github.com/mamoe/mirai) bot for Minecraft servers
> Mirai is a high-performance multi-platform library, as well as a framework, providing protocol support for Tencent QQ.
> Mirai is designed to handle all sorts of messaging works that can be automatically done by bots in a perfect way.
> Tencent QQ: A modern messaging software used by all Chinese netizens.

## Features
* Support Bukkit/Sponge servers.
* Support BungeeCord/Velocity proxies.
* Optimized for GUI-less OS such as Linux
* Dynamically load dependent libraries to minimize file size.

## Getting Started (Server)
1. Download MiraiMC from “Featured versions” part. Then install it like installing other plugins.
2. Configure any plugins’ that depend on MiraiMC (if any) and login to your bot account

A more detailed tutorial can be found here: https://docs.miraimc.dreamvoid.me/

## Getting Started (Plugin Developer)
* It is simple to develop a new MiriMC-based plugin by using template:
– [Maven](https://github.com/MiraiMC/MiraiMC-Template)
– [Gradle KotlinDSL](https://github.com/MiraiMC/MiraiMC-Template-Gradle-KotlinDSL)
* MiraiMC javadoc here: https://jd.miraimc.dreamvoid.me
* Detailed development tutorial here: https://docs.miraimc.dreamvoid.me/

### Dependency
#### Maven
“`

io.github.dreamvoid
MiraiMC-Integration
1.9
provided

“`

#### Gradle
“`
implementation ‘io.github.dreamvoid:MiraiMC-Integration:1.9’
“`

## LICENSE

[GNU Affero General Public License v3.0](https://github.com/DreamVoid/MiraiMC/blob/main/LICENSE)

## Acknowledgments

Thanks to the following people/teams/projects for their contributions to MiraiMC!

* [mamoe/mirai](https://github.com/mamoe/mirai): Powerful QQ robot support library, the core and foundation of MiraiMC.
* [lucko/helper](https://github.com/lucko/helper): Provide MiraiMC with a solution to dynamically load the mirai core.
* [brettwooldridge/HikariCP](https://github.com/brettwooldridge/HikariCP): An efficient SQL connection pool, providing database connection solutions for MiraiMC.
* [LT_Name](https://github.com/lt-name): Optimized a lot of Nukkit code for MiraiMC, also provided a lot of help for MiraiMC.
* You.

[DreamVoid](https://github.com/DreamVoid) and [MiraiMC](https://github.com/MiraiMC), made with ❤.

This file is a translated version of the [original file](https://github.com/DreamVoid/MiraiMC/blob/main/README.md), and some semantics may differ from the original file.

MiniMOTD

![MiniMOTD logo](https://i.imgur.com/CXWwjOJ.png)

### MiniMOTD is a basic server list MOTD plugin/mod for Minecraft servers and proxies

– MiniMOTD supports RGB colors and gradients through [MiniMessage](https://github.com/KyoriPowered/adventure-text-minimessage), which is also where MiniMOTD gets it’s name.
– For more detailed info on formatting text, refer to the [MiniMessage docs](https://docs.adventure.kyori.net/minimessage.html).
– RGB colors are automatically downsampled for outdated clients.
– Requires [Fabric API](https://modrinth.com/mod/fabric-api)

#### Downloads
Downloads can be obtained from [GitHub releases](https://github.com/jpenilla/MiniMOTD/releases). There is a separate jar for each platform, as well as a universal jar for all platforms. Paper and Spigot share the same jar, as do Waterfall and Bungeecord.

#### Configuration
See the [wiki](https://github.com/jpenilla/MiniMOTD/wiki) for configuration details

#### Screenshots
![demo motd image](https://i.ibb.co/1LRCV8b/minimotd-demo.png)

Minecraft Server Management Protocol Legacy Support

# Minecraft Server Management Protocol Legacy Support

Adds a Minecraft Server Management Protocol endpoint to server software that does not provide Mojang’s native implementation.

The Minecraft Server Management Protocol is the newer management API for Minecraft servers. It exposes server information and management actions through JSON-RPC over WebSocket, instead of relying on older mechanisms such as server-list ping or RCON. This plugin brings that protocol shape to older server versions and proxy environments so external tools can speak one management protocol across mixed infrastructure.

## What it provides

– A WebSocket endpoint for Minecraft Server Management Protocol clients.
– JSON-RPC request and response handling compatible with the protocol model documented on the Minecraft Wiki.
– Discovery through `rpc.discover`, so clients can inspect which methods are available.
– Server/proxy status support, including online player list and version information.
– Management operations for Bukkit-based servers, including players, allowlist, bans, operators, selected server settings, gamerules, save, stop, and system messages.
– Proxy management operations for Velocity and BungeeCord, including players, kick, status, stop, and system messages.
– Authentication by shared secret, with browser-origin checks for WebSocket subprotocol authentication.
– Optional TLS using a PKCS12 keystore.

Reference: https://minecraft.wiki/w/Minecraft_Server_Management_Protocol

## Platform Status

For legacy SpaceChunks usage, install the Spigot/Paper build on the backend server when you need live server status and online player counts from old Minecraft versions.

## Supported Methods

| Method group | Spigot / Paper | Velocity | BungeeCord |
| — | — | — | — |
| `rpc.discover` | yes | yes | yes |
| `minecraft:players` | yes | yes | yes |
| `minecraft:players/kick` | yes | yes | yes |
| `minecraft:server/status` | yes | yes, proxy status | yes, proxy status |
| `minecraft:server/stop` | yes | yes, stops proxy | yes, stops proxy |
| `minecraft:server/system_message` | yes | yes, proxy players | yes, proxy players |
| `minecraft:server/save` | yes | no | no |
| `minecraft:allowlist/*` | yes | no | no |
| `minecraft:bans/*` | yes | no | no |
| `minecraft:ip_bans/*` | yes | no | no |
| `minecraft:operators/*` | yes | no | no |
| `minecraft:serversettings/*` | partial | no | no |
| `minecraft:gamerules/*` | yes | no | no |

Spigot/Paper server settings are limited to APIs available through the Spigot 1.8.8 API. Implemented settings are `autosave`, `difficulty`, `use_allowlist`, `player_idle_timeout`, `allow_flight` read-only, `motd` read-only, `spawn_protection_radius`, `game_mode`, and `view_distance` read-only.

## Supported Notifications

| Notification group | Spigot / Paper | Velocity | BungeeCord |
| — | — | — | — |
| `minecraft:notification/server/started` | yes | yes | yes |
| `minecraft:notification/server/stopping` | yes | yes | yes |
| `minecraft:notification/server/status` | yes | yes | yes |
| `minecraft:notification/server/activity` | yes | yes | yes |
| `minecraft:notification/players/joined` | yes | yes | yes |
| `minecraft:notification/players/left` | yes | yes | yes |
| `minecraft:notification/server/saving` | yes | no | no |
| `minecraft:notification/server/saved` | yes | no | no |
| `minecraft:notification/allowlist/*` | management API changes only | no | no |
| `minecraft:notification/bans/*` | management API changes only | no | no |
| `minecraft:notification/ip_bans/*` | management API changes only | no | no |
| `minecraft:notification/operators/*` | management API changes only | no | no |
| `minecraft:notification/gamerules/*` | management API changes only | no | no |

## Configuration

The service is disabled by default. Enable it only after setting a secret and deciding where it should listen.

Spigot/Paper uses `plugins/MinecraftServerManagementProtocolLegacySupport/config.yml`:

“`yaml
management-server-enabled: true
management-server-host: localhost
management-server-port: 25585
management-server-secret: ‘replaceWithExactly40AlphaNumericCharacters’
management-server-allowed-origins: ”
management-server-tls-enabled: false
management-server-tls-keystore: ”
management-server-tls-keystore-password: ”
“`

Velocity and BungeeCord create `management-server.properties` in the plugin data folder with the same setting names.

### Settings

– `management-server-enabled`: Starts or disables the management endpoint.
– `management-server-host`: Interface to bind. Use `localhost` when only local tooling or a reverse proxy should connect.
– `management-server-port`: Port for the WebSocket server. Use a fixed port for production.
– `management-server-secret`: Required shared secret. It must be exactly 40 alphanumeric characters.
– `management-server-allowed-origins`: Comma-separated list of allowed browser origins when authenticating through `Sec-WebSocket-Protocol`.
– `management-server-tls-enabled`: Enables `wss://`. Requires a valid keystore.
– `management-server-tls-keystore`: Path to a PKCS12 keystore.
– `management-server-tls-keystore-password`: Keystore password. It can also be supplied through `MINECRAFT_MANAGEMENT_TLS_KEYSTORE_PASSWORD` or the JVM property `management.tls.keystore.password`.

## License

Licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE).

MineCord Link

# MineCord Link

MineCord Link is a Minecraft plugin that links your Minecraft server to Discord, enabling seamless communication between the two platforms.

## Features

– Connect your Minecraft server chat with a Discord channel
– Send Minecraft server events to Discord:
– Player join/leave notifications
– Player death messages
– Player advancement achievements
– Execute Minecraft commands from Discord
– Share player coordinates between Minecraft and Discord
– Automatic plugin updates
– Cross-chat toggle to enable/disable chat synchronization
– Display online players list in Discord
– Server start/stop notifications in Discord
– Customizable bot activity status
– Link Minecraft and Discord accounts

## Commands

### Minecraft Commands
– `/mcl reload` – Reloads the plugin configuration (requires `minecordlink.reload` permission)
– `/mclcoords [location name]` – Share your current coordinates in the game and Discord
– `/mcllinkdiscord [code]` – Generate or enter a code to link your Minecraft account to Discord
– `/mcltogglelistener ` – Toggle individual listeners on or off (requires `minecordlink.togglelistener` permission)

### Discord Commands
– `/ping` – Responds with “Pong!” to check if the bot is active
– `/admin ` – Executes a Minecraft server command (only for authorized users)
– `/setup` – Sets up the bot for the current server and channel (requires Discord Administrator permission)
– `/players` – Displays a list of online players
– `/crosschat` – Toggles the crosschat feature on or off (only for authorized users)
– `/linkminecraft [code]` – Link your Discord account to your Minecraft account or generate a link code

MineAds Monitor

# MineAds Monitor Plugin

We at MineAds provide this plugin to help Minecraft server owners integrate their servers with our analytics platform. It automatically tracks server activity like player joins, leaves, chat, and commands, then sends this data to us for analysis.

## What We Use It For

As a server analytics platform, we collect data from servers that sign up their networks with us. We use this information to provide detailed analytics to server owners, helping them understand player behavior, optimize their servers, and improve their community’s experience. This data also helps us enhance our platform’s insights.

## Setup Instructions

1. Download the plugin JAR file that matches your server type (Bukkit/Spigot/Paper, BungeeCord, or Velocity).
2. Place the JAR in your server’s plugins folder.
3. Restart your server to generate the config file.
4. Open the `config.yml` file in your plugins/MineAdsMonitor folder.
5. Add your unique plugin key from the MineAds dashboard (it starts with “pluginkey_”).
6. Set a server ID like “survival-main” to identify this server.
7. Save the file and restart the server again.

## Configuration Options

The plugin uses a simple YAML format for its settings. Here’s what each option does:

– **pluginKey**: Your special key from MineAds that links your server to their system. You get this from their website.
– **serverId**: A name for your server, like “creative-hub” or “pvp-arena”, using only letters, numbers, and dashes.
– **enabledEvents**: Choose which types of player activities to track. By default, it tracks everything: purchases, chat, commands, joins, and leaves.
– **disableChatContent**: Turn this on if you don’t want the actual words players type in chat to be sent (only that they chatted).
– **defaultMaxCommandArgs**: How many parts of a command to record. For example, “/warp home” would save 1 part (just “warp”) by default.
– **commandArgLimits**: Set different limits for specific commands, like allowing more details for “/warp” commands.
– **debug**: Turn this on to see extra messages in the server console for troubleshooting.

## Commands

The plugin includes commands for server admins (you need the “mineadsmonitor.admin” permission):

– **/mineadsmonitor help**: Shows all available commands.
– **/mineadsmonitor version**: Tells you what version of the plugin you’re running.
– **/mineadsmonitor reload**: Reloads the config file without restarting the server.
– **/mineadsmonitor initial/expiry/renewal/chargeback/refund** [details]: Manually record purchase-related events (like when someone buys or loses a rank).

## Performance and Lag Prevention

To keep your server running smoothly, the plugin is designed to be very lightweight:

– It collects data in the background without slowing down gameplay.
– Instead of sending data immediately, it groups events together and sends them in batches every 10 seconds.
– All network requests happen on separate threads, so they never interrupt your server’s main operations.
– Data is compressed before sending to use less bandwidth.
– If there are connection problems, it automatically retries with smart delays to avoid overwhelming your server.

mclo.gs

Server Plugin/Mod

A mod/plugin to easily share and analyse your server logs with mclo.gs

## About mclo.gs

mclo.gs allows you to quickly share and analyze logs for Minecraft servers and clients. It highlights different log levels, removes sensitive information like IP-Addresses and detects common problems as well as version information.

## Features
– Upload server logs with a single command
– Share logs with a short url
– Automatic on-device removal of sensitive information like IP addresses and system usernames
– Uploading other logs and reports
– Deleting uploaded logs

## Commands

The Plugin/Mod contains the following commands:

For special cases, the following commands are available:

### Permissions

Commands are not available to players by default. You can give players access to the commands by giving them the
required permissions. Plugin servers permissions use permission nodes for fine-grained access control. The `mclogs`
permission node is required for all other commands as well.

Modded servers use the Vanilla permission level system instead.

## Configuration
If you use a self-hosted instance of mclo.gs or want to use an alternative front-end, you can configure the plugin/mod to use your instance.
The config file is located in `plugins/mclogs/config.toml` for plugin servers and `config/mclogs.toml` for modded servers.

### Default configuration
“`toml
# Base URL for the API used to upload logs
apiBaseUrl = “https://api.mclo.gs”
“`

## Requirements
This project requires Java 11 or higher to run, even on Minecraft versions that run on Java 8.

MCKotlin

# MCKotlin
[![WorkFlow](https://img.shields.io/github/actions/workflow/status/4drian3d/MCKotlin/gradle.yml?style=flat-square)](https://github.com/MCKotlin/MCKotlin/actions)
[![Latest Version](https://img.shields.io/github/v/release/4drian3d/MCKotlin?style=flat-square)](https://modrinth.com/plugin/mckotlin)
[![Discord](https://img.shields.io/discord/899740810956910683?color=7289da&logo=Discord&label=Discord&style=flat-square)](https://discord.gg/5NMMzK5mAn)
[![Modrinth Downloads](https://img.shields.io/modrinth/dt/1iWA0pjH?logo=Modrinth&style=flat-square)](https://modrinth.com/plugin/mckotlin)
[![GitHub Downloads](https://img.shields.io/github/downloads/4drian3d/MCKotlin/total?logo=GitHub&style=flat-square)](https://github.com/4drian3d/MCKotlin/releases)

Get the ability to run and develop Kotlin plugins on your Minecraft server or proxy.

This plugin includes the necessary Kotlin libraries to the server to avoid including them independently in several plugins at the same time

[![](https://www.bisecthosting.com/partners/custom-banners/6fa909d5-ad2b-42c2-a7ec-1c51f8b6384f.webp)](https://www.bisecthosting.com/4drian3d?r=ModMCKotlin)

## Requirements
– Java 8+

## Compatibility
– Velocity 3+
– Sponge 8
– CraftBukkit/Spigot/Paper/forks 1.8+
– BungeeCord/Waterfall

## How to use

### Server Admin
Simply install the latest version of the plugin on your server or proxy

### Developers
Add MCKotlin as a dependency

#### Spigot

**plugin.yml**
“`yaml
depend: MCKotlin-Paper
“`

#### Paper 1.19.4+

**paper-plugin.yml**
“`yaml
dependencies:
server:
MCKotlin-Paper:
required: true
“`

#### Velocity

“`java
@Plugin(
id = “myplugin”,
dependencies = {
@Dependency(id = “mckotlin-velocity”)
}
)
public class VelocityPlugin {}
“`

## Libraries included
– Kotlin StdLib 1.9.20
– Kotlin Reflect 1.9.20
– KotlinX Coroutines

### How does this plugin differ from other plugins such as [Kotlin](https://modrinth.com/plugin/kotlin)?
Unfortunately there are no plugins available that provide the necessary libraries to make kotlin plugins for environments like Velocity or Bungeecord. That was my motivation to develop this plugin that includes Kotlin-stlib 1.9.0 (created by Jetbrains, Apache 2 license)

MC-Data-Bridge

# MC Data Bridge

MC Data Bridge is a robust, high-performance hybrid plugin for PaperMC (Spigot), **Folia**, BungeeCord, and Velocity. It is designed to seamlessly synchronize player data across multiple Minecraft servers, ensuring that players have a consistent experience by retaining their health, hunger, experience, inventory, **Ender Chests, Advancements, Statistics, and Persistent Data** as they move between linked servers.

## Compatibility

* **Minecraft Version:** `1.21.x` and `26.1.x`
* **Server Platforms:** PaperMC (Purpur), **Folia**, Spigot
* **Proxy Platforms:** BungeeCord, Waterfall, Velocity
* **Java Version:** 25+

This plugin is a hybrid build and the same JAR file works on all supported platforms, automatically activating the correct functionality for each platform.

## Features

* **Hybrid Plugin:** A single JAR file works on your PaperMC/Spigot/Folia servers and your BungeeCord/Velocity proxy.
* **SHA-256 Data Integrity:** Implements cryptographic checksums with server-side salting to detect and prevent manual database tampering or corruption.
* **Industrial Identity Protection:** Tracks `last_known_name` and secure identity hashes to prevent identity hijacking and manage UUID transitions in hybrid (Cracked/Premium) environments.
* **Zero-Tick Identity Verification:** Database locks and identity checks are performed during the `AsyncPlayerPreLoginEvent`, ensuring that player state is verified and ready before they even reach the server’s “Join” state.
* **Regionalized Folia Support:** Built with `SchedulerUtils` to handle regionalized threading, ensuring safe execution on Folia’s multi-threaded clusters.
* **Administrative Inspector GUI (NEW):** A visual interface for administrators to inspect saved player data (inventories, stats, PDC) even when the player is offline.
* **Proxy-Initiated Saves:** The proxy (BungeeCord/Velocity) orchestrates the data saving process, ensuring that a player’s data is saved from their source server *before* they connect to the destination server. This eliminates race conditions.
* **Fully Asynchronous:** All database and serialization operations are performed on a separate thread, ensuring that your server’s main thread is never blocked.
* **Robust Locking Mechanism:** A database-level locking mechanism with an automatic timeout and heartbeats prevents data corruption.
* **Version-Independent Item Serialization:** Player inventories are serialized using native binary methods (Paper/Folia) or NBT-API fallback (Spigot), ensuring 100% integrity across updates.
* **Cross-Server Player Data Sync (Granular Control):**
* Health (Attribute-aware)
* Food Level, Saturation, & **Exhaustion**
* Experience (Total XP, current XP, and Level)
* Inventory & Armor Contents
* Active Potion Effects
* **Ender Chest Contents**
* **Advancements & Recipes**
* **Player Statistics** (Vanilla stats)
* **Persistent Data Container (PDC)** (Custom metadata)
* **Flight & GameMode** status
* **Resilient Connection Pooling:** Uses HikariCP with optimized settings for resilience against network jitter.
* **Flexible Storage:** Support for **MySQL/MariaDB** or local **SQLite** databases.
* **Granular Sync Control**: Enable or disable synchronization for any specific data type via `config.yml`.
* **Server/World Blacklist**: Prevent synchronization on specific servers or worlds.

## Installation

1. **Download the Plugin JAR:**
* Download the latest release JAR (`mc-data-bridge-*.jar`) from this page (Modrinth) or the official GitHub Releases.
2. **Deploy to Servers:**
* Copy the single `mc-data-bridge-*.jar` file into the `plugins/` folder of **each PaperMC/Folia server** you wish to synchronize.
* Copy the **same JAR file** into the `plugins/` folder of your **BungeeCord or Velocity proxy server**.
3. **Optional: Manual Build (For Developers)**
* To build from source, clone the repository and run `mvn clean package`.

## Commands & Permissions

**Proxy Commands:**
– `/databridge unlock ` (Bungee/Velocity): Releases a lock across the network.
– `/databridge forceunlock ` (Bungee/Velocity): Relays a signal to the backend server to drop the lock immediately.

## Configuration

A `config.yml` file will be generated in the `plugins/mc-data-bridge/` folder after the first run. **Existing configs will be safely auto-updated.**

“`yaml
# Database Configuration
database:
type: mysql # “mysql” or “sqlite”
host: localhost
port: 3306
database: minecraft
username: user
password: password
sqlite-file: “player_data.db”

# A list of JDBC properties to apply.
properties:
useSSL: false
allowPublicKeyRetrieval: true

# HikariCP Connection Pool Settings
pool-settings:
maximum-pool-size: 10
minimum-idle: 10
max-lifetime: 1800000 # 30 minutes
connection-timeout: 5000 # 5 seconds
idle-timeout: 600000 # 10 minutes

# A unique name for this server. This is CRITICAL for data locking.
server-id: “default-server”

# Toggle specific data to sync
sync-data:
health: true
food-level: true
experience: true
inventory: true
armor: true
potion-effects: true
ender-chest: true
advancements: true
statistics: true
pdc: true
flight-gamemode: true

# Security & Identity
security:
verify-data-integrity: true
seed: “change-me-to-a-long-random-string” # SALT FOR CHECKSUMS

identity:
mode: PREMIUM # PREMIUM or HYBRID
auto-migrate-fastlogin: false
auto-migrate-authme: false
“`

### Detailed Configuration Breakdown

* **`database.type`**: Choose between `mysql` (external) or `sqlite` (local file).
* **`server-id` (Required):** You **must** set a unique name for each backend server.
* **`security.seed`**: A secret string used to salt all SHA-256 hashes. Change this immediately!
* **`identity.mode`**: Choose between `PREMIUM` (strictly enforces UUID consistency) or `HYBRID` (allows flexible identity shifts). Note: **`HYBRID` mode is required** to enable auto-migration features like `auto-migrate-fastlogin`.
* **`sync-data`**: Individual toggles for every data type.
* **`sync-blacklist`**: Define servers or worlds where synchronization should be skipped.

## 📊 Technical: Database Schema

—
_For more detailed information, please refer to the [official documentation](https://github.com/westkevin12/mc-data-bridge/wiki)._

modl

MiraiMC

MiraiMC

MiniMOTD

Minecraft Server Management Protocol Legacy Support

MineCord Link

MineAds Monitor

mclo.gs

Server Plugin/Mod

MCKotlin

MC-Data-Bridge

MatrixColorAPI