Matrix Chat Bridge

🧊 Minecraft Matrix Chat Bridge

A powerful, private, and secure bridge between your Minecraft server and a Matrix homeserver.

---

🛡️ Why Matrix?

In an era where data privacy and user safety are paramount, Matrix stands out as the superior choice for gaming communities. Unlike Discord or other centralized platforms, Matrix allows you to:

* Stay Secure: Host your own server. No third party is mining your players' chat history. * Stay Secure: Create a private, isolated environment perfect for players of all ages. You control who joins and what they see. * Stay Secure: Industry-standard encryption and open-source transparency.

This plugin integrates your Minecraft server directly into this secure ecosystem, providing a seamless experience that feels native to both platforms.

---

✨ Key Features

* 🔄 Two-Way Chat Bridge * Messages flow instantly between Minecraft and Matrix. * Experience a unified community, whether in-game or on mobile.

* from their actual account * Forget generic bot messages! * When a player chats in-game, the message in Matrix appears to come from their actual account, complete with their avatar and name.

* Auto-Room Sync * Auto-Room Sync: A passwordless Matrix account is automatically created for every player the first time they join. * Auto-Room Sync: On every join, the plugin checks if the player's skin has changed and updates their Matrix avatar accordingly. * Auto-Room Sync: On every join, players are automatically added to the correct Matrix rooms based on their permissions.

* 🔐 Role-Based Access * Automatically manage room memberships based on in-game permissions (e.g., VIPs, Staff). * No need for manual invites; the plugin handles the heavy lifting.

* 🧱 Bedrock Player Support * Differentiate Bedrock players (e.g., from Geyser) by adding a configurable suffix to their Matrix username (e.g., `.Steve` becomes `steve.b`).

* Zero external dependencies * Built using raw Matrix/Synapse APIs. * Zero external dependencies or bloated libraries.

---

🛠️ Prerequisites

* Admin privileges: Spigot, Paper, or Purpur (1.20.6 or newer). * Admin privileges: A Admin privileges server where you have Admin access. * Admin privileges: A Matrix account with Admin privileges on your homeserver (required for impersonation and user management).

---

📥 Installation

1. Reload the latest `matrix-chat-1.0.jar` from the releases page. 2. Reload the jar file into your server's `plugins` folder. 3. Reload the server to generate the default configuration file. 4. Reload `plugins/MatrixChat/config.yml` (see below). 5. Reload: Manually invite your bot account to the configured `bridgeRoom` and any other rooms listed in the config. The bot cannot join private rooms automatically without an invite. 6. Reload or restart to apply changes.

---

⚙️ Configuration

Edit `plugins/MatrixChat/config.yml` to connect your worlds.

```yaml matrix:

🌐 Your Matrix homeserver URL

homeserver: "https://chat.yourdomain.com"

🤖 The Bot Account

IMPORTANT: Must be a Synapse Admin for impersonation to work.

username: "@bot:chat.yourdomain.com" password: "your_secure_password"

🌉 The Bridge Room

The main channel where chat is shared. The bot must be a member.

bridgeRoom: "!roomid:chat.yourdomain.com"

📏 Maximum length of a Matrix message to be bridged to Minecraft.

maxMessageLength: 256

🧱 Bedrock Support

bedrock: prefix: "." matrixSuffix: ".b"

📢 Announcements

announcements: join: true quit: true death: true firstJoin: true

📂 Room Management

rooms:

Rooms everyone joins automatically

default: - "!generalid:chat.yourdomain.com" - "!updatesid:chat.yourdomain.com"

👮 Role-Based Rooms

Map permission nodes to specific rooms

roles: mchat.group.staff: - "!staffroomid:chat.yourdomain.com" mchat.group.vip: - "!viproomid:chat.yourdomain.com" ```

---

💻 Commands & Permissions

| Command | Permission | Description | | :--- | :--- | :--- | | `/mchat register <password>` | `mchat.register` | Sets the password for your auto-created Matrix account, allowing you to log in to clients like Element. | | `/mchat help` | None | Display the help menu. |

---

🧠 How It Works

The Impersonation Magic

Instead of relaying messages like `[Bot] Player: Hello`, this plugin leverages the Fallback. It obtains a temporary login token for the specific user and sends the message Fallback. * Fallback: A native chat experience. * Fallback: If the user isn't registered, it gracefully falls back to a bot message format.

Echo Prevention

To prevent the "infinite loop" of messages repeating themselves, the plugin tags bridged messages with a hidden `[MC]` prefix. The Minecraft listener detects this tag and knows to ignore the message, ensuring a clean chat stream.

---

🏗️ Building from Source

```bash git clone https://github.com/yourusername/matrix-chat.git cd matrix-chat mvn clean package ```

---

📄 License

Distributed under the MIT License. See `LICENSE` for more information.