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.
163 lines
8.7 KiB
Markdown
163 lines
8.7 KiB
Markdown
# Как применить тему в 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 —
|
||
в корне проекта:
|
||
|
||
```powershell
|
||
Set-Location 'E:\Danil\Projects\Godot\ExchangerThemeDlcBuilder'
|
||
```
|
||
|
||
Скрипты автоматически ищут Godot среди запущенных процессов, команд `godot`/`godot4` в `PATH` и
|
||
переменных `GODOT4_EXECUTABLE`/`GODOT_EXECUTABLE`.
|
||
|
||
## 2. Выбрать тему для preview
|
||
|
||
В Godot Editor выберите `Редактор → Выбрать тему`, укажите нужную тему и подтвердите выбор.
|
||
|
||
Эквивалентная команда для `space-pixel`:
|
||
|
||
```powershell
|
||
.\activate-theme.ps1 -ThemeId space-pixel
|
||
```
|
||
|
||
Активация записывает выбранный package в `build/active-theme.json`. Она не собирает PCK и не
|
||
изменяет установленную тему Exchanger.
|
||
|
||
## 3. Редактировать production-файлы
|
||
|
||
Редактируйте файлы непосредственно в:
|
||
|
||
```text
|
||
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 либо выполните:
|
||
|
||
```powershell
|
||
.\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. Выполнить автоматические проверки
|
||
|
||
```powershell
|
||
.\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. Во время работы видны текущий этап и процент выполнения.
|
||
|
||
Эквивалентная команда:
|
||
|
||
```powershell
|
||
.\build-theme.ps1 -ThemeId space-pixel -InstallToDefaultUserPath
|
||
```
|
||
|
||
Команда валидирует тему, собирает `build/space-pixel.pck`, обновляет совместимую копию
|
||
`build/active_theme.pck` и устанавливает пакет по пути:
|
||
|
||
```text
|
||
%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 или отсутствующего
|
||
ресурса.
|
||
|
||
## Короткий ежедневный цикл
|
||
|
||
После редактирования темы выполните:
|
||
|
||
```powershell
|
||
.\activate-theme.ps1 -ThemeId space-pixel
|
||
.\tools\Test-PackagedBindingContract.ps1
|
||
.\test-theme.ps1 -ThemeId space-pixel
|
||
```
|
||
|
||
Затем закройте Exchanger, установите новую сборку и запустите приложение заново:
|
||
|
||
```powershell
|
||
.\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.
|