Показуйте, у що хтось грає

Огляд

Настільний застосунок mssgs запускає невеликий локальний HTTP-міст (bridge), з яким спілкується гра на тому самому комп’ютері. Ваша гра ніколи не звертається до наших серверів, ніколи не бачить пароля чи токена облікового запису і ніколи не може дописувати від імені гравця. Вона спілкується з копією mssgs, у яку гравець уже ввійшов, і саме ця копія вирішує, що відповісти.

Що з ним можна робити:

• Визначити, що mssgs встановлено і хтось у нього ввійшов.
• Дізнатися, хто гравець: user_guid, ім’я користувача, аватар.
• Запитати «чи є цей гравець у спільноті X?» і яку роль він там має.
• Опублікувати статус «Грає …» з кнопкою «Приєднатися» для інших.
• Отримати передачу приєднання, коли хтось натискає цю кнопку.

Як знайти клієнт

Міст слухає лише 127.0.0.1, на першому вільному порту з невеликого діапазону. Перебирайте їх по черзі, доки один не відповість: 7440, 7441, 7442, 7443. Збірки mssgs для розробки натомість слухають 7540–7543, тож тестова збірка ніколи не відповідає на виклики справжньої гри.

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

Перш ніж іти далі, перевірте product === "mssgs" та api. Якщо жоден із чотирьох портів не відповідає, mssgs не запущено. Просто запропонуйте звичайний досвід гри, а не змушуйте гравця чекати.

Запит дозволу

Усе, крім /hello, потребує токена, а токен з’являється лише після того, як гравець схвалив вашу гру в діалозі всередині застосунку. Запитуйте лише ті області доступу, якими справді користуєтеся: гравець бачить кожну окремо, з поясненням, і може зняти позначку з будь-якої.

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

Ви отримуєте {"status":"pending","request_id":"…","poll_after_ms":1000}, а гравець бачить діалог. Далі опитуйте, доки він не відповість (запит спливає через 3 хвилини):

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

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

Збережіть токен і надсилайте його як Authorization: Bearer <token>. Він переживає перезапуски, тож гравець схвалює вашу гру один раз, а не на кожну сесію. Якщо згодом ви повторно авторизуєтеся з уже наданими областями доступу, ви одразу отримаєте той самий токен без діалогу.

Області доступу й приватність

П’ять областей доступу розкривають дуже різні обсяги даних. Це не випадковість, а вся суть задуму. Запитуйте якомога менше, рухаючись цією таблицею згори вниз.

Перевірка членства

Це альтернатива запиту «дайте мені весь список». Ви вказуєте server_guid власної спільноти (який ви й так знаєте) і отримуєте відповідь лише про неї.

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

# учасник:
# {"server_guid":"ca94ecc…","member":true,"name":"Acme Fans","is_owner":false,
#  "roles":[{"guid":"0aa32…","name":"Pro"}]}

# не учасник, і більше нічого:
# {"server_guid":"…","member":false}

«Ні» означає саме це і нічого більше. За один виклик можна передати до 10 guid (повторіть server_guid або перелічіть через кому), і тоді повертається масив results. Група @everyone ніколи не потрапляє в roles: вона стосується кожного учасника, тож нічого вам не каже.

Публікація ігрового статусу

Один PUT додає рядок «Грає …» під ім’ям гравця всюди, де його бачать його спільноти.

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

Обов’язкове лише поле name. Відповідь каже, скільки живе статус і як часто надсилати heartbeat:

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

Кількість гравців і роль

party.kind визначає, яке речення буде показано, бо ті самі два числа означають різне. Загін із чотирьох це не сервер, на якому четверо гравців.

role (до 48 символів) означає, ким грає гравець: професія, клас чи персонаж. Це окреме поле, а не ще одне речення в state, бо воно показується як мітка поруч із кількістю гравців.

