165 lines
14 KiB
Markdown
165 lines
14 KiB
Markdown
# Карта структуры проекта 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`<br>Страницы: `ui/objects/exposition_pages/`<br>Анимации: `ui/objects/exposition_pages/animations/` |
|
||
| **Поиск песен (логика и результаты)** | Менеджер: `JD/gameplay/Managers/Search/JD_SearchManager.*`<br>Стейт: `GS_Exposition/GSStates/JD_GSS_Exposition_UpdateSearch.*` | Страница: `ui/objects/exposition_pages/exposition_page_search.isc`<br>Лента: `.../animations/exposition_page_search.tape` |
|
||
| **Игровой экран танца (HUD, пиктограммы, счет, звездочки)** | Экран: `JD/gameplay/GameModes/GameScreens/GS_HUD/`<br>Компоненты: `JD/gameplay/components/` | Сцена: `ui/screens/hud/`<br>Виджеты: `ui/objects/hud_*` (пиктограммы, полоса прогресса, лирика) |
|
||
| **База песен и метаданные треков** | `JD/gameplay/Managers/JD_SongDatabase.*`<br>`JD/gameplay/Managers/JD_SongsManager.*` | Карты песен: `data/World/MAPS/<SongName>/` |
|
||
| **Сетки и карусели треков / списков** | Менеджер: `JD/gameplay/Managers/Carousel/`<br>Экран: `GS_UICarouselBase/` | Сетка: `ui/objects/grid_generic/`<br>Карточки песен: `ui/objects/song_panel/` |
|
||
| **Профиль игрока, Dancer Cards, кастомизация** | Экраны: `GS_DancerCard*`, `GS_StickerAlbum/`<br>Менеджеры: `JD/gameplay/Managers/Dancer*/` | Сцены: `ui/screens/profile_*`<br>Виджеты: `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/`<br>`JD/gameplay/Managers/WDF/` | Сцены: `ui/screens/wdf_*`<br>Виджеты: `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.*`<br>Треки: `engine/tapes/tape/` | Файлы лент `.tape` в папках `animations/` соответствующих экранов |
|
||
| **Шрифты и оформление текста** | `engine/localisation/`, `gameplay/Components/UI/UITextBox.*` | Стили шрифтов: `ui/fonts/fontstyles.xml`<br>Шрифты: `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/ # Карты песен (хореография, треки, видео, трек-дата)
|
||
│ └── <SongCodename>/ # Данные отдельной песни
|
||
│
|
||
├── playlists/ # Плейлисты (встроенные и системные)
|
||
├── Avatars/ # Аватары игроков и танцоров
|
||
└── skins/ # Скины и темы оформления
|
||
```
|
||
|
||
---
|
||
|
||
## 4. Основные типы файлов и их назначение
|
||
|
||
1. **`.isc` (Inter Scene)**:
|
||
- Файлы сцен и субсцен в формате XML.
|
||
- Описывают иерархию акторов (`<ACTORS>`), их привязки (`<Bind>`), координаты (`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/` — Рабочая директория запуска игры со всеми библиотеками.
|