Документування архітектури та 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 будуємо на 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 Гц) перед відпусканням. 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 Гц з профілюванням draw calls та FPS
• Тестування на фізичному обладнанні (Quest, SteamVR, HoloLens) із залученням користувачів
• Повну документацію по збірці, деплою та підтримці
• Навчання команди замовника (воркшоп по роботі з XR Toolkit)
• Гарантійну підтримку протягом 1 місяця після здачі

Що впливає на вартість та терміни

VR/AR проєкти дорожчі за звичайні ігри аналогічного обсягу. Ітерації повільніші — кожну правку потрібно тестувати в гарнітурі, емулятор не передає реальний досвід. Motion sickness змушує переробляти частину концептуальних рішень після першого плейтесту. Оптимізація займає суттєву частку часу — для мобільного VR (Quest) до 60-70% циклу. Для проєктів під Quest починаємо оптимізацію з першого спринту.

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