---
title: "Game SDK: näita, mida mängijad mssgs’is mängivad"
description: "Avalda oma mängust „Playing“ olek nupuga Join now ja kontrolli kogukonna liikmesust. mssgs Game SDK natiiv-, brauseri- ja telefonimängudele."
canonical: https://docs.mss.gs/et/game-sdk
language: et
---

# Näita, mida keegi mängib

Lase oma mängul öelda mssgs’ile, mida mängija parasjagu teeb. Sõbrad näevad tema nime all „Playing“, avavad üksikasjad ja vajutavad Join now, et samasse mängu hüpata. Sinu mäng saab ka kontrollida, kas mängija on sinu kogukonnas.

## Mida saad teha

- **Avalda mänguolek** Mäng, mida mängija parasjagu teeb, tema roll ja kui täis grupp on.

- **Lisa nupp Join now** Sõbrad liituvad ühe vajutusega sama mängu, serveri või lobbyga.

- **Kontrolli liikmesust** Küsi, kas mängija on sinu kogukonnas ja millised rollid tal seal on.

- **Arvuti, brauser või telefon** Natiivsed mängud kasutavad kohalikku silda; brauseri- ja telefonimängud käivad läbi sinu backendi.

Rakenduses

Olek nime all ja üksikasjad, mis sellest avanevad. Mäng avaldas ühe JSON-ploki; ülejäänu teeb rakendus.

