Visa vad någon spelar

Översikt

Skrivbordsappen mssgs kör en liten lokal HTTP-brygga som ett spel på samma dator pratar med. Ditt spel pratar aldrig med våra servrar, ser aldrig ett kontolösenord eller en token och kan aldrig posta som spelaren. Det pratar med den kopia av mssgs som spelaren redan är inloggad i, och den kopian bestämmer vad som besvaras.

Det här kan du göra med den:

• Upptäcka att mssgs är installerat och att någon är inloggad.
• Läsa vem spelaren är: user_guid, användarnamn, profilbild.
• Fråga "är den här spelaren med i community X?" och vilken roll spelaren har där.
• Publicera en "Spelar …"-status med en Gå med nu-knapp för andra.
• Ta emot en överlämning när någon trycker på den knappen.

Hitta klienten

Bryggan lyssnar bara på 127.0.0.1, på den första lediga porten i ett litet intervall. Prova dem i ordning tills en svarar: 7440, 7441, 7442, 7443. Utvecklingsversioner av mssgs lyssnar i stället på 7540–7543, så att en testversion aldrig svarar på ett riktigt spels anrop.

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

Kontrollera product === "mssgs" och api innan du går vidare. Om ingen av de fyra portarna svarar körs inte mssgs. Erbjud då bara din vanliga upplevelse i stället för att låta spelaren vänta.

Be om tillåtelse

Allt utom /hello kräver en token, och en token finns bara efter att spelaren godkänt ditt spel i en dialog i appen. Be bara om de scopes du faktiskt använder: spelaren ser varje scope för sig, förklarat, och kan bocka ur dem ett och ett.

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 får tillbaka {"status":"pending","request_id":"…","poll_after_ms":1000} och spelaren ser dialogen. Polla sedan tills spelaren svarar (begäran går ut efter 3 minuter):

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

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

Spara token och skicka den som Authorization: Bearer <token>. Den överlever omstarter, så en spelare godkänner ditt spel en gång i stället för varje session. Om du senare auktoriserar på nytt med scopes som redan beviljats får du samma token direkt tillbaka, utan dialog.

Scopes och integritet

De fem scopes ger bort väldigt olika mycket. Det är ingen slump; det är hela designen. Be om så lite du kan, och arbeta dig nedåt i tabellen.

Kontrollera medlemskap

Det här är alternativet till "ge mig hela listan". Du anger server_guid för din egen community (som du redan känner till) och får ett svar om bara den.

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

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

# inte medlem, och inget annat:
# {"server_guid":"…","member":false}

Ett "nej" är precis det och inget mer. Du kan skicka upp till 10 guids per anrop (upprepa server_guid eller separera dem med komma), vilket ger en results-array. Gruppen @everyone finns aldrig i roles: den gäller varje medlem, så den säger dig ingenting.

Publicera en spelstatus

En enda PUT lägger raden "Spelar …" under spelarens namn, överallt där spelarens communities ser spelaren.

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

Bara name är obligatoriskt. Svaret talar om hur länge statusen lever och hur ofta du ska skicka heartbeat:

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

Antal spelare och roll

party.kind avgör vilken mening som visas, eftersom samma två siffror inte betyder samma sak. En trupp på fyra är inte en server med fyra spelare på.

role (upp till 48 tecken) är vad spelaren spelar som: ett jobb, en klass eller en karaktär. Det får ett eget fält i stället för ännu en mening i state, eftersom det visas som en etikett bredvid antalet spelare.

details och state är begränsade till 128 tecken var, name till 64. Radbrytningar och kontrolltecken tas bort. En ikon-URL stöds medvetet inte: den skulle hämtas av varje klient som visar raden, vilket gör en status till en fyr som rapporterar varje medlem i varje community spelaren är med i tillbaka till din server.

Knappen Gå med nu

Lägg ett join-block i din aktivitet så får andra medlemmar en Gå med nu-knapp bredvid statusen. Det finns två sätt, och du kan kombinera dem.

1. En hemlighet (för native spel)

Sätt {"join":{"secret":"raid-42"}}. När någon trycker på Gå med nu levereras hemligheten till den personens egen kopia av ditt spel, på den personens egen dator, matchad via samma game_id. Ingen URL öppnas och ingen schemahanterare anropas. Ditt spel hämtar den med:

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

Polla med ?since=<cursor> så att du ser varje händelse en gång. Om spelet hos den som tryckte inte körs levereras ingenting, vilket är ett bra skäl att också erbjuda en URL.

2. En https-URL (för webbspel och lobbylänkar)