details і state обмежено 128 символами кожне, name 64 символами. Розриви рядків і керівні символи вилучаються. URL значка навмисно не підтримується: його завантажував би кожен клієнт, що показує рядок, і статус перетворився б на маячок, який повідомляє вашому серверу про кожного учасника кожної спільноти, де є гравець.

Кнопка «Приєднатися»

Додайте до своєї активності блок join, і інші учасники побачать поруч зі статусом кнопку «Приєднатися». Є два способи, і їх можна поєднувати.

1. Секрет (для нативних ігор)

Задайте {"join":{"secret":"raid-42"}}. Коли хтось натискає «Приєднатися», цей секрет доставляється в його власну копію вашої гри, на його власному комп’ютері, за тим самим game_id. Жоден URL не відкривається і жоден обробник схеми не викликається. Ваша гра забирає його так:

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

Опитуйте з ?since=<cursor>, щоб бачити кожну подію один раз. Якщо гра того, хто натиснув, не запущена, нічого не доставляється, і це вагома причина також запропонувати URL.

2. URL https (для вебігор і посилань на лобі)

Задайте {"join":{"url":"https://play.example.com/s/abc"}}, і кнопка відкриє це посилання. Приймається лише https. Власна схема (steam://, mygame://, file://) відхиляється: цей блок з’являється на екрані кожного учасника, а такий URL дає змогу змусити чужий комп’ютер викликати локальний обробник з аргументами, які вибрали ви.

FiveM

У клієнтському Lua-середовищі FiveM немає HTTP, тож ресурс спілкується з мостом через NUI, представлення CEF, яке надсилає Origin. Міст явно приймає такі origin: https://cfx-nui-<resource> і старіший nui://<resource>. Звичайні вебсторінки й далі відхиляються, а сторінка з відкритого інтернету не може заявити такий origin: браузер встановлює його сам.

-- HTTP-запити робить сторінка NUI; Lua лише передає їй дані.
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: статус спливає через 90 с
  end
end)

const BASE = 'http://127.0.0.1:7440/mssgs/v1';   // пробуємо 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']          // більше тут нічого не потрібно
    })
  });
  const started = await res.json();
  if (started.status === 'approved') { return started.token; }

  // Тепер гравець бачить діалог дозволу в 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' } // ваше посилання cfx.re
    })
  });
});

Результат: Грає FiveM · Los Santos Roleplay · 4/100 гравців · Police, з кнопкою «Приєднатися», що відкриває ваше посилання cfx.re.

Браузерні й мобільні ігри: зв’язок через ваш бекенд

Гра у вкладці браузера або на телефоні не може дістатися до описаного вище мосту. Він працює на комп’ютері гравця, і між ними стоять три стіни: міст відхиляє кожен запит із браузерним Origin, Chrome показує запит дозволу, коли публічна сторінка звертається до 127.0.0.1, а Safari одразу відмовляє, і телефон узагалі не має шляху до loopback-інтерфейсу комп’ютера.

Тому напрям змінюється. Ваш власний бекенд уже знає, хто грає, і повідомляє про це mssgs, для гравців, які пов’язали свій обліковий запис mssgs з вашою грою. Зв’язок схвалюється у застосунку mssgs, ніколи не у вашій грі, і він створює зв’язок, а не сесію: ніщо з описаного нижче не може нікого авторизувати чи діяти від імені гравця. Клієнт вашої гри ніколи не бачить ключа і ніколи не звертається до mss.gs. Перша гра на цьому шляху це CozyCity, симулятор будівництва міста, що постачається як WebGL-сторінка та застосунок для iPhone без настільної збірки; приклади нижче взято з неї.

1. Зареєструйте свою гру

