# Карта структуры проекта Just Dance (UbiArt Framework)
Этот документ содержит структурированную карту репозитория и навигационный справочник. Используйте его, чтобы мгновенно определять пути к коду C++, сценам, шаблонам, лентам анимаций (Tape) и ресурсам игры без лишнего поиска.
---
## 1. Быстрый указатель: «Куда идти, если нужно...»
| Задача / Модуль | Исходный код C++ (`main/src/`) | Данные и интерфейс (`data/World/`) |
| :--- | :--- | :--- |
| **Главное меню (Экспозиция, табы Home/Songs/Playlists/Search/Profile)** | `JD/gameplay/GameModes/GameScreens/GS_Exposition/` (стейты: `GSStates/`) | Сцена: `ui/screens/exposition/exposition.isc`
Страницы: `ui/objects/exposition_pages/`
Анимации: `ui/objects/exposition_pages/animations/` |
| **Поиск песен (логика и результаты)** | Менеджер: `JD/gameplay/Managers/Search/JD_SearchManager.*`
Стейт: `GS_Exposition/GSStates/JD_GSS_Exposition_UpdateSearch.*` | Страница: `ui/objects/exposition_pages/exposition_page_search.isc`
Лента: `.../animations/exposition_page_search.tape` |
| **Игровой экран танца (HUD, пиктограммы, счет, звездочки)** | Экран: `JD/gameplay/GameModes/GameScreens/GS_HUD/`
Компоненты: `JD/gameplay/components/` | Сцена: `ui/screens/hud/`
Виджеты: `ui/objects/hud_*` (пиктограммы, полоса прогресса, лирика) |
| **База песен и метаданные треков** | `JD/gameplay/Managers/JD_SongDatabase.*`
`JD/gameplay/Managers/JD_SongsManager.*` | Карты песен: `data/World/MAPS//` |
| **Сетки и карусели треков / списков** | Менеджер: `JD/gameplay/Managers/Carousel/`
Экран: `GS_UICarouselBase/` | Сетка: `ui/objects/grid_generic/`
Карточки песен: `ui/objects/song_panel/` |
| **Профиль игрока, Dancer Cards, кастомизация** | Экраны: `GS_DancerCard*`, `GS_StickerAlbum/`
Менеджеры: `JD/gameplay/Managers/Dancer*/` | Сцены: `ui/screens/profile_*`
Виджеты: `ui/objects/profile_*`, `Avatars/` |
| **Лобби выбора контроллеров и треков** | `GS_LobbyClassic/`, `GS_LobbyBase/` | Сцены: `ui/screens/lobby/` |
| **Всплывающие окна (Попапы, диалоги)** | `GS_Popups/` | `ui/screens/popups/`, `ui/objects/popup_*` |
| **World Dance Floor (WDF / Мультиплеер)** | `JD/gameplay/GameModes/GameMode_WDF/`
`JD/gameplay/Managers/WDF/` | Сцены: `ui/screens/wdf_*`
Виджеты: `ui/objects/wdf_*` |
| **Базовые компоненты UI (TextBox, NineSlice, UIComponent)** | `gameplay/Components/UI/` (`UITextBox.*`, `UIComponent.*`, `UINineSliceComponent.*`, `UIControl.*`) | Шаблоны: `ui/components/` (`textbox.tpl`, `nineslice.tpl` и др.) |
| **Система анимаций Tape** | Движок: `engine/tapes/components/TapeCase_Component.*`
Треки: `engine/tapes/tape/` | Файлы лент `.tape` в папках `animations/` соответствующих экранов |
| **Шрифты и оформление текста** | `engine/localisation/`, `gameplay/Components/UI/UITextBox.*` | Стили шрифтов: `ui/fonts/fontstyles.xml`
Шрифты: `ui/fonts/` |
| **Локализация текстов** | `engine/localisation/CLocalisationManager.*` | `data/World/ui/database/localisation/` |
---
## 2. Архитектура исходного кода (`main/src/`)
```text
main/src/
├── JD/ # Код, специфичный для Just Dance
│ ├── gameplay/
│ │ ├── Conductor/ # Тайминг трека, синхронизация с аудио
│ │ ├── Events/ # Игровые события JD
│ │ ├── GameModes/
│ │ │ ├── BootSequence/ # Начальная загрузка и предупреждения
│ │ │ ├── Classic/ # Классический режим
│ │ │ ├── WDF/ # World Dance Floor
│ │ │ └── GameScreens/ # [КЛЮЧЕВОЙ] Все экраны интерфейса игры
│ │ │ ├── GS_Exposition/ # Главное меню (Home, Songs, Playlist, Search, Profile)
│ │ │ │ └── GSStates/ # Стейты: Init, Navigation, Search, Carousel, Update...
│ │ │ ├── GS_HUD/ # HUD геймплея во время танца
│ │ │ ├── GS_LobbyClassic/ # Лобби ожидания/подключения
│ │ │ ├── GS_Popups/ # Модальные окна
│ │ │ ├── GS_Start/ # Экран "Press any button"
│ │ │ ├── GS_UICarouselBase/ # Базовый класс экранов с каруселями
│ │ │ ├── GS_TabbedLayout_Base/# Базовый класс для экранов с табами
│ │ │ └── ... # Остальные 50+ экранов игры
│ │ ├── Managers/ # [КЛЮЧЕВОЙ] Синглтоны и сервисы
│ │ │ ├── Carousel/ # Управление каруселями контента
│ │ │ ├── Dancer/ & DancerProfile/# Карточки и статистика танцоров
│ │ │ ├── Search/ # JD_SearchManager (поиск по БД)
│ │ │ ├── Playlist/ # Менеджер плейлистов
│ │ │ ├── WDF/ # Менеджер сетевых турниров
│ │ │ ├── JD_GameManager.* # Главный менеджер игрового процесса
│ │ │ ├── JD_PlayerManager.* # Игроки, джойконы, телефоны, камеры
│ │ │ ├── JD_SongDatabase.* # База данных треков и метаданные
│ │ │ └── JD_SongsManager.* # Загрузка и фильтрация песен
│ │ ├── components/ # Специфичные актор-компоненты JD
│ │ └── Tapes/ # Специфичные для JD треки Tape
│ └── editor/ # Редакторы и тулзы внутри JD
│
├── gameplay/ # Общий геймплейный слой движка UbiArt
│ └── Components/
│ └── UI/ # Движковые компоненты интерфейса:
│ ├── UIComponent.* # Базовый компонент UI, playAnim, связь с Tape
│ ├── UITextBox.* # Текстовые поля, шрифты, locId, перенос строк
│ ├── UINineSliceComponent.* # 9-slice плашки, кнопки, рамки
│ ├── UIControl.* # Базовые интерактивные элементы ввода
│ ├── UICheckbox.* # Чекбоксы
│ └── UIRootComponent.* # Корень субсцены UI, мост к TapeCase_Component
│
└── engine/ # Низкоуровневое ядро UbiArt Framework
├── actors/ # Базовый класс Actor, ActorComponent, Pickable
├── scene/ # Scene, SceneManager, SubSceneActor
├── tapes/ # ЯДРО АНИМАЦИИ TAPE
│ ├── components/
│ │ └── TapeCase_Component.* # Компонент на акторе, запускает воспроизведение .tape
│ └── tape/ # Реализация клипов, треков, меток (Labels)
├── localisation/ # Менеджер локализации (CLocalisationManager)
├── serializer/ # Чтение/запись XML, Lua, Binary сериализаторы
├── display/ # Рендерер, шейдеры, материалы
├── sound/ # Звуковой движок (Wwise / UbiArt Sound)
└── zinput/ # Ввод (геймпады, клавиатура, сенсор)
```
---
## 3. Архитектура ассетов и данных (`data/World/`)
```text
data/World/
├── ui/ # [КЛЮЧЕВОЙ] Все ресурсы графического интерфейса
│ ├── screens/ # Корневые сцены игровых экранов (.isc)
│ │ ├── exposition/ # exposition.isc, exposition.tpl, animations/exposition.tape
│ │ ├── hud/ # Игровой экран танца
│ │ ├── lobby/ # Лобби выбора треков
│ │ ├── popups/ # Модальные окна
│ │ ├── start/ # Стартовый экран
│ │ └── ... # 70+ экранов
│ │
│ ├── objects/ # Субсцены, составные виджеты и страницы (.isc, .tape)
│ │ ├── exposition_pages/ # Страницы табов меню:
│ │ │ ├── exposition_page_home.isc # Главная страница
│ │ │ ├── exposition_page_songs.isc # Каталог песен
│ │ │ ├── exposition_page_playlist.isc # Плейлисты
│ │ │ ├── exposition_page_search.isc # Поиск песен (с анимацией EMPTY/NORMAL)
│ │ │ └── animations/ # Ленты анимаций страниц (.tape)
│ │ ├── grid_generic/ # Универсальная сетка элементов
│ │ ├── song_panel/ # Виджет плашки/карточки песни
│ │ ├── button/ # Кнопки
│ │ ├── checkbox/ # Чекбоксы
│ │ ├── scrollbar/ # Скроллбары
│ │ ├── tabs_list/ # Список табов навигации
│ │ └── ... # 190+ переиспользуемых UI-виджетов
│ │
│ ├── components/ # Базовые шаблоны акторов (.tpl):
│ │ ├── textbox.tpl # Шаблон текстового блока
│ │ ├── nineslice.tpl # Шаблон 9-slice плашки
│ │ └── ...
│ │
│ ├── fonts/ # Шрифты и стили:
│ │ ├── fontstyles.xml # Определение размеров, цветов и стилей шрифтов
│ │ └── *.ttf, *.fnt
│ │
│ └── database/ # Локализация и базы данных UI
│
├── MAPS/ # Карты песен (хореография, треки, видео, трек-дата)
│ └── / # Данные отдельной песни
│
├── playlists/ # Плейлисты (встроенные и системные)
├── Avatars/ # Аватары игроков и танцоров
└── skins/ # Скины и темы оформления
```
---
## 4. Основные типы файлов и их назначение
1. **`.isc` (Inter Scene)**:
- Файлы сцен и субсцен в формате XML.
- Описывают иерархию акторов (``), их привязки (``), координаты (`POS2D`), базовые свойства и компоненты (`UITextBox`, `UINineSliceComponent`, `UIComponent`).
- Используют дружественные имена: `USERFRIENDLY="my_actor_name"`.
2. **`.tape` (Animation Tape)**:
- Файлы лент анимаций в формате Lua-таблиц.
- Управляют треками свойств во времени (`Track2D`, `AlphaTrack`, `TransformTrack`).
- Адресуют целевые акторы по понятным именам: `ActorPaths = { { VAL = "friendly_name" } }`.
- Содержат метки состояний (Labels, например `NORMAL`, `EMPTY`, `IN`, `OUT`), запускаемые из C++ через `UIComponent::playAnim("LABEL")`.
3. **`.tpl` (Template)**:
- Файлы шаблонов акторов и компонентов в формате Lua (`params = { NAME = "...", ... }`).
- Определяют базовый набор компонентов и неизменяемые параметры сущности.
4. **`.act` (Actor)**:
- Описание отдельного актора в формате Lua (обычно используется для инстанцирования в сцену).
---
## 5. Сборка, генерация решений и бинарники
- `main/run_sharpmake.ps1` — Запуск Sharpmake для генерации файлов решений и проектов Visual Studio (`.sln`, `.vcxproj`).
- `main/build/` — Папка со сгенерированными решениями (например, `Engine.tu1.2017.sln`).
- `engine/ua_engine.exe` — Исполняемый файл собранного движка UbiArt.
- `engine/` — Рабочая директория запуска игры со всеми библиотеками.