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:
  # 🌐 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 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

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.