PROJECT_ARCHITECTURE.md

Основные термины

• Клиент - конечный пользователь, подключающийся к серверу. (он же игрок)
• Сервер - машина, на которой выполняется серверный код.
• Платформа - набор компонентов для разработки игрового контента. (она же Arma 3, он же Движок)
• SQF - высокоуровневый скриптовый интерпретируемый язык программирования, использующийся в платформе при разработке различных компонентов и функционала.
• Проект - совокупность исходных файлов клиента и сервера, а так же сторонних утилит для разработки контента. (он же ReSDK)
• Серверный билд - совокупность серверных модулей, запакованных в pbo файл для запуска на сервере.
• Клиенский билд - сжатый файл с клиентскими модулями, хранящийся в файле миссии, которая загружается клиенту при подключении.
• Репликация - процесс автоматического синхронизирования данных и состояния между сервером и клиентами в игровой среде. При репликации сервер передает информацию о положении объектов, действиях игроков и других важных событиях клиентам, чтобы обеспечить согласованное восприятие игрового мира на всех устройствах. Это позволяет игрокам видеть и взаимодействовать с одним и тем же игровым контентом в режиме реального времени.

Модель взаимодействия

Архитектура завязана на модели "сервер-клиент".

Концепция сервер-клиент - это модель взаимодействия между компьютерами, где сервер предоставляет ресурсы и услуги, а клиенты используют эти ресурсы и обращаются к серверу для выполнения определенных задач. В игровой среде, сервер выполняет роль центрального узла, который управляет игровой логикой, обрабатывает действия игроков, синхронизирует данные и обеспечивает согласованное состояние игрового мира. Клиенты, в свою очередь, подключаются к серверу и получают актуальные данные и обновления, отображая игровое содержимое и позволяя игрокам взаимодействовать с ним.

Пример взаимодействия

Когда игрок на клиенте нажимает кнопку "Атаковать", клиент отправляет запрос на сервер с информацией о цели атаки. Сервер принимает запрос, проверяет его на корректность и выполняет соответствующую игровую логику, например, вычитает здоровье цели и рассылает обновленную информацию о состоянии цели всем клиентам. Клиенты получают обновления от сервера и обновляют отображение игрового мира, показывая, что цель получила урон от атаки.

Файловая структура

Весь код проекта хранится в папке src. Содержимое данной папки описано ниже:

Названия, выделенные курсивом являются папками с API нижнего уровня. На них строится основа клиента или сервера и к редактированию содержимого этих модулей нужно подходить с должным вниманием.

Базовые директории

В папке src есть несколько папок:

• client - Здесь всё, что связано с работой на стороне клиента. Весь код из этой папки есть у конечного клиента при подключении к серверу.
• Editor - Редактор ReEngine. Внутри него создаются файлы конфигурации редактора (пользовательскх настроек)
• host - Это сердце проекта. Код, который выполняется на сервере. Управляет вообще всем, начиная от инициализации модулей и заканчивая обработкой подключающихся клиентов.
• ReBridge - Это компонент, реализующий связку с библиотекой ReEngine и позволяющий выполнять управляемый код, написанный на C#.
• Scripts - Базовый набор C# скриптов, с которыми тесно связана работа SDK функционала.

Серверные модули

Всё, что хранится в папке host является кодом, который будет выполняться на стороне сервера. Вот полный список модулей, существующих на сервере:

