FitRPG

FitRPG — экспериментальная Android-игра, которая превращает реальные упражнения в короткие RPG-сражения. Камера телефона отслеживает позу локально на устройстве, завершённый повтор становится атакой, а тренировка — боем с противником.

Проект находится на стадии MVP. Приседания считаются основным готовым детектором; остальные упражнения доступны для быстрого тестирования, но пока отмечены как экспериментальные и требуют калибровки на реальных устройствах.

Что уже реализовано

Тренировки и распознавание движений

• семь упражнений: приседания, отжимания, подтягивания, скручивания, выпады, jumping jacks и планка;
• MediaPipe Pose Landmarker с обработкой кадров полностью на устройстве;
• 3D-геометрия суставов на основе world landmarks с резервным использованием нормализованных x/y/z координат;
• state machine для каждого упражнения: исходная позиция → целевая фаза → возврат;
• фронтальное положение относительно камеры является основным тестовым сценарием, при этом боковой ракурс продолжает поддерживаться;
• отжимания и планка могут использовать колени или лодыжки как точку опоры и не требуют идеально горизонтального положения тела в кадре;
• планка наносит один удар за каждые три секунды корректно отслеживаемого удержания;
• debug-режим позволяет симулировать повтор без камеры. Такие повторы намеренно не записываются в статистику.

Упражнение	Статус	Принцип подсчёта
Приседания	Готово	стойка → нижняя точка → стойка
Отжимания	Экспериментально	верх → сгибание рук → верх
Подтягивания	Экспериментально	прямые руки → подтягивание → прямые руки
Скручивания	Экспериментально	индивидуальная стартовая амплитуда → подъём → возврат
Выпады	Экспериментально	стойка → выпад одной ногой → стойка
Jumping Jacks	Экспериментально	закрытая → открытая → закрытая позиция
Планка	Экспериментально	интервалы корректного удержания по 3 секунды

Боевая система

• выбор одного из трёх случайных противников перед боем;
• гарантирован как минимум один противник без сопротивления выбранному упражнению;
• слабости дают множитель урона 1.5x, сопротивления — 0.75x;
• атака врага каждые 15 секунд временно снижает урон игрока на 25%;
• попадания сопровождаются анимацией, вспышкой, числом урона и изменением HP;
• победа наступает при снижении HP противника до нуля.

Прогрессия и статистика

• локальная история упражнений за 7, 30 или 90 дней;
• фильтрация статистики по упражнению;
• приблизительный расчёт калорий с учётом веса профиля или условных 70 кг;
• уровни 0–12, рассчитанные по суммарным приблизительным калориям;
• порог уровня n: 100 × 2^n ккал;
• базовые HP противников соответствуют первому уровню и растут по кубической кривой до 3x на двенадцатом уровне.

Калории являются игровой оценкой, а не медицинским измерением.

Инвентарь и задания

• локальный каталог из 36 предметов разных уровней редкости;
• экипировка по слотам тела, оружия и артефакта;
• награды-артефакты за победы над противниками с сопротивлением;
• еженедельные наборы обычных, сложных и максимальных испытаний;
• сохранение прогресса, экипировки и полученных наград на устройстве.

Интерфейс

• Jetpack Compose UI;
• экраны профиля, настроек, статистики, инвентаря, квестов, выбора врага, боя и победы;
• поддержка русского, английского, немецкого, испанского, французского и португальского языков;
• корректные отступы для жестовой и трёхкнопочной системной навигации;
• адаптивная иконка приложения.

Игровой цикл

Выбор упражнения
        ↓
Выбор одного из трёх противников
        ↓
Камера → MediaPipe → PoseFrame
        ↓
Детектор упражнения → RepetitionCompleted
        ↓
Расчёт урона и обновление статистики
        ↓
Победа → награды и прогресс квестов

Архитектура

Проект разделён на пять Gradle-модулей с направленными зависимостями:

Модуль	Ответственность
:app	Android, Compose UI, CameraX, ViewModel, локальное SharedPreferences-хранилище
:pose	адаптер MediaPipe и преобразование результатов в доменную модель позы
:domain	модели позы, типы упражнений, 3D-геометрия и детекторы повторов
:game	бой, урон, HP, слабости, сопротивления и масштабирование врагов
:data	каталоги упражнений, врагов, предметов, квестов и статистические правила

:app  → :pose, :domain, :game, :data
:pose → :domain
:data → :domain, :game
:game → :domain

CameraX и MediaPipe не проникают в боевую логику, а детекторы упражнений не знают о врагах и уроне. Подробности находятся в ARCHITECTURE.md.

Технологии

• Kotlin и Kotlin Coroutines;
• Jetpack Compose и Material 3;
• CameraX;
• MediaPipe Tasks Vision Pose Landmarker;
• AndroidX Lifecycle и StateFlow;
• Gradle Wrapper;
• JUnit 4.

Требования

• Android Studio с поддержкой текущей версии Android Gradle Plugin;
• JDK 21 для Gradle daemon (конфигурация находится в gradle/gradle-daemon-jvm.properties);
• Android SDK 36.1 для сборки;
• устройство или эмулятор с Android 12 / API 31 или новее;
• реальное устройство с фронтальной камерой для проверки распознавания поз.

Сборка и запуск

1. Клонируйте репозиторий:

   git clone https://github.com/DNA476/RPG.git
   cd RPG

2. Откройте проект в Android Studio и дождитесь Gradle Sync.

3. Подключите устройство с включённой USB-отладкой или запустите эмулятор.

4. Соберите и установите debug-вариант:

   ./gradlew :app:installDebug

   В Windows PowerShell используйте:

   .\gradlew.bat :app:installDebug

Debug APK без установки можно собрать командой:

./gradlew :app:assembleDebug

Результат находится в app/build/outputs/apk/debug/.

Проверка через тестовое видео

Debug-сборка умеет переключаться между камерой и зацикленным видео. Для этого поместите файл test_video.mp4 в:

app/src/debug/assets/raw/test_video.mp4

Видео намеренно не хранится в репозитории. Если файла нет, используйте камеру или debug-кнопку симуляции повтора.

Тестирование

Основные проверки:

./gradlew :domain:test
./gradlew :game:test :data:test
./gradlew :app:testDebugUnitTest
./gradlew :app:assembleDebug :app:assembleRelease
./gradlew :app:lintDebug

Тесты покрывают state machine детекторов, 3D-геометрию, бой, выбор врагов, инвентарь, квесты, статистику, уровни и масштабирование HP.

Данные и приватность

• кадры камеры и координаты поз не отправляются на сервер;
• профиль, статистика, инвентарь, экипировка и прогресс квестов сохраняются локально через SharedPreferences;
• аккаунты, аналитика, облачная синхронизация и backend отсутствуют;
• приложение не делает медицинских утверждений.

Известные ограничения

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

Документация проекта

• PROJECT_CONTEXT.md — текущее состояние продукта;
• ARCHITECTURE.md — модули, зависимости и runtime-поток;
• GAME_DESIGN.md — игровые правила и баланс;
• ROADMAP.md — выполненные и следующие этапы;
• IDEAS.md — ещё не утверждённые идеи;
• THIRD_PARTY_NOTICES.md — сторонние компоненты и атрибуция.

Разработка

Перед изменениями прочитайте CODEX_RULES.md. При изменении поведения приложения необходимо синхронно обновлять четыре основных документа: PROJECT_CONTEXT.md, ARCHITECTURE.md, GAME_DESIGN.md и ROADMAP.md.

Проект пока не содержит отдельного файла лицензии. Условия сторонних компонентов перечислены в THIRD_PARTY_NOTICES.md.