Ukáž, čo niekto práve hrá

Prehľad

Desktopová aplikácia mssgs spúšťa malý lokálny HTTP most, s ktorým komunikuje hra na tom istom počítači. Tvoja hra nikdy nekomunikuje s našimi servermi, nikdy nevidí heslo ani token účtu a nikdy nemôže uverejňovať za hráča. Komunikuje s kópiou mssgs, v ktorej je hráč už prihlásený, a táto kópia rozhoduje, čo odpovie.

Čo s ním môžeš robiť:

• Zistiť, že je mssgs nainštalovaný a niekto je prihlásený.
• Prečítať, kto je hráč: user_guid, username, avatar.
• Opýtať sa „je tento hráč v komunite X?“ a akú rolu tam má.
• Zverejniť pre ostatných status „Playing …“ s tlačidlom Join now.
• Prijať údaje na pripojenie, keď niekto toto tlačidlo stlačí.

Hľadanie klienta

Most počúva iba na 127.0.0.1, na prvom voľnom porte z malého rozsahu. Skúšaj ich postupne, kým niektorý neodpovie: 7440, 7441, 7442, 7443. Vývojárske zostavy mssgs namiesto toho počúvajú na 7540–7543, takže testovacia zostava nikdy neodpovie na volania skutočnej hry.

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

Skôr než pôjdeš ďalej, skontroluj product === "mssgs" a api. Ak neodpovie žiadny zo štyroch portov, mssgs nebeží. Jednoducho ponúkni bežný zážitok a nenechaj hráča čakať.

Žiadosť o povolenie

Všetko okrem /hello potrebuje token a token existuje až potom, čo hráč schváli tvoju hru v dialógovom okne v aplikácii. Žiadaj len o rozsahy, ktoré naozaj používaš: hráč vidí každý zvlášť, s vysvetlením, a môže ich odškrtnúť jednotlivo.

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

Späť dostaneš {"status":"pending","request_id":"…","poll_after_ms":1000} a hráč uvidí dialógové okno. Potom sa opakovane pýtaj, kým neodpovie (žiadosť vyprší po 3 minútach):

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

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

Ulož si token a posielaj ho ako Authorization: Bearer <token>. Prežije reštarty, takže hráč schváli tvoju hru raz, nie v každej relácii. Ak neskôr znova autorizuješ s rozsahmi, ktoré už boli udelené, rovno dostaneš ten istý token, bez dialógového okna.

Rozsahy a súkromie

Päť rozsahov prezrádza veľmi rozdielne množstvo údajov. To nie je náhoda, na tom stojí celý návrh. Žiadaj čo najmenej a postupuj touto tabuľkou zhora nadol.

Overenie členstva

Toto je alternatíva k „daj mi celý zoznam“. Uvedieš server_guid vlastnej komunity (ten už poznáš) a dostaneš odpoveď iba o nej.

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

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

# nie je člen a nič viac:
# {"server_guid":"…","member":false}

„Nie“ znamená presne to a nič viac. V jednom volaní môžeš poslať až 10 guidov (zopakuj server_guid alebo ich oddeľ čiarkami) a dostaneš pole results. Skupina @everyone nikdy nie je v roles: platí pre každého člena, takže ti nič nepovie.

Zverejnenie herného statusu

Jeden PUT umiestni riadok „Playing …“ pod meno hráča, všade, kde ho vidia jeho komunity.

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

Povinné je iba name. Odpoveď ti povie, ako dlho status žije a ako často posielať heartbeat:

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

Počet hráčov a rola

party.kind určuje, ktorá veta sa zobrazí, pretože tie isté dve čísla neznamenajú to isté. Štvorčlenná partia nie je server so štyrmi hráčmi.

role (do 48 znakov) je to, za koho hráč hrá: povolanie, trieda alebo postava. Má vlastné pole namiesto ďalšej vety v state, pretože sa zobrazuje ako štítok vedľa počtu hráčov.

details a state majú limit 128 znakov, name 64. Zalomenia riadkov a riadiace znaky sa odstraňujú. URL ikony zámerne nie je podporovaná: sťahoval by ju každý klient, ktorý riadok zobrazí, a zo statusu by sa stal maják, ktorý tvojmu serveru hlási každého člena každej komunity, v ktorej hráč je.