- [Ülevaade](#overview)

- [Kliendi leidmine](#discover)

- [Loa küsimine](#authorize)

- [Mänguolek](#activity)

- [Join now](#join)

- [Brauser ja telefon](#linked)

- [Teatmik](#reference)

## Ülevaade

mssgs’i arvutirakendus käitab väikest **kohalikku HTTP-silda**, millega samas arvutis olev mäng suhtleb. Sinu mäng ei suhtle kunagi meie serveritega, ei näe kunagi konto parooli ega tokenit ega saa kunagi mängija nimel postitada. See suhtleb selle mssgs’i koopiaga, kuhu mängija on juba sisse logitud, ja see koopia otsustab, mida vastata.

Mida sellega teha saab:

- Tuvastada, et mssgs on paigaldatud ja keegi on sisse logitud.

- Lugeda, kes mängija on: user_guid, username, avatar.

- Küsida „kas see mängija on kogukonnas X?“ ja millist rolli ta seal kannab.

- Avaldada teistele „Playing …“ olek nupuga **Join now**.

- Võtta vastu liitumisandmed, kui keegi seda nuppu vajutab.

### Kaks teed sisse

**Natiivne arvutimäng** suhtleb kohaliku sillaga; sellest räägivad järgmised jaotised. **Brauseris või telefonis** töötav mäng selle sillani ei ulatu. Nende puhul avaldab olekut sinu enda backend nende mängijate eest, kes on oma mssgs’i konto QR-koodi või kaheksamärgilise koodiga sidunud: vaata [Brauseri- ja telefonimängud](#linked), esimese näitena [CozyCity](https://cozycity.net). Mänguolek ise on mõlemal juhul sama plokk.

### Vaikimisi minimaalne avalikustamine

Ulatused on teadlikult ebavõrdsed. Kui sul on vaja teada ainult seda, „kas see inimene on meie kogukonnas“, küsid ulatust membership.query ja annad server_guid väärtuse ise: saad jah/ei ja tema rollid seal ega saa midagi teada tema ülejäänud kogukondade kohta. Täielik nimekiri on eraldi, kõrgema ulatuse taga, mille mängija peab omaette heaks kiitma.

## Kliendi leidmine

Sild kuulab ainult aadressil 127.0.0.1 , väikese vahemiku esimesel vabal pordil. Proovi neid järjest, kuni mõni vastab: **7440, 7441, 7442, 7443**. mssgs’i arendusversioonid kuulavad selle asemel portidel **7540–7543**, nii et testversioon ei vasta kunagi päris mängu päringutele.

Tokenit pole vaja ja vastus ei ütle mängija kohta midagi, ainult seda, et mssgs on olemas ja kas keegi on sisse logitud.

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

Enne edasi minemist kontrolli product === "mssgs" ja api . Kui ükski neljast pordist ei vasta, mssgs ei tööta. Paku siis lihtsalt oma tavalist kogemust, selle asemel et mängijat ootama panna.

## Loa küsimine

Kõik peale /hello vajab tokenit ja token tekib alles siis, kui mängija on sinu mängu rakenduse dialoogis heaks kiitnud. Küsi ainult neid ulatusi, mida tegelikult kasutad: mängija näeb igaüht eraldi koos selgitusega ja saab igaühelt eraldi linnukese ära võtta.

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

Tagasi saad {"status":"pending","request_id":"…","poll_after_ms":1000} ja mängija näeb dialoogi. Seejärel küsitle, kuni ta vastab (päring aegub 3 minuti pärast):

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

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

### Kontrolli alati, mida tegelikult said

Vastuses olev scopes võib olla **lühem** kui see, mida küsisid: mängija võib üksikutelt ulatustelt linnukese ära võtta. Ülaltoodud näites lükati membership.query tagasi. Lähtu sellest, mida vastus ütleb, mitte sellest, mida küsisid, muidu tabab sind 403 MISSING_SCOPE , mida sa ei osanud oodata.

Salvesta token ja saada see kujul Authorization: Bearer <token> . See püsib üle taaskäivituste, nii et mängija kiidab sinu mängu heaks ühe korra, mitte igal seansil. Kui hiljem autoriseerid uuesti juba antud ulatustega, saad sama tokeni kohe tagasi, ilma dialoogita.

## Ulatused ja privaatsus

Viis ulatust annavad välja väga erineva hulga andmeid. See pole juhuslik, see ongi kogu disaini mõte. Küsi nii vähe kui võimalik, liikudes selles tabelis ülevalt alla.

| Ulatus | Mida see lubab | Millest mängija loobub |
| --- | --- | --- |
| presence.write | **Näitab, mida mängija mängib** | Mitte midagi. See ulatus ainult kirjutab; see ei loe üldse kontoandmeid. |
| identity | **Kes mängija on** | user_guid, username, kuvatav nimi, avatari URL. |
| staff | **Personali / moderaatori lipud** | Kaks tõeväärtust lisaks ulatusele identity. Eraldi, sest mängul, mis näitab nime, pole asja teada, et mängija modereerib kogukondi. |
| membership.query | **Kontrollib kogukonda, mida juba tead** | Sinu antud server_guid kohta: jah/ei, selle nimi ja rollid, mis mängijal seal on. Mitte midagi ühegi teise kogukonna kohta. |
| servers.list | **Kõik kogukonnad, kus mängija on** | Täielik nimekiri: guidid, nimed, ikoonid ja rollid. See on kallis ulatus: küsi seda ainult siis, kui sul on seda tõesti vaja. |

### Enamikule mängudest piisab kahest

identity ja presence.write katavad „kes sa oled“ ja „näita, mida sa mängid“, mis on peaaegu iga integratsioon. Lisa membership.query , kui tahad siduda auhinna oma kogukonna liikmesusega. Ulatust servers.list pole sul peaaegu kunagi vaja ja mängija näeb seda punasega esile tõstetuna.

## Liikmesuse kontrollimine

See on alternatiiv palvele „anna mulle kogu nimekiri“. Annad oma kogukonna server_guid väärtuse (mida sa juba tead) ja saad vastuse ainult selle kohta.

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

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

# pole liige ja muud midagi:
# {"server_guid":"…","member":false}
```

„Ei“ tähendab täpselt seda ja mitte midagi enamat. Ühes päringus võid anda kuni 10 guidi (korda parameetrit server_guid või eralda need komadega), siis saad tagasi massiivi results . Gruppi @everyone pole kunagi loendis roles : see kehtib iga liikme kohta, nii et see ei ütle sulle midagi.

## Mänguoleku avaldamine

Üks PUT-päring paneb „Playing …“ rea mängija nime alla kõikjal, kus tema kogukonnad teda näevad.

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

Kohustuslik on ainult name . Vastus ütleb, kui kaua olek kestab ja kui tihti heartbeati saata:

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

### Heartbeat, muidu olek kaob

Olek, millest pole 90 sekundit elumärki tulnud, kustutatakse automaatselt. See on teadlik valik: kui sinu mäng kokku jookseb, ei jää mängija tundideks „mängima“. Saada iga 30 sekundi järel POST /mssgs/v1/activity/heartbeat ja korrektsel sulgemisel DELETE /mssgs/v1/activity .

### Mängijate arv ja roll

party.kind otsustab, milline lause kuvatakse, sest samad kaks numbrit ei tähenda alati sama asja. Neljaliikmeline meeskond pole server, kus on neli mängijat.

| kind | Kuvatakse kui | Milleks |
| --- | --- | --- |
| party (vaikimisi) | 3 of 4 in the party | meeskond, salk või grupp |
| server | 4/100 players | mänguserver (FiveM, kogukonna server) |
| lobby | 4/100 players | lobby enne matši algust |
| match | 4/100 players | käimasolev matš või raund |

role (kuni 48 märki) on see, *kellena* mängija mängib: amet, klass või tegelane. Sellel on oma väli, mitte järjekordne lause väljal state , sest seda näidatakse sildina mängijate arvu kõrval.

details ja state on piiratud kumbki 128 märgiga, name 64 märgiga. Reavahetused ja juhtmärgid eemaldatakse. **Ikooni URL-i teadlikult ei toetata**: selle laadiks alla iga klient, mis rea kuvab, ja nii muutuks olek majakaks, mis raporteerib sinu serverile iga liikme igast kogukonnast, kus mängija on.

## Nupp Join now

Pane oma tegevusse plokk join ja teised liikmed saavad oleku kõrvale nupu **Join now**. Selleks on kaks viisi ja neid võib kombineerida.

### 1. Saladus (natiivsetele mängudele)

Määra {"join":{"secret":"raid-42"}} . Kui keegi vajutab Join now, toimetatakse see saladus *tema enda* koopiale sinu mängust, tema enda arvutis, sobitatuna sama game_id järgi. Ühtegi URL-i ei avata ja ühtegi skeemi käsitlejat ei käivitata. Sinu mäng korjab selle üles nii:

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

Küsitle parameetriga ?since=<cursor> , et näha iga sündmust ainult üks kord. Kui vajutaja mäng ei tööta, ei toimetata midagi kohale, ja see on hea põhjus pakkuda ka URL-i.

### 2. https-URL (veebimängudele ja lobby linkidele)

Määra {"join":{"url":"https://play.example.com/s/abc"}} ja nupp avab selle lingi. **Lubatud on ainult https .** Kohandatud skeem ( steam:// , mygame:// , file:// ) lükatakse tagasi: see plokk jõuab iga liikme ekraanile ja selline URL on viis panna kellegi teise arvuti käivitama kohalikku käsitlejat sinu valitud argumentidega.

### Kõik join-plokis on avalik

Join-plokk saadetakse kõigile, kes mängija olekut näevad; see ongi nupu Join now mõte. Käsitle seda seega nagu lobby koodi, mitte nagu sisselogimisandmeid. Ära pane sinna kunagi midagi, mis peab salajaseks jääma, ja lase oma koodidel aeguda.

## FiveM

FiveM-i kliendipoolses Lua keskkonnas pole HTTP-d, nii et ressurss suhtleb sillaga **NUI** kaudu: see on CEF-vaade, mis saadab Origin päise. Sild aktsepteerib neid päritolusid selgesõnaliselt: https://cfx-nui-<resource> ja vanemat nui://<resource> . Tavalised veebilehed lükatakse endiselt tagasi ja avatud veebis olev leht ei saa seda päritolu enda omaks kuulutada; brauser määrab selle ise.

```lua
-- NUI-leht teeb HTTP-päringu; Lua saadab sellele ainult andmed.
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: olek aegub 90 s pärast
  end
end)
```

```javascript
const BASE = 'http://127.0.0.1:7440/mssgs/v1';   // proovi 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']          // rohkem pole siin vaja
    })
  });
  const started = await res.json();
  if (started.status === 'approved') { return started.token; }

  // Mängija näeb nüüd mssgs’is loa dialoogi.
  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' } // sinu cfx.re link
    })
  });
});
```

Tulemus: **Playing FiveM · Los Santos Roleplay · 4/100 players · Police**, koos nupuga Join now, mis avab sinu cfx.re lingi.

### Küsi ainult ulatust presence.write

Mänguolek ei vaja midagi muud: see ulatus ei loe üldse midagi. Kui tahad siduda mängusisese auhinna oma mssgs’i kogukonna liikmesusega, lisa membership.query ja anna oma server_guid; mängija teiste kogukondade kohta ei saa sa ikka midagi teada.

### Server, kus mängid, pole automaatselt usaldusväärne

Iga FiveM-i server saab käitada kliendiressursse, nii et iga server, millega keegi liitub, saab luba küsida. Just seepärast on vahepeal dialoog, mis nimetab ressursi: otsustab mängija, mitte server.

## Brauseri- ja telefonimängud: sidumine sinu backendi kaudu

Brauseri vahelehel või telefonis töötav mäng ei ulatu ülalkirjeldatud sillani. Sild töötab mängija arvutis ja vahel on kolm müüri: sild lükkab tagasi iga päringu, millel on brauseri Origin , Chrome näitab loaküsimust, enne kui avalik leht saab pöörduda aadressi 127.0.0.1 poole, ja Safari keeldub otse, ning telefonil pole arvuti loopbackini üldse teed.

Seega pöördub suund ümber. **Sinu enda backend teab juba, kes mängib, ja annab sellest mssgs’ile teada** nende mängijate puhul, kes on oma mssgs’i konto sinu mänguga sidunud. Sidumine kinnitatakse *mssgs’i rakenduses*, mitte kunagi sinu mängus, ja see loob seose, mitte kunagi seanssi: miski allpool ei saa kedagi sisse logida ega mängija nimel tegutseda. Sinu mängu klient ei näe kunagi võtit ega suhtle kunagi mss.gs-iga. Esimene mäng sellel teel on [CozyCity](https://cozycity.net), linnaehitusmäng, mis ilmub WebGL-lehena ja iPhone’i rakendusena ilma arvutiversioonita; allolevad näited on tema omad.

### 1. Registreeri oma mäng

Registreeri mäng [Game SDK registreerimislehel](https://mss.gs/et/docs/game-sdk/register): sinu game_id (näiteks com.deverence.cozycity ), nimi ja ikoon, mida mängija kinnituslehel näeb, ning sinu backendi hostinimed. Vaatame selle seal üle ja kui see on heaks kiidetud, ootab samal lehel sinu **backendi võti**, mida näidatakse ühe korra; meie hoiame alles ainult selle räsi. Võti kuulub sinu serverisse ja mitte kuhugi mujale. Saad seda seal igal ajal vahetada ja vana jääb 24 tunniks kehtima, et juurutus jõuaks rahulikult läbi minna.

[Registreeri oma mäng](https://mss.gs/et/docs/game-sdk/register)

Nimi ja ikoon kinnituslehel **tulevad alati registreeringust**, mitte kunagi päringust. Muidu saaks andmepüügilink sidumispäringu riietada ükskõik milliseks mänguks. Hostinimed piiravad, kuhu join.url tohib viidata, vaata allpool.

### 2. Seo mängija

Mängija valib sinu mängus **Connect mssgs**. Sinu mäng küsib sinu backendilt ja sinu backend küsib meilt:

```bash
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 on sinu enda püsiv ID selle mängija jaoks (kuni 128 märki), mitte seansi või matši jaoks; player_name (kuni 64) on see, mida kinnitusleht näitab kujul „Player: …“. Anna oma mängukliendile ainult link_code , qr_url ja deep_link . device_code on sinu küsitlemise käepide ja jääb serverisse.

