mssgs Game SDK

Overzicht

De mssgs desktop-app draait een kleine lokale HTTP-bridge waar een game op dezelfde computer mee praat. Je game praat nooit met onze servers, ziet nooit een wachtwoord of token van het account, en kan nooit namens de speler iets posten. Hij praat met de kopie van mssgs waar de speler al is ingelogd, en die kopie bepaalt wat er wordt geantwoord.

Wat je ermee kunt:

• Detecteren dat mssgs geïnstalleerd is en er iemand is ingelogd.
• Uitlezen wie de speler is: user_guid, gebruikersnaam, avatar.
• Vragen "zit deze speler in community X?" en welke rol ze daar hebben.
• Een "Speelt …"-status publiceren met een Meedoen-knop voor anderen.
• Een join-overdracht ontvangen wanneer iemand die knop indrukt.

De client vinden

De bridge luistert alleen op 127.0.0.1, op de eerste vrije poort in een klein bereik. Probeer ze op volgorde tot er één antwoordt: 7440, 7441, 7442, 7443. Ontwikkelbuilds van mssgs luisteren op 7540–7543, zodat een testbuild nooit de aanroepen van een echte game beantwoordt.

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

Controleer product === "mssgs" en api voordat je verder gaat. Krijg je geen antwoord op alle vier de poorten, dan draait mssgs niet — bied dan gewoon je normale ervaring aan in plaats van de speler te laten wachten.

Toestemming vragen

Alles behalve /hello vereist een token, en een token bestaat pas nadat de speler jouw game heeft goedgekeurd in een venster binnen de app. Vraag alleen de scopes die je echt gebruikt: de speler ziet ze allemaal los, met uitleg, en kan ze stuk voor stuk uitvinken.

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"]
  }'

Je krijgt {"status":"pending","request_id":"…","poll_after_ms":1000} terug en de speler ziet het venster. Poll daarna tot hij antwoordt (de vraag verloopt na 3 minuten):

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

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

Bewaar het token en gebruik het als Authorization: Bearer <token>. Het blijft geldig over herstarts heen, dus een speler keurt jouw game één keer goed en niet elke sessie opnieuw. Vraag je later opnieuw autorisatie met scopes die al zijn verleend, dan krijg je meteen hetzelfde token terug zonder venster.

Scopes & privacy

De vijf scopes geven heel verschillende hoeveelheden weg. Dat is geen toeval: het is de hele opzet. Vraag van boven naar beneden zo min mogelijk.

Lidmaatschap checken

Dit is het alternatief voor "geef me de hele lijst". Jij noemt de server_guid van jouw eigen community — die je toch al kent — en krijgt alleen daarover antwoord.

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

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

# geen lid — en verder niets:
# {"server_guid":"…","member":false}

Een "nee" is precies dat en niets meer. Je kunt tot 10 guids per aanroep meegeven (herhaal server_guid of gebruik komma's); dan krijg je een results-array terug. De @everyone-groep zit nooit in roles: die geldt voor iedereen en zegt dus niets.

Een speelstatus tonen

Eén PUT zet de "Speelt …"-regel onder de naam van de speler, overal waar hun communities ze zien.

{
  "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" }
}

Alleen name is verplicht. Het antwoord vertelt je hoe lang de status blijft staan en hoe vaak je moet heartbeaten:

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

Aantal spelers en rol

party.kind bepaalt welke zin er komt te staan, want dezelfde twee getallen betekenen niet hetzelfde. Een squad van vier is geen server met vier spelers erop.

role (max 48 tekens) is waar de speler als speelt: een job, klasse of personage. Het krijgt een eigen veld in plaats van nog een zin in state, omdat het als label naast het aantal spelers wordt getoond.

details en state zijn elk maximaal 128 tekens, name maximaal 64. Regeleindes en stuurtekens worden eruit gehaald. Een icoon-URL wordt bewust niet ondersteund: die zou door elke client worden opgehaald die de regel toont, en dat maakt van een statusregel een baken dat elk lid van elke community van de speler bij jouw server meldt.

