Ukaž, co kdo právě hraje

Přehled

Desktopová aplikace mssgs spouští malý lokální HTTP most, se kterým mluví hra na stejném počítači. Tvoje hra nikdy nekomunikuje s našimi servery, nikdy nevidí heslo ani token účtu a nikdy nemůže psát za hráče. Mluví s kopií mssgs, ve které je hráč už přihlášený, a ta kopie rozhoduje, co odpoví.

Co s ním můžeš dělat:

• Zjistit, že je aplikace mssgs nainstalovaná a někdo je v ní přihlášený.
• Přečíst, kdo je hráč: user_guid, username, avatar.
• Zeptat se „je tento hráč v komunitě X?“ a jakou tam má roli.
• Zveřejnit status „Playing …“ s tlačítkem Join now pro ostatní.
• Přijmout předání pro připojení, když někdo to tlačítko stiskne.

Hledání klienta

Most naslouchá jen na 127.0.0.1, na prvním volném portu z malé řady. Zkoušej je popořadě, dokud některý neodpoví: 7440, 7441, 7442, 7443. Vývojová sestavení mssgs místo toho naslouchají na 7540–7543, takže testovací sestavení nikdy neodpoví na volání skutečné 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"]
}

Než budeš pokračovat, zkontroluj product === "mssgs" a api. Pokud žádný ze čtyř portů neodpoví, mssgs neběží. Pak prostě nabídni hru jako obvykle, místo abys nechal hráče čekat.

Žádost o souhlas

Všechno kromě /hello potřebuje token a token existuje teprve poté, co hráč schválí tvou hru v dialogu v aplikaci. Žádej jen o rozsahy, které opravdu používáš: hráč vidí každý zvlášť, s vysvětlením, a může je jednotlivě odškrtnout.

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

Zpátky dostaneš {"status":"pending","request_id":"…","poll_after_ms":1000} a hráč uvidí dialog. Pak se dotazuj, dokud neodpoví (žádost vyprší po 3 minutách):

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 posílej ho jako Authorization: Bearer <token>. Přežije restarty, takže hráč schválí tvou hru jednou, ne v každé relaci. Pokud později znovu autorizuješ s rozsahy, které už byly uděleny, dostaneš rovnou stejný token bez dialogu.

Rozsahy a soukromí

Pět rozsahů prozrazuje velmi rozdílné množství údajů. Není to náhoda, na tom stojí celý návrh. Žádej o co nejméně a v tabulce postupuj shora dolů jen tak daleko, jak musíš.

Ověření členství

Tohle je alternativa k „dej mi celý seznam“. Zadáš server_guid své vlastní komunity (který už znáš) a dostaneš odpověď jen o ní.

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

# není člen, a nic dalšího:
# {"server_guid":"…","member":false}

„Ne“ znamená přesně to a nic víc. V jednom volání můžeš poslat až 10 guidů (opakuj server_guid nebo je odděl čárkami) a dostaneš pole results. Skupina @everyone v roles nikdy není: platí pro každého člena, takže ti nic neřekne.

Zveřejnění herního statusu

Jeden PUT umístí řádek „Playing …“ pod jméno hráče, všude, kde ho jeho komunity vidí.

{
  "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 jen name. Odpověď ti řekne, jak dlouho status vydrží a jak často posílat heartbeat:

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

Počet hráčů a role

party.kind určuje, jaká věta se zobrazí, protože stejná dvě čísla neznamenají totéž. Čtyřčlenná parta není server se čtyřmi hráči.

role (až 48 znaků) je to, za koho hráč hraje: povolání, třída nebo postava. Má vlastní pole místo další věty v state, protože se zobrazuje jako štítek vedle počtu hráčů.

details a state mají limit 128 znaků, name 64. Zalomení řádků a řídicí znaky se odstraní. URL adresa ikony záměrně není podporována: stahoval by ji každý klient, který řádek zobrazí, a ze statusu by se stal maják, který tvému serveru hlásí každého člena každé komunity, ve které hráč je.

Tlačítko Join now

Přidej do aktivity blok join a ostatní členové uvidí vedle statusu tlačítko Join now. Jsou dva způsoby a můžeš je kombinovat.

1. Tajný kód (pro nativní hry)

Nastav {"join":{"secret":"raid-42"}}. Když někdo stiskne Join now, tajný kód se doručí do jeho vlastní kopie tvé hry, na jeho vlastním počítači, podle stejného game_id. Neotevře se žádná URL a nespustí se žádný handler schématu. Tvoje hra si ho vyzvedne takto:

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

Dotazuj se s ?since=<cursor>, abys každou událost viděl jen jednou. Pokud hra toho, kdo tlačítko stiskl, neběží, nic se nedoručí, a to je dobrý důvod nabídnout i URL.

2. URL s https (pro webové hry a odkazy do lobby)

Nastav {"join":{"url":"https://play.example.com/s/abc"}} a tlačítko otevře tento odkaz. Přijímá se jen https. Vlastní schéma (steam://, mygame://, file://) se odmítne: ten blok se objeví na obrazovce každého člena a taková URL je způsob, jak přimět cizí počítač spustit lokální handler s argumenty, které jsi vybral ty.

FiveM

FiveM nemá ve svém klientském prostředí Lua žádné HTTP, takže resource mluví s mostem přes NUI, pohled CEF, který posílá hlavičku Origin. Most tyto originy výslovně přijímá: https://cfx-nui-<resource> a starší nui://<resource>. Běžné webové stránky jsou dál odmítány a stránka na otevřeném webu si tento origin nemůže přisvojit; nastavuje ho sám prohlížeč.

-- HTTP obstará stránka NUI; Lua jí jen předá data.
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';   // zkus 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']          // víc tu není potřeba
    })
  });
  const started = await res.json();
  if (started.status === 'approved') { return started.token; }

  // Hráč teď v mssgs vidí dialog se žádostí o souhlas.
  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' } // tvůj odkaz cfx.re
    })
  });
});

