Montrer à quoi quelqu’un joue

Présentation

L’application de bureau mssgs fait tourner un petit pont HTTP local auquel un jeu sur la même machine s’adresse. Ton jeu ne parle jamais à nos serveurs, ne voit jamais le mot de passe ni le jeton d’un compte, et ne peut jamais publier au nom du joueur. Il parle à la copie de mssgs sur laquelle le joueur est déjà connecté, et c’est cette copie qui décide quoi répondre.

Ce que tu peux en faire :

• Détecter que mssgs est installé et que quelqu’un est connecté.
• Savoir qui est le joueur : user_guid, nom d’utilisateur, avatar.
• Demander « ce joueur est-il dans la communauté X ? » et quel rôle il y occupe.
• Publier un statut « Joue à … » avec un bouton Rejoindre pour les autres.
• Recevoir une transmission de connexion quand quelqu’un appuie sur ce bouton.

Trouver le client

Le pont écoute uniquement sur 127.0.0.1, sur le premier port libre d’une petite plage. Essaie-les dans l’ordre jusqu’à ce que l’un réponde : 7440, 7441, 7442, 7443. Les versions de développement de mssgs écoutent plutôt sur 7540–7543, pour qu’une version de test ne réponde jamais aux appels d’un vrai jeu.

{
  "product": "mssgs",
  "api": 1,
  "client": "desktop",
  "version": "14.2.20015",
  "platform": "darwin",
  "signed_in": true,
  "scopes": ["identity", "staff", "membership.query", "servers.list", "presence.write"]
}

Vérifie product === "mssgs" et api avant d’aller plus loin. Si aucun des quatre ports ne répond, mssgs ne tourne pas. Propose simplement ton expérience normale au lieu de faire attendre le joueur.

Demander la permission

Tout sauf /hello nécessite un jeton, et un jeton n’existe qu’une fois que le joueur a approuvé ton jeu dans une boîte de dialogue de l’application. Ne demande que les scopes que tu utilises vraiment : le joueur voit chacun séparément, expliqué, et peut les décocher un par un.

curl -X POST http://127.0.0.1:7440/mssgs/v1/authorize \
  -H "Content-Type: application/json" \
  -d '{
    "game_id": "com.acme.spacegame",
    "name": "Space Raiders",
    "scopes": ["identity", "membership.query", "presence.write"]
  }'

Tu reçois {"status":"pending","request_id":"…","poll_after_ms":1000} et le joueur voit la boîte de dialogue. Interroge ensuite jusqu’à ce qu’il réponde (la demande expire au bout de 3 minutes) :

curl http://127.0.0.1:7440/mssgs/v1/authorize/<request_id>

# {"status":"approved","token":"…","scopes":["identity","presence.write"],"game_id":"com.acme.spacegame"}

Conserve le jeton et envoie-le sous la forme Authorization: Bearer <token>. Il survit aux redémarrages, donc un joueur approuve ton jeu une fois plutôt qu’à chaque session. Si tu redemandes plus tard l’autorisation avec des scopes déjà accordés, tu récupères directement le même jeton, sans boîte de dialogue.

Scopes et confidentialité

Les cinq scopes révèlent des quantités très différentes. Ce n’est pas un hasard, c’est tout le principe. Demande le moins possible, en descendant ce tableau.

Vérifier l’appartenance

C’est l’alternative à « donne-moi toute la liste ». Tu nommes le server_guid de ta propre communauté (que tu connais déjà) et tu obtiens une réponse sur celle-là seulement.

curl -H "Authorization: Bearer $TOKEN" \
  "http://127.0.0.1:7440/mssgs/v1/membership?server_guid=ca94ecc…f4g02"

# membre :
# {"server_guid":"ca94ecc…","member":true,"name":"Acme Fans","is_owner":false,
#  "roles":[{"guid":"0aa32…","name":"Pro"}]}

# pas membre, et rien d’autre :
# {"server_guid":"…","member":false}

Un « non » veut dire exactement cela, rien de plus. Tu peux passer jusqu’à 10 guids par appel (répète server_guid ou sépare-les par des virgules), ce qui renvoie un tableau results. Le groupe @everyone n’est jamais dans roles : il vaut pour chaque membre, il ne t’apprend donc rien.

