Intégration chat externe

👋 Salut l'agent ! Briefing — Mod Matrix pour Minecraft 1.20.1 Forge

Ce document est un condensé de la conception réalisée avec un autre agent Claude. Bonne lecture et bon courage pour le dev ! 🚀

🎯 Objectif du projet

Créer un mod Forge 1.20.1 qui intègre un client Matrix directement dans Minecraft :

Remplace/enrichit le chat vanilla MC avec des salons Matrix
Interface GUI dédiée (keybind M) pour switcher de salon
Le salon Matrix actif s'affiche dans le chat vanilla dynamiquement
HUD minimaliste indiquant le salon actif (ex: [#général])

Le mod sera publié sur CurseForge, usage sur un serveur Minecraft privé (whitelist).

✅ Fonctionnalités retenues

Feature	Statut
Authentification Matrix (token)	✅ À implémenter
Sync temps réel des rooms	✅ À implémenter
Affichage messages dans chat MC	✅ À implémenter
Envoi de messages	✅ À implémenter
Switch de salon via GUI	✅ À implémenter
Filtrage des rooms par Space Matrix	✅ À implémenter
Notifications in-game (toast/HUD)	✅ À implémenter
VoIP / Appels	❌ Hors scope
Envoi de fichiers/images	❌ Hors scope

🏗️ Architecture globale

[Joueur MC] ──── /whitelist sur Discord
                        │
                        ▼
              [Bot Discord] ────► crée compte Matrix via API Admin Synapse
                        │         stocke liaison Discord ↔ UUID ↔ compte Matrix
                        │
                        ▼
              [Serveur Minecraft] ◄── whitelist ajoutée
                        │
                        ▼
              [Mod Forge 1.20.1] ──── récupère credentials Matrix au 1er lancement
                        │
                        ▼
              [Serveur Matrix Synapse] ──── hébergé sur VPS dédié

Points clés de sécurité

Le token d'enregistrement Synapse n'est jamais dans le mod (mod public sur CurseForge)
La création de compte Matrix est déléguée au bot Discord (point d'entrée unique)
Le bot Discord détient seul les droits admin Synapse

🖥️ Serveur Matrix Synapse

Hébergement : VPS Ubuntu 22.04/24.04 dédié (4 cœurs, 8 Go RAM, 75 Go NVMe)
Domaine : matrix.protosrv.fr
Reverse proxy : Nginx + Let's Encrypt (Certbot)
Base de données : PostgreSQL (pas SQLite, anticipation de la charge)
Fédération : désactivée (serveur privé, port 8448 non exposé)
Enregistrement : registration_requires_token: true — tokens gérés par le bot Discord
Synapse Admin : déployé dans Docker, accessible sur https://matrix.protosrv.fr:8443 (accès restreint par IP)
Compte admin : @protomehka-admin:matrix.protosrv.fr — seul compte admin du serveur

Config homeserver.yaml retenue

pid_file: "/var/run/matrix-synapse.pid"
server_name: "matrix.mondomaine.fr"

listeners:
  - bind_addresses:
      - "127.0.0.1"
    port: 8008
    type: http
    tls: false
    x_forwarded: true
    resources:
      - names: [client]
        compress: false

database:
  name: psycopg2
  args:
    user: synapse_user
    password: CHANGEME
    dbname: synapse
    host: localhost
    cp_min: 5
    cp_max: 10

log_config: "/etc/matrix-synapse/log.yaml"
signing_key_path: "/etc/matrix-synapse/homeserver.signing.key"
media_store_path: /var/lib/matrix-synapse/media
max_upload_size: 1M

federation_domain_whitelist: []
allow_public_rooms_over_federation: false
allow_public_rooms_without_auth: false

enable_registration: true
enable_registration_without_verification: true
registration_requires_token: true

trusted_key_servers: []
suppress_key_server_warning: true

event_cache_size: 10K
caches:
  global_factor: 1.0

enable_metrics: false
report_stats: false
user_directory:
  enabled: false
url_preview_enabled: false

rc_message:
  per_second: 0.5
  burst_count: 10
rc_login:
  address:
    per_second: 0.1
    burst_count: 3
  account:
    per_second: 0.1
    burst_count: 3
  failed_attempts:
    per_second: 0.1
    burst_count: 3

🤖 Bot Discord — Rôle et responsabilités

Le bot Discord est le chef d'orchestre du système :

Commande /whitelist <pseudo_minecraft> libre (accessible à tous)
Vérifie et ajoute le joueur à la whitelist Minecraft

Crée automatiquement un compte Matrix via l'API Admin Synapse :

POST /_synapse/admin/v2/users/@pseudo:matrix.protosrv.fr
Authorization: Bearer <access_token_admin>

Stocke la liaison Discord ID ↔ UUID Minecraft ↔ compte Matrix
Génère/fournit les credentials Matrix au mod au premier lancement

ℹ️ Le token d'accès admin s'obtient via :
curl -X POST "https://matrix.protosrv.fr/_matrix/client/v3/login" \
  -H "Content-Type: application/json" \
  -d '{"type": "m.login.password", "user": "protomehka-admin", "password": "***"}'
La réponse contient le champ access_token à stocker dans les variables d'environnement du bot.

ℹ️ Le bot est déjà en cours de développement dans une autre session avec ProtoMehka — à coordonner pour l'ajout de la partie création de compte Matrix.

🔐 Authentification du joueur dans le mod

Méthode retenue : Option A — Mot de passe envoyé par MP Discord

Le bot génère un mot de passe aléatoire à la création du compte Matrix et l'envoie en MP Discord au joueur. Le mod construit automatiquement l'identifiant Matrix à partir du pseudo Minecraft, le joueur n'a qu'à saisir son mot de passe au premier lancement.

Flow d'authentification :

1. Mod détecte qu'aucun token n'est stocké localement
2. Écran de config s'ouvre automatiquement :
   ┌─────────────────────────────────────┐
   │ Bienvenue ProtoMehka !              │
   │                                     │
   │ Mot de passe Matrix :               │
   │ [____________________________]      │
   │                                     │
   │           [Se connecter]            │
   └─────────────────────────────────────┘
3. Le mod récupère le pseudo MC automatiquement :
   String mcUsername = Minecraft.getInstance().getUser().getName();
   String matrixUserId = "@" + mcUsername.toLowerCase() + ":matrix.protosrv.fr";
4. Appel POST /_matrix/client/v3/login avec userId + password
5. Token d'accès Matrix stocké localement → plus jamais redemandé

MP Discord envoyé par le bot :

✅ Tu es whitelisté sur ProtoSRV !

Ton mot de passe Matrix : xK9#mP2$nL
Entre-le dans Minecraft au premier lancement du mod.

ℹ️ Le pseudo Minecraft = le pseudo Matrix (sans le @...protosrv.fr). Le bot doit créer le compte Matrix avec exactement le même username que le pseudo Minecraft du joueur.

Le mod est configuré pour utiliser un Space Matrix dédié (l'équivalent d'un serveur Discord) plutôt que d'afficher toutes les rooms du compte joueur. Seules les rooms appartenant au Space du serveur Minecraft sont visibles dans le mod.

Structure du Space :

Space: "Mon Serveur Minecraft"
├── #général          — chat ouvert à tous
├── #annonces         — read-only pour les joueurs
├── #aide             — support
├── #off-topic        — détente
└── #staff            — privé, réservé aux admins

Avantages :

Les DM perso ou autres rooms Matrix du joueur ne se mélangent pas dans l'interface MC
Ajouter un nouveau salon dans le Space côté Synapse le fait apparaître automatiquement dans le mod pour tous les joueurs, sans mise à jour du mod
Rooms publiques et privées gérées nativement par Matrix

Config du mod :

{
  "homeserver": "matrix.protosrv.fr",
  "space_id": "!xxxxx:matrix.protosrv.fr"
}

ℹ️ Le Space et ses rooms sont à précréer sur Synapse avant le premier lancement du mod. Les rooms privées (ex: #staff) ne seront visibles que pour les joueurs qui y ont été invités.

Forge 1.20.1
├── OkHttp          — HTTP + WebSocket (connexion Matrix /sync)
├── Gson            — parsing JSON des events Matrix
├── GUI Minecraft   — Screen natif Forge pour l'interface
└── Thread dédié    — sync Matrix hors thread principal MC

Dépendances Gradle à ajouter

dependencies {
    implementation fg.deobf("...")  // Forge standard

    // OkHttp
    implementation 'com.squareup.okhttp3:okhttp:4.12.0'
    // Gson (déjà présent dans MC, vérifier version)
    implementation 'com.google.code.gson:gson:2.10.1'
}

⚠️ Attention aux conflits de dépendances avec le classpath Forge/MC — shading d'OkHttp probablement nécessaire.

📦 Architecture des packages suggérée

fr.protomehka.matrixmod/
├── MatrixMod.java              — Entry point Forge
├── config/
│   └── MatrixConfig.java       — Homeserver URL, credentials stockés
├── matrix/
│   ├── MatrixClient.java       — Gestion auth + /sync polling
│   ├── MatrixRoom.java         — Modèle d'une room
│   └── MatrixMessage.java      — Modèle d'un message
├── gui/
│   ├── MatrixScreen.java       — GUI principal (liste rooms + messages)
│   └── RoomListWidget.java     — Widget liste des salons
├── chat/
│   ├── ChatInterceptor.java    — Intercepte envoi/réception chat MC
│   └── MatrixChatRenderer.java — Injection messages Matrix dans chat vanilla
├── events/
│   └── KeyBindHandler.java     — Keybind M pour ouvrir le GUI
└── notification/
    └── ToastNotifier.java      — Notifications toast in-game

🔄 Flow utilisateur complet

1. Joueur fait /whitelist sur Discord
2. Bot crée compte Matrix (@pseudoMC:matrix.protosrv.fr) + génère mot de passe aléatoire
3. Bot envoie le mot de passe en MP Discord au joueur
4. Bot invite le joueur au Space Matrix
5. Joueur rejoint le serveur Minecraft
6. Mod détecte qu'aucun token n'est stocké → écran de saisie mot de passe
7. Joueur entre son mot de passe → mod fait /login → token stocké localement
8. MatrixClient se connecte, thread de sync démarre
9. Messages du salon actif s'affichent dans le chat MC
10. Joueur tape dans le chat → envoyé dans le salon Matrix actif
11. Appui sur M → GUI s'ouvre → switch de salon possible
12. Notification toast si message reçu dans un autre salon

❓ Points ouverts à définir

~~Comment le mod récupère les credentials au premier lancement ?~~ → Mot de passe envoyé par MP Discord, pseudo MC = pseudo Matrix
Chiffrement E2EE ? (complexifie, via libolm — optionnel)
Rooms Matrix précréées (recommandé) ou créées à la volée ?
Le Space ID est-il hardcodé dans le mod ou configurable par fichier ?
Gestion des rooms privées (DM entre joueurs) ?

Briefing généré depuis une session de conception avec Claude — Mars 2026