# Minecraft

URL: https://zerodev.ca/docs/medusa/paid-modules/minecraft

> Connect a Minecraft server to Discord: chat bridge, account linking, status, RCON and rank sync.



Minecraft links your Minecraft server and Discord. Chat flows both ways, players link their accounts, staff can run console commands from Discord, and Discord roles can give in-game ranks.

## What You Need

* A Bukkit-based server on any Minecraft version from 1.7.10 to 26.x: CraftBukkit, Spigot, Paper, Purpur, Folia, or a Forge/Bukkit hybrid such as Thermos, Crucible, Mohist or Arclight.
* Java 8 or newer.
* The **MedusaBridge** plugin, which comes with the module.
* RCON turned on, if you want to run commands from Discord.

## Install the Plugin

1. Get `MedusaBridge.jar` from `modules/minecraft/resources/plugin/`, or download it from `<API URL>/api/modules/minecraft/download`.
2. Put it in your server's `plugins/` folder and restart the server.
3. Edit `plugins/MedusaBridge/config.yml`:

```yaml title="plugins/MedusaBridge/config.yml"
api-url: "http://your-medusa-host:3001/api/modules/minecraft"
api-key: "a-long-random-secret"
sync-chat: true
sync-join-quit: true
sync-deaths: true
sync-console-commands: true
sync-ranks: true
status-interval-seconds: 30
```

4. Put the same secret in **Companion Plugin API Secret Key** on the dashboard and restart the Minecraft server.

`api-url` must point at Medusa's API port, `3001` by default, and be reachable from the Minecraft server.

## Turn On RCON

`/minecraft rcon` and the console channel need RCON. In `server.properties`:

```properties title="server.properties"
enable-rcon=true
rcon.port=25575
rcon.password=a-strong-password
```

Restart the server, then enter the port and password on the dashboard. Medusa must be able to reach the RCON port.

## Linking Accounts

1. A player runs `/minecraft link` and gets a private 6-digit code.
2. They join the server and type `/discord link <code>`.
3. Medusa links the two accounts and gives the **Verified Player Discord Role**.

The **Minecraft Players** dashboard page lists every linked player.

## Rank Sync

Give linked players an in-game rank based on a Discord role, such as a booster role giving a `booster` rank.

1. Pick your **Rank Plugin**, or leave it on **Detect Automatically**, which checks LuckPerms, UltraPermissions, Chatty, then Vault.
2. Under **Role Rank Sync**, add a **Discord Role** and the **Rank Name** exactly as it is in your rank plugin.

Ranks are checked when a player joins, right after they link, and for everyone online at each status update. Losing the Discord role removes the rank.

| Rank Plugin      | Command used                                     |
| ---------------- | ------------------------------------------------ |
| LuckPerms        | `lp user <uuid> parent add/remove <rank>`        |
| UltraPermissions | `upc addGroup/removeGroup <player> <rank>`       |
| Chatty           | `chatty user <player> addrank/removerank <rank>` |
| Vault            | The Vault permission API                         |

<Callout type="info">
  The plugin records the ranks it gives in `plugins/MedusaBridge/synced.yml` and only ever removes those, so ranks you give by hand are left alone. Rank names can use letters, numbers, `_`, `.` and `-`.
</Callout>

## Settings

| Setting                             | Default              | What it does                           |
| ----------------------------------- | -------------------- | -------------------------------------- |
| Display Server Name                 | Survival             | Name shown in messages.                |
| Server Host or IP Address           | `127.0.0.1`          | Your Minecraft server's address.       |
| Server Game Port                    | 25565                | The game port.                         |
| Server RCON Port                    | 25575                | The RCON port.                         |
| Server RCON Password                | None                 | Matches `rcon.password`.               |
| Companion Plugin API Secret Key     | None                 | Matches `api-key` in the plugin.       |
| Discord In-Game Chat Bridge Channel | None                 | Channel synced with in-game chat.      |
| Server Console Log Channel          | None                 | Channel for console output.            |
| Live Server Status Channel          | None                 | Channel for the live status message.   |
| Verified Player Discord Role        | None                 | Role given after linking.              |
| Rank Plugin                         | Detect Automatically | Plugin that receives ranks.            |
| Role Rank Sync                      | None                 | Discord roles and the ranks they give. |

## Commands

| Command                     | What it does                                                                                                                   |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `/minecraft link`           | Get a code to link your account.                                                                                               |
| `/minecraft players`        | Show who is online.                                                                                                            |
| `/minecraft status`         | Show whether the server is up, its version and player count.                                                                   |
| `/minecraft rcon <command>` | Run a console command. Administrators only.                                                                                    |
| Minecraft Profile           | Right-click a member, then **Apps > Minecraft Profile**, to see their linked account. Off by default on the **Commands** page. |

The **Minecraft Events** log records links, console commands and the bridge connecting.