Danil Iarosh
ca52efbedc
Godot 4.7 project for authoring, previewing, validating, and building Exchanger PCK themes. Includes the example and space-pixel themes, binding contracts, editor tooling, validation/build scripts, and project documentation.
104 lines
7.0 KiB
Markdown
104 lines
7.0 KiB
Markdown
# Жизненный цикл темы
|
||
|
||
## 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-команда:
|
||
|
||
```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
|
||
|
||
```powershell
|
||
.\preview-theme.ps1 -ThemeId space-pixel
|
||
```
|
||
|
||
Верхняя панель переключает девять экранов. `BINDINGS: ON/OFF` включает подписи metadata. Overlay
|
||
нужен для проверки контракта, а финальный визуальный QA делается с выключенными подписями. Галерея
|
||
не меняет инстанцированные сцены и не добавляет им оформление или preview-only содержимое.
|
||
|
||
## 5. Проверка
|
||
|
||
```powershell
|
||
.\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.
|
||
Окно прогресса показывает импорт, проверку контракта, экспорт, проверку пакета и завершение.
|
||
|
||
Эквивалентная команда с путём по умолчанию:
|
||
|
||
```powershell
|
||
.\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 и установку в фоновом потоке;
|
||
редактор остаётся доступен, а отдельное окно показывает текущий этап, процент и результат.
|
||
|
||
Эквивалентная команда для автоматизации:
|
||
|
||
```powershell
|
||
.\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](BINDING_CONTRACT.md). Никогда не правьте 481 ID вручную в обход host.
|