• AI - модуль искусственного интеллекта.
• AmbientControl - Модуль окружающего звука.
• CaveSystem - Система генерации пещер.
• Client - Описание класса клиента.
• ClientManager - Менеджер клиентов. Управляет подключением клиентов.
• CombatSystem - Различные классы боевой системы
• CommonComponents - Общие компоненты клиента и сервера.
• CraftSystem - Система крафта.
• Curl - Комопонент для веб-запросов.
• Database - Комопонет взаимодействия с базой данных. Поддерживается только SQLite.
• DataObjects - Классы системных объектов, например как информация об повреждениях.
• Discord - Модуль для работы с дискордом.
• FaithSystem - Религии.
• Family - Семьи.
• GameEvents - Различные игровые события
• GamemodeManager - Менеджер игровых режимов.
• GameModes - Игровые режимы.
• GameObjects - Библиотека игровых объектов.
• Gender - Описательные классы полов.
• GURPS - Модуль ролевой системы.
• Logger - Логирование в файл
• MapManager - Загрузчик карт
• MatterSystem - Система реагентов на основе хэш-карт.
• Medals - Система ачивок.
• Namings - Шаблоны имён и возможные лица персонажей.
• Networking - Различные способы взаимодействия с клиентами.
• NOEngine - Модуль репликации и управления загрузкой ресурсов клиентам (Net Objects Engine)
• ObjectiveSystem - Система задач.
• OOP_engine - ядро загрузчика и компиляции классов.
• Perks - Классы перков.
• PointerSystem - Компонент преобразования "поинтеров" в игровые объекты.
• Reagents - Новая недописанная система реагентов на основе классов.
• Reputation - Модуль репутации.
• SceneReloader - Различные загрузочные утилиты.
• ScriptErrorHandler - Обработчик ошибок выполнения.
• ServerChat - Неиспользуемые функции отправки сообщений в чат.
• ServerInteraction - Серверный обработчик взаимодействий.
• ServerLighting - Менеджер управления локальными объектами освещения на сервере.
• ServerRpc - Серверный комопнент RPC (Remote Procedure Call), регистрирует серверные обработчики, позволяет отправлять ответы клиентам.
• ServerSceneTest - Дебаг функции
• ServerVoice - Управляет радиоканалами.
• SpecialActions - Обёртка обработчиков спец.действий (пинать, бросать и т.д.)
• StatusEffects - Различные статус эффекты. Например, алкогольное опьянение.
• Tools - Инструменты SDK.
• Traits - Черты персонажа.
• UnitTests - Старый модуль юнит-тестов. Не используется.
• VerbSystem - Система действий, вызываемых на ПКМ.

Клиентские модули

Всё, что в папке client работает у локального клиента. Обратите внимание, что при сборке в клиентский билд так же копируется папака из сервера CommonComponents

• Chat - Модуль игрового чата
• ClientData - Различные системные клиентские функции
• ClientInit - Инициализатор клиента. Точка входа с отправкой первого запроса на сервер об успешном подключении.
• ClientMenus - Различные клиентские меню. Не используется.
• ClientRpc - Клиентский комопнент RPC (Remote Procedure Call), регистрирует клиентские обработчики, позволяет отправлять запросы на сервер.
• ClientStatistic - Отладочные функции для вывода основной информации на экране.
• ColorThemes - Цветовые схемы.
• CraftMenu - Меню крафта.
• DiscordRPC - Менеджер управления DiscordRichPresence
• GeometryFixer - Различные компоненты для исправления недочетов движка платформы.
• Hud - Комопонент вывода и обновления HUD-а в правой части экрана.
• InputSystem - Обработчик пользовательского ввода.
• Interactions - Функции взаимодействия.
• Inventory - Модуль инвентаря.
• LightEngine - Модуль обработки освещения. Управляет созданием и удалением источников света.
• Lobby - Менеджер лобби.
• LocalEffects - Обработчик локальных эффектов, как правило распространяющихся на коррекцию постпроцесса (размытие, коррекция цвета и т.д.).
• NetDisplays - Модуль сетевых дисплеев. Содержит шаблоны различных типов дисплеев и функции для работы с ними.
• NOEngineClient - Клиентский обработчик серверных пакетов (Net Objects Engine)
• OneSync - Обработчики некоторых особых действий и своевременное уведомление сервера о них. Например обработка падения.
• ParticleEngine - Система обработки частиц. Не используется.
• ProxyItems - Компонент создания моделей в прокси зонах инвентаря. Например в руках, за спиной персонажа и т.д.
• Rendering - Базовые утилиты для управления HDR и постпроцессом. Шаблоны различных визуальных эффектов.
• SoundSystem - Система симуляции и распределения 3d звуков, воспроизведение зацикленных звуков и воспроизведение 2д звуков.
• StaminaControl - Визуальный компонент отображения стамины.
• SyncMobData - Модуль синхронизации особых данных между клиентами. (Пример: визуальные объекты в слотах персонажей, лица, анимации держания предметов)
• Traps - Клиентское расширение системы ловушек.
• VoiceSystem - Компонент-надстройка для управления голосовыми функциями.
• WidgetSystem - Компонент для управления элементами пользовательского интерфейса.

Заголовочные файлы

В проекте чаще всего практически в каждом файле определены какие-то заголовочные файлы. Объясняем предназначение самых основных и востребованых:

