Danro/ARCHITECTURE.md

Архитектура проекта "Mario-like platformer"

Обзор

Проект представляет собой 2D-платформер на Unity. Архитектура построена вокруг одного постоянного GameManager, набора сервисных менеджеров в Globals, компонентного игрового поведения на сценах и отдельной системы ввода, которая может работать как от клавиатуры, так и от COM-устройств.

Код в основном разделен по доменным папкам внутри Assets/Scripts, а логика сцены собирается из независимых MonoBehaviour-компонентов.

Технологический стек

• Unity (2D-проект);
• C#;
• Unity Input System;
• Unity UI (com.unity.ugui);
• Cinemachine;
• Universal Render Pipeline;
• Visual Effect Graph;
• PlayerPrefs для части runtime-данных;
• JSON через JsonUtility для сохранения настроек.

Актуальная структура проекта

Assets/Scripts/Abstract

Базовые перечисления и интерфейсы, на которых держатся общие контракты игрового кода:

• Enums.cs;
• Interfaces.cs.

Assets/Scripts/Managers

Глобальные менеджеры и сервисы верхнего уровня:

• GameManager - центральная точка управления сессией;
• AudioManager - музыка, пауза и SFX;
• PaymentManager - кредиты и логика оплаты;
• BalanceManager - баланс для запуска/продолжения игры;
• InactivityManager - реакция на бездействие;
• GlobalsManager - инициализация общих зависимостей;
• PrizeSystemManager - управление призовой системой.

Assets/Scripts/Settings

Новая система настроек, отделенная от игрового цикла:

• Core/SettingsManager - хранение значений, загрузка, сохранение, рассылка событий;
• Core/SettingsDatabase - схема настроек и значения по умолчанию;
• Core/SettingsApplier - применение значений к рантайм-системам;
• UI/* - генерация и связывание интерфейса настроек.

Assets/Scripts/Controls

Подсистема ввода и интеграции с внешним оборудованием:

• Inputs/In.cs - фасад поверх выбранного источника ввода;
• Inputs/InputSource* - абстракции и реализации источников;
• Inputs/KeyboardInput.cs - клавиатурное управление;
• Inputs/COMInput.cs - чтение данных с COM-контроллера;
• Inputs/ComSystem/* - подключение устройств, handshake, освещение, призовые стойки и маршрутизация сообщений;
• ComInputToInputSystemAdapter.cs - адаптер в сторону Unity Input System.

Assets/Scripts/Behaviour

Основная игровая логика, размещаемая на объектах сцен:

• Controllers/* - игрок, враги, сценовая музыка;
• Camera/* - слежение и ограничение поведения камеры;
• Checkpoints/* - точки возрождения и текущий активный чекпоинт;
• Projectiles/* и ThrowProjectiles/* - снаряды и логика стрельбы;
• Sequence/* - сценарные последовательности действий;
• Health, LevelFinish, ScoreSystem, MessageController, Parallax, LightDimmer, пулы VFX и окружения.

Assets/Scripts/Entities

Интерактивные сущности уровня:

• платформы (MovingPlatform, ShiftingPlatform, TrajectoryPlatform, VanishingPlatform, TriggeringPlatform, HidingTriggeringPlatform);
• собираемые объекты (CoinCollectible, LeafCollectible, BatCollectible);
• ловушки и рычаги (Trap, Lever, DeactivatingLever);
• прочие физические объекты (JumpPad2D, Rotator, Oscillator, LightActionsController).

Assets/Scripts/UI

Пользовательский интерфейс игры и служебные окна:

• главное меню, пауза, выбор уровня, финальные баннеры;
• верхняя панель статуса, отображение кредитов и баланса;
• модальная система (UI/Modal);
• текстовый ввод (UI/TextInput);
• служебные окна статистики и QR-кодов.

Дополнительные домены

• Audio - обвязка звуковых эффектов и сценовых аудио-наборов;
• Animations - обработчики animation events;
• FX - запуск визуальных эффектов;
• ScriptableObjects - конфигурация врагов, SFX и sequence actions;
• Utilities - логирование, утилиты, атрибуты, QR-коды, форматирование и отладочные настройки;
• Editor - кастомные инспекторы и drawers.

Ключевые runtime-компоненты

GameManager

GameManager создается автоматически через RuntimeInitializeOnLoadMethod, живет между сценами и является главным координационным узлом:

• инициализирует логгер;
• поднимает AudioManager;
• загружает prefab Resources/Prefabs/Global/Globals;
• получает ссылки на SettingsManager, PaymentManager, BalanceManager, ComSystemManager;
• управляет паузой, жизнями, монетами, переходами между уровнями и спавном игрока;
• публикует основные события игры (PauseStateChanged, PlayerSpawned, CoinsChanged, LivesChanged, GameOverEvent, GameWonEvent).

Globals

Глобальный prefab из Resources/Prefabs/Global/Globals выступает контейнером для постоянных компонентов, которые должны существовать независимо от текущей сцены. Через него GameManager подцепляет сервисы настроек, оплаты и COM-системы.

SettingsManager

Новая подсистема настроек работает независимо от старой игровой логики и хранит значения в persistentDataPath/settings.json:

• читает схему из SettingsDatabase;
• приводит входные значения к допустимому диапазону через Sanitize;
• применяет изменения сразу через SettingsApplier;
• сообщает об изменениях через OnSettingsLoaded, OnSettingsSaved, OnSettingChanged.

ComSystemManager

Подсистема внешних устройств отвечает за:

• обнаружение одного или нескольких COM-устройств;
• handshake и идентификацию роли устройства;
• прием монет и обновление кредитов;
• маршрутизацию входных битов от контроллера;
• управление подсветкой через LightController;
• подключение специализированных обработчиков, например призовой стойки.

Потоки управления

Запуск приложения

1. Unity вызывает автоматическую инициализацию GameManager.
2. GameManager.Awake() создает логгер, аудио и поднимает Globals.
3. Из Globals получаются ссылки на настройки, оплату, баланс и COM-систему.
4. После загрузки сцены уровня GameManager пытается заспавнить игрока в PlayerSpawn.

Старт игровой сессии

1. GameManager.NewGame() проверяет режим бесплатной игры и доступный баланс.
2. Баланс конвертируется в стартовое число жизней.
3. Сбрасываются монеты и статистика (ScoreSystem).
4. Загружается сцена первого уровня и аддитивно сцена Level UI.

Смерть и возрождение

1. Игровой объект получает урон через Health.
2. При необходимости вызывается GameManager.RespawnPlayer().
3. Менеджер уменьшает число жизней.
4. Если жизни есть, игрок переносится к активному чекпоинту или стартовой точке.
5. Если жизни закончились, вызывается событие окончания игры.

Переход между уровнями

1. LevelFinish или другая игровая логика вызывает GameManager.NextLevel().
2. GameManager вычисляет следующую сцену по схеме world-stage.
3. Если сцена существует в build settings, она загружается.
4. Если следующей сцены нет, игра считается пройденной.

Архитектурные принципы

Компонентная модель Unity

Игровая логика вынесена в независимые MonoBehaviour, которые комбинируются на prefab-ах и объектах сцен. Большинство сущностей собирается из небольших компонентов вместо глубокой иерархии наследования.

Централизованное orchestration + событийная связь

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

Конфигурация через ScriptableObject

Настройки, конфигурации врагов, аудио-наборы и сценарные действия вынесены в ресурсы, чтобы часть поведения менялась без переписывания кода.

Разделение по доменам

Код разделен не по техническим слоям MVC, а по игровым областям ответственности: Managers, Behaviour, Controls, UI, Entities, Settings.

Фасад над вводом

In.cs скрывает конкретный источник сигналов от остального игрового кода. Благодаря этому один и тот же gameplay-код может работать и с клавиатурой, и с COM-платой.

Сцены и ресурсы

Сцены

В проекте явно присутствуют:

• MainMenu;
• Level UI;
• игровые сцены уровня (например, 1-1, 99-99) по шаблону world-stage.

Resources

Критичные runtime-ресурсы, которые подгружаются из кода:

• Prefabs/Global/Globals;
• Prefabs/Player_New (или альтернативный player prefab);
• Audio/Master;
• SettingsDatabase.

Это означает, что проект по-прежнему опирается на Resources.Load для части базовой инициализации.

Пространства имен

Основные пространства имен в текущем коде:

• RR.Game2D.Core.Managers;
• RR.Common.Settings;
• RR.Common.Controls;
• RR.Common.Behaviour;
• RR.Game2D.Behaviour;
• RR.Game2D.Entities;
• RR.Common.Utility.

Что важно учитывать при изменениях

• GameManager остается точкой входа и зависит от структуры Globals; изменения в prefab-е могут ломать инициализацию всей игры.
• Схема имен сцен (1-1, 1-2 и т.д.) встроена в логику переходов между уровнями.
• Настройки частично влияют на базовый gameplay (startLives, additionalLives, параметры оплаты).
• COM-подсистема тесно связана с аркадным режимом: кредиты, свет, призовые устройства и внешний ввод.
• Для части критичных объектов используются пути в Resources, поэтому переименование или перенос этих ассетов требует обновления строковых путей в коде.