Tlačidlo Join now

Pridaj do svojej aktivity blok join a ostatní členovia dostanú vedľa statusu tlačidlo Join now. Sú dva spôsoby a môžeš ich kombinovať.

1. Tajný reťazec (pre natívne hry)

Nastav {"join":{"secret":"raid-42"}}. Keď niekto stlačí Join now, tento reťazec sa doručí do jeho vlastnej kópie tvojej hry, na jeho vlastnom počítači, spárovanej podľa toho istého game_id. Neotvorí sa žiadna URL a nespustí sa žiadny handler schémy. Tvoja hra si ho vyzdvihne takto:

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

Pýtaj sa s ?since=<cursor>, aby ti každá udalosť prišla iba raz. Ak hra toho, kto tlačidlo stlačil, nebeží, nedoručí sa nič, a to je dobrý dôvod ponúknuť aj URL.

2. URL s https (pre webové hry a odkazy na lobby)

Nastav {"join":{"url":"https://play.example.com/s/abc"}} a tlačidlo otvorí tento odkaz. Akceptuje sa iba https. Vlastná schéma (steam://, mygame://, file://) sa odmietne: tento blok sa dostane na obrazovku každého člena a taká URL je spôsob, ako prinútiť cudzí počítač spustiť lokálny handler s argumentmi podľa tvojej voľby.

FiveM

FiveM nemá vo svojom klientskom prostredí Lua žiadne HTTP, takže zdroj (resource) komunikuje s mostom cez NUI, zobrazenie CEF, ktoré posiela Origin. Most tieto originy výslovne akceptuje: https://cfx-nui-<resource> a starší nui://<resource>. Bežné webové stránky zostávajú odmietnuté a stránka na otvorenom webe sa za tento origin vydávať nemôže; nastavuje ho sám prehliadač.

-- Stránka NUI robí HTTP; Lua jej iba posiela údaje.
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: status vyprší po 90 s
  end
end)

const BASE = 'http://127.0.0.1:7440/mssgs/v1';   // skúšaj 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']          // nič viac tu netreba
    })
  });
  const started = await res.json();
  if (started.status === 'approved') { return started.token; }

  // Hráč teraz v mssgs vidí dialóg so žiadosťou o povolenie.
  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' } // tvoj odkaz cfx.re
    })
  });
});

Výsledok: Playing FiveM · Los Santos Roleplay · 4/100 players · Police, s tlačidlom Join now, ktoré otvorí tvoj odkaz cfx.re.

Hry v prehliadači a na mobile: prepojenie cez tvoj backend

Hra v karte prehliadača alebo na mobile sa k mostu opísanému vyššie nedostane. Most beží na hráčovom počítači a v ceste stoja tri prekážky: most odmietne každú požiadavku s hlavičkou Origin prehliadača, Chrome sa pýta na povolenie, skôr než verejná stránka načíta 127.0.0.1, a Safari to rovno odmietne, a mobil sa k loopbacku počítača nedostane vôbec.

Smer sa preto otočí. Tvoj vlastný backend už vie, kto hrá, a oznámi to mssgs, a to pre hráčov, ktorí prepojili svoj účet mssgs s tvojou hrou. Prepojenie sa schvaľuje v aplikácii mssgs, nikdy v tvojej hre, a vzniká ním prepojenie, nikdy relácia: nič z toho, čo nasleduje, nemôže nikoho prihlásiť ani konať za hráča. Klient tvojej hry nikdy nevidí kľúč a nikdy nekomunikuje s mss.gs. Prvou hrou na tejto ceste je CozyCity, budovateľská hra o meste, ktorá vychádza ako stránka WebGL a aplikácia pre iPhone, bez desktopovej verzie; príklady nižšie sú priamo z nej.

1. Zaregistruj svoju hru