• host\engine.hpp - основные макросы общего назначения и флаги компиляции (используется практически во всех файлах как на сервере так и в клиенте). Без подключения этого заголовочного файла у вас не будет доступа к флагам типа DEBUG или командам log(), warning(), error()
• host\text.hpp - макросы для работы со структурированным текстом (структурированный текст это более лайтовая версия html, реазиованная в Платформе: https://community.bistudio.com/wiki/Structured_Text). Этот заголовочный файл используется как на клиенте, так и на сервере.
• host\oop.hpp - заголовочный файл для декларации классов и работы с объектами. Там где есть классы или управление объектами, созданными из них используется этот заголовочный файл (пример: Игровые объекты, режимы, роли и т.д.). Этот заголовочный файл используется только в серверных модулях.
• host\GameObjects\GameConstants.hpp - содержит все необходимые константы и макросы для нормальной работы игровых объектов. Этот заголовочный файл используется только в серверных модулях.

Описание OOP_engine

OOP_engine - это модуль загрузки классов. (OOP - Object Orientired Programming) Он генерирует иерарихю наследования в объектно-ориентированной системе и позволяет создавать различные виртуальные объекты. Виртуальные объекты классов и самих объектов этих классов основаны на встроенном типе Location, определенном в платформе. По своей сути виртуальный объект это набор пар ключ-значение. Когда мы создаем объект какого-то класса, он имеет набор изменяемых членов (полей, переменных класса), а так же ссылку на базовый тип для получения имени класса, различные метаданные (например информацию о количестве переменных в этом классе) а также методы (функции класса). Создание классов возможно через добавление заголовочного файла oop.hpp, который импортирует макросы для декларации классов и управлении их объектами.

Создание классов реализовано с помощью групп макросов. Вот небольшой пример создания класса и манипуляции с его членами:

class(SomeName) extends(BasicClass)
	var(testNumber,1);
	var(testBool,true);

	func(testMethod)
	{
		objParams();
		private _one = getSelf(testNumber);
		private _isTrue = getVar(this,testBool);
		
		callSelfParams(printData,_isTrue);
		callFuncParams(this,printData,_one + 1);

		callFuncParams(this,printData, [1 arg 2 arg 3]);
		//same as
		private _list = [1,2,3];
		callFuncParams(this,printData,_list);
	};

	func(printData)
	{
		objParams_1(_data);
		logformat("printed: %1",_data);
	};

endclass

Обратитесь к содержимому файла oop.hpp для возможности получения расширенной информации обо всех возможных макросах, используемых при программировании классов и их объектов.

Описание системы репликации NOEngine

NOEngine (Net Objects Engine) - это система загрузки и синхронизации игровых объектов. Во время игрового процесса на средней карте создается от 2000 визуальных игровых объектов и больше. Если все эти объекты будут создаваться стандартным способом и существовать у каждого клиента (не говоря уже про всю информацию об их состоянии, начиная от названия и заканчивая различнымми числовыми переменными), то это убъет производительность и сервера и клиента.

Стандартный способ создания объектов на платформе реализован через глобальное создание и постоянную синхронизацию на клиенте. Чем больше таких объектов - тем больше нагрузка на сеть и отсюда ниже частота кадров. Данная проблема является особенностю платформы.

Для решения этой проблемы была разработана система, динамически подгружающая части карты кусками (чанками) каждому клиенту. На каждом компьютере подгружаются чанки, который находятся непосредственно в области видимости клиента. Причем все эти объекты создаются локально а репликация (изменение состояния объекта) происходит программно. Причем для распределенной нагрузки объекты делятся на несколько типов, каждый из которых имеет свою дистанцию видимости. Подробнее об этих типах объектов смотрите в следующем разделе. Игровые объекты (имеются ввиду модели), которые создаются программно на клиенте и сервере являются локальными. Отличие лишь в том, что на клиенте создаются только объекты, попадающие в область видимости конкретного клиента. На сервере же существуют все объекты.

Описание системы игровых объектов GameObjects

Все игровые объекты унаследованы от класса GameObject, определённого в host\GameObjects\GameObject.sqf. Это самый базовый класс игрового объекта, реализующий основные функции для манипуляции с ними.

Все игровые объекты можно разделить на 4 вида с соответствующими названиями классов:

• Item - базовый класс игрового предмета, который могут подбирать и использовать персонажи. Объекты, унаследованные от этого класса имеют самую меньшую дистанцию прорисовки, так как их больше всего может быть в одном чанке.
• IStruct - структуры выполняющие роль различных объектов взаимодействия, как например двери, лампы, консоли и т.д. Эти объекты встречаются чуть реже чем объекты типа Item и дистанция прорисовки у них средняя.
• Decor - различные декорации, выполняющие сугубо декоративную роль и зачастую не имеющие практически никаких способов взаимодействия. Как правило это крупные объекты типа блоков земли, зданий и огромных стен. Имеют самую большую дистанцию прорисовки.
• BasicMob - базовый класс игровой сущности, управляемой игроком или ИИ. От него наследуются мужские и женские персонажи, призраки и жруны, а в будущем и прочие живые существа.