Sätt {"join":{"url":"https://play.example.com/s/abc"}} så öppnar knappen den länken. Bara https accepteras. Ett eget schema (steam://, mygame://, file://) avvisas: blocket hamnar på varje medlems skärm, och en sådan URL är ett sätt att få någon annans dator att anropa en lokal hanterare med argument du valt.

FiveM

FiveM har ingen HTTP i sin Lua-runtime på klientsidan, så en resurs pratar med bryggan via NUI, en CEF-vy, som skickar en Origin. Bryggan accepterar de origins uttryckligen: https://cfx-nui-<resource> och den äldre nui://<resource>. Vanliga webbsidor avvisas fortfarande, och en sida på den öppna webben kan inte utge sig för att ha den origin; webbläsaren sätter den själv.

-- NUI-sidan gör HTTP-anropet; Lua skickar bara datan till den.
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: statusen går ut efter 90 s
  end
end)

const BASE = 'http://127.0.0.1:7440/mssgs/v1';   // prova 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']          // inget mer behövs här
    })
  });
  const started = await res.json();
  if (started.status === 'approved') { return started.token; }

  // Spelaren ser nu behörighetsdialogen i 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' } // din cfx.re-länk
    })
  });
});

Resultatet: Spelar FiveM · Los Santos Roleplay · 4/100 spelare · Police, med en Gå med nu-knapp som öppnar din cfx.re-länk.

Webbläsar- och telefonspel: koppla via din backend

Ett spel i en webbläsarflik eller på en telefon kan inte nå bryggan ovan. Den körs på spelarens skrivbordsdator, och tre murar står emellan: bryggan avvisar varje förfrågan som bär en webbläsar-Origin, Chrome ställer en behörighetsfråga framför en offentlig sida som hämtar från 127.0.0.1 och Safari vägrar helt, och en telefon har ingen väg alls till en skrivbordsdators loopback.

Så riktningen vänds. Din egen backend vet redan vem som spelar, och den berättar det för mssgs, för spelare som kopplat sitt mssgs-konto till ditt spel. Kopplingen godkänns i mssgs-appen, aldrig i ditt spel, och den skapar en koppling, aldrig en session: inget nedan kan logga in någon eller agera som spelaren. Din spelklient ser aldrig en nyckel och pratar aldrig med mss.gs. Det första spelet på den här vägen är CozyCity, ett stadsbyggarspel som levereras som en WebGL-sida och en iPhone-app utan skrivbordsversion; exemplen nedan är dess egna.

1. Registrera ditt spel

Registrera spelet på Game SDK:ts registreringssida: ditt game_id (till exempel com.deverence.cozycity), namnet och ikonen som spelaren ser på godkännandebladet, och dina backend-värdnamn. Vi granskar det där, och när det är godkänt väntar din backend-nyckel på samma sida, visad en gång; vi sparar bara en hash av den. Nyckeln hör hemma på din server och ingen annanstans. Du kan rotera den där när som helst, och den gamla gäller i 24 timmar till så att en deploy hinner rulla ut.

Registrera ditt spel

Namnet och ikonen på bladet kommer alltid från registreringen, aldrig från förfrågan. Annars skulle en nätfiskelänk kunna klä ut en kopplingsförfrågan till vilket spel den ville. Värdnamnen avgör vart en join.url får peka, se nedan.

2. Koppla en spelare

Spelaren väljer Koppla mssgs i ditt spel. Ditt spel frågar din backend, och din backend frågar oss:

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 är ditt eget stabila id för den spelaren (upp till 128 tecken), inte för en session eller en match; player_name (upp till 64) är det som bladet visar som "Spelare: …". Ge din spelklient bara link_code, qr_url och deep_link. device_code är ditt pollingid och stannar på servern.

Ditt spel visar sedan tre saker samtidigt, eftersom spelaren kan befinna sig var som helst:

• QR-koden för qr_url. En telefon med mssgs öppnar den direkt i appens godkännandeblad. Utan appen hamnar den på en sida på mss.gs som visar koden och erbjuder nedladdningen.
• En "Öppna i mssgs"-knapp med deep_link, för en webbläsare på en dator där skrivbordsappen också finns. Det är den enda externa URL ditt spel någonsin behöver öppna.
• Själva koden, i två grupper om fyra, att skriva in under Inställningar → Spelaktivitet → Koppla ett spel. Alfabetet saknar 0/O och 1/I, så det blir sällan fel när man skriver den.

Det här ser spelaren i mssgs, ritat av appen utifrån registreringen:

Under tiden pollar din backend var interval:e sekund (snabbare ger 429 SLOW_DOWN) tills statusen ändras. En kod fungerar en gång och går ut efter tio minuter:

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"}      # spelaren valde Inte nu
# {"status":"expired"}
# {"status":"linked","link_guid":"…","user":{"user_guid":"62e377…"}}

Spara link_guid tillsammans med din spelare; från och med nu är det adressen du publicerar för. Svaret innehåller bara user_guid; ett username läggs till endast när din registrering har scopet identity.link, och det finns inget utöver det. Ett andra godkännande för samma player_ref ersätter den tidigare kopplingen, så en spelare i ditt spel är ett mssgs-konto. Samma mssgs-konto kan kopplas till flera spel och till flera player_ref i ett och samma spel (en familje-iPad).

