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:

.\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. Подробности — в быстром старте.

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

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

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
• Как применить тему в Exchanger
• Архитектура и границы проектов
• Полный жизненный цикл темы
• Manifest v2 и binding-контракт
• Создание и оформление темы
• Скрипты и runtime-логика темы
• Композитные анимации питомца: гайд для дизайнера
• Установка и интеграция
• QA и решение проблем
• Текущее состояние и handoff для ИИ
• Особенности space-pixel
• Правила участия

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