Zeigen, was jemand spielt

Überblick

Die mssgs-Desktop-App betreibt eine kleine lokale HTTP-Bridge, mit der ein Spiel auf demselben Rechner spricht. Dein Spiel spricht nie mit unseren Servern, sieht nie ein Passwort oder Token eines Kontos und kann nie als der Spieler posten. Es spricht mit der mssgs-Kopie, bei der der Spieler schon angemeldet ist, und diese Kopie entscheidet, was sie antwortet.

Was du damit tun kannst:

• Erkennen, dass mssgs installiert ist und jemand angemeldet ist.
• Lesen, wer der Spieler ist: user_guid, Benutzername, Avatar.
• Fragen „ist dieser Spieler in Community X?“ und welche Rolle er dort hat.
• Einen Status „Spielt …“ mit einem Button Jetzt mitmachen für andere veröffentlichen.
• Eine Beitritts-Übergabe empfangen, wenn jemand diesen Button drückt.

Den Client finden

Die Bridge lauscht nur auf 127.0.0.1, auf dem ersten freien Port in einem kleinen Bereich. Probiere sie der Reihe nach durch, bis einer antwortet: 7440, 7441, 7442, 7443. Entwicklungs-Builds von mssgs lauschen stattdessen auf 7540–7543, damit ein Test-Build nie die Aufrufe eines echten Spiels beantwortet.

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

Prüfe product === "mssgs" und api, bevor du weitermachst. Antwortet keiner der vier Ports, läuft mssgs nicht. Biete dann einfach dein normales Spielerlebnis an, statt den Spieler warten zu lassen.

Um Erlaubnis fragen

Alles außer /hello braucht ein Token, und ein Token gibt es erst, nachdem der Spieler dein Spiel in einem Dialog in der App genehmigt hat. Frag nur nach den Scopes, die du wirklich nutzt: Der Spieler sieht jeden einzeln, mit Erklärung, und kann sie einzeln abwählen.

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

Du bekommst {"status":"pending","request_id":"…","poll_after_ms":1000} zurück, und der Spieler sieht den Dialog. Frag dann regelmäßig ab, bis er antwortet (die Anfrage läuft nach 3 Minuten ab):

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

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

Speichere das Token und sende es als Authorization: Bearer <token>. Es übersteht Neustarts, sodass ein Spieler dein Spiel einmal genehmigt statt in jeder Session. Autorisierst du später erneut mit Scopes, die schon gewährt wurden, bekommst du dasselbe Token direkt zurück, ohne Dialog.

Scopes & Datenschutz

Die fünf Scopes geben sehr unterschiedlich viel preis. Das ist kein Zufall, sondern das ganze Design. Frag nach so wenig wie möglich und arbeite dich in dieser Tabelle von oben nach unten.

Mitgliedschaft prüfen

Das ist die Alternative zu „gib mir die ganze Liste“. Du nennst die server_guid deiner eigenen Community (die du ohnehin kennst) und bekommst eine Antwort nur dazu.

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

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

# kein Mitglied, und sonst nichts:
# {"server_guid":"…","member":false}

Ein „nein“ ist genau das und nichts weiter. Du kannst bis zu 10 GUIDs pro Aufruf übergeben (server_guid wiederholen oder kommagetrennt), dann kommt ein Array results zurück. Die Gruppe @everyone steht nie in roles: Sie gilt für jedes Mitglied, sagt dir also nichts.

Einen Spielstatus veröffentlichen

Ein PUT setzt die Zeile „Spielt …“ unter den Namen des Spielers, überall dort, wo seine Communities ihn sehen.

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

Nur name ist Pflicht. Die Antwort sagt dir, wie lange der Status lebt und wie oft du einen Heartbeat senden sollst:

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

Spielerzahl und Rolle

party.kind entscheidet, welcher Satz angezeigt wird, denn dieselben zwei Zahlen bedeuten nicht dasselbe. Ein Trupp aus vier ist kein Server mit vier Spielern darauf.

role (bis zu 48 Zeichen) ist das, als was der Spieler spielt: ein Job, eine Klasse oder eine Figur. Es bekommt ein eigenes Feld statt eines weiteren Satzes in state, weil es als Label neben der Spielerzahl angezeigt wird.

details und state sind auf je 128 Zeichen begrenzt, name auf 64. Zeilenumbrüche und Steuerzeichen werden entfernt. Eine Icon-URL wird bewusst nicht unterstützt: Sie würde von jedem Client abgerufen, der die Zeile anzeigt, und so würde aus einem Status ein Peilsender, der jedes Mitglied jeder Community des Spielers an deinen Server meldet.

