exchanger-themes/docs/APPLY_THEME.md

Как применить тему в Exchanger

Эта инструкция описывает полный пользовательский путь: от выбора и редактирования темы до установки нового PCK в Exchanger.

Важно различать действия:

• Редактор → Выбрать тему и activate-theme.ps1 выбирают тему только для builder-preview;
• Редактор → Экспортировать тему позволяет выбрать любую тему по ID и создаёт указанный пользователем .pck, но не устанавливает его и не переключает preview;
• Редактор → Применить тему к Exchanger проверяет, собирает и устанавливает активную тему;
• build-theme.ps1 -InstallToDefaultUserPath выполняет ту же установку из PowerShell.

1. Открыть проект

Требуется Godot 4.7.x. Откройте проект ExchangerThemeDlcBuilder в Godot Editor, а PowerShell — в корне проекта:

Set-Location 'E:\Danil\Projects\Godot\ExchangerThemeDlcBuilder'

Скрипты автоматически ищут Godot среди запущенных процессов, команд godot/godot4 в PATH и переменных GODOT4_EXECUTABLE/GODOT_EXECUTABLE.

2. Выбрать тему для preview

В Godot Editor выберите Редактор → Выбрать тему, укажите нужную тему и подтвердите выбор.

Эквивалентная команда для space-pixel:

.\activate-theme.ps1 -ThemeId space-pixel

Активация записывает выбранный package в build/active-theme.json. Она не собирает PCK и не изменяет установленную тему Exchanger.

3. Редактировать production-файлы

Редактируйте файлы непосредственно в:

themes/<theme-id>/package/

Основные каталоги и файлы:

• scenes/ — девять экранов приложения;
• components/ — общие компоненты темы;
• assets/ — изображения, шрифты и звук;
• visuals/ — дополнительные визуальные ресурсы;
• ui_theme.tres — стили элементов интерфейса;
• background_decoration.tscn — отдельная фоновая декорация.

source/ используется для оригиналов и references, но в production PCK не экспортируется.

Все зависимости внутри package/ должны оставаться переносимыми. Используйте относительные ссылки, например ../ui_theme.tres или ../assets/button.png. Ссылки вида res://themes/<theme-id>/package/... могут открываться в builder, но не разрешатся в изолированном workspace сборки, где package монтируется как res://exchanger_theme_dlc/.

4. Проверить preview

Запустите проект из Godot либо выполните:

.\preview-theme.ps1 -ThemeId space-pixel

Preview показывает реальные production-сцены без изменения их визуального дерева. Проверьте все девять вкладок: HOME, CASH, SUM, KEYPAD, CARD, SUCCESS, ERROR, SERVICE, SETTINGS.

Сначала включите BINDINGS: ON, чтобы проверить размеченные функциональные элементы, затем выключите overlay и проверьте внешний вид в портретном окне 720×1280. В SETTINGS дополнительно проверьте состояния KEYBOARD: OFF/TEXT/NUM и INVENTORY: OFF/PANEL/DIALOG.

Сохранённые изменения .tscn, .tres, JSON, изображений, шрифтов и звука обычно появляются через live reload. Если этого не произошло, убедитесь, что активирована правильная тема, сохраните файл на диск и перезапустите preview.

5. Выполнить автоматические проверки

.\tools\Test-PackagedBindingContract.ps1
.\test-theme.ps1 -ThemeId space-pixel

Первая команда проверяет byte-identical копии binding-контракта во всех темах. Вторая создаёт изолированный workspace, импортирует ресурсы, проверяет manifest v2, девять сцен, обязательные биндинги и запрещённые production-узлы, а затем выполняет headless preview smoke.

Не переходите к установке, пока обе команды не завершатся успешно.

6. Закрыть Exchanger

Полностью закройте запущенное приложение перед заменой PCK. Live reload действует только в builder-preview; Exchanger загружает внешний пакет при запуске.

7. Собрать и установить тему

Предпочтительный интерактивный путь: закройте Exchanger и выберите в Godot Editor Редактор → Применить тему к Exchanger. Подтверждение показывает ID активной темы и конечный путь. Сборка идёт в фоне; по завершении аддон сообщает об успехе либо показывает последние строки ошибки PowerShell. Во время работы видны текущий этап и процент выполнения.

Эквивалентная команда:

.\build-theme.ps1 -ThemeId space-pixel -InstallToDefaultUserPath

Команда валидирует тему, собирает build/space-pixel.pck, обновляет совместимую копию build/active_theme.pck и устанавливает пакет по пути:

%APPDATA%\Godot\app_userdata\Exchanger\theme_dlc\active_theme.pck

Команда без -InstallToDefaultUserPath только создаёт PCK в build/; в Exchanger такая сборка автоматически не попадёт.

8. Перезапустить и проверить Exchanger

Запустите Exchanger заново и проверьте все затронутые экраны и интерактивные элементы. В журнале должны быть указаны ожидаемые ThemeId и manifest версии 2.

Если приложение показывает встроенную fallback-тему:

1. убедитесь, что Exchanger был полностью перезапущен;
2. проверьте наличие установленного active_theme.pck по пути выше;
3. повторите validator и сборку без -SkipValidation;
4. проверьте журнал ThemeManager на ошибку manifest, контракта, binding-id или отсутствующего ресурса.

Короткий ежедневный цикл

После редактирования темы выполните:

.\activate-theme.ps1 -ThemeId space-pixel
.\tools\Test-PackagedBindingContract.ps1
.\test-theme.ps1 -ThemeId space-pixel

Затем закройте Exchanger, установите новую сборку и запустите приложение заново:

.\build-theme.ps1 -ThemeId space-pixel -InstallToDefaultUserPath

Выполнение через VS Code

Откройте палитру команд Ctrl+Shift+P, выберите Tasks: Run Task и последовательно запустите:

1. Theme: активировать;
2. Theme: проверить копии контракта;
3. Theme: проверить validator и preview smoke;
4. после закрытия Exchanger — Theme: собрать и установить PCK (заменяет установленную тему).

Задача Theme: полный локальный QA выполняет проверки и обычную сборку, но не устанавливает PCK в пользовательский каталог Exchanger.