1. Pour qui
En mode Pont, le mod PortalSync garde une connexion WebSocket ouverte vers un bot Discord. Il lui envoie le chat et les événements du jeu, et reçoit les messages de Discord à afficher en jeu. Aelyx est un de ces bots, mais tu peux écrire le tien en suivant cette page : le mod est le client, ton bot est le serveur.
Tu peux librement écrire et publier un bot qui parle ce protocole. Le code du mod reste sous licence Tous droits réservés (voir les licences). Si ton bot est utilisé par d’autres, c’est sa propre politique de confidentialité qui s’applique, pas celle d’Aelyx.
2. Côté mod
Dans config/portalsync-common.toml du serveur Minecraft, puis /portalsync reload :
[general]
mode = "BRIDGE"
[bridge]
url = "wss://mon-bot.example/ws"
serverId = "ps_survie01"
token = "exemple-de-jeton-a-changer-0001"
playerStats = true
fullStats = true
modIcons = true
C’est ton bot qui choisit serverId et token pour chaque serveur Minecraft, et qui les donne à son
administrateur. Le mod refuse un serverId ou un token qui n’a pas le bon format (voir le tableau du point 4),
et une url avec ? ou #. playerStats = false coupe l’envoi des statistiques. /portalsync status affiche l’état de la liaison.
3. Transport
- WebSocket standard.
wss://(TLS, avec un certificat valide pour le nom de domaine) ;ws://seulement pour des tests en local. - Un message = un objet JSON en texte UTF-8, avec un champ
type. - Accepte des messages jusqu’à 64 Ko : la liste des mods d’un gros modpack dépasse souvent 16 Ko.
- Le mod s’annonce avec l’en-tête
User-Agent: PortalSync/<version>. - Tout se passe sur un fil à part du serveur Minecraft : ton bot ne peut pas ralentir le jeu.
4. Connexion
Dès que la connexion est ouverte, le mod envoie hello :
{"type":"hello","v":1,"server_id":"ps_survie01","token":"exemple-de-jeton-a-changer-0001",
"mod_version":"0.8.0","mc_version":"1.21.1","loader":"neoforge",
"capabilities":["events","discord_in","status","stats","stats_full","item_assets"]}
| Champ | Contenu |
|---|---|
v | Version du protocole : 1. |
server_id | Identifiant de la liaison, donné par ton bot : ps_ puis 6 à 40 lettres minuscules ou chiffres. Ce n’est pas un secret. |
token | Jeton secret de la liaison, donné par ton bot : 20 à 200 caractères parmi A-Z, a-z, 0-9, _ et -. |
mod_version | Version de PortalSync, ex. 0.8.0. |
mc_version | Version de Minecraft, ex. 1.21.1. |
loader | forge, neoforge ou fabric. |
capabilities | Ce que le mod sait faire : events, discord_in, status, stats, stats_full, item_assets. |
Ton bot doit répondre en moins de 10 secondes, par welcome s’il accepte :
{"type":"welcome","v":1,"server_id":"ps_survie01","name":"Survie","capabilities":["status","stats","stats_full","item_assets"]}
| Champ | Contenu |
|---|---|
v | Version du protocole : 1. |
server_id | Le même que dans hello. |
name | Facultatif. Nom de la liaison, affiché dans la console du serveur Minecraft. |
capabilities | Ce que ton bot accepte en plus des événements : status, stats, stats_full, item_assets, ou une liste vide. |
ou par error s’il refuse, puis fermer la connexion :
{"type":"error","code":"auth_failed","message":"Unknown server_id or wrong token"}
| Code | Quand | Ce que fait le mod |
|---|---|---|
auth_failed | server_id inconnu ou mauvais jeton. | Réessaie dans 5 minutes, ou tout de suite si url, serverId ou token change (/portalsync reload). |
revoked | La liaison n’est plus autorisée. | Pareil : 5 minutes. |
unsupported_protocol | Version v non gérée. | Pareil : 5 minutes. |
too_many_failures | Trop d’échecs depuis cette adresse. | Pareil : 5 minutes. |
hello_expected | Le premier message n’était pas hello. | Réessaie avec l’attente normale. |
replaced | Une autre connexion a été ouverte avec la même liaison. | Réessaie avec l’attente normale. |
Conseil : une seule connexion par liaison. Si une nouvelle arrive, ferme l’ancienne avec replaced.
Une erreur reçue après welcome coupe aussi la connexion, et le mod se reconnecte.
5. Maintien et reconnexion
{"type":"ping"}
{"type":"pong"}
- Le mod envoie
pingtoutes les 30 secondes. Répondspong. - Sans aucun message de ton bot pendant 90 secondes, le mod ferme et se reconnecte. Fais pareil de ton côté.
- Entre deux essais, le mod attend 1, 2, 5, 10, 30 puis 60 secondes. Après un refus de jeton, 5 minutes.
6. Événements
{"type":"event","event_id":"3f0c2a4e-9b1d-4c8e-a6f2-2d7b9e1c5a10","kind":"chat","ts":1763208000000,
"payload":{"content":"Salut tout le monde !","username":"Steve",
"avatar_url":"https://minotar.net/helm/8667ba71-b85a-4004-af54-457a9734eed7/64.png",
"player":{"name":"Steve","uuid":"8667ba71-b85a-4004-af54-457a9734eed7",
"skin":"https://textures.minecraft.net/texture/31f477eb1a7beee631c2ca64d06f8f68fa93a3386d04452ab27f43acdf1b60cb"},
"head":true,"allowed_mentions":{"parse":[]}}}
event_id est unique (UUID), ts est la date en millisecondes, kind le type d’événement.
Le mod n’envoie que les types activés dans sa config.
| kind | Événement |
|---|---|
chat | Message dans le chat du jeu. |
join | Un joueur arrive. |
leave | Un joueur part. |
firstJoin | Première connexion d’un joueur sur ce monde. |
death | Mort d’un joueur. |
advancement | Progrès obtenu. |
boss | Boss vaincu (liste [options] bossEntities du mod). |
command | Commande utilisée (liste [options] commands, désactivé par défaut). |
serverStart | Serveur démarré. |
serverStop | Serveur arrêté. Le mod attend son ack 3 secondes au plus avant de fermer. |
payload a la même forme que le corps d’un webhook Discord :
| Champ | Contenu |
|---|---|
content | Le texte, prêt à poster sur Discord (Markdown, 2 000 caractères au plus). Toujours présent. |
username | Facultatif. Nom à afficher, ex. le pseudo du joueur ou le nom du serveur. |
avatar_url | Facultatif. Image à afficher, d’après [webhook] playerAvatarUrl du mod. |
player | Facultatif. Le joueur concerné : name, uuid, et skin (adresse textures.minecraft.net) quand le mod la connaît. |
head | Facultatif. true pour le chat : le message s’affiche sous la tête du joueur. |
allowed_mentions | Toujours {"parse":[]} : poste le message sans aucune mention. |
Réponds à chaque événement par un accusé de réception :
{"type":"ack","event_id":"3f0c2a4e-9b1d-4c8e-a6f2-2d7b9e1c5a10"}
- Tant qu’il n’a pas reçu l’
ack, le mod garde l’événement (500 au plus) et le renvoie après une reconnexion. - Tu peux donc recevoir un événement deux fois : garde les derniers
event_idpour ignorer les doublons, mais acquitte-les quand même. - Rien n’est gardé après l’arrêt du serveur Minecraft.
7. De Discord vers Minecraft
Si le hello contient discord_in, ton bot peut envoyer à tout moment :
{"type":"discord_message","author":"Alex","content":"J'arrive dans 5 minutes","attachments":0}
Le mod l’affiche dans le chat du jeu. author est coupé à 80 caractères, content à 500.
attachments (0 à 99) affiche le nombre de pièces jointes. Envoie du texte simple : sans mentions brutes ni code d’emoji.
8. Statut et statistiques
Ces messages sont facultatifs. Le mod ne les envoie que si les capabilities du welcome contiennent
status (statut et liste des mods) et stats (statistiques des joueurs). Ils n’ont pas d’ack.
status, toutes les 15 secondes
{"type":"status","online":2,"max":20,
"players":[{"name":"Steve","uuid":"8667ba71-b85a-4004-af54-457a9734eed7"},{"name":"Alex","uuid":"ec561538-f3fd-461d-aff5-086b22154bce"}],
"mspt":12.4,"tps":20,"mem_used_mb":3120,"mem_max_mb":8192,"uptime_s":5400}
100 joueurs listés au plus. mspt et tps manquent si le loader ne permet pas de les mesurer.
Mémoire en Mo, uptime_s en secondes depuis le démarrage du serveur.
server_info, une fois par connexion
{"type":"server_info","mods_total":2,
"mods":[{"id":"portalsync","name":"PortalSync","version":"0.8.0"},{"id":"jei","name":"Just Enough Items","version":"19.21.0"}]}
Les mods du jeu lui-même (minecraft, java, forge, neoforge, fabricloader…) sont retirés. 400 mods listés au plus, mods_total donne le vrai nombre.
player_stats, toutes les 5 minutes
{"type":"player_stats","uuid":"8667ba71-b85a-4004-af54-457a9734eed7","name":"Steve","updated":1763207700000,
"play_ticks":432000,"deaths":7,"mob_kills":312,"player_kills":0,"jumps":5120,
"damage_dealt":48210,"damage_taken":9730,"leave_game":14,
"mined":20514,"crafted":1830,"used":15022,"broken":41,"picked_up":26310,"dropped":512,
"distance_cm":{"walk":3120000,"sprint":1840000,"crouch":21000,"swim":95000,"fly":0,"elytra":0,
"climb":12000,"fall":61000,"ride":230000},
"top_mined":[["minecraft:stone",8120],["minecraft:deepslate",4310]],
"top_killed":[["minecraft:zombie",88],["minecraft:skeleton",61]],
"top_crafted":[["minecraft:torch",640]],
"top_killed_by":[["minecraft:creeper",3]],
"bosses":[["minecraft:ender_dragon",1]],
"advancements":42}
Lues dans world/stats/ et world/advancements/. À chaque connexion, le mod envoie tous les joueurs, par
paquets de 20 avec 1 seconde de pause ; ensuite seulement ceux dont le fichier a changé. Minecraft écrit ces fichiers toutes les
5 minutes et quand un joueur se déconnecte. Un message par joueur, qui remplace le précédent.
| Champ | Contenu |
|---|---|
uuid, name | Le joueur (name vient de usercache.json, il peut manquer). |
updated | Date de modification du fichier de stats (millisecondes). |
play_ticks | Temps de jeu en ticks (20 par seconde). |
deaths … dropped | Compteurs : morts, créatures et joueurs tués, sauts, dégâts infligés et subis (unité des stats de Minecraft), déconnexions, blocs minés, objets fabriqués, utilisés, cassés, ramassés, jetés. |
distance_cm | Distances en centimètres : walk, sprint, crouch, swim, fly, elytra, climb, fall, ride. |
top_mined, top_killed, top_crafted, top_killed_by | Les 10 plus grands compteurs : [["identifiant", nombre], …]. |
bosses | Boss vaincus, même format. |
advancements | Nombre de progrès faits, sans les recettes. Absent si le fichier manque. |
player_stats_full, avec les player_stats
Seulement si le welcome contient stats_full (PortalSync 1.1.0 et plus) et que fullStats n’est pas
coupé dans la config. Ce sont toutes les lignes des statistiques d’un joueur, une catégorie par message, envoyées juste après
son player_stats (même rythme) :
{"type":"player_stats_full","uuid":"8667ba71-b85a-4004-af54-457a9734eed7","updated":1763207700000,
"cat":"mined","items":[["minecraft:stone",8120],["minecraft:deepslate",4310],["create:zinc_ore",212]]}
cat:mined(blocs minés),killed(créatures tuées),crafted,used,broken,picked_up,dropped,killed_byetcustom(statistiques générales : temps, distances, dégâts…).items:[["id", nombre], …], du plus grand au plus petit, sans les zéros, 1 000 lignes au plus par catégorie. Les identifiants des mods sont inclus. Une catégorie vide n’est pas envoyée.- Un message par joueur et par catégorie, qui remplace le précédent. Chaque message reste sous 64 Ko.
customgarde les unités de Minecraft : ticks pour le temps, centimètres pour les distances*_one_cm, dixièmes de point de vie pour les dégâts.
assets_request et item_assets : icônes et noms des mods
Seulement si les deux côtés annoncent item_assets (PortalSync 1.2.0 et plus) et que modIcons n’est pas coupé.
Ton bot demande les identifiants de mods qu’il ne connaît pas (200 au plus par message, kind = block, item ou entity) :
{"type":"assets_request","ids":[["create:zinc_ore","block"],["create:wrench","item"],["alexsmobs:grizzly_bear","entity"]]}
Le mod les cherche dans les JAR du dossier mods/ du serveur et répond (40 objets au plus par message, toujours sous 64 Ko) :
{"type":"item_assets","items":[
{"id":"create:zinc_ore","kind":"block","fr":"Minerai de zinc","en":"Zinc Ore","png":"iVBORw0KGgoAAAANSUhEUgAA…"},
{"id":"create:cog","kind":"item","en":"Cogwheel","tex":"minecraft:item/iron_ingot"},
{"id":"alexsmobs:grizzly_bear","kind":"entity"}]}
fr,en: noms tirés des fichiers de langue du mod, s’ils existent.png: icône en PNG (base64), carrée, 32×32 au plus ;texà la place quand le mod réutilise une texture de Minecraft.- Un objet sans rien trouvé revient avec seulement
idetkind: ne le redemande pas tout de suite. - Les identifiants
minecraft:ne sont jamais traités. Pas d’ack.
9. Exemple minimal
Un bot Node.js avec le paquet ws, qui accepte un serveur et affiche son chat :
// Bot de liaison minimal : accepte un serveur PortalSync et affiche son chat.
import { WebSocketServer } from 'ws';
// Tes liaisons. En vrai, garde une empreinte SHA-256 et compare avec crypto.timingSafeEqual.
const LINKS = { ps_survie01: 'exemple-de-jeton-a-changer-0001' };
// Derrière Nginx (ou un autre proxy) qui gère le TLS : le mod se connecte à wss://ton-domaine/ws.
const wss = new WebSocketServer({ host: '127.0.0.1', port: 8080, path: '/ws', maxPayload: 64 * 1024 });
wss.on('connection', (ws) => {
let serverId = null;
ws.on('message', (raw) => {
let msg;
try { msg = JSON.parse(raw.toString()); } catch { return ws.close(4002, 'bad_json'); }
if (!serverId) {
// Le premier message doit être hello.
if (msg.type !== 'hello') return refuse(ws, 'hello_expected');
if (msg.v !== 1) return refuse(ws, 'unsupported_protocol');
if (!LINKS[msg.server_id] || LINKS[msg.server_id] !== msg.token) return refuse(ws, 'auth_failed');
serverId = msg.server_id;
return send(ws, { type: 'welcome', v: 1, server_id: serverId, name: 'Survie', capabilities: [] });
}
if (msg.type === 'ping') return send(ws, { type: 'pong' });
if (msg.type === 'event') {
// Toujours acquitter, même un doublon.
send(ws, { type: 'ack', event_id: msg.event_id });
// Ici : poste msg.payload.content dans ton salon Discord.
console.log(`[${serverId}] ${msg.kind}: ${msg.payload.content}`);
}
});
});
function send(ws, msg) { ws.send(JSON.stringify(msg)); }
function refuse(ws, code) { send(ws, { type: 'error', code }); ws.close(4001, code); }
10. Sécurité
- Ne garde jamais les jetons en clair : enregistre une empreinte (SHA-256) et compare en temps constant.
- N’écris jamais un jeton dans tes journaux.
- Bloque une adresse après plusieurs échecs (Aelyx : 10 échecs en 10 minutes).
- Traite tout ce qui vient d’un serveur Minecraft comme du texte de joueur : pas de mentions, longueur bornée.
- Ton bot doit avoir sa propre politique de confidentialité s’il est utilisé par d’autres.
11. Compatibilité
- Les deux côtés ignorent les types de messages et les champs qu’ils ne connaissent pas : de nouveaux champs peuvent arriver sans changer
v. - Un changement incompatible passera en
v: 2, annoncé sur cette page. - Un bot qui ne renvoie aucune
capabilitiesreçoit seulement les événements : il marche avec toutes les versions du mod.
Une question, ou un bot qui parle PortalSync à faire connaître ? Écris à contact@cmloxy.fr.