Publier un statut de jeu

Un seul PUT place la ligne « Joue à … » sous le nom du joueur, partout où ses communautés le voient.

{
  "name":    "Space Raiders",
  "details": "Sector 7",
  "state":   "In a raid",
  "role":    "Gunner",
  "started_at": 1755859200000,
  "party":   { "size": 3, "max": 4, "kind": "party" },
  "join":    { "secret": "raid-42" }
}

Seul name est obligatoire. La réponse te dit combien de temps le statut vit et à quelle fréquence envoyer un heartbeat :

{ "ok": true, "expires_in_ms": 90000, "heartbeat_every_ms": 30000 }

Nombre de joueurs et rôle

party.kind décide quelle phrase est affichée, car les deux mêmes nombres ne veulent pas dire la même chose. Une escouade de quatre n’est pas un serveur avec quatre joueurs dessus.

role (jusqu’à 48 caractères) est ce que le joueur incarne : un métier, une classe ou un personnage. Il a son propre champ plutôt qu’une phrase de plus dans state, car il s’affiche comme une étiquette à côté du nombre de joueurs.

details et state sont limités à 128 caractères chacun, name à 64. Les sauts de ligne et les caractères de contrôle sont supprimés. Une URL d’icône n’est volontairement pas prise en charge : elle serait chargée par chaque client qui affiche la ligne, ce qui transformerait un statut en balise signalant à ton serveur chaque membre de chaque communauté dont le joueur fait partie.

Le bouton Rejoindre

Mets un bloc join dans ton activité et les autres membres voient un bouton Rejoindre à côté du statut. Il y a deux façons de faire, et tu peux les combiner.

1. Un secret (pour les jeux natifs)

Définis {"join":{"secret":"raid-42"}}. Quand quelqu’un appuie sur Rejoindre, ce secret est remis à sa propre copie de ton jeu, sur sa propre machine, identifiée par le même game_id. Aucune URL n’est ouverte et aucun gestionnaire de schéma n’est invoqué. Ton jeu le récupère avec :

{
  "events": [
    { "seq": 1, "type": "join", "secret": "raid-42",
      "from": { "user_guid": "62e377…", "username": "mssgs-test-1" } }
  ],
  "cursor": 1
}

Interroge avec ?since=<cursor> pour voir chaque événement une seule fois. Si le jeu de la personne qui a appuyé ne tourne pas, rien n’est remis, ce qui est une bonne raison de proposer aussi une URL.

2. Une URL https (pour les jeux web et les liens de lobby)

Définis {"join":{"url":"https://play.example.com/s/abc"}} et le bouton ouvre ce lien. Seul https est accepté. Un schéma personnalisé (steam://, mygame://, file://) est refusé : ce bloc atterrit sur l’écran de chaque membre, et une telle URL permet de faire invoquer à la machine de quelqu’un d’autre un gestionnaire local avec des arguments que tu as choisis.

FiveM

FiveM n’a pas de HTTP dans son runtime Lua côté client, donc une ressource s’adresse au pont via NUI, une vue CEF, qui envoie un Origin. Le pont accepte explicitement ces origines : https://cfx-nui-<resource> et l’ancien nui://<resource>. Les pages web ordinaires restent refusées, et une page du web ouvert ne peut pas revendiquer cette origine ; c’est le navigateur qui la définit lui-même.

-- La page NUI fait le HTTP ; Lua lui envoie seulement les données.
CreateThread(function()
  while true do
    SendNUIMessage({
      action  = 'mssgs:publish',
      players = GetActivePlayers and #GetActivePlayers() or 0,
      maxPlayers = GetConvarInt('sv_maxclients', 100),
      job     = exports['qb-core'] and 'Police' or nil
    })
    Wait(30000) -- heartbeat : le statut expire après 90 s
  end
end)

const BASE = 'http://127.0.0.1:7440/mssgs/v1';   // essaie 7440-7443
let token = null;

async function authorize () {
  const res = await fetch(`${BASE}/authorize`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      game_id: 'fivem.lossantos.rp',
      name: 'Los Santos Roleplay',
      scopes: ['presence.write']          // rien de plus n’est nécessaire ici
    })
  });
  const started = await res.json();
  if (started.status === 'approved') { return started.token; }

  // Le joueur voit maintenant la boîte de dialogue de permission dans mssgs.
  for (let i = 0; i < 180; i += 1) {
    await new Promise((r) => { setTimeout(r, 1000); });
    const poll = await (await fetch(`${BASE}/authorize/${started.request_id}`)).json();
    if (poll.status === 'approved') { return poll.token; }
    if (poll.status !== 'pending') { return null; }
  }
  return null;
}