Zaregistruj hru na registračnej stránke Game SDK: tvoj game_id (napríklad com.deverence.cozycity), názov a ikonu, ktoré hráč uvidí v okne na schválenie, a názvy hostiteľov tvojho backendu. Tam ju posúdime a po schválení ťa na tej istej stránke čaká tvoj kľúč backendu, zobrazený iba raz; my si uchovávame len jeho odtlačok. Kľúč patrí na tvoj server a nikam inam. Kedykoľvek ho tam môžeš vymeniť a starý zostane platný 24 hodín, aby nasadenie mohlo prebehnúť postupne.

Zaregistruj svoju hru

Názov a ikona v okne vždy pochádzajú z registrácie, nikdy z požiadavky. Inak by phishingový odkaz mohol žiadosť o prepojenie vydávať za ľubovoľnú hru. Názvy hostiteľov určujú, kam môže join.url smerovať, pozri nižšie.

2. Prepoj hráča

Hráč v tvojej hre zvolí Connect mssgs. Tvoja hra sa opýta tvojho backendu a tvoj backend sa opýta nás:

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 je tvoje vlastné stále ID tohto hráča (do 128 znakov), nie relácie ani zápasu; player_name (do 64) je to, čo okno ukáže ako „Player: …“. Klientovi hry odovzdaj iba link_code, qr_url a deep_link. device_code slúži na tvoje dopytovanie a zostáva na serveri.

Tvoja hra potom ukáže naraz tri veci, pretože hráč môže byť kdekoľvek:

• QR kód z qr_url. Mobil s mssgs ho otvorí rovno v okne aplikácie na schválenie. Bez aplikácie skončí na stránke na mss.gs, ktorá ukáže kód a ponúkne stiahnutie.
• Tlačidlo „Open in mssgs“ s deep_link, pre prehliadač na počítači, kde beží desktopová aplikácia. Je to jediná externá URL, ktorú tvoja hra kedy potrebuje otvoriť.
• Samotný kód, v dvoch skupinách po štyri znaky, na zadanie v Settings → Game Activity → Link a game. Abeceda nemá 0/O ani 1/I, takže pri prepisovaní sa chyba stane len zriedka.

Čo hráč uvidí v mssgs, v okne, ktoré aplikácia vykreslí z registrácie:

Medzitým sa tvoj backend každých interval sekúnd pýta (na častejšie otázky dostane 429 SLOW_DOWN), kým sa status nezmení. Kód funguje raz a vyprší po desiatich minútach:

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"}      # hráč zvolil Not now
# {"status":"expired"}
# {"status":"linked","link_guid":"…","user":{"user_guid":"62e377…"}}

Ulož si link_guid k svojmu hráčovi; odteraz je to adresa, pre ktorú zverejňuješ. Odpoveď obsahuje iba user_guid; username sa pridá len vtedy, keď má tvoja registrácia rozsah identity.link, a nič viac už nie. Druhé schválenie pre ten istý player_ref nahradí predchádzajúce prepojenie, takže jeden hráč tvojej hry je jeden účet mssgs. Ten istý účet mssgs môže byť prepojený s viacerými hrami a s viacerými player_ref jednej hry (rodinný iPad).

3. Zverejni herný status

Ten istý blok ako pri moste, s tými istými pravidlami a limitmi, len teraz pre každé prepojenie zvlášť a s tvojím kľúčom backendu:

{
  "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}     # blok sa zmenil a bol rozoslaný
200 {"published":true,"changed":false}    # zhodný s uloženým; obnovilo sa iba TTL
204                                        # uložené, ale hráč teraz nie je online v mssgs
410 {"error":"LINK_REVOKED"}               # hráč sa odpojil: zahoď prepojenie

Ber 200 a 204 rovnako: uložené. { "activity": null } blok vymaže, pošli to, keď hráč odíde. Jeden rozdiel oproti mostu: hostiteľ v join.url musí byť jeden z tvojich registrovaných backendov (alebo jeho subdoména), inak dostaneš 400 INVALID_PAYLOAD. Backend tak nemôže do statusu hráča pridať tlačidlo Join now, ktoré vedie niekam, kde ten hráč nikdy nehral.

So stovkami hráčov online posielaj heartbeat jedným volaním, až 100 položiek naraz. Každá položka dostane vlastný status, takže jeden hráč, ktorý sa v mssgs odpojil, nikdy nezastaví ostatných deväťdesiatdeväť:

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

Ako sa status zobrazuje

• Rovnako ako status z mostu: Playing CozyCity · Lantern Hollow · 6/40 players, s Join now, keď je k dispozícii join.url. Server blok označí via: "backend", takže klient môže doplniť „Shared by the game's server“.
• Iba vtedy, keď je hráč online v mssgs. Bez otvoreného klienta mssgs je účet offline a offline aj zostane; tvoj backend nemôže spôsobiť, aby niekto vyzeral prítomný. Vďaka tomu sa z tejto cesty nestane ani maják „sedí René pri počítači?“.
• Priorita: hra v aplikácii > hra cez most > tvoj backend. Keď si hráč v mssgs sadne k šachu, zatiaľ čo tvoj backend ďalej posiela heartbeat, vyhrá šach, nie ten, kto zapísal posledný.

Odpojenie

Hráč vidí každé prepojenie v Settings → Game Activity → Linked games, s tvojou ikonou a názvom, menom hráča z tvojej hry, časom prepojenia a posledného zverejnenia a tlačidlom Disconnect. Potom na tvoje ďalšie zverejnenie príde odpoveď 410 LINK_REVOKED; tak sa to tvoja hra dozvie. Zahoď link_guid a znova ponúkni „Connect mssgs“. Zo svojej strany prepojenie ukončíš cez DELETE /game-sdk/v1/links/{link_guid}.

Referencia endpointov: most

Základná URL http://127.0.0.1:<port>. Všetko okrem prvých troch vyžaduje Authorization: Bearer <token>.

Referencia endpointov: prepojené backendy

Základná URL https://ams1-gateway.mss.gs. Každá trasa vyžaduje Authorization: Bearer <backend key> a rozsah activity.write v tvojej registrácii; odpovede odchádzajú s Cache-Control: no-store. Volaj ich zo svojho servera, nikdy z herného klienta.

Chybové kódy

Chyby sa vracajú ako {"error":"CODE","message":"…"} so zodpovedajúcim HTTP statusom.

Prepojené backendy

Trasy backendu používajú ten istý tvar. V dávke sa status vracia pre každú položku zvlášť v results, takže jedno ukončené prepojenie nikdy nezhodí celé volanie.

Bezpečnosť

Iba natívne hry

Požiadavky s hlavičkou Origin webovej stránky sa odmietnu s 403 ORIGIN_NOT_ALLOWED. Keby ľubovoľná webová stránka mohla zistiť, že používaš mssgs, a vyvolať dialóg so žiadosťou o povolenie, bola by to vstupná brána pre fingerprinting a phishing, nie funkcia. Natívna hra Origin vôbec neposiela, takže sa jej to netýka, a vlastný vstavaný prehliadač hry je povolený menovite, pozri FiveM. Ak vytváraš hru pre prehliadač alebo mobil, s mostom nekomunikuješ: za prepojených hráčov zverejňuje tvoj vlastný backend, pozri Hry v prehliadači a na mobile.

Čo má hráč stále pod kontrolou

• Hráč môže most vypnúť v Settings → Game Activity a potom už žiadna hra mssgs vôbec nevidí.
• Každá schválená hra je tam uvedená presne s povoleniami, ktoré má, s časom poslednej aktivity a tlačidlom Remove. Odstránenie platí okamžite: token hneď prestane fungovať.
• Prepojená hra v prehliadači alebo na mobile je uvedená v Linked games s tlačidlom Disconnect. Odpojenie tiež platí okamžite: ďalšie zverejnenie tohto backendu dostane 410.
• Most počúva iba na 127.0.0.1, nikdy v sieti.
• Súkromné správy sa nikdy neprezradia, ani pri servers.list.
• Každá hra má limit 120 požiadaviek za minútu.

Dobré zvyky

• Žiadaj o rozsahy, keď ich potrebuješ, nie o všetky naraz pri prvom spustení.
• Funguj aj bez mssgs: hráč ho mať nemusí.
• Keď hranie skončí, vymaž svoj status a nečakaj na TTL.
• Odmietnutý rozsah ber ako bežný výsledok, nie ako chybu.