exchanger-themes/docs/WORKFLOW.md

Жизненный цикл темы

1. Создание

В Godot Editor выберите Редактор → Создать тему. Укажите стабильный lowercase ID с латинскими буквами, цифрами и дефисами и человекочитаемое название. Аддон скопирует example, обновит manifest и сразу активирует новую тему.

Для автоматизации можно скопировать themes/example в themes/<theme-id>. Используйте ID с латинскими буквами, цифрами и дефисами. Измените только ThemeId и человекочитаемый DisplayName в manifest; канонические scene keys/paths не меняйте.

2. Активация

В Godot Editor выберите Редактор → Выбрать тему. После подтверждения аддон остановит запущенный preview при необходимости, запишет выбранный package в build/active-theme.json, откроет preview и восстановит запуск.

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

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

Команда только проверяет manifest и пишет build/active-theme.json. Корневая копия темы не создаётся: активный package остаётся единственным источником.

3. Редактирование и live reload

Источник — видимый в Godot FileSystem каталог themes/<id>/package/. Запущенный preview загружает его сцены напрямую, следит за изменёнными .tscn, .tres, JSON, изображениями, шрифтами и звуком и сохраняет выбранную вкладку при перезагрузке.

Открывайте production-сцены прямо из res://themes/<id>/package/scenes/. Их ссылки относительные: каждая тема использует собственные assets/, components/ и visuals, даже когда рядом индексируются остальные темы. Сцена уже содержит собственные Theme, статический фон и decoration, поэтому её вид в редакторе является production-видом, а не упрощённым каркасом. Если Godot Editor пересохранил ссылку с полным builder-префиксом, временный test/build workspace автоматически заменит его на res://exchanger_theme_dlc/; исходный package при этом не меняется.

4. Preview

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

Верхняя панель переключает девять экранов. BINDINGS: ON/OFF включает подписи metadata. Overlay нужен для проверки контракта, а финальный визуальный QA делается с выключенными подписями. Галерея не меняет инстанцированные сцены и не добавляет им оформление или preview-only содержимое.

5. Проверка

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

Первая команда без Godot сверяет byte-identical копии контракта во всех темах. Вторая выбирает тему, валидирует её в изолированном временном workspace и запускает headless smoke preview, который читает исходный package напрямую.

6. Сборка

В Godot Editor выберите Редактор → Экспортировать тему, выберите любую валидную тему по ID, затем укажите каталог и имя .pck в стандартном диалоге сохранения. Аддон проверит и соберёт именно выбранную тему в фоне, не переключая preview и не заменяя установленную тему Exchanger. Окно прогресса показывает импорт, проверку контракта, экспорт, проверку пакета и завершение.

Эквивалентная команда с путём по умолчанию:

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

Результаты: build/space-pixel.pck и совместимая копия build/active_theme.pck. Для сохранения обязательных runtime-путей сборка кратковременно создаёт build/theme-workspaces/<id>-build/exchanger_theme_dlc/, экспортирует PCK и удаляет workspace. build/ скрыт от Godot через собственный .gdignore и игнорируется системой контроля версий. Выбор другого пути в Editor передаётся скрипту как -OutputPath -PreserveActiveTheme: поэтому редакторский экспорт не меняет build/active-theme.json и build/active_theme.pck. Прямой запуск скрипта без -PreserveActiveTheme сохраняет прежнее поведение и обновляет совместимую копию.

7. Установка

Закройте Exchanger, затем в Godot Editor выберите Редактор → Применить тему к Exchanger. В компактном окне проверьте ID активной темы и путь, нажмите Собрать и применить. Аддон выполняет validator, export и установку в фоновом потоке; редактор остаётся доступен, а отдельное окно показывает текущий этап, процент и результат.

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

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

Команда заменяет %APPDATA%\Godot\app_userdata\Exchanger\theme_dlc\active_theme.pck. После этого нужен полный перезапуск Exchanger и интеграционный checklist из THEME_INTEGRATION.md.

8. Изменение host-контракта

Это отдельная миграция, а не часть обычного оформления темы. Сначала изменяется Exchanger и его тесты, затем builder синхронизируется штатной командой. Последовательность описана в BINDING_CONTRACT.md. Никогда не правьте 481 ID вручную в обход host.