window.addEventListener('message', async (event) => {
  if (event.data.action !== 'mssgs:publish') { return; }
  if (!token) { token = await authorize(); }
  if (!token) { return; }

  await fetch(`${BASE}/activity`, {
    method: 'PUT',
    headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${token}` },
    body: JSON.stringify({
      name: 'FiveM',
      details: 'Los Santos Roleplay',
      role: event.data.job,                       // "Police"
      party: { size: event.data.players, max: event.data.maxPlayers, kind: 'server' },
      join: { url: 'https://cfx.re/join/abc123' } // ton lien cfx.re
    })
  });
});

Le résultat : Joue à FiveM · Los Santos Roleplay · 4/100 joueurs · Police, avec un bouton Rejoindre qui ouvre ton lien cfx.re.

Jeux navigateur et mobile : la liaison via ton backend

Un jeu dans un onglet de navigateur ou sur un téléphone ne peut pas atteindre le pont décrit plus haut. Le pont tourne sur l’ordinateur du joueur, et trois murs se dressent entre les deux : le pont refuse toute requête qui porte un Origin de navigateur, Chrome place une demande de permission devant une page publique qui interroge 127.0.0.1 et Safari refuse tout net, et un téléphone n’a aucun chemin vers la boucle locale d’un ordinateur.

Le sens s’inverse donc. Ton propre backend sait déjà qui joue, et c’est lui qui le dit à mssgs, pour les joueurs qui ont relié leur compte mssgs à ton jeu. La liaison est approuvée dans l’application mssgs, jamais dans ton jeu, et elle crée un lien, jamais une session : rien de ce qui suit ne peut connecter qui que ce soit ni agir au nom du joueur. Ton client de jeu ne voit jamais de clé et ne parle jamais à mss.gs. Le premier jeu sur cette voie est CozyCity, un city builder livré sous forme de page WebGL et d’app iPhone, sans version de bureau ; les exemples ci-dessous sont les siens.

1. Enregistre ton jeu

Enregistre le jeu sur la page d’enregistrement du Game SDK : ton game_id (par exemple com.deverence.cozycity), le nom et l’icône que le joueur voit sur la fiche d’approbation, et les noms d’hôte de ton backend. Nous l’examinons là-bas, et une fois approuvé, ta clé de backend t’attend sur la même page, affichée une seule fois ; nous n’en gardons qu’une empreinte. La clé a sa place sur ton serveur et nulle part ailleurs. Tu peux la renouveler là-bas à tout moment, et l’ancienne reste valable 24 heures pour qu’un déploiement puisse se faire progressivement.

Enregistrer ton jeu

Le nom et l’icône de la fiche viennent toujours de l’enregistrement, jamais de la requête. Sinon, un lien d’hameçonnage pourrait déguiser une demande de liaison en n’importe quel jeu. Les noms d’hôte délimitent où un join.url peut pointer, voir plus bas.

2. Relie un joueur

Le joueur choisit Connecter mssgs dans ton jeu. Ton jeu demande à ton backend, et ton backend nous demande :

curl -X POST https://ams1-gateway.mss.gs/game-sdk/v1/link/start \
  -H "Authorization: Bearer $BACKEND_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "player_ref": "player-8812", "player_name": "René\u2019s city" }'

# {"link_code":"K7PQ2XM4","device_code":"…","qr_url":"https://mss.gs/gl/K7PQ2XM4",
#  "deep_link":"mssgs://link-game/K7PQ2XM4","expires_in":600,"interval":5}

player_ref est ton propre id stable pour ce joueur (jusqu’à 128 caractères), pas pour une session ni une partie ; player_name (jusqu’à 64) est ce que la fiche affiche après « Joueur : ». Ne transmets à ton client de jeu que link_code, qr_url et deep_link. device_code est ta référence d’interrogation et reste sur le serveur.

Ton jeu affiche alors trois choses à la fois, car le joueur peut se trouver n’importe où :

• Le QR de qr_url. Un téléphone avec mssgs l’ouvre directement sur la fiche d’approbation de l’application. Sans l’application, il arrive sur une page de mss.gs qui affiche le code et propose le téléchargement.
• Un bouton « Ouvrir dans mssgs » avec deep_link, pour un navigateur de bureau qui se trouve à côté de l’application de bureau. C’est la seule URL externe que ton jeu doit jamais ouvrir.
• Le code lui-même, en deux groupes de quatre, à saisir dans Réglages → Activité de jeu → Lier un jeu. L’alphabet n’a ni 0/O ni 1/I, donc la saisie se passe rarement mal.

Ce que le joueur voit dans mssgs, dessiné par l’application à partir de l’enregistrement :

Pendant ce temps, ton backend interroge toutes les interval secondes (plus vite, la réponse est 429 SLOW_DOWN) jusqu’à ce que le statut change. Un code ne sert qu’une fois et expire au bout de dix minutes :

curl -X POST https://ams1-gateway.mss.gs/game-sdk/v1/link/poll \
  -H "Authorization: Bearer $BACKEND_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "device_code": "…" }'

# {"status":"pending"}
# {"status":"denied"}      # le joueur a choisi Pas maintenant
# {"status":"expired"}
# {"status":"linked","link_guid":"…","user":{"user_guid":"62e377…"}}

Associe link_guid à ton joueur ; c’est désormais l’adresse pour laquelle tu publies. La réponse ne contient que le user_guid ; un username n’est ajouté que si ton enregistrement détient le scope identity.link, et il n’y a rien au-delà. Une deuxième approbation pour le même player_ref remplace la liaison précédente, donc un joueur de ton jeu correspond à un compte mssgs. Un même compte mssgs peut être relié à plusieurs jeux et à plusieurs player_ref d’un même jeu (un iPad familial).

3. Publie le statut de jeu

Le même bloc que sur le pont, avec les mêmes règles et les mêmes limites, mais cette fois par liaison et avec ta clé de backend :

{
  "activity": {
    "name":       "CozyCity",
    "details":    "Lantern Hollow",
    "state":      "Day 12 · 34 residents",
    "started_at": 1788901000000,
    "party":      { "size": 6, "max": 40, "kind": "server" },
    "join":       { "url": "https://cozycity.net/game/?share=…" }
  }
}

200 {"published":true,"changed":true}     # le bloc a changé et a été diffusé
200 {"published":true,"changed":false}    # identique à ce qui était stocké ; seul le TTL a été rafraîchi
204                                        # stocké, mais le joueur n’est pas en ligne dans mssgs en ce moment
410 {"error":"LINK_REVOKED"}               # le joueur s’est déconnecté : abandonne la liaison

Traite 200 et 204 de la même façon : stocké. { "activity": null } efface le bloc, envoie-le quand le joueur s’en va. Une différence avec le pont : l’hôte de join.url doit être l’un de tes backends enregistrés (ou un sous-domaine de l’un d’eux), sinon tu reçois 400 INVALID_PAYLOAD. Un backend ne peut donc pas placer sur le statut d’un joueur un bouton Rejoindre qui mène quelque part où ce joueur n’a jamais joué.

Avec des centaines de joueurs en ligne, envoie le heartbeat en un seul appel, jusqu’à 100 éléments à la fois. Chaque élément reçoit son propre statut, donc un joueur qui s’est déconnecté dans mssgs n’arrête jamais les quatre-vingt-dix-neuf autres :

{ "items": [ { "link_guid": "…", "activity": { "name": "CozyCity", "details": "Lantern Hollow" } },
             { "link_guid": "…", "activity": null } ] }

// → 200 { "results": [ { "link_guid": "…", "status": 200, "changed": false },
//                      { "link_guid": "…", "status": 410 } ] }

Comment le statut s’affiche

• Exactement comme un statut du pont : Joue à CozyCity · Lantern Hollow · 6/40 joueurs, avec Rejoindre quand il y a un join.url. Le bloc est marqué via: "backend" côté serveur, donc un client peut ajouter « Partagé par le serveur du jeu ».
• Seulement tant que le joueur est en ligne dans mssgs. Sans client mssgs ouvert, le compte est hors ligne et le reste ; ton backend ne peut pas faire paraître quelqu’un présent. Cela empêche aussi cette voie de devenir une balise « René est-il devant son ordinateur ».
• Priorité : un jeu intégré à l’application > un jeu sur le pont > ton backend. Si le joueur se lance dans une partie d’échecs dans mssgs pendant que ton backend continue d’envoyer des heartbeats, ce sont les échecs qui l’emportent, pas le dernier à avoir écrit.

Déconnexion

Le joueur voit chaque liaison dans Réglages → Activité de jeu → Jeux liés, avec ton icône et ton nom, le nom de joueur venant de ton jeu, la date de la liaison et de la dernière publication, et un bouton Déconnecter. Ensuite, ta publication suivante répond 410 LINK_REVOKED ; c’est ainsi que ton jeu l’apprend. Abandonne le link_guid et propose à nouveau « Connecter mssgs ». De ton côté, mets fin à une liaison avec DELETE /game-sdk/v1/links/{link_guid}.

Référence des endpoints : le pont

URL de base http://127.0.0.1:<port>. Tout sauf les trois premiers exige Authorization: Bearer <token>.

Référence des endpoints : backends liés

URL de base https://ams1-gateway.mss.gs. Chaque route exige Authorization: Bearer <backend key> et le scope activity.write sur ton enregistrement ; les réponses partent avec Cache-Control: no-store. Appelle-les depuis ton serveur, jamais depuis le client de jeu.

Codes d’erreur

Les erreurs reviennent sous la forme {"error":"CODE","message":"…"} avec le statut HTTP correspondant.

Backends liés

Les routes du backend utilisent la même forme. Dans un lot, le statut revient par élément dans results, donc une liaison terminée ne fait jamais échouer tout l’appel.

Sécurité

Jeux natifs uniquement

Les requêtes qui portent un Origin de page web sont refusées avec 403 ORIGIN_NOT_ALLOWED. Qu’une page web quelconque puisse détecter que tu utilises mssgs et faire apparaître une demande de permission serait une surface de fingerprinting et d’hameçonnage, pas une fonctionnalité. Un jeu natif n’envoie aucun Origin, il n’est donc pas concerné, et le navigateur intégré d’un jeu est autorisé nommément, voir FiveM. Si tu développes un jeu navigateur ou mobile, tu ne t’adresses pas au pont : ton propre backend publie pour les joueurs liés, voir Jeux navigateur et mobile.

Ce que le joueur garde en main

• Le joueur peut désactiver le pont dans Réglages → Activité de jeu, après quoi aucun jeu ne peut plus voir mssgs.
• Chaque jeu approuvé y est listé avec exactement les permissions qu’il détient, sa dernière activité et un bouton Retirer. Le retrait est immédiat : le jeton meurt aussitôt.
• Un jeu navigateur ou mobile lié est listé sous Jeux liés avec un bouton Déconnecter. La déconnexion est immédiate aussi : la publication suivante de ce backend reçoit un 410.
• Le pont écoute uniquement sur 127.0.0.1, jamais sur le réseau.
• Les messages privés ne sont jamais divulgués, pas même avec servers.list.
• Chaque jeu dispose d’un budget de 120 requêtes par minute.

Se comporter en bon citoyen

• Demande les scopes quand tu en as besoin, pas tous d’un coup au premier lancement.
• Fonctionne sans mssgs : le joueur n’est pas obligé de l’avoir.
• Efface ton statut quand la partie s’arrête au lieu d’attendre le TTL.
• Traite un scope refusé comme un résultat normal, pas comme une erreur.