Výsledek: Playing FiveM · Los Santos Roleplay · 4/100 players · Police, s tlačítkem Join now, které otevře tvůj odkaz cfx.re.

Hry v prohlížeči a na telefonu: propojení přes tvůj backend

Hra v kartě prohlížeče nebo na telefonu se k mostu popsanému výše nedostane. Ten běží na hráčově počítači a mezi nimi stojí tři zdi: most odmítne každý požadavek s hlavičkou Origin z prohlížeče, Chrome před veřejnou stránkou, která volá 127.0.0.1, zobrazí žádost o povolení a Safari to rovnou odmítne, a telefon nemá k loopbacku počítače vůbec žádnou cestu.

Proto se směr obrací. Tvůj vlastní backend už ví, kdo hraje, a řekne to mssgs, u hráčů, kteří propojili svůj účet mssgs s tvou hrou. Propojení se schvaluje v aplikaci mssgs, nikdy ve tvé hře, a vzniká tím propojení, nikdy relace: nic z toho, co následuje, nemůže nikoho přihlásit ani jednat za hráče. Klient tvé hry nikdy nevidí klíč a nikdy nekomunikuje s mss.gs. První hrou na této cestě je CozyCity, budovatelská hra, která vychází jako stránka WebGL a aplikace pro iPhone bez desktopové verze; příklady níže jsou přímo z ní.

1. Zaregistruj svou hru

Zaregistruj hru na registrační stránce Game SDK: své game_id (například com.deverence.cozycity), název a ikonu, které hráč uvidí v okně schválení, a hostnames svého backendu. Tam ji zkontrolujeme a po schválení na tebe na stejné stránce čeká klíč backendu, zobrazený jen jednou; my si uchováváme pouze jeho otisk. Klíč patří na tvůj server a nikam jinam. Můžeš ho tam kdykoli vyměnit a starý zůstane platný 24 hodin, aby nasazení mohlo proběhnout postupně.

Zaregistruj hru

Název a ikona v okně vždy pocházejí z registrace, nikdy z požadavku. Jinak by phishingový odkaz mohl žádost o propojení přestrojit za jakoukoli hru. Hostnames určují, kam smí vést join.url, viz níže.

2. Propoj hráče

Hráč ve tvé hře zvolí Connect mssgs. Hra se zeptá tvého backendu a backend se zeptá 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álé ID toho hráče (až 128 znaků), ne relace nebo zápasu; player_name (až 64) je to, co okno ukáže jako „Player: …“. Klientovi hry předej jen link_code, qr_url a deep_link. device_code slouží k dotazování a zůstává na serveru.

Hra pak ukáže tři věci najednou, protože hráč může být kdekoli:

• QR kód z qr_url. Telefon s mssgs ho otevře rovnou v okně schválení v aplikaci. Bez aplikace skončí na stránce na mss.gs, která ukáže kód a nabídne stažení.
• Tlačítko „Open in mssgs“ s deep_link, pro prohlížeč na počítači, kde běží desktopová aplikace. Je to jediná externí URL, kterou tvoje hra kdy potřebuje otevřít.
• Samotný kód, ve dvou skupinách po čtyřech znacích, k zadání v Settings → Game Activity → Link a game. V abecedě nejsou 0/O ani 1/I, takže se při přepisování málokdy spleteš.

Co hráč uvidí v mssgs, v okně, které aplikace sestaví z registrace:

Mezitím se tvůj backend dotazuje každých interval sekund (na častější dotazy přijde 429 SLOW_DOWN), dokud se status nezmění. Kód funguje jednou a vyprší po deseti minutách:

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 ke svému hráči; od teď je to adresa, pro kterou zveřejňuješ. Odpověď obsahuje jen user_guid; username přibude jen tehdy, když má tvoje registrace rozsah identity.link, a víc nic. Druhé schválení pro stejné player_ref nahradí dřívější propojení, takže jeden hráč tvé hry je jeden účet mssgs. Stejný účet mssgs může být propojený s několika hrami a s několika player_ref jedné hry (rodinný iPad).

