Составление документации по архитектуре и API модулей игр

Мы не раз сталкивались с ситуацией, когда команда тратит недели на отладку кросс-модульного взаимодействия. Например, в одном VR-проекте на Unity с Zenject баг в модуле SaveSystem проявлялся только на устройстве, потому что в редакторе использовались PlayerPrefs, а в продакшене — облачное API. Разработчик потратил 3 недели, чтобы найти причину: отсутствовала документация, описывающая эту разницу.

Документирование архитектуры модулей решает эту проблему. После внедрения документации онбординг новых разработчиков сокращается с 2 недель до 2 дней — разница в 5 раз. Экономия бюджета команды за счёт снижения времени на поддержку достигает 40%.

Ценная документация отвечает на три ключевых вопроса: почему это сделано именно так, что произойдёт в граничном случае и с чем это взаимодействует. Без ответа на эти вопросы код остаётся чёрным ящиком.

Что делает документацию по игровым модулям действительно полезной

Главная ошибка — документировать «что делает метод», когда это и так видно из сигнатуры. /// <summary>Adds item to inventory</summary> над AddItem(Item item) — бесполезная строка. Вместо этого фиксируем неочевидные детали: почему модуль использует Service Locator вместо DI, как ведёт себя при повторной инициализации, какие ресурсы освобождает в OnDestroy. Сравнение: документированные модули отлаживаются в 3 раза быстрее, чем недокументированные.

Для игровых проектов особенно важна документация по состояниям и зависимостям. Модуль SaveSystem, который работает через PlayerPrefs в Editor и через облачный API в продакшене, — это неочевидное поведение, которое нужно явно описать. Иначе разработчик пишет тест, который проходит локально и падает на устройстве.

Второй пласт — документация по потокам данных между модулями. В Unity-проектах с Zenject или VContainer зависимости инжектируются, и IDE не всегда подсказывает, откуда пришёл конкретный сервис. Architectural Decision Record (ADR) на одну страницу с диаграммой зависимостей экономит часы при онбординге.

Почему важна структура документации?

Для модульной игровой архитектуры строим документацию на нескольких уровнях:

• Обзор архитектуры — диаграмма модулей и их зависимостей (PlantUML или Mermaid, встраивается прямо в Markdown в Confluence/Notion). Обязательно: слои (Presentation, Domain, Infrastructure), направления зависимостей, что является Singleton, что создаётся через фабрику.
• Модульные карточки — для каждого крупного модуля: назначение, публичный API, события которые испускает и на которые подписывается, требования к инициализации (порядок Awake/Start), известные ограничения.
• API Reference — генерируем из XML-комментариев через DocFX. Для C# Unity-проектов DocFX даёт чистый HTML с навигацией. Настраиваем автогенерацию в CI: при каждом пуше в main обновляется документация на внутреннем сервере.
• Сценарии использования — конкретные примеры кода для неочевидных случаев. Не public void Initialize() с описанием параметров, а «как правильно инициализировать WeaponSystem в сцене, где нет PlayerController в момент старта».
• XR Interaction Flow — для VR/AR-проектов: описание последовательности событий от SelectEntered до SelectExited в XR Interaction Toolkit, маппинг кнопок контроллера, специфика работы с разными HMD (Quest vs Pico vs HTC Vive).

Какие инструменты использовать для документирования?