De Meedoen-knop

Zet een join-blok in je activiteit en anderen krijgen een Meedoen-knop naast de status. Er zijn twee manieren, en je kunt ze combineren.

1. Een secret — voor native games

Zet {"join":{"secret":"raid-42"}}. Drukt iemand op Meedoen, dan wordt dat secret afgeleverd bij hun eigen kopie van jouw game, op hun eigen computer — herkend aan hetzelfde game_id. Er wordt geen URL geopend en geen schema-handler aangeroepen. Jouw game haalt het op met:

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

Poll met ?since=<cursor> zodat je elk event één keer ziet. Draait de game van de drukker niet, dan wordt er niets afgeleverd — bied dan gerust ook een URL aan.

2. Een https-URL — voor webgames en lobby-links

Zet {"join":{"url":"https://play.example.com/s/abc"}} en de knop opent die link. Alleen https wordt geaccepteerd. Een eigen schema (steam://, mygame://, file://) wordt geweigerd: dat blok komt op het scherm van elk lid terecht, en zo'n URL is een manier om op andermans computer een lokale handler aan te roepen met argumenten die jij hebt gekozen.

FiveM

FiveM heeft geen HTTP in de client-side Lua-runtime, dus een resource praat via NUI met de bridge — dat is een CEF-view, en die stuurt een Origin mee. De bridge accepteert die origins expliciet: https://cfx-nui-<resource> en het oudere nui://<resource>. Gewone webpagina's blijven geweigerd, en een pagina op het open web kan die origin niet claimen — de browser zet hem zelf.

-- De NUI-pagina doet het HTTP-werk; Lua stuurt alleen de gegevens.
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: de status vervalt na 90 s
  end
end)

const BASE = 'http://127.0.0.1:7440/mssgs/v1';   // probeer 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']          // meer heb je hier niet nodig
    })
  });
  const started = await res.json();
  if (started.status === 'approved') { return started.token; }

  // De speler ziet nu het toestemmingsvenster in 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' } // jullie cfx.re-link
    })
  });
});

Resultaat: Speelt FiveM — Los Santos Roleplay — 4/100 spelers — Police, met een Meedoen-knop die je cfx.re-link opent.

Endpoint-referentie

Basis-URL http://127.0.0.1:<poort>. Alles behalve de eerste drie vereist Authorization: Bearer <token>.

Foutcodes

Fouten komen terug als {"error":"CODE","message":"…"} met een passende HTTP-status.

Beveiliging

Alleen native games

Verzoeken met de Origin van een webpagina worden geweigerd met 403 ORIGIN_NOT_ALLOWED. Een willekeurige webpagina die kan detecteren dat je mssgs draait en een toestemmingsvenster kan openen, is een fingerprint- en phishingoppervlak — geen functie. Een native game stuurt helemaal geen Origin en heeft hier dus geen last van, en de ingebouwde browser van een game wordt met naam toegelaten — zie FiveM. Bouw je een browsergame, laat de speler dan meedoen via een join.url in plaats van rechtstreeks met de bridge te praten.

Wat de speler in handen houdt

• De speler kan de bridge uitzetten in Instellingen → Spelactiviteit; daarna kan geen enkele game mssgs meer zien.
• Elke goedgekeurde game staat daar met precies de rechten die hij heeft, wanneer hij voor het laatst actief was, en een Verwijderen-knop. Verwijderen werkt direct: het token is meteen dood.
• De bridge luistert alleen op 127.0.0.1 en nooit op het netwerk.
• Directe berichten worden nooit prijsgegeven — ook niet met servers.list.
• Er is per game een limiet van 120 verzoeken per minuut.

Goed burgerschap

• Vraag scopes pas wanneer je ze nodig hebt, niet allemaal bij de eerste start.
• Werkt zonder mssgs: de speler hoeft het niet te hebben.
• Wis je status als het spelen stopt, in plaats van te wachten tot de TTL verloopt.
• Behandel een geweigerde scope als een normale uitkomst, niet als een fout.