Основні поняття

Терміни, які решта сторінок вживає без пояснень. Для кожного тут є коротке визначення й посилання на сторінку, де описано механізм, що за ним стоїть.

Три теми завеликі для короткої статті, тож кожна має власну сторінку: Хто ухвалює рішення — хто робить виклик і що вирішує вже сам цей факт; Як побудовано SDK — з чого складається SDK; Успадкування і композиція — як модулі будуються один на одному.

Чотири способи роботи з модулем

Кожен модуль дає рівно чотири способи роботи з ним (surface), і за ними побудовано кожну сторінку модуля. Це і є модель програмування:

Спосіб	Що це означає
Оголошення (declaration)	що існує і як воно поводиться. Їх пишуть у коді або в адмін-панелі, і модель в обох випадках однакова
Хуки	ваші правила, які платформа викликає на іменованих кроках. Їх деплоять як хмарні функції
Події (event)	повідомлення платформи про те, що вже сталося. На події підписуються, а не опитують їх
Операції (operation)	те, що ви запитуєте або наказуєте зробити — з функції чи з клієнта

Актор

Той, хто робить виклик. Що дозволено виклику, вирішує актор, від імені якого його зроблено, а не збірка, у яку скомпільовано код. Чому саме так, пояснює сторінка Хто ухвалює рішення, а сам механізм — атомарні дозволи (permission atom), ролі, складені з них, і InterfaceGrant — описує сторінка Access & Roles.

Імена акторів на цих сторінках узято з пресетів, які постачає платформа. Проєкт може дати своїм акторам власні імена, а в пресетах є такі:

player · backend-service · operator · host · moderator · schema-author · architect · bot-brain · room-owner · room-visitor · entry-validator · spectator · match-organizer · warehouse-keeper · seller — і any, коли йдеться про всіх одразу.

Місце виконання

Де працює код. Ці чотири мітки трапляються в кожній таблиці операцій:

Мітка	Місце
`fn`	Хмарна функція (C# · TypeScript · Python · Go). Рішення ухвалює сервер, і саме тут насамперед живуть ваші правила
`cl`	Ігровий клієнт (Unreal C++ / Unity C#). API такий самий, але ролі (role) відкривають тут менше
`mc`	Місце роботи хоста кімнати: майстер-клієнт (клієнт, якому належить кімната) або виділений сервер Unreal з власним ключем хоста (host key)
`adm`	Адмін-панель / CLI / MCP — тут SDK і операторський рівень (operator plane) мають спільну модель

Де працює код і від чийого імені — різні речі

Де виконується код і який інтерфейс актора він має — два окремі питання. Хоч куди ви помістите той самий код, прав у нього буде стільки ж. Відрізнятися можуть лише видані права (grant).

Проєкт і середовище

Проєкт (project) — це бекенд однієї гри. Його схема й дані живуть в ізольованих середовищах (environment): dev, prod. Кожен виклик виконується в межах конкретного проєкту та середовища.

Сутність

Центральне поняття. Сутність (entity) — це оголошення в схемі (schema) разом із його живими аспектами: дані 0..*, стани 0..*, RPC 0..*, події 0..*, хуки та історія змін. Танк, двері, шкала характеристики й квест — усе це сутності, і відрізняються вони лише набором аспектів. Поширені поєднання постачаються готовими пресетами (GameObject, Stat, Character, Interactable, Projectile). Див. Entity.

Очікуваний стан

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

Відповідь описує саме цей момент і нічого не обіцяє на майбутнє. Якщо поки відповідь іде до вас, встигне застосуватися чийсь інший перехід, відповідь однаково лишається правдивою, і цей перехід її не скасовує.

Вказуйте очікуваний стан, коли це важливо

Якщо результат залежить від того, що було до переходу, вкажіть очікуваний стан. В інших випадках не вважайте відповідь снапшотом, який лишається правдивим і після виклику.

Кімната

Кімната (room) — це ігрова сесія, а не місце, де працює ваш код. Платформі байдуже, хто її хостить: виділений сервер, майстер-клієнт чи сам бекенд. Внутрішня будова кімнати — наша справа. Ви керуєте кімнатою ззовні — з хмарних функцій і клієнтів, через оголошення, хуки, події та операції. Див. Rooms.

Канал і потік даних

Асинхронні примітиви, на яких тримається все інше. Канал (channel) — це адресована тема pub/sub: кімната, група, сутність або ваш власний канал. Потік даних (stream) передає дані частинами в будь-який бік: файл читають у міру того, як надходять частини, запити можуть віддавати результат потоком, а RPC може розійтися по всій групі й зібрати відповіді. Див. Core.

Примітив

Одна з чотирьох цеглинок, з яких складено кожен модуль: події (оголосити, надіслати, підписатися), RPC (виклик через мережу), дані й підписки (механіка синхронізації) і групи (один список, багато слухачів). Кімната, чат і пул підбору гравців (matchmaking) влаштовані однаково. Усі вони — той самий примітив групи (group), лише з різними правилами.

Контракт хуків

Контракт скрізь один. Хук before виконується до валідації: він отримує типізовані дані запиту і може змінити їх або відхилити запит. Хук after виконується, коли операцію вже зафіксовано: він отримує запит і результат і може лише додати побічні ефекти — зірвати операцію він не може. Хуки виконуються в заданому порядку, і повісити їх можна на будь-який зареєстрований крок платформи. Див. Extensibility.

Дельта і ревізія

Клієнти отримують стан дельтами: приходять лише змінені поля (field), закодовані відносно останнього стану, який підтвердив отримувач. Кожен запис має ревізію, і платформа відхиляє умовний запис, якщо ревізія не збіглася. Одне й те саме поняття версії обслуговує і синхронізацію, і конкурентний доступ, і історію. Див. Data & Subscriptions.

Те, що в Unreal називають реплікацією (replication), — який клієнт який стан бачить і як часто, — описано тут, а також на сторінках Visibility і Prediction & Lag Comp. Сторінка Що лишається після втрати хоста — про інше: яка машина володіє сутністю і до якої машини вона перейде далі.

Тік

Симуляція кімнат іде з фіксованим кроком. Кожну зміну стану позначено номером тіку, тож синхронізація, передбачення, компенсація лагів та історія рахують час у тіках, а не за реальним годинником. Дані зберігають справжній час події, тому відкат і реконсиляція виходять точними. Див. Prediction & Lag Comp.