MiniGamesSystem

Namespace: Vortex.Sdk.MiniGamesSystem.* Assembly: ru.vortex.sdk.minigames (фреймворк) + отдельные сборки для каждой игры

Назначение

Фреймворк встраивания миниигр в основной проект. Предоставляет единый жизненный цикл, управление состояниями, статистику и шаблонизацию для создания новых миниигр.

Возможности:

• Единый жизненный цикл: инициализация → запуск → игровой процесс → завершение (победа/поражение)
• Управление состояниями (Off, Play, Win, Fail, Paused, Loading) с реактивным оповещением
• Автоматическая пауза при потере фокуса приложением
• Сбор статистики по запускам, победам и поражениям
• Подключение View через конфигурацию (префаб задаётся в ScriptableObject)
• Подмена контроллера через dropdown в инспекторе (direct DI через конфигурацию)
• Генерация бойлерплейта новой миниигры из .vtp-шаблона

Вне ответственности:

• Игровая логика конкретной миниигры (реализуется в контроллере наследника)
• Загрузка/выгрузка сцен и ресурсов
• Сетевое взаимодействие
• Сохранение прогресса миниигр между сессиями (Save/Load заложен, но не задействован)

Зависимости

Core

• Vortex.Core.System.Abstractions — Singleton<T>, IDataStorage
• Vortex.Core.AppSystem.Bus — App.OnStateChanged
• Vortex.Core.Extensions.LogicExtensions — утилиты строк, сериализации

Unity

• Vortex.Unity.Extensions.Abstractions — MonoBehaviourSingleton
• Vortex.Unity.AppSystem.System.TimeSystem — Timer, TimeController
• Vortex.Unity.UI — UIStateSwitcher, UIComponent, Pool, DataStorage
• Vortex.Unity.EditorTools — ClassFilter, AutoLink

SDK

• Vortex.Sdk.Core.GameCore — GameController, GameModel.IGameData, GameStates

Внешние

• Odin Inspector — атрибуты инспектора (InfoBox, ValueDropdown, GUIColor)

Архитектура

┌─────────────────────────────────────────────┐
│              Внешний код                     │
│     await XxxGameHub.Play(config)            │
│     hub.OnWin += ...                         │
└──────────┬──────────────────┬───────────────┘
           │                  │
           ▼                  ▼
┌────────────────────┐  ┌─────────────────────┐
│       Hub          │  │  MiniGamesController │
│ (MonoBehaviour-    │  │  (статистика,        │
│  Singleton)        │  │   регистрация)       │
│                    │  └─────────────────────┘
│ - хранит config    │
│ - создаёт Controller
│ - IDataStorage     │
│ - async Play()     │
└────────┬───────────┘
         │ создаёт (Activator)
         ▼
┌────────────────────┐
│    Controller      │
│ (Singleton, POCO)  │
│                    │
│ - владеет Data     │
│ - SetState()       │
│ - игровая логика   │
│ - реакция на       │
│   AppState         │
└────────┬───────────┘
         │ читает / изменяет
         ▼
┌────────────────────┐
│      Data          │
│ (MiniGameData)     │
│                    │
│ - State            │
│ - OnGameStateChanged
│ - OnUpdated        │
│ - параметры игры   │
└────────┬───────────┘
         │ подписка на события
         ▼
┌────────────────────┐
│      View          │
│ (MonoBehaviour)    │
│                    │
│ - получает данные  │
│   через IDataStorage
│ - отображает       │
│ - действия через   │
│   ExtLogic →       │
│   Controller       │
└────────────────────┘

Поток данных однонаправленный: Controller → Data → View. Обратная связь: View → ExtLogic (extension method) → Controller.

Ключевые концепции

Компоненты фреймворка

Переиспользуемые обработчики

Контракт

Вход

• ScriptableObject-конфиг: контроллер, View-префаб, уровни сложности
• Hub-компонент на сцене с назначенным конфигом
• PlayConfig-структура с параметрами запуска (опционально)

Выход