Der Button „Jetzt mitmachen“

Setz einen join-Block in deine Aktivität, und andere Mitglieder bekommen neben dem Status einen Button Jetzt mitmachen. Es gibt zwei Wege, und du kannst sie kombinieren.

1. Ein Secret (für native Spiele)

Setze {"join":{"secret":"raid-42"}}. Drückt jemand auf Jetzt mitmachen, wird dieses Secret an seine eigene Kopie deines Spiels geliefert, auf seinem eigenen Rechner, zugeordnet über dieselbe game_id. Es wird keine URL geöffnet und kein Scheme-Handler aufgerufen. Dein Spiel holt es so ab:

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

Frag mit ?since=<cursor> ab, damit du jedes Event nur einmal siehst. Läuft das Spiel der Person, die gedrückt hat, nicht, wird nichts geliefert, und das ist ein guter Grund, zusätzlich eine URL anzubieten.

2. Eine https-URL (für Webspiele und Lobby-Links)

Setze {"join":{"url":"https://play.example.com/s/abc"}}, und der Button öffnet diesen Link. Nur https wird akzeptiert. Ein eigenes Scheme (steam://, mygame://, file://) wird abgelehnt: Dieser Block landet auf dem Bildschirm jedes Mitglieds, und eine solche URL ist ein Weg, den Rechner eines anderen einen lokalen Handler mit Argumenten deiner Wahl aufrufen zu lassen.

FiveM

FiveM hat in seiner clientseitigen Lua-Laufzeit kein HTTP, deshalb spricht eine Resource über NUI mit der Bridge, eine CEF-Ansicht, die einen Origin mitsendet. Die Bridge akzeptiert diese Origins ausdrücklich: https://cfx-nui-<resource> und das ältere nui://<resource>. Gewöhnliche Webseiten bleiben abgelehnt, und eine Seite im offenen Web kann diesen Origin nicht vortäuschen; der Browser setzt ihn selbst.

-- Die NUI-Seite macht das HTTP; Lua schickt ihr nur die Daten.
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: Der Status läuft nach 90 s ab
  end
end)

const BASE = 'http://127.0.0.1:7440/mssgs/v1';   // 7440-7443 durchprobieren
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']          // mehr ist hier nicht nötig
    })
  });
  const started = await res.json();
  if (started.status === 'approved') { return started.token; }

  // Der Spieler sieht jetzt den Erlaubnis-Dialog 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' } // dein cfx.re-Link
    })
  });
});

Das Ergebnis: Spielt FiveM · Los Santos Roleplay · 4/100 Spieler · Police, mit einem Button „Jetzt mitmachen“, der deinen cfx.re-Link öffnet.

Browser- und Handyspiele: Verknüpfen über dein Backend

Ein Spiel in einem Browser-Tab oder auf einem Handy erreicht die Bridge oben nicht. Sie läuft auf dem Desktop des Spielers, und drei Mauern stehen dazwischen: Die Bridge lehnt jede Anfrage mit einem Browser-Origin ab, Chrome stellt eine Berechtigungsabfrage vor jeden Abruf von 127.0.0.1 durch eine öffentliche Seite und Safari verweigert ihn ganz, und ein Handy hat überhaupt keinen Weg zum Loopback eines Desktops.

Also dreht sich die Richtung um. Dein eigenes Backend weiß bereits, wer spielt, und sagt es mssgs, für Spieler, die ihr mssgs-Konto mit deinem Spiel verknüpft haben. Die Verknüpfung wird in der mssgs-App genehmigt, nie in deinem Spiel, und sie erzeugt eine Verknüpfung, nie eine Session: Nichts von dem, was folgt, kann jemanden anmelden oder als der Spieler handeln. Dein Spiel-Client sieht nie einen Key und spricht nie mit mss.gs. Das erste Spiel auf diesem Weg ist CozyCity, ein Städtebauspiel, das als WebGL-Seite und als iPhone-App erscheint, ohne Desktop-Build; die Beispiele unten stammen von dort.

1. Registriere dein Spiel