Зареєструйте гру на сторінці реєстрації Game SDK: свій game_id (наприклад, com.deverence.cozycity), назву й значок, які гравець бачить на аркуші схвалення, і хости свого бекенда. Ми перевіримо її там, і після схвалення ваш ключ бекенда чекатиме на тій самій сторінці, показаний один раз; ми зберігаємо лише його дайджест. Ключ має бути на вашому сервері й більше ніде. Там само його можна замінити будь-коли, а старий залишається дійсним 24 години, щоб деплой устиг пройти.

Зареєструвати гру

Назва й значок на аркуші завжди беруться з реєстрації, ніколи із запиту. Інакше фішингове посилання могло б видати запит на зв’язок за будь-яку гру. Хости визначають, куди може вказувати join.url, див. нижче.

2. Пов’яжіть гравця

Гравець вибирає у вашій грі «Під’єднати mssgs». Ваша гра звертається до вашого бекенда, а ваш бекенд до нас:

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 це ваш власний стабільний ID гравця (до 128 символів), а не сесії чи матчу; player_name (до 64) аркуш показує як «Гравець: …». Передавайте клієнту гри лише link_code, qr_url і deep_link. device_code це ваш дескриптор для опитування, і він лишається на сервері.

Далі ваша гра показує одразу три речі, бо гравець може бути будь-де:

• QR-код з qr_url. Телефон із mssgs відкриває його просто на аркуші схвалення в застосунку. Без застосунку він потрапляє на сторінку mss.gs, яка показує код і пропонує завантаження.
• Кнопку «Відкрити в mssgs» з deep_link, для настільного браузера поруч із настільним застосунком. Це єдиний зовнішній URL, який вашій грі будь-коли знадобиться відкрити.
• Сам код, двома групами по чотири символи, щоб ввести його в Налаштування → Ігрова активність → Пов’язати гру. В алфавіті немає 0/O та 1/I, тож помилки під час введення трапляються рідко.

Що гравець бачить у mssgs; застосунок малює це з реєстрації:

Тим часом ваш бекенд опитує кожні interval секунд (на частіші запити приходить 429 SLOW_DOWN), доки статус не зміниться. Код працює один раз і спливає через десять хвилин:

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"}      # гравець вибрав «Не зараз»
# {"status":"expired"}
# {"status":"linked","link_guid":"…","user":{"user_guid":"62e377…"}}

Збережіть link_guid для свого гравця; відтепер це адреса, для якої ви публікуєте. Відповідь містить лише user_guid; username додається, тільки якщо ваша реєстрація має область доступу identity.link, і нічого понад це. Повторне схвалення для того самого player_ref замінює попередній зв’язок, тож один гравець вашої гри це один обліковий запис mssgs. Той самий обліковий запис mssgs може бути пов’язаний із кількома іграми та з кількома player_ref однієї гри (сімейний iPad).

3. Опублікуйте ігровий статус

Той самий блок, що й для мосту, з тими самими правилами й обмеженнями, лише тепер для кожного зв’язку окремо та з вашим ключем бекенда:

{
  "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}     # блок змінився і його розіслано
200 {"published":true,"changed":false}    # збігається зі збереженим; оновлено лише TTL
204                                        # збережено, але гравець зараз не в мережі в mssgs
410 {"error":"LINK_REVOKED"}               # гравець від’єднався: видаліть зв’язок

Обробляйте 200 і 204 однаково: збережено. { "activity": null } прибирає блок; надсилайте його, коли гравець виходить. Одна відмінність від мосту: хост join.url має бути одним із ваших зареєстрованих бекендів (або його піддоменом), інакше ви отримаєте 400 INVALID_PAYLOAD. Тож бекенд не може додати до статусу гравця кнопку «Приєднатися», що веде туди, де цей гравець ніколи не грав.

Коли в мережі сотні гравців, надсилайте heartbeat одним викликом, до 100 елементів за раз. Кожен елемент отримує власний статус, тож один гравець, що від’єднався в mssgs, ніколи не зупиняє решту дев’яносто дев’ять:

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

Як показується статус

• Так само, як статус із мосту: Грає CozyCity · Lantern Hollow · 6/40 гравців, з кнопкою «Приєднатися», коли є join.url. На сервері блок позначається як via: "backend", тож клієнт може додати «Надіслано сервером гри».
• Лише поки гравець у мережі в mssgs. Якщо жоден клієнт mssgs не відкрито, обліковий запис не в мережі й таким лишається; ваш бекенд не може створити враження, що хтось присутній. Це також не дає цьому шляху стати маячком «чи Рене зараз за комп’ютером».
• Пріоритет: гра в застосунку > гра через міст > ваш бекенд. Якщо гравець сідає грати в шахи всередині mssgs, поки ваш бекенд і далі надсилає heartbeat, перемагають шахи, а не той, хто писав останнім.

Від’єднання

Гравець бачить кожен зв’язок у Налаштування → Ігрова активність → Пов’язані ігри: з вашим значком і назвою, ім’ям гравця з вашої гри, датою зв’язування й останньої публікації та кнопкою «Від’єднати». Після цього ваша наступна публікація отримує відповідь 410 LINK_REVOKED; так ваша гра про це дізнається. Видаліть link_guid і знову запропонуйте «Під’єднати mssgs». Зі свого боку ви завершуєте зв’язок через DELETE /game-sdk/v1/links/{link_guid}.

Довідник ендпоінтів: міст

Базовий URL http://127.0.0.1:<port>. Усе, крім перших трьох, потребує Authorization: Bearer <token>.

Довідник ендпоінтів: пов’язані бекенди

Базовий URL https://ams1-gateway.mss.gs. Кожен маршрут потребує Authorization: Bearer <backend key> і області доступу activity.write у вашій реєстрації; відповіді надсилаються з Cache-Control: no-store. Викликайте їх зі свого сервера, ніколи з клієнта гри.

Коди помилок

Помилки повертаються як {"error":"CODE","message":"…"} з відповідним HTTP-статусом.

Пов’язані бекенди

Маршрути бекенда використовують ту саму форму. У пакеті статус повертається для кожного елемента окремо в results, тож один завершений зв’язок ніколи не зриває весь виклик.

Безпека

Лише нативні ігри

Запити з Origin вебсторінки відхиляються з 403 ORIGIN_NOT_ALLOWED. Якби будь-яка вебсторінка могла визначити, що у вас запущено mssgs, і викликати діалог дозволу, це була б поверхня для фінгерпринтингу й фішингу, а не функція. Нативна гра взагалі не надсилає Origin, тож її це не стосується, а вбудований браузер самої гри дозволено за назвою, див. FiveM. Якщо ви створюєте браузерну чи мобільну гру, ви не звертаєтеся до мосту: ваш власний бекенд публікує для пов’язаних гравців, див. Браузерні й мобільні ігри.

Що лишається під контролем гравця

• Гравець може вимкнути міст у Налаштування → Ігрова активність, і після цього жодна гра взагалі не бачитиме mssgs.
• Кожна схвалена гра вказана там разом із точними дозволами, які вона має, часом останньої активності та кнопкою «Прибрати». Прибирання діє негайно: токен одразу перестає працювати.
• Пов’язана браузерна чи мобільна гра вказана в Пов’язані ігри з кнопкою «Від’єднати». Від’єднання теж діє негайно: наступна публікація цього бекенда отримує 410.
• Міст слухає лише 127.0.0.1, ніколи мережу.
• Особисті повідомлення ніколи не розкриваються, навіть із servers.list.
• Для кожної гри діє ліміт 120 запитів на хвилину.

Як бути добрим сусідом

• Запитуйте області доступу тоді, коли вони потрібні, а не всі одразу під час першого запуску.
• Працюйте й без mssgs: гравець не зобов’язаний його мати.
• Прибирайте свій статус, коли гра припиняється, а не чекайте на TTL.
• Сприймайте відхилену область доступу як звичайний результат, а не як помилку.