• async UniTask Play() — завершается при переходе в Off
• События OnWin, OnFail, OnStart на Hub'е
• Статистика в MiniGamesStatisticsData через GameController.Get<>()

Гарантии

• При GameStates.Paused — автоматическая пауза миниигры
• При GameStates.Off/Fail/Win/Loading — состояние миниигры сбрасывается в Off
• MiniGameObserver гарантирует отписку при дерегистрации
• Регистрация в MiniGamesController — автоматическая в Awake() / OnDestroy()

Ограничения

• Один экземпляр миниигры на приложение (Hub — Singleton, Controller — Singleton)
• Контроллер создаётся через Activator.CreateInstance — нужен публичный конструктор без параметров
• Тип контроллера задаётся строкой — при переименовании / смене assembly будет NullReferenceException
• Префаб View должен содержать DataStorage на корневом GameObject
• Data.State изменяется только через Controller.SetState() (кроме debug-инструментов)

Использование

Создание новой миниигры из шаблона

1. В окне Project выбрать целевую папку
2. Assets → Create → Vortex Templates → MiniGame
3. Ввести название миниигры
4. Шаблонизатор создаст структуру файлов

Структура реализации

Каждая миниигра повторяет паттерн:

MyGame/
├── Abstractions/
│   └── IMyGameController.cs       ← интерфейс контроллера
├── Config/
│   └── MyGameGeneralConfig.cs     ← ScriptableObject-конфигурация
├── Controllers/
│   ├── MyGameController.cs        ← игровая логика
│   └── MyGameDataExtLogic.cs      ← extension-методы View → Controller
├── Models/
│   ├── MyGameData.cs              ← модель данных
│   └── MyGamePlayConfig.cs        ← параметры запуска
├── View/
│   └── MyGameFieldView.cs         ← визуальное представление
├── Editor/
│   └── MyGameMenuController.cs    ← editor-утилиты
└── Prefabs/

Реализация контроллера

public class MyGameController : MiniGameController<MyGameController, MyGameData>, IMyGameController
{
    public override void Play()
    {
        Data.StartTimer(OnTimerRunOut);
        Data.OnGameStateChanged -= OnStateLogic;
        Data.OnGameStateChanged += OnStateLogic;
        SetState(MiniGameStates.Play);
    }

    public void PlayerAction(MyPieceData piece)
    {
        // игровая логика
        if (CheckWinCondition())
            SetState(MiniGameStates.Win);
    }

    private void OnTimerRunOut()
    {
        SetState(CheckWinCondition() ? MiniGameStates.Win : MiniGameStates.Fail);
    }

    private void OnStateLogic(MiniGameStates state)
    {
        switch (state)
        {
            case MiniGameStates.Play:
                Data.Timer.Resume();
                break;
            case MiniGameStates.Off:
                Data.OnGameStateChanged -= OnStateLogic;
                break;
            default:
                if (!Data.Timer.IsComplete)
                    Data.Timer.SetPause();
                break;
        }
    }
}

Связка View → Controller через ExtLogic

// ExtLogic
public static class MyGameDataExtLogic
{
    public static void PlayerAction(this MyPieceData piece) =>
        MiniGamesController.GetController<IMyGameController>().PlayerAction(piece);
}

// View вызывает extension-метод на данных — не знает о контроллере
private void OnClick() => _data.PlayerAction();

Запуск из внешнего кода

await MyGameHub.Play(new MyGamePlayConfig { Difficulty = 1 });

MyGameHub.Instance.OnWin += HandleWin;
MyGameHub.Instance.OnFail += HandleFail;

Редакторные инструменты

• Генератор из шаблона (MiniGameTemplateMenu) — создаёт полную структуру файлов новой миниигры
• Валидация контроллера — конфиг конкретной миниигры подсвечивает поле контроллера красным при невалидном типе
• Синхронизация массивов — OnLevelsChanged автоматически подгоняет длины массивов таймеров, размеров поля и пр. под количество уровней сложности
• Debug-кнопки — MockUpStateSwitcher, MiniGameCheatWinHandler, MiniGameCheatFailHandler для тестирования без прохождения

Граничные случаи