JD2022-TU1/.agents/rules/project_structure_map.md

Карта структуры проекта 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/<SongName>/
Сетки и карусели треков / списков	Менеджер: 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/)

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/)

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/ — Рабочая директория запуска игры со всеми библиотеками.