Основные понятия

Термины, которые на остальных страницах используются без объяснений. Для каждого здесь есть короткое определение и ссылка на страницу, где описан механизм, который за ним стоит.

Три темы в короткую статью не помещаются, поэтому у каждой своя страница:

Кто принимает решения — кто делает вызов и что решается уже одним этим;
Как устроен SDK — из чего состоит SDK;
Наследование и композиция — как модули строятся друг на друге.

Четыре способа работы с модулем

Любой модуль даёт ровно четыре способа работы с ним, и вокруг них устроена каждая страница модуля. Это и есть модель программирования:

Способ	Что это
Объявления (declaration)	что существует и как оно себя ведёт. Их пишут в коде или в админ-панели, и модель в обоих случаях одна и та же
Хуки	ваши правила, которые платформа вызывает на именованных шагах. Деплоятся как облачные функции
События (event)	то, о чём платформа сообщает как об уже случившемся. На события подписываются, а не опрашивают
Операции (operation)	то, что вы запрашиваете или приказываете — из функции или с клиента

Актор

Тот, кто делает вызов. Что разрешено вызову, решает актор, от имени которого он сделан, а не сборка, в которую скомпилирован код. Почему так, объясняет страница Кто принимает решения, а сам механизм — атомарные разрешения (permission), роли, собранные из них, и 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 такой же, но роли открывают здесь меньше
`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), закодированные относительно последнего состояния, которое подтвердил получатель. У каждой записи есть ревизия (revision), и условная запись отклоняется, если ревизия не совпала. Одно и то же понятие версии обслуживает и синхронизацию, и конкурентный доступ, и историю. См. Data & Subscriptions.

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

Тик

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