3. Zveřejni herní status

Stejný blok jako u mostu, se stejnými pravidly a limity, jen teď pro každé propojení zvlášť a s tvým klíčem 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 se změnil a byl rozeslán
200 {"published":true,"changed":false}    # shodný s uloženým; obnovilo se jen TTL
204                                        # uloženo, ale hráč teď není v mssgs online
410 {"error":"LINK_REVOKED"}               # hráč se odpojil: zahoď propojení

Ber 200 a 204 stejně: uloženo. { "activity": null } blok smaže, pošli ho, když hráč odchází. Jeden rozdíl oproti mostu: host v join.url musí být jeden z tvých registrovaných backendů (nebo jeho subdoména), jinak dostaneš 400 INVALID_PAYLOAD. Backend tak nemůže hráči přidat ke statusu tlačítko Join now, které vede někam, kde ten hráč nikdy nehrál.

Se stovkami hráčů online posílej heartbeat jedním voláním, až 100 položek najednou. Každá položka dostane vlastní status, takže jeden hráč, který se v mssgs odpojil, nikdy nezastaví zbylých devadesát devět:

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

Jak se status zobrazuje

• Stejně jako status z mostu: Playing CozyCity · Lantern Hollow · 6/40 players, s Join now, když je k dispozici join.url. Server blok označí via: "backend", takže klient může doplnit „Shared by the game's server“.
• Jen když je hráč v mssgs online. Bez otevřeného klienta mssgs je účet offline a offline zůstane; tvůj backend nemůže nikoho udělat přítomným. Díky tomu se z této cesty ani nestane maják „sedí René u počítače?“.
• Přednost: hra v aplikaci > hra přes most > tvůj backend. Když si hráč v mssgs sedne k šachům a tvůj backend dál posílá heartbeat, vyhrají šachy, ne ten, kdo zapsal poslední.

Odpojení

Hráč vidí každé propojení v Settings → Game Activity → Linked games, s tvou ikonou a názvem, jménem hráče z tvé hry, datem propojení a posledního zveřejnění a tlačítkem Disconnect. Na tvé další zveřejnění pak přijde odpověď 410 LINK_REVOKED; tak se to tvoje hra dozví. Zahoď link_guid a znovu nabídni „Connect mssgs“. Ze své strany propojení ukončíš přes DELETE /game-sdk/v1/links/{link_guid}.

Reference endpointů: most

Základní URL http://127.0.0.1:<port>. Všechno kromě prvních tří vyžaduje Authorization: Bearer <token>.

Reference endpointů: propojené backendy

Základní URL https://ams1-gateway.mss.gs. Každá cesta vyžaduje Authorization: Bearer <backend key> a rozsah activity.write ve tvé registraci; odpovědi odcházejí s Cache-Control: no-store. Volej je ze svého serveru, nikdy z klienta hry.

Chybové kódy

Chyby se vracejí jako {"error":"CODE","message":"…"} s odpovídajícím HTTP statusem.

Propojené backendy

Cesty backendu používají stejný tvar. V dávce se status vrací pro každou položku zvlášť v results, takže jedno ukončené propojení nikdy neshodí celé volání.

Zabezpečení

Jen nativní hry

Požadavky s hlavičkou Origin webové stránky se odmítají s 403 ORIGIN_NOT_ALLOWED. Kdyby jakákoli webová stránka mohla zjistit, že používáš mssgs, a vyvolat dialog se žádostí o souhlas, otevřelo by to cestu fingerprintingu a phishingu, nebyla by to funkce. Nativní hra Origin vůbec neposílá, takže se jí to netýká, a vestavěný prohlížeč hry je povolený jmenovitě, viz FiveM. Pokud stavíš hru pro prohlížeč nebo telefon, s mostem nemluvíš: pro propojené hráče zveřejňuje tvůj vlastní backend, viz Hry v prohlížeči a na telefonu.

Co má hráč pod kontrolou

• Hráč může most vypnout v Settings → Game Activity, a pak žádná hra mssgs vůbec neuvidí.
• Každá schválená hra je tam uvedená přesně s oprávněními, která má, s časem poslední aktivity a tlačítkem Remove. Odebrání platí okamžitě: token přestane fungovat hned.
• Propojená hra v prohlížeči nebo na telefonu je uvedená v Linked games s tlačítkem Disconnect. Odpojení také platí okamžitě: další zveřejnění toho backendu dostane 410.
• Most naslouchá jen na 127.0.0.1, nikdy v síti.
• Přímé zprávy se nikdy neprozrazují, ani se servers.list.
• Každá hra má limit 120 požadavků za minutu.

Slušné chování

• Žádej o rozsahy, až je potřebuješ, ne o všechny najednou při prvním spuštění.
• Funguj i bez mssgs: hráč ho mít nemusí.
• Když hraní skončí, smaž status, místo abys čekal na TTL.
• Odmítnutý rozsah ber jako běžný výsledek, ne jako chybu.