Seejärel näitab sinu mäng korraga kolme asja, sest mängija võib olla ükskõik kus:

- **QR-kood** väärtusest qr_url . Telefon, kus on mssgs, avab selle otse rakenduse kinnituslehele. Ilma rakenduseta jõuab see lehele mss.gs-is, mis näitab koodi ja pakub allalaadimist.

- **Nupp „Open in mssgs“** lingiga deep_link , brauserile arvutis, kus töötab ka arvutirakendus. See on ainus väline URL, mida sinu mäng kunagi avama peab.

- **Kood ise**, kahes neljases rühmas, sisestamiseks menüüs **Settings → Game Activity → Link a game**. Tähestikus pole 0/O ega 1/I, nii et sisestamisel läheb harva midagi valesti.

Mida mängija mssgs’is näeb; rakendus koostab selle registreeringu põhjal:

### Connect CozyCity to your mssgs account?

CozyCity will be able to show what you are playing as your mssgs status. It will not see your messages, your friends or your servers, and it cannot post as you. Player: *René's city* · **Connect** / **Not now**

Vahepeal küsitleb sinu backend iga interval sekundi järel (kiiremini küsides tuleb vastuseks 429 SLOW_DOWN ), kuni olek muutub. Kood töötab ühe korra ja aegub kümne minuti pärast:

```bash
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"}      # mängija valis Not now
# {"status":"expired"}
# {"status":"linked","link_guid":"…","user":{"user_guid":"62e377…"}}
```

Salvesta link_guid oma mängija juurde; nüüdsest on see aadress, mille jaoks avaldad. Vastuses on ainult user_guid ; username lisatakse ainult siis, kui sinu registreeringul on ulatus identity.link , ja rohkem pole midagi. Teine kinnitus sama player_ref jaoks **asendab** varasema seose, nii et üks sinu mängu mängija on üks mssgs’i konto. Sama mssgs’i konto võib olla seotud mitme mänguga ja ühe mängu mitme player_ref väärtusega (pere iPad).

### 3. Avalda mänguolek

Sama plokk nagu [sillal](#activity), samade reeglite ja piirangutega, ainult nüüd iga seose kohta eraldi ja sinu backendi võtmega:

```json
{
  "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=…" }
  }
}
```

```bash
200 {"published":true,"changed":true}     # plokk muutus ja saadeti laiali
200 {"published":true,"changed":false}    # sama mis salvestatud; värskendati ainult TTL-i
204                                        # salvestatud, aga mängija pole praegu mssgs’is võrgus
410 {"error":"LINK_REVOKED"}               # mängija katkestas seose: kustuta see
```

Käsitle vastuseid 200 ja 204 ühtemoodi: salvestatud. { "activity": null } tühjendab ploki, saada see, kui mängija lahkub. Üks erinevus sillast: join.url host peab olema üks sinu registreeritud backendidest (või selle alamdomeen), muidu saad 400 INVALID_PAYLOAD . Nii ei saa backend panna mängija olekule nuppu Join now, mis viib kuhugi, kus see mängija pole kunagi mänginud.

### Heartbeat iga 60 sekundi järel, TTL 120

Avaldatud olek elab ilma uue sõnumita **120 sekundit** ja kaob siis ise. Saada seega sama plokki uuesti iga 60 sekundi järel; muutmata plokk ei maksa midagi ja värskendab ainult TTL-i. Kui sinu heartbeat lakkab, kaob ka „Playing …“ rida, ja just see ongi mõte.

Kui võrgus on sadu mängijaid, saada heartbeat ühe päringuga, kuni 100 kirjet korraga. Iga kirje saab oma oleku, nii et üks mängija, kes mssgs’is seose katkestas, ei peata kunagi ülejäänud üheksakümmend üheksat:

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

### Kuidas olekut näidatakse

- Täpselt nagu silla olek: **Playing CozyCity · Lantern Hollow · 6/40 players**, koos nupuga Join now, kui on olemas join.url . Server märgistab ploki kui via: "backend" , nii et klient võib lisada „Shared by the game's server“.

- **Ainult siis, kui mängija on mssgs’is võrgus.** Kui ükski mssgs’i klient pole avatud, on konto võrgust väljas ja jääb selleks; sinu backend ei saa panna kedagi kohalolevana paistma. See takistab ka seda, et sellest teest saaks „kas René on arvuti taga“ majakas.

- Eelisjärjekord: **rakendusesisene mäng > mäng sillal > sinu backend**. Kui mängija istub mssgs’is male mängima, samal ajal kui sinu backend heartbeate saadab, võidab male, mitte see, kes viimasena kirjutas.

### Seose katkestamine

Mängija näeb iga seost jaotises **Settings → Game Activity → Linked games** koos sinu ikooni ja nimega, sinu mängust pärit mängijanimega, sidumise ja viimase avaldamise ajaga ning nupuga **Disconnect**. Pärast seda vastab sinu järgmine avaldamine 410 LINK_REVOKED ; nii saab sinu mäng sellest teada. Kustuta link_guid ja paku uuesti „Connect mssgs“. Enda poolt lõpetad seose päringuga DELETE /game-sdk/v1/links/{link_guid} .

### Piirangud

Iga seose kohta loetakse *muudatust* kõige rohkem iga 2 sekundi järel; muutmata heartbeat on tasuta. Iga võtme kohta on 600 päringut minutis ja koondpäringu kirjed loetakse eraldi: 300 mängija heartbeat iga 60 sekundi järel kulutab 600-st 5.

## Endpointide teatmik: sild

Baas-URL http://127.0.0.1:<port> . Kõik peale kolme esimese nõuavad päist Authorization: Bearer <token> .

| Meetod | Tee | Scope | Mida teeb |
| --- | --- | --- | --- |
| GET | /mssgs/v1/hello | puudub | Kas mssgs on olemas, mida see toetab ja kas keegi on sisse logitud. Ainus marsruut, mis ei vaja tokenit, ja see ei ütle mängija kohta midagi. |
| POST | /mssgs/v1/authorize | puudub | Küsi mängijalt luba. Avab rakenduses dialoogi ja tagastab request_id, mida küsitleda. |
| GET | /mssgs/v1/authorize/:request_id | puudub | pending, approved (koos tokeniga), denied või expired. |
| GET | /mssgs/v1/me | identity | Sisse logitud mängija. Lisab is_staff / is_moderator ainult ulatusega staff. |
| GET | /mssgs/v1/membership | membership.query | Liikmesus kogukondades, mille server_guid väärtused annad (kuni 10, korduvalt või komadega eraldatult). |
| GET | /mssgs/v1/servers | servers.list | Kõik kogukonnad, kus mängija on, koos tema rollidega. Otsesõnumeid ei kaasata kunagi. |
| PUT | /mssgs/v1/activity | presence.write | Avalda „Playing …“ plokk. Tagastab TTL-i ja selle, kui tihti heartbeati saata. |
| POST | /mssgs/v1/activity/heartbeat | presence.write | Hoia avaldatud tegevus elus ilma seda uuesti saatmata. |
| DELETE | /mssgs/v1/activity | presence.write | Tühjenda see kohe, korrektseks sulgemiseks. |
| GET | /mssgs/v1/events | presence.write | Sinu mängule suunatud liitumisandmed. Küsitle parameetriga ?since=<cursor>. |
| GET | /mssgs/v1/session | puudub | Mida see token hoiab: game_id, antud ulatused, kas keegi on sisse logitud. |
| DELETE | /mssgs/v1/session | puudub | Anna luba tagasi. Sama tulemus, kui mängija tühistab selle jaotises Settings. |

## Endpointide teatmik: seotud backendid

Baas-URL https://ams1-gateway.mss.gs . Iga marsruut nõuab päist Authorization: Bearer <backend key> ja sinu registreeringul ulatust activity.write ; vastused saadetakse päisega Cache-Control: no-store . Kutsu neid välja oma serverist, mitte kunagi mängukliendist.

| Meetod | Tee | Mida teeb |
| --- | --- | --- |
| POST | /game-sdk/v1/link/start | Alusta seost ühe oma mängija jaoks ({ player_ref, player_name? }). Tagastab link_code, device_code, qr_url, deep_link, expires_in ja interval. |
| POST | /game-sdk/v1/link/poll | { device_code } → pending, denied, expired või linked koos link_guid ja user väärtusega. |
| DELETE | /game-sdk/v1/links/{link_guid} | Lõpeta seos enda poolt. Mängija saab sama teha jaotises Settings. |
| PUT | /game-sdk/v1/links/{link_guid}/activity | Avalda ühe mängija „Playing …“ plokk; { "activity": null } tühjendab selle. |
| POST | /game-sdk/v1/activity/batch | Sama kuni 100 mängija jaoks ühe päringuga. Iga kirje vastab eraldi. |

## Veakoodid

Vead tulevad tagasi kujul {"error":"CODE","message":"…"} koos vastava HTTP olekukoodiga.

| Kood | Tähendus |
| --- | --- |
| 401 UNAUTHORIZED | Token puudub või on tundmatu; autoriseeri esmalt. |
| 403 MISSING_SCOPE | Mängija ei andnud seda luba. Ta võis linnukese ära võtta. |
| 403 ORIGIN_NOT_ALLOWED | Päringul oli brauseri Origin. Vaata allpool „Ainult natiivsed mängud“. |
| 409 NOT_SIGNED_IN | mssgs töötab, aga keegi pole sisse logitud. |
| 429 RATE_LIMITED | Ühelt mängult üle 120 päringu minutis. |
| 400 INVALID_GAME_ID | game_id tohib sisaldada ainult tähti, numbreid, punkti, sidekriipsu või allkriipsu. |
| 400 TOO_MANY_GUIDS | Ühe membership-päringu kohta kõige rohkem 10 server_guid väärtust. |

### Seotud backendid

Backendi marsruudid kasutavad sama kuju. Koondpäringus tuleb olek tagasi iga kirje kohta eraldi väljal results , nii et üks lõppenud seos ei nurjata kunagi kogu päringut.

| Kood | Tähendus |
| --- | --- |
| 401 INVALID_BACKEND_KEY | Tundmatu võti või võti, mis vahetati välja rohkem kui 24 tundi tagasi. |
| 403 SCOPE_NOT_GRANTED | Sinu registreeringul pole ulatust, mida see marsruut vajab. |
| 400 INVALID_PAYLOAD | Vigane päringu sisu, üle 100 kirje koondpäringus või join.url, mille host pole üks sinu registreeritud backendidest. |
| 400 INVALID_ACTIVITY | Pärast normaliseerimist ei jäänud kasutatavat nime alles. |
| 410 LINK_REVOKED | Seos lõppes, ükskõik kummal poolel. Kustuta see ja paku uuesti „Connect mssgs“. |
| 429 SLOW_DOWN | Küsitlesid marsruuti link/poll tihemini, kui interval lubab. |
| 429 RATE_LIMITED | Ühe seose muudatus 2 sekundi jooksul eelmisest või sinu võtmel üle 600 päringu minutis. |
| 503 LINK_STORE_UNAVAILABLE | Ajutine probleem meie poolel. Proovi uuesti järgmise heartbeatiga. |

## Turvalisus

### Ainult natiivsed mängud

Päringud, millel on veebilehe Origin , lükatakse tagasi koodiga 403 ORIGIN_NOT_ALLOWED . Kui iga veebileht saaks tuvastada, et kasutad mssgs’i, ja avada loa dialoogi, oleks see sõrmejälgede kogumise ja andmepüügi pind, mitte funktsioon. Natiivne mäng ei saada üldse Origin päist, nii et teda see ei puuduta, ja mängu enda sisseehitatud brauser on nime järgi lubatud, vaata [FiveM](#fivem). Kui ehitad brauseri- või telefonimängu, sa sillaga ei suhtle: sinu enda backend avaldab seotud mängijate eest, vaata [Brauseri- ja telefonimängud](#linked).

### Mille üle mängija kontrolli säilitab

- Mängija saab silla välja lülitada jaotises **Settings → Game Activity**, misjärel ükski mäng ei näe mssgs’i üldse.

- Iga heakskiidetud mäng on seal loetletud täpselt nende õigustega, mis tal on, viimase aktiivsuse ajaga ja nupuga **Remove**. Eemaldamine on kohene: token sureb otsekohe.

- Seotud brauseri- või telefonimäng on loetletud jaotises **Linked games** nupuga **Disconnect**. Ka seose katkestamine on kohene: selle backendi järgmine avaldamine saab vastuseks 410 .

- Sild kuulab ainult aadressil 127.0.0.1, mitte kunagi võrgus.

- Otsesõnumeid ei avalikustata kunagi, isegi mitte ulatusega servers.list.

- Iga mängu kohta on piirang 120 päringut minutis.

### Hea tava

- Küsi ulatusi siis, kui neid vajad, mitte kõiki korraga esimesel käivitamisel.

- Tööta ka ilma mssgs’ita: mängijal ei pea seda olema.

- Tühjenda oma olek, kui mängimine lõpeb, selle asemel et TTL-i oodata.

- Käsitle tagasilükatud ulatust tavalise tulemusena, mitte veana.

## Ehita edasi