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.
74 lines
5.6 KiB
Markdown
74 lines
5.6 KiB
Markdown
# Интеграция полносценовой темы в Exchanger
|
||
|
||
Этот документ описывает границу с основным приложением. Для локального цикла разработки используйте
|
||
[WORKFLOW.md](WORKFLOW.md), а для точной схемы контракта —
|
||
[BINDING_CONTRACT.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-тему.
|
||
|
||
## Установка
|
||
|
||
```powershell
|
||
.\build-theme.ps1 -ThemeId space-pixel -InstallToDefaultUserPath
|
||
```
|
||
|
||
Пакет устанавливается в:
|
||
|
||
```text
|
||
%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`. В пользовательском русском интерфейсе используются «промо» и
|
||
«промо-ролик».
|