exchanger-themes/README.md

# Exchanger Theme DLC Builder

Самостоятельный Godot 4.7-проект для разработки, визуального просмотра, проверки и сборки
полносценовых DLC-тем Exchanger. Тема полностью рисует девять экранов, а приложение подключает к
размеченным элементам бизнес-логику через binding-id.

## Быстрый путь

Требуется Godot 4.7.x. Откройте эту папку в VS Code, установите рекомендованное расширение и
запустите проект в Godot Editor. В меню `Редактор` доступны четыре команды:

- `Выбрать тему` — выбирает существующую тему и открывает preview прямо из её `package/`;
- `Создать тему` — создаёт полную тему из `example`, задаёт её ID/название и сразу активирует;
- `Экспортировать тему` — предлагает выбрать любую найденную тему по ID, затем открывает
  стандартный диалог сохранения и собирает выбранный `.pck` без установки в приложение;
- `Применить тему к Exchanger` — в фоне проверяет и собирает активную тему, затем устанавливает
  `active_theme.pck` в пользовательский каталог приложения.

Выбор, создание, экспорт и применение сопровождаются окном прогресса: в нём видны текущий этап,
процент выполнения и итоговый путь либо диагностическое сообщение.

Для автоматизации и CI те же операции доступны через VS Code tasks или PowerShell:

```powershell
.\activate-theme.ps1 -ThemeId space-pixel
.\preview-theme.ps1 -ThemeId space-pixel
.\test-theme.ps1 -ThemeId space-pixel
.\build-theme.ps1 -ThemeId space-pixel -InstallToDefaultUserPath
```

После активации preview показывает реальные production-сцены всех девяти экранов в `720×1280`.
Кнопка `BINDINGS: ON/OFF` слева в верхней панели показывает, к какому binding-id подключится
каждый элемент. Изменения `themes/space-pixel/package/` подхватываются live reload.
На вкладке SETTINGS дополнительная кнопка `KEYBOARD: OFF/TEXT/NUM` показывает оба скрытых
состояния экранной клавиатуры и их биндинги.
Кнопка `INVENTORY: OFF/PANEL/DIALOG` рядом показывает theme-owned раздел «Сервис» и его диалог
пересчёта/ручного добавления, не создавая runtime-узлов.
Кнопка `PET` в правой части верхней панели открывает отдельную сцену просмотра интерактивного
питомца активной темы. В ней доступны все состояния, счётчик кадров, пауза, повтор, ручное
переключение и автоматический последовательный показ. Кнопка «СОСТАВНОЕ ДЕЙСТВИЕ: INTERACT»
запускает theme-owned сценарий через тестовый host-runtime с границами и верхней опорой;
`Esc` или «← ГАЛЕРЕЯ» возвращают к экранам.
Viewer берёт компонент из необязательного поля manifest `InteractivePetScene` и строит список
анимаций через публичный API сцены. Папки текстур и их имена определяет сама тема: builder не
сканирует и не требует каталог `alien_pet`.

Preview не добавляет к сценам тему, фон, декорации или демонстрационные узлы: он только собирает
девять `.tscn` во вкладки и рисует отдельный диагностический overlay. Поэтому production-сцена,
открытая прямо из `themes/<id>/package/scenes/`, выглядит так же, как в preview и в Exchanger.
Home, CardAmount и Settings уже содержат все визуальные состояния и фиксированные строки; host
только подключает логику к существующим binding-id и не перестраивает ThemeView.

Новую тему создавайте через `Редактор → Создать тему`. Ручное копирование `themes/example`
остаётся только скриптовым fallback. Подробности — в [быстром старте](docs/QUICK_START.md).

Все каталоги внутри `themes/` всегда видны в Godot FileSystem. Открывайте и редактируйте
`themes/<id>/package/` напрямую; `.gdignore` в темах не используется и при создании новых тем не
появляется. При открытии проекта аддон автоматически удаляет такие файлы, оставшиеся от старой
структуры.

## Что где находится

```text
themes/example/             самодостаточная тема-шаблон со всеми сценами и биндингами
themes/space-pixel/         текущая оформленная тема для preview и сборки
themes/<theme-id>/source/   оригиналы, лицензии и локальные references
themes/<theme-id>/package/  единственный источник production PCK
contracts/                  авторитетный binding-контракт builder
tools/preview/              галерея, просмотрщик питомца и binding overlay, не входят в PCK
addons/exchanger_theme_manager/  EditorPlugin выбора, создания, экспорта и применения тем
build/                      PCK, active-theme.json и временный скрытый workspace сборки
```

В format v2 обязательны ровно девять канонических сцен, 481 immutable element-binding из JSON и
24 обязательных supplemental runtime-binding, проверяемых Builder Validator отдельно, и четыре
совместимых optional supplemental binding для новых текстов баннеров, выбора промо-изображения и
переключателя интерактивного питомца. Тема считается
доверенной: её GDScript и runtime-узлы входят в PCK и исполняются в preview и Exchanger. `source/`,
references и builder preview tooling в production PCK не экспортируются.

## Документация

- [Быстрый старт из VS Code](docs/QUICK_START.md)
- [Как применить тему в Exchanger](docs/APPLY_THEME.md)
- [Архитектура и границы проектов](docs/ARCHITECTURE.md)
- [Полный жизненный цикл темы](docs/WORKFLOW.md)
- [Manifest v2 и binding-контракт](docs/BINDING_CONTRACT.md)
- [Создание и оформление темы](docs/THEME_AUTHORING.md)
- [Скрипты и runtime-логика темы](docs/SCRIPTING.md)
- [Композитные анимации питомца: гайд для дизайнера](docs/COMPOSITE_PET_ANIMATIONS.md)
- [Установка и интеграция](docs/THEME_INTEGRATION.md)
- [QA и решение проблем](docs/QA_AND_TROUBLESHOOTING.md)
- [Текущее состояние и handoff для ИИ](docs/PROJECT_CONTEXT.md)
- [Особенности `space-pixel`](docs/SPACE_PIXEL.md)
- [Правила участия](CONTRIBUTING.md)

Для этого проекта категорически запрещён Ziva-Godot. Godot-автоматизация выполняется только через
`godot-ai` или штатные безопасные команды Godot. ИИ-агент начинает с [AGENTS.md](AGENTS.md).