exchanger-themes/docs/THEME_INTEGRATION.md

Интеграция полносценовой темы в Exchanger

Этот документ описывает границу с основным приложением. Для локального цикла разработки используйте WORKFLOW.md, а для точной схемы контракта — BINDING_CONTRACT.md.

Граница ответственности

Exchanger монтирует один внешний PCK, проверяет manifest v2 и создаёт визуальный корень выбранного экрана из ScreenScenes. C#-контроллер экрана остаётся в приложении. Он разрешает нужные тематические узлы по exchanger_binding_id, подписывает кнопки и обновляет текст/состояния. Он не добавляет, не удаляет, не переносит и не стилизует визуальные узлы ThemeView. Тема считается доверенной: прикреплённый GDScript и её runtime-узлы исполняются как часть инстанцированной сцены. App-owned C#-контроллеры оплаты, оборудования и настроек остаются вне ThemeView, но тема может содержать собственные таймеры, аудио, сетевые запросы и другую вспомогательную логику.

PackedScene уже содержит root Theme, ThemeBackground и BackgroundDecoration; это тот же файл, который открывается напрямую и показывается в builder preview. UiThemePath описывает Theme самодостаточных сцен. BackgroundTexturePath и BackgroundDecorationPath у самодостаточных тем пусты, поэтому общий background-layer Exchanger не дублирует визуальные слои экранной сцены.

При любой ошибке PCK приложение использует единственную встроенную fallback-тему.

Установка

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

Пакет устанавливается в:

%APPDATA%\Godot\app_userdata\Exchanger\theme_dlc\active_theme.pck

Перед заменой PCK закройте Exchanger. После установки выполните полный перезапуск.

Контракт

Источником истины для автономной работы builder является contracts/screen_bindings.v2.json. Он генерируется и при согласованной миграции синхронизируется с:

• src/core/ThemeManager/ThemeSceneContract.cs;
• src/core/ThemeManager/ThemeBindingResolver.cs;
• вызовами GetNode(SafeMargin/...) в девяти C#-контроллерах экранов.

Путь, имя root, screen metadata, element metadata и тип каждого обязательного узла должны совпасть. Фактическая иерархия узлов внутри сцены темы свободна: приложение ищет их по metadata, а не NodePath.

Каждая тема включает точную байтовую копию каталога по каноническому runtime-пути res://exchanger_theme_dlc/contracts/screen_bindings.v2.json. Host до создания ThemeView вычисляет SHA-256 встроенного файла и сравнивает его с закреплённым хешем поддерживаемой версии контракта. Несовпадение означает несовместимый или изменённый пакет и приводит к безопасной fallback-теме.

Проверка интеграции

1. В журнале активирован ожидаемый ThemeId и manifest версии 2.
2. Все девять экранов созданы из соответствующих ScreenScenes.
3. Кнопки навигации и оплаты реагируют на касание.
4. Динамические Label, формы, PIN-клавиатуры и настройки обновляются через биндинги.
5. Home находит готовые stock/connection/promo nodes без изменения дерева ThemeView.
6. Технические панели остаются скрытыми/управляются host-логикой так же, как во fallback-сцене.
7. В production PCK нет preview overlay, builder tooling, source/ и references; GDScript и runtime-ресурсы самой темы присутствуют и запускаются без ошибок.
8. При повреждённой сцене, неверном типе или отсутствующем binding-id активируется безопасный fallback.

Совместимость

Manifest v1 и VisualSlots относятся к прежней частичной модели. space-pixel пока сохраняет старые English Advertisement* identifiers и VisualSlots для миграции, но новым темам следует использовать v2 ScreenScenes. В пользовательском русском интерфейсе используются «промо» и «промо-ролик».