Registriere das Spiel auf der Registrierungsseite des Game SDK: deine game_id (zum Beispiel com.deverence.cozycity), den Namen und das Icon, die der Spieler auf dem Genehmigungsfenster sieht, und die Hostnamen deines Backends. Wir prüfen es dort, und nach der Freigabe wartet dein Backend-Key auf derselben Seite, nur einmal angezeigt; wir speichern nur einen Digest. Der Key gehört auf deinen Server und nirgendwo sonst hin. Du kannst ihn dort jederzeit rotieren, und der alte bleibt 24 Stunden gültig, damit ein Deploy durchlaufen kann.

Spiel registrieren

Name und Icon auf dem Fenster kommen immer aus der Registrierung, nie aus der Anfrage. Sonst könnte ein Phishing-Link eine Verknüpfungsanfrage als jedes beliebige Spiel verkleiden. Die Hostnamen begrenzen, wohin eine join.url zeigen darf, siehe unten.

2. Einen Spieler verknüpfen

Der Spieler wählt in deinem Spiel mssgs verbinden. Dein Spiel fragt dein Backend, und dein Backend fragt uns:

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 ist deine eigene, stabile ID für diesen Spieler (bis zu 128 Zeichen), nicht für eine Session oder ein Match; player_name (bis zu 64) ist das, was das Fenster als „Spieler: …“ zeigt. Gib deinem Spiel-Client nur link_code, qr_url und deep_link. device_code ist dein Handle zum Abfragen und bleibt auf dem Server.

Dein Spiel zeigt dann drei Dinge gleichzeitig, denn der Spieler könnte überall sein:

• Den QR-Code von qr_url. Ein Handy mit mssgs öffnet ihn direkt im Genehmigungsfenster der App. Ohne die App landet er auf einer Seite auf mss.gs, die den Code zeigt und den Download anbietet.
• Einen Button „In mssgs öffnen“ mit deep_link, für einen Desktop-Browser, der neben der Desktop-App läuft. Das ist die einzige externe URL, die dein Spiel je öffnen muss.
• Den Code selbst, in zwei Vierergruppen, zum Eintippen unter Einstellungen → Spielaktivität → Ein Spiel verknüpfen. Das Alphabet enthält kein 0/O und kein 1/I, deshalb geht beim Abtippen selten etwas schief.

Was der Spieler in mssgs sieht, von der App aus der Registrierung gezeichnet:

Währenddessen fragt dein Backend alle interval Sekunden ab (schneller ergibt 429 SLOW_DOWN), bis sich der Status ändert. Ein Code funktioniert einmal und läuft nach zehn Minuten ab:

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"}      # der Spieler hat Nicht jetzt gewählt
# {"status":"expired"}
# {"status":"linked","link_guid":"…","user":{"user_guid":"62e377…"}}

Speichere link_guid bei deinem Spieler; ab jetzt ist das die Adresse, für die du veröffentlichst. Die Antwort enthält nur die user_guid; ein username kommt nur hinzu, wenn deine Registrierung den Scope identity.link hat, und darüber hinaus gibt es nichts. Eine zweite Genehmigung für dieselbe player_ref ersetzt die frühere Verknüpfung, sodass ein Spieler deines Spiels genau ein mssgs-Konto ist. Dasselbe mssgs-Konto darf mit mehreren Spielen verknüpft sein und mit mehreren player_refs eines Spiels (ein Familien-iPad).

3. Den Spielstatus veröffentlichen

Derselbe Block wie bei der Bridge, mit denselben Regeln und denselben Grenzen, nur jetzt pro Verknüpfung und mit deinem Backend-Key:

{
  "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}     # der Block hat sich geändert und wurde verteilt
200 {"published":true,"changed":false}    # identisch mit dem Gespeicherten; nur die TTL wurde erneuert
204                                        # gespeichert, aber der Spieler ist gerade nicht online in mssgs
410 {"error":"LINK_REVOKED"}               # der Spieler hat getrennt: Verknüpfung verwerfen

Behandle 200 und 204 gleich: gespeichert. { "activity": null } löscht den Block; sende das, wenn der Spieler geht. Ein Unterschied zur Bridge: Der Host von join.url muss eines deiner registrierten Backends sein (oder eine Subdomain davon), sonst bekommst du 400 INVALID_PAYLOAD. So kann ein Backend keinen Button „Jetzt mitmachen“ in den Status eines Spielers setzen, der irgendwohin führt, wo dieser Spieler nie gespielt hat.

Mit Hunderten Spielern online sendest du den Heartbeat in einem Aufruf, bis zu 100 Einträge auf einmal. Jeder Eintrag bekommt seinen eigenen Status, sodass ein Spieler, der in mssgs getrennt hat, nie die anderen neunundneunzig aufhält:

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

Wie der Status angezeigt wird

• Genau wie ein Bridge-Status: Spielt CozyCity · Lantern Hollow · 6/40 Spieler, mit Jetzt mitmachen, wenn es eine join.url gibt. Der Block wird serverseitig mit via: "backend" gestempelt, sodass ein Client „Vom Server des Spiels geteilt“ dazuschreiben kann.
• Nur solange der Spieler in mssgs online ist. Ist kein mssgs-Client geöffnet, ist das Konto offline und bleibt offline; dein Backend kann niemanden anwesend aussehen lassen. Das verhindert auch, dass dieser Weg zum Peilsender „sitzt René an seinem Computer“ wird.
• Vorrang: ein Spiel in der App > ein Spiel über die Bridge > dein Backend. Setzt sich der Spieler in mssgs an eine Partie Schach, während dein Backend weiter Heartbeats sendet, gewinnt Schach, nicht wer zuletzt geschrieben hat.

Trennen

Der Spieler sieht jede Verknüpfung unter Einstellungen → Spielaktivität → Verknüpfte Spiele, mit deinem Icon und Namen, dem Spielernamen aus deinem Spiel, wann verknüpft und wann zuletzt veröffentlicht wurde, und einem Button Trennen. Danach antwortet deine nächste Veröffentlichung mit 410 LINK_REVOKED; so erfährt dein Spiel davon. Verwirf die link_guid und biete wieder „mssgs verbinden“ an. Von deiner Seite beendest du eine Verknüpfung mit DELETE /game-sdk/v1/links/{link_guid}.

Endpoint-Referenz: die Bridge

Basis-URL http://127.0.0.1:<port>. Alles außer den ersten drei braucht Authorization: Bearer <token>.

Endpoint-Referenz: verknüpfte Backends

Basis-URL https://ams1-gateway.mss.gs. Jede Route braucht Authorization: Bearer <backend key> und den Scope activity.write in deiner Registrierung; Antworten gehen mit Cache-Control: no-store raus. Ruf sie von deinem Server auf, nie vom Spiel-Client.

Fehlercodes

Fehler kommen als {"error":"CODE","message":"…"} mit passendem HTTP-Status zurück.

Verknüpfte Backends

Die Backend-Routen nutzen dieselbe Form. Innerhalb eines Batches kommt der Status pro Eintrag in results zurück, sodass eine beendete Verknüpfung nie den ganzen Aufruf scheitern lässt.

Sicherheit

Nur native Spiele

Anfragen mit dem Origin einer Webseite werden mit 403 ORIGIN_NOT_ALLOWED abgelehnt. Wenn jede Webseite erkennen könnte, dass du mssgs nutzt, und einen Erlaubnis-Dialog auslösen könnte, wäre das eine Angriffsfläche für Fingerprinting und Phishing, kein Feature. Ein natives Spiel sendet überhaupt keinen Origin, ist also nicht betroffen, und der eingebettete Browser eines Spiels ist namentlich erlaubt, siehe FiveM. Baust du ein Browser- oder Handyspiel, sprichst du nicht mit der Bridge: Dein eigenes Backend veröffentlicht für verknüpfte Spieler, siehe Browser- und Handyspiele.

Was der Spieler in der Hand behält

• Der Spieler kann die Bridge unter Einstellungen → Spielaktivität ausschalten, danach kann kein Spiel mssgs mehr sehen.
• Jedes genehmigte Spiel steht dort mit genau den Berechtigungen, die es hat, wann es zuletzt aktiv war, und einem Button Entfernen. Entfernen wirkt sofort: Das Token ist auf der Stelle ungültig.
• Ein verknüpftes Browser- oder Handyspiel steht unter Verknüpfte Spiele mit einem Button Trennen. Auch Trennen wirkt sofort: Die nächste Veröffentlichung dieses Backends bekommt ein 410.
• Die Bridge lauscht nur auf 127.0.0.1, nie im Netzwerk.
• Direktnachrichten werden nie preisgegeben, auch nicht mit servers.list.
• Pro Spiel gibt es ein Budget von 120 Anfragen pro Minute.

Ein guter Nachbar sein

• Frag nach Scopes, wenn du sie brauchst, nicht alle auf einmal beim ersten Start.
• Funktioniere ohne mssgs: Der Spieler muss es nicht haben.
• Lösch deinen Status, wenn das Spielen aufhört, statt auf die TTL zu warten.
• Behandle einen abgelehnten Scope als normales Ergebnis, nicht als Fehler.