NATS Message Broker Client¶

🇬🇧 English | 🇺🇦 Українська

Нативний клієнт NATS для Unreal Engine — Core (publish/subscribe, request/reply) і JetStream (стріми, споживачі, Key-Value), з Blueprint і з C++.

Версія 2.1 · Runtime · UE 5.8 · Примітки до випуску Win64 · Mac · Linux · iOS · Android · tvOS Без сторонніх бібліотек: протокол NATS реалізовано напряму поверх сокетів Unreal

Швидкий старт: три ноди¶

Найкоротший шлях від «щойно встановив» до «повідомлення надіслано й отримано назад».

1. Підніміть тестовий сервер (якщо ще немає свого):

docker run -p 4222:4222 -p 8222:8222 nats:latest -js

2. Підключіться й підпишіться

Get Game Instance Subsystem (Nats Client Subsystem)
   │
   ├─► Connect To Server
   │
   └─► Bind Event to On Connected
            │
            └─► Subscribe   Subject: "game.events.>"

Створювати клієнта чи зберігати його у змінній не треба — підсистема робить це за вас.

3. Опублікуйте

Get Game Instance Subsystem (Nats Client Subsystem)  →  Publish   Subject: "game.events.player.join"

Повний покроковий розбір, разом із перевіркою кнопками просто в редакторі, — у 2. Швидкому старті.

Розділи¶

Розділ	Про що
Примітки до випуску	Що з'явилося й що виправлено в кожному випуску
1. Вступ до NATS	Subject, wildcard, publish/subscribe, request/reply, Core проти JetStream — терміни, на яких тримається все інше
2. Швидкий старт	Перше підключення, перша публікація й перший стрім, крок за кроком
3. Налаштування	Сторінка Project Settings, облікові дані, компонент актора, автопідписка й автостворення ресурсів JetStream
4. Облікові дані: як не зберігати секрети в клієнті	Editor Only оверрайд для тестування й отримання облікових даних під час виконання для продакшну
5. Основний обмін повідомленнями	Підсистема, компонент чи голий клієнт; підключення, Publish/Subscribe, Request/Reply, події
6. Бінарні дані	`TArray<uint8>` замість тексту: зображення, стиснені дані, серіалізовані структури
7. JetStream: стріми	Створення й керування стрімами, retention, білдери конфігурації
8. JetStream: публікація	Публікація з підтвердженням сервера, дедуплікація, оптимістична конкурентність
9. JetStream: споживачі	Push проти pull, підтвердження Ack/Nak/Term, приклад черги завдань
10. JetStream: Key-Value	Сховище ключ-значення: ревізії, Watch у реальному часі, історія
11. Помилки та діагностика	Коди помилок, типові причини, логи, кнопки перевірки
12. Тестування та локальний сервер	Готовий Docker-сервер із плагіна, перевірка власної інтеграції, автотести
13. Поширені запитання	Короткі відповіді на те, що запитують найчастіше

Що вміє плагін¶

Core. Publish/Subscribe із шаблонами subject'ів (*/>), Request/Reply з автоматичною скринькою відповіді й тайм-аутом, заголовки повідомлень, автоматичне перепідключення до останнього сервера після розриву зв'язку.

Автентифікація. Без авторизації, Basic (логін/пароль), Token (спільний секрет), JWT — кожен спосіб доступний і зі сторінки налаштувань, і з коду в момент підключення.

Бінарні дані. Публікація, запит-відповідь і Key-Value працюють і з текстом, і з точними байтами — жоден байт (включно з нульовими) не губиться й не спотворюється на шляху.

JetStream: стріми. Персистентне зберігання повідомлень із гнучкими лімітами (кількість, розмір, вік), трьома політиками утримання (Limits, Interest, WorkQueue) і білдерами конфігурації для C++.

JetStream: споживачі. Push (сервер сам надсилає) і pull (ви самі запитуєте пакетами) споживачі, явне підтвердження (Ack/Nak/Term), гнучкий вибір точки початку читання — від початку історії, з конкретного моменту чи лише нові повідомлення.

JetStream: публікація. Підтвердження запису сервером із номером послідовності, дедуплікація за власним ідентифікатором повідомлення, оптимістична конкурентність через очікувану послідовність.

JetStream: Key-Value. Сховище ключ-значення з ревізіями, оптимістичним блокуванням, атомарним «створити, лише якщо не існує», спостереженням за змінами в реальному часі (включно з шаблонами ключів) та історією версій.

Три точки входу. Підсистема (один спільний потік на всю гру), компонент актора (з'єднання прив'язане до конкретного актора) чи голий об'єкт з'єднання для повного контролю — однаковий набір операцій у всіх трьох.

Діагностика. Структуровані коди помилок у JetStream, окремі категорії логів для кожного шару, кнопки перевірки з'єднання й JetStream прямо в Project Settings.

Чого немає¶

TLS-з'єднання. Канал наразі не шифрується — для захисту трафіка використовуйте мережеву інфраструктуру (VPN, тунель, TLS-термінацію перед сервером).
Повна децентралізована автентифікація JWT + NKey. JWT-токен передається серверу як є, без підписування виклику (nonce) приватним ключем — детальніше в 3. Налаштуваннях.
Список серверів для відмовостійкого підключення (seed list). Кожне з'єднання йде на одну конкретну адресу; при розриву клієнт повторює спроби до неї самої, а не переходить на резервний сервер кластера.
Групи черг (queue groups) на рівні Core-підписки. Для розподілу навантаження між кількома обробниками використовуйте pull-споживача JetStream — детальніше у FAQ.