Комментарии в коде пишем по конвенции XML doc (C#): <summary>, <param>, <returns>, <exception>, <remarks> — последний используем для неочевидных деталей поведения.

Как строится работа

1. Аудит существующей кодовой базы. Читаем код, выявляем неочевидные паттерны, точки связи между модулями, нестандартные решения.
2. Интервью с разработчиками. Задаём вопросы по решениям, которые не объяснены в коде. Записываем как ADR.
3. Создание структуры документации. Определяем, где живёт документация (Confluence, GitHub Wiki, отдельный DocFX-сайт), какой формат для каких задач.
4. Написание и разметка. Документируем модули по приоритету: сначала самые критичные и самые непрозрачные.
5. Настройка автогенерации. CI-пайплайн для обновления API Reference при изменениях кода.
6. Ревью с командой. Разработчики подтверждают корректность, выявляем пробелы.

Что входит в работу

• Полный аудит кодовой базы с выявлением неочевидных решений
• Модульные карточки для каждого крупного модуля (до 20 штук для среднего проекта)
• API Reference с автогенерацией через DocFX или Doxygen
• Диаграммы зависимостей в Mermaid (встроенные в Markdown)
• XR Interaction Flow для VR/AR-проектов
• Настройка CI-пайплайна для автоматического обновления
• Двухнедельная поддержка после сдачи: правки по замечаниям команды

Стоимость рассчитывается индивидуально после анализа объёма кодовой базы и требований к формату документации. Опыт работы с крупными VR-проектами подтверждает эффективность нашего подхода — экономия времени на поддержку кода достигает 40%.

Свяжитесь с нами для оценки вашего проекта — мы предложим оптимальный формат и сроки. Закажите аудит текущей документации, чтобы понять, какие модули требуют описания в первую очередь. Получите консультацию по внедрению документации в ваш CI-пайплайн. Гарантируем, что после нашей работы ни один новый разработчик не потеряет день на поиск зависимостей.

VR и AR разработка

Когда мы впервые запускаем проект в VR-гарнитуре, большинство команд сталкивается с одним и тем же: технически всё работает, но в гарнитуре либо укачивает, либо руки «плавают» с задержкой, либо сцена выглядит дёрганой на периферии взгляда. Это не баги в привычном смысле — это следствие того, что VR/AR разработка требует другого подхода к архитектуре рендера, взаимодействию и UX с самого начала проекта. Наш опыт — более 7 лет в геймдеве, 15+ завершённых VR/AR-проектов для Meta Quest, SteamVR, PSVR2, HoloLens.

Платформы и SDK

Работаем со всем актуальным стеком. OpenXR используем как базовый слой везде, где это возможно — он даёт кроссплатформенность между Meta, Valve Index, HP Reverb и другими PC VR-устройствами (OpenXR на Wikipedia). Поверх OpenXR строим на XR Interaction Toolkit (Unity) или VR Expansion Plugin (Unreal).

Как минимизировать укачивание при локомоции в VR?

Locomotion — главный источник motion sickness для неопытных VR-пользователей. Согласно исследованиям, около 70% пользователей испытывают дискомфорт при неправильной настройке движения (Oculus Developer Guidelines). Teleportation — стандартный способ навигации, когда плавное передвижение нежелательно.

Компоненты из XR Interaction Toolkit: TeleportationArea, TeleportationAnchor, TeleportationProvider. Базовая реализация работает «из коробки», но для продакшна дорабатываем её в четыре шага:

1. Настройка XRRayInteractor с изогнутым лучом (Bend Ray) — дуга телепортации выглядит натуральнее прямого луча, лучше считывается пользователями.
2. Добавление валидной зоны приземления — визуальный индикатор меняет цвет при наведении на препятствие (красный/зелёный).
3. Внедрение fade transition — плавное затухание экрана (black fade) перед телепортом снижает дезориентацию.
4. Rotation snapping — после телепорта предлагаем snap-поворот на 45° или 90° вместо плавного, что снижает риск укачивания.

Для проектов, где нужна плавная локомоция (экшн-игры, симуляторы), используем comfort settings: виньетирование при движении, снижение FOV во время ускорения. Настройки доступны пользователю в меню — разные люди имеют разный порог чувствительности.

Как сделать захват объектов в VR физически реалистичным?

Это самая недооценённая часть VR-разработки. Клиенты часто воспринимают её как «просто анимация рук», но на практике — сложная система, где физическая корректность, отзывчивость и комфорт вступают в противоречие.

Grab (захват)

XR Interaction Toolkit предоставляет три типа Interactable для захвата:

• XRGrabInteractable — стандартный захват, объект следует за контроллером через физический joint или direct position/rotation
• XRSimpleInteractable — для объектов без физического перемещения (кнопки, рычаги)
• Кастомные Interactable через наследование от XRBaseInteractable

Attach Transform — часто игнорируемая деталь. У каждого Interactable должен быть правильно настроенный Attach Transform (точка, к которой рука «прилипает»). Без него рукоятка пистолета окажется по центру меша, а не там, где её держат.

Для оружия и инструментов с двуручным захватом — отдельная система TwoHandGrab: ведущая рука определяет позицию, вторая — ориентацию. XR Interaction Toolkit поддерживает это через XRTwoHandGrabInteractable или кастомную логику с двумя Attach Points.

Throw (бросок)

Почему velocity smoothing критично для реалистичного броска? Проблема в том, что Rigidbody.velocity в момент отпускания контроллера отражает мгновенную скорость, которая часто некорректна из-за дискретизации трекинга. Пользователь делает быстрое движение запястьем — а объект летит вдвое медленнее.

Решение: velocity smoothing за последние N кадров (типично 5-10 кадров, ~80-160 мс при 60 Hz) перед отпусканием. XR Interaction Toolkit делает это через VelocityEstimator. Дополнительно применяем velocity scaling multiplier — небольшое умножение скорости (1.2-1.5x) делает броски субъективно более удовлетворительными. Угловую скорость (для объектов, которые должны крутиться в полёте) тоже усредняем аналогичным образом.

AR: Plane Tracking и работа с окружением

AR добавляет другой класс проблем — работу с реальным, непредсказуемым окружением. AR Foundation — кроссплатформенный слой поверх ARKit и ARCore. Большинство базовых функций (plane detection, raycasting, image tracking, face tracking) доступны через единый API.

Plane Detection

ARPlaneManager обнаруживает горизонтальные и вертикальные плоскости. Практические нюансы:

• Инициализация занимает время — пользователь должен осмотреть помещение, пока система строит карту. Нужен явный onboarding с инструкцией «медленно поводите камерой по поверхностям».
• Плоскости нестабильны — их границы и позиция обновляются по мере накопления данных. Объекты, размещённые на плоскости, нужно привязывать через parenting к ARPlane, а не к мировым координатам.
• Слияние плоскостей — два обнаруженных сегмента пола могут слиться в один, что двигает якорь. Для критичных якорей используем ARAnchor вместо прямой привязки к плоскости.

Оптимизация для VR: фреймрейт и комфорт

VR требует стабильного высокого фреймрейта. Около 60% времени разработки в мобильном VR уходит на оптимизацию, а не на функционал — ретрофит в два раза дороже правильной архитектуры с первого спринта.

Single Pass Instanced Rendering

Главная оптимизация рендера в VR. Без неё сцена рендерится дважды (для каждого глаза), что удваивает draw calls. Single Pass Instanced рендерит оба глаза за один проход через instancing: geometry обрабатывается один раз, шейдер получает два view/projection matrix через GPU instancing. Включается в Unity через XR Plug-in Management > Rendering Mode: Single Pass Instanced. Важно: кастомные шейдеры должны поддерживать SPI — стандартные URP/HDRP шейдеры поддерживают, кастомные HLSL требуют правки (UNITY_SETUP_STEREO_EYE_INDEX_POST_VERTEX и связанные макросы). Применение этой техники сокращает количество draw calls на 40-50%.

Foveated Rendering

На Meta Quest доступен Fixed Foveated Rendering (FFR) — снижение разрешения на периферии кадра, где острота восприятия ниже. Настраивается через OVRManager или Meta XR SDK:

OVRManager.fixedFoveatedRenderingLevel = OVRManager.FixedFoveatedRenderingLevel.High;
OVRManager.useDynamicFixedFoveatedRendering = true;

Dynamic FFR автоматически повышает уровень при просадке фреймрейта — удобнее фиксированного в сценах с переменной нагрузкой.

IPD и Comfort Settings

IPD (Inter-Pupillary Distance) — расстояние между зрачками, влияет на восприятие глубины. На программируемом уровне в большинстве устройств доступно только чтение IPD (OVRPlugin.GetSystemDisplayFrequency), физическая настройка — на гарнитуре. Для приложений с точным позиционированием (медицинские симуляторы, тренинги) учитываем IPD в расчётах масштаба сцены.

Haptics

Тактильный фидбек — недооценённый инструмент. Даже простой вибрационный отклик при захвате объекта или попадании значительно повышает ощущение присутствия. В среднем интеграция тактильных паттернов занимает 30–80 часов на проект.

XR Haptics через OpenXR:

var hapticImpulse = new UnityEngine.XR.HapticCapabilities();
InputDevice device = InputDevices.GetDeviceAtXRNode(XRNode.RightHand);
device.SendHapticImpulse(0, amplitude: 0.5f, duration: 0.1f);

Для сложных паттернов (тактильная «текстура» поверхности при прикосновении, нарастающая вибрация при натяжении тетивы лука) используем Meta Haptics Studio — позволяет дизайнить haptic-клипы визуально.

Что входит в разработку VR/AR-приложения

При заказе проекта под ключ мы предоставляем:

• Архитектурный документ с описанием стека, логики рендера и системы взаимодействия
• Рабочий прототип (MVP) для тестирования на целевом устройстве
• Интеграцию необходимых SDK (Meta XR, OpenXR, AR Foundation и др.)
• Оптимизацию под целевые частоты 72/90/120 Hz с профилированием draw calls и FPS
• Тестирование на физическом оборудовании (Quest, SteamVR, HoloLens) с привлечением пользователей
• Полную документацию по сборке, деплою и поддержке
• Обучение команды заказчика (воркшоп по работе с XR Toolkit)
• Гарантийную поддержку в течение 1 месяца после сдачи

Что влияет на стоимость и сроки

VR/AR проекты дороже обычных игр аналогичного объёма. Итерации медленнее — каждую правку нужно тестировать в гарнитуре, эмулятор не передаёт реальный опыт. Motion sickness вынуждает переделывать часть концептуальных решений после первого плейтеста. Оптимизация занимает существенную долю времени — для мобильного VR (Quest) до 60-70% цикла. Для проектов под Quest начинаем оптимизацию с первого спринта. Стоимость интеграции базового SDK (XR Interaction Toolkit) обычно варьируется от 200 000 до 600 000 рублей в зависимости от объёма кастомных Interactable. Средний бюджет полного проекта под Quest составляет от 1 500 000 до 4 000 000 рублей.

Получите консультацию по вашему проекту — оценим задачу, стек и сроки. Закажите разработку VR/AR-приложения под ключ с гарантией стабильного фреймрейта.