1. Who this is for
In Bridge mode, the PortalSync mod keeps a WebSocket connection open to a Discord bot. It sends the game chat and events, and receives Discord messages to show in game. Aelyx is one of these bots, but you can write your own by following this page: the mod is the client, your bot is the server.
You may freely write and publish a bot that speaks this protocol. The mod’s code stays All Rights Reserved (see the licences, in French). If others use your bot, its own privacy policy applies, not Aelyx’s.
2. Mod side
In the Minecraft server’s config/portalsync-common.toml, then /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
Your bot chooses the serverId and token for each Minecraft server and gives them to its administrator.
The mod rejects a serverId or token with the wrong format (see the table in section 4), and a url
with ? or #. playerStats = false turns statistics off. /portalsync status shows the link state.
3. Transport
- Standard WebSocket.
wss://(TLS, with a valid certificate for the domain name);ws://only for local tests. - One message = one JSON object as UTF-8 text, with a
typefield. - Accept messages up to 64 KB: a large modpack’s mod list often exceeds 16 KB.
- The mod sends the header
User-Agent: PortalSync/<version>. - Everything runs on a thread separate from the Minecraft server: your bot cannot slow the game down.
4. Connection
As soon as the connection is open, the mod sends 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"]}
| Field | Content |
|---|---|
v | Protocol version: 1. |
server_id | Link ID, given by your bot: ps_ followed by 6 to 40 lowercase letters or digits. Not a secret. |
token | Secret link token, given by your bot: 20 to 200 characters among A-Z, a-z, 0-9, _ and -. |
mod_version | PortalSync version, e.g. 0.8.0. |
mc_version | Minecraft version, e.g. 1.21.1. |
loader | forge, neoforge or fabric. |
capabilities | What the mod can do: events, discord_in, status, stats, stats_full, item_assets. |
Your bot must answer within 10 seconds, with welcome if it accepts:
{"type":"welcome","v":1,"server_id":"ps_survie01","name":"Survie","capabilities":["status","stats","stats_full","item_assets"]}
| Field | Content |
|---|---|
v | Protocol version: 1. |
server_id | The same as in hello. |
name | Optional. Link name, shown in the Minecraft server console. |
capabilities | What your bot accepts on top of events: status, stats, stats_full, item_assets, or an empty list. |
or with error if it refuses, then close the connection:
{"type":"error","code":"auth_failed","message":"Unknown server_id or wrong token"}
| Code | When | What the mod does |
|---|---|---|
auth_failed | Unknown server_id or wrong token. | Retries in 5 minutes, or right away if url, serverId or token changes (/portalsync reload). |
revoked | The link is no longer allowed. | Same: 5 minutes. |
unsupported_protocol | Unsupported v. | Same: 5 minutes. |
too_many_failures | Too many failures from this address. | Same: 5 minutes. |
hello_expected | The first message was not hello. | Retries with the normal delay. |
replaced | Another connection was opened with the same link. | Retries with the normal delay. |
Tip: one connection per link. If a new one arrives, close the old one with replaced.
An error received after welcome also closes the connection, and the mod reconnects.
5. Keep-alive and reconnection
{"type":"ping"}
{"type":"pong"}
- The mod sends
pingevery 30 seconds. Answerpong. - With no message at all from your bot for 90 seconds, the mod closes and reconnects. Do the same on your side.
- Between attempts, the mod waits 1, 2, 5, 10, 30 then 60 seconds. After a token refusal, 5 minutes.
6. Events
{"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 is unique (UUID), ts is the date in milliseconds, kind the event type.
The mod only sends the types enabled in its config.
| kind | Event |
|---|---|
chat | Game chat message. |
join | A player joins. |
leave | A player leaves. |
firstJoin | A player’s first join on this world. |
death | A player dies. |
advancement | Advancement made. |
boss | Boss killed (the mod’s [options] bossEntities list). |
command | Command used (the [options] commands list, off by default). |
serverStart | Server started. |
serverStop | Server stopped. The mod waits at most 3 seconds for its ack before closing. |
payload has the same shape as a Discord webhook body:
| Field | Content |
|---|---|
content | The text, ready to post on Discord (Markdown, 2,000 characters at most). Always present. |
username | Optional. Name to show, e.g. the player’s name or the server name. |
avatar_url | Optional. Image to show, from the mod’s [webhook] playerAvatarUrl. |
player | Optional. The player concerned: name, uuid, and skin (textures.minecraft.net address) when the mod knows it. |
head | Optional. true for chat: the message is shown under the player’s head. |
allowed_mentions | Always {"parse":[]}: post the message without any mention. |
Answer every event with an acknowledgement:
{"type":"ack","event_id":"3f0c2a4e-9b1d-4c8e-a6f2-2d7b9e1c5a10"}
- Until it gets the
ack, the mod keeps the event (500 at most) and sends it again after a reconnection. - You may therefore get an event twice: keep the latest
event_ids to ignore duplicates, but acknowledge them anyway. - Nothing is kept after the Minecraft server stops.
7. Discord to Minecraft
If the hello contains discord_in, your bot can send at any time:
{"type":"discord_message","author":"Alex","content":"J'arrive dans 5 minutes","attachments":0}
The mod shows it in the game chat. author is cut at 80 characters, content at 500.
attachments (0 to 99) shows the number of attachments. Send plain text: no raw mentions or emoji codes.
8. Status and statistics
These messages are optional. The mod only sends them if the welcome’s capabilities contain
status (status and mod list) and stats (player statistics). They have no ack.
status, every 15 seconds
{"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 players listed at most. mspt and tps are missing if the loader does not allow measuring them.
Memory in MB, uptime_s in seconds since the server started.
server_info, once per connection
{"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"}]}
The game’s own entries (minecraft, java, forge, neoforge, fabricloader…) are removed. 400 mods listed at most; mods_total gives the real count.
player_stats, every 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}
Read from world/stats/ and world/advancements/. On each connection, the mod sends every player, in batches
of 20 with a 1-second pause; after that, only those whose file changed. Minecraft writes these files every 5 minutes and when a
player disconnects. One message per player, replacing the previous one.
| Field | Content |
|---|---|
uuid, name | The player (name comes from usercache.json and may be missing). |
updated | Modification date of the stats file (milliseconds). |
play_ticks | Play time in ticks (20 per second). |
deaths … dropped | Counters: deaths, mobs and players killed, jumps, damage dealt and taken (Minecraft stats unit), disconnections, blocks mined, items crafted, used, broken, picked up, dropped. |
distance_cm | Distances in centimetres: walk, sprint, crouch, swim, fly, elytra, climb, fall, ride. |
top_mined, top_killed, top_crafted, top_killed_by | The 10 largest counters: [["id", count], …]. |
bosses | Bosses killed, same format. |
advancements | Number of advancements made, recipes excluded. Missing if the file is missing. |
player_stats_full, alongside player_stats
Only if the welcome contains stats_full (PortalSync 1.1.0 and later) and fullStats is not turned off in the
config. These are every line of a player’s statistics, one category per message, sent right after their player_stats
(same pace):
{"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,killed,crafted,used,broken,picked_up,dropped,killed_byandcustom(general statistics: time, distances, damage…).items:[["id", count], …], largest first, zeros left out, at most 1,000 lines per category. Mod ids are included. An empty category is not sent.- One message per player and category, replacing the previous one. Each message stays under 64 KB.
customkeeps Minecraft’s units: ticks for time, centimetres for*_one_cmdistances, tenths of a health point for damage.
assets_request and item_assets: mod icons and names
Only if both sides announce item_assets (PortalSync 1.2.0 and later) and modIcons is not turned off.
Your bot asks for the modded ids it does not know (at most 200 per message, kind = block, item or entity):
{"type":"assets_request","ids":[["create:zinc_ore","block"],["create:wrench","item"],["alexsmobs:grizzly_bear","entity"]]}
The mod looks them up in the jars of the server’s mods/ folder and answers (at most 40 items per message, always under 64 KB):
{"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: names from the mod’s language files, when they exist.png: square PNG icon (base64), 32×32 at most;texinstead when the mod reuses a Minecraft texture.- An item with nothing found comes back with only
idandkind: do not ask again right away. minecraft:ids are never handled. Noack.
9. Minimal example
A Node.js bot using the ws package, which accepts one server and prints its chat:
// Minimal bridge bot: accepts one PortalSync server and prints its chat.
import { WebSocketServer } from 'ws';
// Your links. In real life, store a SHA-256 fingerprint and compare with crypto.timingSafeEqual.
const LINKS = { ps_survie01: 'exemple-de-jeton-a-changer-0001' };
// Behind Nginx (or another proxy) that handles TLS: the mod connects to wss://your-domain/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) {
// The first message must be 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') {
// Always acknowledge, even a duplicate.
send(ws, { type: 'ack', event_id: msg.event_id });
// Here: post msg.payload.content in your Discord channel.
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. Security
- Never store tokens in plain text: store a fingerprint (SHA-256) and compare in constant time.
- Never write a token to your logs.
- Block an address after several failures (Aelyx: 10 failures in 10 minutes).
- Treat everything coming from a Minecraft server as player text: no mentions, bounded length.
- Your bot needs its own privacy policy if others use it.
11. Compatibility
- Both sides ignore message types and fields they do not know: new fields may appear without changing
v. - An incompatible change will move to
v: 2, announced on this page. - A bot that returns no
capabilitiesonly receives events: it works with every version of the mod.
A question, or a bot that speaks PortalSync you want to share? Email contact@cmloxy.fr.