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:

• Own Your Data: Host your own server. No third party is mining your players' chat history.
• Ensure Safety: 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.
• True User Impersonation
  • 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.
• Automatic Onboarding & Syncing
  • Auto-Account Creation: A passwordless Matrix account is automatically created for every player the first time they join.
  • Auto-Avatar 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).
• ️ Lightweight & Native
  • Built using raw Matrix/Synapse APIs.
  • Zero external dependencies or bloated libraries.

️ Prerequisites

• Minecraft Server: Spigot, Paper, or Purpur (1.20.6 or newer).
• Matrix Homeserver: A Synapse server where you have Admin access.
• Bot Account: A Matrix account with Admin privileges on your homeserver (required for impersonation and user management).

Installation

1. Download the latest matrix-chat-1.0.jar from the releases page.
2. Drop the jar file into your server's plugins folder.
3. Restart the server to generate the default configuration file.
4. Configure plugins/MatrixChat/config.yml (see below).
5. Important: 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.

matrix:

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 Synapse Admin API. It obtains a temporary login token for the specific user and sends the message as them.

• Result: 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
License
Distributed under the MIT License. See LICENSE for more information.