3. Publicera spelstatusen

Samma block som på bryggan, med samma regler och samma begränsningar, bara per koppling och med din backend-nyckel:

{
  "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}     # blocket ändrades och sändes ut
200 {"published":true,"changed":false}    # identiskt med det som var sparat; bara TTL förnyades
204                                        # sparat, men spelaren är inte online i mssgs just nu
410 {"error":"LINK_REVOKED"}               # spelaren kopplade bort: släpp kopplingen

Behandla 200 och 204 likadant: sparat. { "activity": null } rensar blocket, skicka det när spelaren slutar. En skillnad mot bryggan: värden i join.url måste vara en av dina registrerade backends (eller en underdomän till en), annars får du 400 INVALID_PAYLOAD. En backend kan alltså inte sätta en Gå med nu-knapp på en spelares status som leder någonstans där spelaren aldrig spelat.

Med hundratals spelare online skickar du heartbeat i ett enda anrop, upp till 100 poster åt gången. Varje post får sin egen status, så en spelare som kopplat bort i mssgs stoppar aldrig de andra nittionio:

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

Hur statusen visas

• Identiskt med en status från bryggan: Spelar CozyCity · Lantern Hollow · 6/40 spelare, med Gå med nu när det finns en join.url. Blocket märks med via: "backend" på serversidan, så en klient kan lägga till "Delas av spelets server".
• Bara medan spelaren är online i mssgs. Utan en öppen mssgs-klient är kontot offline och förblir offline; din backend kan inte få någon att se närvarande ut. Det hindrar också den här vägen från att bli en fyr för "sitter René vid datorn".
• Företräde: ett spel i appen > ett spel på bryggan > din backend. Om spelaren sätter sig och spelar schack i mssgs medan din backend fortsätter skicka heartbeat vinner schacket, inte den som skrev senast.

Koppla bort

Spelaren ser varje koppling under Inställningar → Spelaktivitet → Kopplade spel, med din ikon och ditt namn, spelarnamnet från ditt spel, när den kopplades och när den senast publicerade, och en Koppla bort-knapp. Därefter svarar din nästa publicering 410 LINK_REVOKED; det är så ditt spel får veta det. Släpp link_guid och erbjud "Koppla mssgs" igen. Från din sida avslutar du en koppling med DELETE /game-sdk/v1/links/{link_guid}.

Endpoint-referens: bryggan

Bas-URL http://127.0.0.1:<port>. Allt utom de tre första kräver Authorization: Bearer <token>.

Endpoint-referens: kopplade backends

Bas-URL https://ams1-gateway.mss.gs. Varje route kräver Authorization: Bearer <backend key> och scopet activity.write på din registrering; svaren skickas med Cache-Control: no-store. Anropa dem från din server, aldrig från spelklienten.

Felkoder

Fel returneras som {"error":"CODE","message":"…"} med en motsvarande HTTP-status.

Kopplade backends

Backend-routes använder samma form. Inuti en batch kommer statusen tillbaka per post i results, så en enda avslutad koppling får aldrig hela anropet att misslyckas.

Säkerhet

Bara native spel

Förfrågningar som bär en webbsidas Origin avvisas med 403 ORIGIN_NOT_ALLOWED. Att vilken webbsida som helst skulle kunna upptäcka att du kör mssgs och öppna en behörighetsdialog vore en yta för fingeravtryck och nätfiske, inte en funktion. Ett native spel skickar ingen Origin alls, så det påverkas inte, och ett spels egen inbäddade webbläsare tillåts vid namn, se FiveM. Bygger du ett webbläsar- eller telefonspel pratar du inte med bryggan: din egen backend publicerar för kopplade spelare, se Webbläsar- och telefonspel.

Det här behåller spelaren kontrollen över

• Spelaren kan stänga av bryggan under Inställningar → Spelaktivitet, och då kan inget spel se mssgs alls.
• Varje godkänt spel listas där med exakt de behörigheter det har, när det senast var aktivt, och en Ta bort-knapp. Borttagningen sker omedelbart: token slutar gälla på en gång.
• Ett kopplat webbläsar- eller telefonspel listas under Kopplade spel med en Koppla bort-knapp. Även bortkopplingen sker omedelbart: den backendens nästa publicering får en 410.
• Bryggan lyssnar bara på 127.0.0.1, aldrig på nätverket.
• Direktmeddelanden avslöjas aldrig, inte ens med servers.list.
• Varje spel har en budget på 120 förfrågningar per minut.

Var en god medborgare

• Be om scopes när du behöver dem, inte alla på en gång vid första start.
• Fungera utan mssgs: spelaren behöver inte ha det.
• Rensa din status när spelandet slutar i stället för att vänta på TTL.
• Behandla ett nekat scope som ett normalt utfall, inte som ett fel.